Document manual website regeneration/deployment via GitHub Actions

README.md

@@ -103,6 +103,8 @@ flowchart BT
 
 The website will automatically be regenerated and redeployed whenever a new commit is made on—or merged into—the `main`
 branch of _this_ repository. Regeneration includes pulling content from the remote repositories. The regeneration and redeployment process usually takes about three minutes to complete.
+If you need to regenerate/redeploy manually (without making a new commit), see the Deployment section in
+[`development.md`](./development.md#deployment).
 
 ## The Home section
 

development.md

@@ -18,6 +18,9 @@ as opposed to the content aspect.
       * [Runtime section](#runtime-section)
       * [Workflow docs](#workflow-docs)
   * [Deployment](#deployment)
+    * [Automatic deployment](#automatic-deployment)
+    * [Manual regeneration and deployment (step-by-step)](#manual-regeneration-and-deployment-step-by-step)
+    * [Workflow details (for GitHub Actions users)](#workflow-details-for-github-actions-users)
   * [Google Analytics](#google-analytics)
 <!-- TOC -->
 
@@ -100,6 +103,41 @@ The `.github/workflows` directory contains YAML files that we use to configure G
 We use GitHub Actions to (a) compile local and remote content into a single website,
 and to (b) publish that single website to GitHub Pages.
 
+### Automatic deployment
+
+Website regeneration and deployment happens automatically when a commit is pushed to the `main` branch of this repository.
+The workflow that performs this is `.github/workflows/deploy-to-gh-pages.yml` ("Deploy to GitHub Pages").
+
+### Manual regeneration and deployment (step-by-step)
+
+Use this procedure when you need to regenerate and redeploy the website without creating a new commit on `main`.
+
+1. Open the repository's **Actions** tab: https://github.com/microbiomedata/docs/actions
+2. In the left sidebar, click **Deploy to GitHub Pages**
+3. Click **Run workflow**
+4. In the **Use workflow from** dropdown, select `main` (recommended for production)
+5. Click the green **Run workflow** button to start the run
+6. Open the new workflow run and monitor the jobs until they complete
+7. Confirm both jobs succeeded:
+   - **Assemble website**
+   - **Deploy website**
+8. Wait ~3 minutes, then verify the live site was refreshed: https://docs.microbiomedata.org
+
+If the run fails, open the failed job, review the logs, fix the root cause, and run the workflow again.
+
+### Workflow details (for GitHub Actions users)
+
+The deployment path is:
+
+1. `Deploy to GitHub Pages` (`deploy-to-gh-pages.yml`) is triggered (`push` to `main` or `workflow_dispatch`)
+2. It calls `Assemble website` (`assemble-website.yml`)
+3. `Assemble website` calls these reusable workflows in parallel:
+   - `compile-home-docs.yml`
+   - `fetch-and-compile-runtime-docs.yml`
+   - `fetch-and-compile-workflow-docs.yml`
+4. The assembled `github-pages` artifact is link-checked (`check-links.yml`)
+5. `actions/deploy-pages` publishes the artifact to GitHub Pages
+
 ## Google Analytics
 
 We use Google Analytics to collect and analyze website traffic. You can search the repository for