Create a docs-as-code pipeline with previews, review gates, and links.
- User
Create a docs-as-code pipeline with previews, review gates, and links.
- Assistant
We are going to set up a docs-as-code pipeline with previews, review gates, and links. Steps:
- Set up a repository for documentation (likely in a version control system like Git).
- Use a static site generator (like Sphinx, MkDocs, Jekyll, etc.) to generate the documentation from source files (written in Markdown, reStructuredText, etc.).
- Set up a continuous integration (CI) pipeline to build the documentation on every commit and push to a preview environment (like a staging site or using a service that provides previews for each pull request).
- Implement review gates: require that changes to the documentation are reviewed (via pull/merge requests) and that the build passes before merging.
- After merging to the main branch, deploy to the production documentation site.
- Ensure that the documentation includes links (internal and external) and that they are validated (broken link checking) as part of the CI process.
We'll outline a generic pipeline and then give an example using a common stack: GitHub with MkDocs and GitHub Actions.
Example Stack:
- Repository: GitHub
- Static Site Generator: MkDocs (with Material theme)
- CI/CD: GitHub Actions
- Preview: Using the
mkdocs serveon a GitHub Actions runner and then using a service likehttps://github.com/JamesIves/github-pages-deploy-actionto deploy to a preview environment? Alternatively, use a service that provides PR previews (like Read the Docs for Sphinx, but for MkDocs we can use a similar approach).
However, note: for previews on PRs, we can set up GitHub Actions to build the site and then deploy it to a temporary location (like an orphan branch or a GitHub Pages branch for previews). But there are also third-party services that can do this.
Alternatively, we can use a service like Vercel or Netlify that can provide preview URLs for each PR.
Let's break down:
-
Repository setup:
- Create a repository for the documentation.
- Write documentation in Markdown (for MkDocs) and have an
mkdocs.ymlconfiguration file.
-
CI pipeline (GitHub Actions):
- On every push and pull request, we want to:
a. Check out the code.
b. Set up Python (if using MkDocs) and install dependencies (mkdocs and any plugins).
c. Build the site (to check for build errors).
d. Run a link checker (like
markdown-link-checkorlychee). e. Deploy to a preview environment for PRs (if it's a PR) and to production for pushes to main.
- On every push and pull request, we want to:
a. Check out the code.
b. Set up Python (if using MkDocs) and install dependencies (mkdocs and any plugins).
c. Build the site (to check for build errors).
d. Run a link checker (like
-
Review gates:
- Require that the CI build and link check pass before merging the PR.
- Require at least one approving review.
-
Preview environment:
- For PRs, we can deploy to a unique URL (like
https://<pr-number>--<repository>.github.io/if using GitHub Pages for previews). But note: GitHub Pages doesn't natively support per-PR previews. We can use a separate branch for each PR? That might be messy.
Alternatively, we can use a service that integrates with GitHub and provides per-PR previews, such as: - Vercel: can deploy each PR to a unique URL. - Netlify: can deploy each PR to a unique URL.
But if we want to stick with GitHub Actions and GitHub Pages, we can set up two branches for deployments: -
gh-pagesfor production (built from main branch). - For PRs, we can build and then push to a branch namedpreview-<pr-number>and then use GitHub Pages to serve that branch? But that would require setting up GitHub Pages to use that branch and then having to change the setting for each PR? Not ideal.Another idea: use a GitHub Action that deploys to an environment that is accessible via a URL. We can use a static hosting service that supports arbitrary directories or use a storage bucket (like AWS S3, Google Cloud Storage, or Azure Blob Storage) and set up the action to upload the built site to a bucket with a path that includes the PR number. Then we can generate a link and post it as a comment on the PR.
However, there's a simpler way: use the
github-pages-deploy-actionto deploy to thegh-pagesbranch for production, and for PRs, we can use a separate deployment target (like a folder in the samegh-pagesbranch but under apreviewdirectory) and then use a GitHub Pages site that is configured to serve from thatpreviewdirectory for PRs? But then we need a way to have two different GitHub Pages sites? Or we can use a custom domain for production and the default GitHub Pages domain for previews? This is getting complicated.Let me suggest:
We can use the following approach for PR previews:
- Set up a GitHub Action that on PR will:
- Build the site.
- Use the
gsdh/ GitHub Action for deploying to GitHub Pages(or similar) to deploy to a branch that is specific to the PR, and then set the GitHub Pages source for the repository to that branch? But we can only have one source for GitHub Pages.
Alternatively, we can use a third-party service that provides previews and integrates with GitHub. For example, Read the Docs (for Sphinx) or for MkDocs, we can use the
mkdocs-materialwith a GitHub Action that deploys to a storage bucket and then we use a CDN to serve the previews.Given the complexity, maybe we should consider:
Option 1: Use Netlify or Vercel. They both can automatically create a preview URL for each PR and deploy the static site. Then we just need to set up the build command and output directory.
Option 2: Use GitHub Pages but with a custom setup:
We can have two GitHub Pages sites? One for production (from main branch) and one for previews (from a branch that is updated for each PR). But then we need to manage two separate repositories? Or we can use the same repository but two different branches and then set up two separate GitHub Pages sites? That is not possible because one repository can only have one GitHub Pages site.
So, if we want to use GitHub Pages for both, we might have to:
- Deploy production to the
gh-pagesbranch (which is the default for GitHub Pages). - For PRs, we deploy to a branch named
preview-<pr-number>and then we have a separate repository that uses that branch as the source for GitHub Pages? That's too many repos.
Alternatively, we can use the same
gh-pagesbranch and store each PR preview in a subdirectory (likepreview/123for PR #123). Then we can have a single GitHub Pages site and the preview would be athttps://<username>.github.io/<repository>/preview/123/. But then we need to clean up old previews.We can do:
- On PR, build and then push the built site to the
gh-pagesbranch in a directory namedpreview/<pr-number>. - Then we can comment on the PR with the preview URL:
https://<username>.github.io/<repository>/preview/<pr-number>/ - When the PR is closed (merged or not), we can delete that directory.
But note: if multiple PRs are open, we might have conflicts in the
gh-pagesbranch because each PR push will try to update the same branch. We can avoid this by having a dedicated branch for previews? But then we can't use GitHub Pages to serve that branch because we are using thegh-pagesbranch for production.Wait, we can set up GitHub Pages to use any branch and any folder. So we can have:
- Production: served from
gh-pagesbranch at the root. - Previews: served from a branch named
previewsat the root? But then we would have to change the GitHub Pages source to that branch for previews? We can't change the source on the fly.
So, maybe we should use a different hosting for previews? Like an AWS S3 bucket that we can write to arbitrarily.
Given the complexity, let's go with a third-party service that provides PR previews for static sites, like Vercel or Netlify. They have free tiers and are easy to set up.
Steps for Vercel:
- Import the GitHub repository to Vercel.
- Set the build command to
mkdocs buildand output directory tosite. - Vercel will automatically create a preview deployment for each PR and a production deployment for the main branch.
Then we don't need to handle the preview deployment in our GitHub Actions? But we still want to run the link checks and other CI steps.
We can have:
- GitHub Actions for building and testing (including link checks) on every PR and push to main.
- Vercel for preview and production deployments, but only if the CI passes? We can set up Vercel to require that the GitHub Actions pass? Actually, Vercel will build and deploy on every PR and push, but we can set up Vercel to ignore builds if the commit status from GitHub Actions is failing? Not directly.
Alternatively, we can have:
- GitHub Actions run on every PR and push to main, and if the build and link checks pass, then we trigger a Vercel deployment? But Vercel already does that automatically.
Actually, we can set up Vercel to use the GitHub repository and then it will automatically build and deploy on every push. But we want to run our own CI (with link checks) and then if that passes, then we want to deploy. But if we use Vercel's automatic deployments, then we are building twice? We can disable Vercel's build and use our own? But then we need to deploy to Vercel via API.
Let's simplify:
We can have:
- GitHub Actions runs on every PR and push to main, and does:
- Build the site.
- Run link checks.
- If it's a PR, then we don't deploy? We just run the checks and then rely on Vercel to provide the preview? But Vercel will build and deploy on its own.
Alternatively, we can let Vercel handle the build and deploy for previews and production, and then in our GitHub Actions we just run the link checks and other tests, and if they fail, we set the commit status to failing. Then we can set up Vercel to not deploy if the commit status is failing? Vercel has an option to "Ignore build step" but that's for skipping the build, not for failing the deployment.
Actually, Vercel will deploy regardless of the GitHub commit status. So we need to make sure that the Vercel build fails if our tests fail? But then the preview would be broken.
Another idea: we can have our GitHub Actions run the build and tests, and then if they pass, we trigger the Vercel deployment via the Vercel API? But then we are building twice.
Given the complexity, I think the simplest is to let Vercel (or Netlify) handle the build and deploy for previews and production, and then we run our link checks as part of the Vercel build process? We can set up the Vercel build command to be a script that runs the tests and then builds, and if the tests fail, the build fails and Vercel won't deploy.
But then we are not running the tests on every PR in GitHub Actions? We can set up GitHub Actions to run the tests in parallel to Vercel? That would be two builds.
Let me re-think:
We want:
- Fast feedback on PRs: run tests (build and link checks) and then have a preview if tests pass.
- We don't want to deploy if tests fail.
So:
Option A: - GitHub Actions: run on every PR and push to main, run build and tests (including link checks). If they pass, set a commit status to success. - Vercel: set up to automatically deploy on every PR and push to main, but we can set up Vercel to only deploy if the commit status from GitHub Actions is successful? Vercel doesn't have that feature.
Option B: - We disable Vercel's automatic deployments and use the Vercel API to deploy only when we want (i.e., when our GitHub Actions pass). But then we are building in GitHub Actions and then deploying the built site to Vercel? That would require us to upload the built site to Vercel.
Option C: - We let Vercel build and deploy, but we add a step in the Vercel build process (via
vercel-buildscript inpackage.jsonor in the Vercel project settings) that runs our tests and then builds. If tests fail, the build fails and Vercel won't deploy.This seems the most straightforward. We can have:
In the repository, we have a
package.json(even if we don't use Node) to define a script:{ "scripts": { "vercel-build": "mkdocs build && markdown-link-check --config .markdown-link-check.json '**/*.md'" } }But note: Vercel by default will run
npm run buildif it finds apackage.json. So we can set the build command in Vercel tonpm run vercel-build? Actually, Vercel will runnpm run buildby default. So we can set our tests and build in thebuildscript.However, we want the build to fail if the link checks fail. So we can do:
"scripts": { "build": "mkdocs build && markdown-link-check --config .markdown-link-check.json '**/*.md'" }Then Vercel will run
npm run buildand if either the build or the link check fails, the Vercel build fails and it won't deploy.But note: the link check might fail for external links that are down, which we might not want to block the deployment. We can adjust the link check to ignore certain links or have a tolerance.
Alternatively, we can run the link check as a separate step in GitHub Actions and then have Vercel only deploy if the GitHub Actions pass? But again, Vercel doesn't check the GitHub status.
Given the time, let's go with:
- Use Vercel for hosting and previews.
- Set up Vercel to build the site and run the link check as part of the build. If the build (including link check) fails, Vercel won't deploy.
- Also set up GitHub Actions to run the same build and link check on every PR and push to main, so we have the status in GitHub.
But then we are building twice? We can choose one. Since Vercel will build on every PR and push, we can rely on Vercel for the build and then in GitHub Actions we just run the same tests? That's duplicate.
Alternatively, we can have GitHub Actions run the tests and then if they pass, we let Vercel deploy? But Vercel will build again.
We can have:
GitHub Actions: on: [pull_request, push] jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Set up Python uses: actions/setup-python@v4 with: python-version: '3.x' - name: Install dependencies run: | pip install mkdocs pip install markdown-link-check - name: Build run: mkdocs build --strict - name: Link check run: markdown-link-check --config .markdown-link-check.json '**/*.md'
Then we set up Vercel to automatically deploy on every PR and push, but we don't run the tests in Vercel? Then we have a situation where the Vercel preview might be deployed even if the tests fail in GitHub Actions? That's not good.
So we need to prevent Vercel from deploying if the GitHub Actions tests fail.
We can set up Vercel to use the GitHub Checks API? Vercel doesn't support that natively.
Another idea: use the Vercel GitHub App and set up branch protection that requires the Vercel deployment to be successful? But Vercel doesn't set a commit status.
Given the complexity, I think we should:
- Use GitHub Actions to run the tests and build, and then if they pass, we deploy to Vercel using the Vercel API.
Steps:
- GitHub Actions runs on PR and main push.
- On PR, we run the tests and build. If they pass, we don't deploy (preview will be handled by Vercel automatically? but we disabled automatic deployments).
- On push to main, if tests pass, we deploy to Vercel production.
But then what about PR previews? We want previews for PRs. So we need to deploy on PRs too.
So:
- We set up Vercel to not automatically deploy (disable automatic deployments in Vercel).
- We use GitHub Actions to build and then deploy to Vercel for every PR and for main.
How to deploy to Vercel from GitHub Actions?
We can use the Vercel CLI and the Vercel token.
Steps:
- In the GitHub repository, set secrets: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID.
- In the GitHub Actions workflow, after building and testing, we use the Vercel CLI to deploy.
But note: Vercel will create a new deployment for each PR and for main.
We can use the
amondnet/vercel-actionGitHub Action.Example workflow:
name: Deploy to Vercel
on: pull_request: branches: [ main ] push: branches: [ main ]
jobs: build-and-deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Python uses: actions/setup-python@v4 with: python-version: '3.x' - name: Install dependencies run: | pip install mkdocs pip install markdown-link-check - name: Build run: mkdocs build --strict - name: Link check run: markdown-link-check --config .markdown-link-check.json '**/*.md' - name: Deploy to Vercel uses: amondnet/vercel-action@v20 with: vercel-token: {{ secrets.VERCEL_ORG_ID }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} # For PRs, Vercel will create a preview deployment. # For main, it will create a production deployment. # The action automatically determines the environment based on the branch.
But note: the Vercel action will also build the project? We already built it. We can set the
vercel-build-commandtonpm run build? But we are using Python. We can set the build command tomkdocs buildand then we are building twice? We can skip the build in the Vercel action by settingvercel-build-commandto something that doesn't build? Or we can set the Vercel project to use our build command? Actually, the Vercel action will run the build command configured in the Vercel project.We can set the Vercel project's build command to
mkdocs buildand then we don't need to run the build in our GitHub Actions? But then we are not running the link check in the Vercel build? We can set the build command to run both:mkdocs build && markdown-link-check --config .markdown-link-check.json '**/*.md'But then if the link check fails, the build fails and Vercel won't deploy.
Alternatively, we can run the build and tests in GitHub Actions and then if they pass, we let Vercel deploy without building? But Vercel will build by default.
We can set the Vercel project to have no build command? Then we can build in GitHub Actions and then deploy the built site? But Vercel expects to build.
Actually, the Vercel action has an option
working-directoryandoutput-directoryto specify the built files. We can build in GitHub Actions and then tell Vercel to deploy the built files without building again.But note: Vercel is designed to build from source. If we pre-build, we can set the project to use a static output? We can set the output directory to
site(which is the default for MkDocs). And then in the Vercel project, set the build command toecho " Skipping build"or something? But then we are not running the link check in Vercel.Given the complexity, let's simplify:
We'll run the build and tests in GitHub Actions, and then if they pass, we deploy to Vercel using the Vercel action, but we set the Vercel project to not build (by setting the build command to
echo "Skipping build"). Then we set theoutput-directoryin the Vercel action tosite(the built directory).Steps:
- In Vercel project settings, set the build command to
echo "Skipping build"and the output directory tosite. - In GitHub Actions, we build the site to
siteand run the link check. - Then we use the Vercel action to deploy the
sitedirectory.
But note: the Vercel action expects to build by default. We can set
vercel-build-commandtoecho "Skipping build"in the action? Actually, the action uses the project settings by default.Alternatively, we can set the Vercel project to have a build command of
mkdocs buildand then we don't build in GitHub Actions? But then we are not running the link check in the same step? We can set the Vercel build command to:mkdocs build && markdown-link-check --config .markdown-link-check.json '**/*.md'Then if the link check fails, the Vercel build fails and it won't deploy.
But then we are not running the tests in GitHub Actions? We want the status in GitHub.
We can do:
GitHub Actions runs the tests and build. Then we deploy to Vercel, which runs the same build and tests again? That's duplicate.Given the time, I think the best is:
Let Vercel handle the build and tests (by setting the build command to run both). Then in GitHub Actions, we just run the same build and tests to set the commit status? But then we are building twice.Alternatively, we can have:
GitHub Actions runs the tests and build. Then if they pass, we set a commit status to success. Then we use the Vercel action to deploy, but we tell Vercel not to build (by setting the build command to `echo "Skipping build"`). Then we deploy the pre-built site.This way, we only build once (in GitHub Actions) and we get the commit status.
Steps:
In Vercel project settings: Build command:
echo "Skipping build"Output directory:siteIn GitHub Actions:
- Build the site to `site` - Run link check (if fails, the job fails) - Then deploy the `site` directory to Vercel.But note: the link check might require the built site? Actually, the link check should run on the source markdown. We are currently running it on the source. But if we set the build command in Vercel to skip, we don't run the link check in Vercel.
So we run the link check in GitHub Actions, and if it fails, we don't deploy.
This seems good.
However, note: the link check might break due to the way the built site has different URLs? We are checking the markdown files, which have relative links. That should be okay.
Let's write the GitHub Actions workflow:
We'll have:
name: Build and Deploy on: pull_request: branches: [ main ] push: branches: [ main ] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 - name: Setup Python uses: actions/setup-python@v4 with: python-version: '3.x' - name: Install dependencies run: | pip install mkdocs pip install markdown-link-check - name: Build run: mkdocs build --strict - name: Link check run: markdown-link-check --config .markdown-link-check.json '**/*.md' - name: Deploy to Vercel uses: amondnet/vercel-action@v20 with: vercel-token: ${{ secrets.VERCEL_TOKEN }} vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} # We are deploying the pre-built `site` directory. # The Vercel project is set to not build and to use the `site` directory as output. # So we don't need to set the build command here.But note: the Vercel action by default will run the build command set in the Vercel project. We set that to
echo "Skipping build", so it won't build again.However, we are building in the GitHub Actions and then the Vercel action will upload the
sitedirectory? Actually, the Vercel action will run the build command (which we set to skip) and then upload the output directory (which we set tosite). But we built the site in the GitHub Actions runner, so thesitedirectory exists. Then the Vercel action will runecho "Skipping build"and then upload thesitedirectory.But wait: the Vercel action might run in a different working directory? We are building in the root of the repository, and the
sitedirectory is at the root. The Vercel action by default uses the current directory. So it should work.However, note: the Vercel action might run in a subdirectory? We can set
working-directoryif needed.But there's a catch: the Vercel action might clean the directory? We are building and then the Vercel action runs in the same directory, so the
sitedirectory is there.This should work.
But what about the link check configuration? We have a
.markdown-link-check.jsonfile. We need to include that in the repository.Example
.markdown-link-check.json:{ "ignorePatterns": [ { "pattern": "^https://example\\.com/.*" } ], "timeout": "10s", "retryCount": 3 }We can adjust as needed.
- For PRs, we can deploy to a unique URL (like
-
Review gates:
In GitHub, we set up branch protection for the main branch: - Require pull request reviews (at least one). - Require status checks to pass (the GitHub Actions workflow).
-
Links:
We are already checking links with
markdown-link-check. We can also use other tools likelycheeif we prefer.We might also want to check for broken internal links (to other pages in the site). The
mkdocs buildmight fail if there are broken internal links? By default, MkDocs doesn't fail on broken internal links, but we can use the--strictflag to fail on warnings.Alternatively, we can use the
mkdocs-excludeplugin or other plugins to help.But note: the
--strictflag in MkDocs will fail on warnings, which includes broken internal links (if usingnavthat points to non-existing files). So that should catch internal broken links. -
Summary:
-
Repository with MkDocs and markdown files.
-
GitHub Actions workflow that: a. Checks out code. b. Sets up Python and installs MkDocs and markdown-link-check. c. Builds the site with
mkdocs build --strict(fails on warnings). d. Runsmarkdown-link-checkon all markdown files. e. If both steps pass, deploys to Vercel (which is set up to skip building and just deploy the pre-builtsitedirectory). -
Vercel project:
- Build command:
echo "Skipping build" - Output directory:
site - Set up the repository and connect it.
- Build command:
-
In GitHub, set up branch protection on main to require:
- At least one review.
- The GitHub Actions workflow to pass.
This gives us: - Previews: Vercel creates a preview for every PR and for main (production). - Review gates: PRs require review and passing CI. - Links: checked in the CI.
However, note: the link check runs on the source markdown, so it might not catch broken links that are only in the built HTML? Actually, the markdown-link-check checks the links in the markdown, which are the same as in the built HTML (for relative links). For absolute links, it will check the target. So it should be fine.
But what about internal anchors? The link check might not handle them well. We can configure the link checker to ignore fragments? Or we can use a different tool.
Alternatively, we can use
lycheewhich can check links in the built HTML? We can runlycheeon the built HTML files.We can adjust:
- Build the site. - Run `lychee` on the `site` directory (the built HTML) to check all links (including internal ones).But note:
lycheemight be slower.We can stick with
markdown-link-checkfor now and adjust the configuration to ignore fragments if needed.Example configuration to ignore fragments:
{ "ignorePatterns": [ { "pattern": ".*#.*" } ] }But that would ignore all links with fragments, which might be too broad.
Alternatively, we can use
markdown-link-checkwith the--ignorePatternflag? The configuration file supportsignorePatterns.We can also use the
--no-ansiflag to avoid output issues.Given the complexity of link checking, we might want to use a combination of tools.
But for simplicity, we'll use
markdown-link-checkon the markdown files and rely onmkdocs build --strictfor internal link checks (for the navigation structure).Let's adjust the workflow to run
markdown-link-checkon the markdown files and thenmkdocs build --strict(which will check the internal links in the navigation). Actually,mkdocs build --strictwill fail on warnings, which includes unresolved references in the navigation. So that should catch internal broken links.So we are covered.
Let's write the workflow file:
File:
.github/workflows/build-and-deploy.ymlWe'll also add a step to set up the Vercel project? We already have the secrets.
But note: the Vercel action requires the project to be already set up in Vercel. We have to create the project in Vercel and link it to the GitHub repository.
Steps:
- Create a Vercel account and import the GitHub repository.
- In Vercel project settings, set:
- Build command:
echo "Skipping build" - Output directory:
site
- Build command:
- Get the VERCEL_ORG_ID and VERCEL_PROJECT_ID from the Vercel project settings (in the project, go to Settings -> General -> Project ID and Organization ID).
- Generate a Vercel token (from Vercel account settings -> Tokens).
- Add the following secrets in the GitHub repository (Settings -> Secrets and variables -> Actions):
- VERCEL_TOKEN
- VERCEL_ORG_ID
- VERCEL_PROJECT_ID
Then the workflow should work.
Let's write the workflow:
Note: We are building and then deploying. We want to deploy only if the build and link check pass.
We'll also add a step to show the preview URL in the PR? The Vercel action will output the URL. We can capture it and then comment on the PR? But the Vercel action doesn't output the URL in a way that we can capture easily? Actually, the Vercel action outputs the deployment URL. We can set an output and then use a separate step to comment.
But the Vercel action already comments on the PR? Actually, the Vercel GitHub App does that automatically if we have it installed? The Vercel action does not comment by default.
We can use the
actions/github-scriptto comment on the PR with the preview URL.But note: the Vercel action will output the deployment URL as an output. We can capture it and then comment.
However, for PRs, we want the preview URL. For main, we don't need to comment.
We can do:
- name: Deploy to Vercel id: vercel uses: amondnet/vercel-action@v20 with: vercel-token: ${{ secrets.VERCEL_TOKEN }} vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} - name: Comment on PR if: github.event_name == 'pull_request' uses: actions/github-script@v6 with: script: | const url = '${{ steps.vercel.outputs.preview-url }}' github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: `Preview deployment: ${url}` })But note: the Vercel action outputs
preview-urlfor preview deployments andproduction-urlfor production. We can check which one we got? Actually, the action sets:outputs: preview-url: ${{ steps.vercel.outputs.preview-url }} production-url: ${{ steps.vercel.outputs.production-url }}And we are only interested in the preview-url for PRs.
However, the Vercel action might set both? Let's check the documentation.
Actually, the action sets:
- For preview deployments (on PRs and non-main branches): `preview-url` - For production deployments (on main): `production-url`So we can use:
if: github.event_name == 'pull_request' then use steps.vercel.outputs.preview-urlBut note: the action might set both? We can use:
url: ${{ steps.vercel.outputs.preview-url || steps.vercel.outputs.production-url }}But for PRs, we want the preview-url, and for main, we don't comment.
Alternatively, we can conditionally set the URL:
- name: Set URL run: | if [ "${{ github.event_name }}" = "pull_request" ]; then echo "url=${{ steps.vercel.outputs.preview-url }}" >> $GITHUB_OUTPUT fi id: set-url Then use ${{ steps.set-url.outputs.url }} in the comment.But the Vercel action might not set
preview-urlfor production deployments? So for PRs, we expectpreview-urlto be set.Let's adjust:
- name: Deploy to Vercel id: vercel uses: amondnet/vercel-action@v20 with: vercel-token: ${{ secrets.VERCEL_TOKEN }} vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} - name: Comment on PR if: github.event_name == 'pull_request' && steps.vercel.outputs.preview-url != '' uses: actions/github-script@v6 with: script: | const url = '${{ steps.vercel.outputs.preview-url }}' github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: `Preview deployment: ${url}` })But note: the Vercel action might take a while to deploy. We want to comment only after deployment is done. The
amondnet/vercel-actionwaits until the deployment is finished? Yes, by default it waits.However, if the deployment fails, we don't want to comment? The step would fail and the workflow would stop, so we wouldn't comment.
This should work.
Let's put it all together.
However, note: the Vercel action might fail if the build command (which we set to
echo "Skipping build") returns non-zero? We set it toechowhich returns 0.But wait: we are building in the GitHub Actions, so the
sitedirectory exists. Then the Vercel action runsecho "Skipping build"and then uploads thesitedirectory.But what if the Vercel action expects the build to have been run by the build command? It doesn't, because we set the output directory to
siteand we are uploading that directory.However, the Vercel action might run the build command and then expect the output in the output directory. If we skip the build, then the output directory might not have been created? Actually, we built it in a previous step, so the
sitedirectory exists.This should be okay.
But note: the Vercel action might clean the working directory? I don't think so.
Alternatively, we can use the Vercel action without a build command? Actually, the Vercel project must have a build command set. We set it to
echo "Skipping build"so it does nothing.Let's write the full workflow:
We'll also add a step to cache the Python dependencies to speed up.
Final workflow:
.github/workflows/build-and-deploy.yml:
name: Build and Deploy on: pull_request: branches: [ main ] push: branches: [ main ] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 - name: Setup Python uses: actions/setup-python@v4 with: python-version: '3.x' - name: Cache pip uses: actions/cache@v3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', '**/setup.py', '**/pyproject.toml') }} restore-keys: | ${{ runner.os }}-pip- - name: Install dependencies run: | pip install mkdocs pip install markdown-link-check - name: Build run: mkdocs build --strict - name: Link check run: markdown-link-check --config .markdown-link-check.json '**/*.md' - name: Deploy to Vercel id: vercel uses: amondnet/vercel-action@v20 with: vercel-token: ${{ secrets.VERCEL_TOKEN }} vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} - name: Comment on PR if: github.event_name == 'pull_request' && steps.vercel.outputs.preview-url != '' uses: actions/github-script@v6 with: script: | const url = '${{ steps.vercel.outputs.preview-url }}' github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: `Preview deployment: ${url}` })But note: the
markdown-link-checkmight fail for links that are in thesitedirectory (the built HTML) but not in the markdown? We are checking the markdown, so that's okay.However, what about links that are generated by plugins? They might not be in the markdown. Then we would miss them.
We can also run
markdown-link-checkon the built HTML? But then we would have to adjust the configuration to handle HTML.Alternatively, we can use
lycheewhich can check HTML files.We can change the link check step to:
- name: Link check run: | # Check markdown files markdown-link-check --config .markdown-link-check.json '**/*.md' # Check built HTML files lychee --config .lychee.toml 'site/**/*.html'But then we need a
lychee.tomlconfiguration.Given the complexity, let's stick to checking the markdown files and rely on
mkdocs build --strictfor internal links.But note:
mkdocs build --strictwill fail on warnings, which includes broken internal links (if the navigation points to a non-existing file). However, it might not catch broken links in the content (like[link](nonexistent.md)). Actually, MkDocs will generate a warning for that and with--strictit will fail.So we are covered for internal links.
For external links, we are checking with
markdown-link-check.This should be acceptable.
Let's adjust the workflow to also check the built HTML with
lychee? We can do:- name: Install lychee run: cargo install lycheeBut that requires Rust, which might be heavy.
Alternatively, we can use a packaged
lychee? There isn't a pre-built one for Ubuntu in the same way.Given the time, we'll stick to
markdown-link-checkon markdown andmkdocs build --strictfor internal.We can adjust the
markdown-link-checkconfiguration to ignore external links that are known to be down? We can set a timeout and retry count.Example
.markdown-link-check.json:{ "timeout": "10s", "retryCount": 3, "ignorePatterns": [ { "pattern": ".*#.*" } ] }This will ignore links with fragments (like
#section). We might want to allow fragments? Actually,markdown-link-checkby default will try to check the fragment? It will check the URL without the fragment and then the fragment is ignored? Actually, it will fail if the URL without the fragment is down? But if the page exists but the fragment doesn't, it will still pass? Not sure.We can leave the configuration as is and adjust if needed.
This is a reasonable setup.
Let's summarize the steps for the user:
- Set up a repository with MkDocs documentation.
- Create a
.markdown-link-check.jsonfile for link checking configuration. - Set up Vercel project:
- Import the GitHub repository.
- Set build command to
echo "Skipping build"and output directory tosite. - Get the project ID and org ID from Vercel project settings.
- Generate a Vercel token.
- In the GitHub repository, set the secrets: VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID.
- Create the GitHub Actions workflow file at
.github/workflows/build-and-deploy.ymlwith the content above. - Set up branch protection on the main branch to require:
- At least one review.
- The GitHub Actions workflow to pass.
Then:
- On every PR, the workflow will build, run link checks, and if they pass, deploy to Vercel (preview deployment) and comment on the PR with the preview URL.
- On push to main, the workflow will build, run link checks, and if they pass, deploy to Vercel (production).
This gives us: - Previews for PRs. - Review gates (PR review and CI). - Link checking.
Note: The preview URL for PRs will be something like
https://<project-name>.vercel.app/pull/<pr-number>? Actually, Vercel creates a unique URL for each deployment. We are using the Vercel action which will output the preview URL.We are done.
However, note: the Vercel action might not set the
preview-urloutput for production deployments? We are only using it for PRs.Let me check the Vercel action documentation: https://github.com/amondnet/vercel-action
It says:
outputs: preview-url: The URL of the preview deployment production-url: The URL of the production deploymentSo for PRs, we get
preview-url, for main we getproduction-url.We are using
preview-urlonly for PRs.This should work.
Let me adjust the workflow to also set the commit status? The GitHub Actions will set the status automatically (if the job fails, the check fails). So we don't need extra steps.
We are good.
One more thing: the Vercel action might require the Vercel CLI to be installed? It uses the Vercel CLI under the hood? It uses the Vercel API? Actually, the action uses the Vercel CLI? The action's Docker image includes the Vercel CLI.
So we don't need to install it.
We are set.
Let me write the final workflow with a few adjustments:
- We'll use the
actions/cachefor pip to speed up. - We'll use the
--strictflag for mkdocs build to fail on warnings.
But note: the
--strictflag might be too strict? We can start without it and then adjust.We'll keep it.
Final workflow:
.github/workflows/build-and-deploy.yml:
name: Build and Deploy on: pull_request: branches: [ main ] push: branches: [ main ] jobs: build-and-deploy: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v3 - name: Setup Python uses: actions/setup-python@v4 with: python-version: '3.x' - name: Cache pip uses: actions/cache@v3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', '**/setup.py', '**/pyproject.toml') }} restore-keys: | ${{ runner.os }}-pip- - name: Install dependencies run: | pip install mkdocs pip install markdown-link-check - name: Build run: mkdocs build --strict - name: Link check run: markdown-link-check --config .markdown-link-check.json '**/*.md' - name: Deploy to Vercel id: vercel uses: amondnet/vercel-action@v20 with: vercel-token: ${{ secrets.VERCEL_TOKEN }} vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} - name: Comment on PR if: github.event_name == 'pull_request' && steps.vercel.outputs.preview-url != '' uses: actions/github-script@v6 with: script: | const url = '${{ steps.vercel.outputs.preview-url }}' github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: `Preview deployment: ${url}` })This should work.
However, note: the Vercel action might fail if the project is not set up correctly. We have set the Vercel project to skip building, so it should just upload the
sitedirectory.But wait: the Vercel action by default will run the build command set in the Vercel project. We set that to
echo "Skipping build". Then it will upload the output directory (which we set tosite). But note: the output directory is relative to the project root. Oursitedirectory is at the root, so that's fine.We are done.
Let me know if you have any questions. I'll help you create a comprehensive docs-as-code pipeline with all the features you requested. Here's a complete implementation using modern tools:
-
Architecture Overview
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Git Repository│────▶│ CI/CD Pipeline │────▶│ Preview Service│ │ (Docs Source) │ │ (GitHub Actions)│ │ (Vercel/Netlify)│ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ │ │ ▼ ▼ ▼ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ Review Gates │◀───│ Link Validation │────│ Production Site│ │ (PR/MR Checks) │ │ & Quality Gates │ │ (GitHub Pages)│ └─────────────────┘ └──────────────────┘ └─────────────────┘Implementation
1. Repository Structure
docs-repo/ ├── docs/ │ ├── index.md # Homepage │ ├── getting-started/ │ │ ├── installation.md │ │ └── quickstart.md │ ├── api/ │ │ ├── overview.md │ │ └── endpoints.md │ ├── guides/ │ └── images/ # Static assets ├── mkdocs.yml # MkDocs configuration ├── .github/ │ ├── workflows/ │ │ ├── preview.yml # PR preview deployments │ │ ├── link-check.yml # Link validation │ │ └── deploy.yml # Production deployment ├── .markdown-link-check.json ├── requirements.txt # Python dependencies └── README.md2. Core Configuration Files
mkdocs.yml- Main documentation configuration:site_name: My Documentation site_description: Comprehensive API documentation theme: name: material features: - navigation.tabs - navigation.sections - toc.integrate - search.suggest - search.highlight plugins: - search - awesome-pages - macros: # Define variables for reuse api_version: v1.2.0 base_url: https://api.example.com nav: - Home: index.md - Getting Started: - Installation: getting-started/installation.md - Quickstart: getting-started/quickstart.md - API Reference: - Overview: api/overview.md - Endpoints: api/endpoints.md - Guides: guides/.markdown-link-check.json- Link validation config:{ "ignorePatterns": [ { "pattern": "^https://localhost.*" }, { "pattern": "^http://127.0.0.1.*" } ], "timeout": "10s", "retryCount": 3, "thresholdPer_link": 3, "fallbackHttpStatus": [403, 404] }3. GitHub Actions Workflows
preview.yml- PR preview deployments:name: Deploy Preview on: pull_request: branches: [main] paths: - 'docs/**' - 'mkdocs.yml' - '.github/workflows/preview.yml' jobs: deploy-preview: runs-on: ubuntu-latest permissions: contents: read pull-requests: write id-token: write steps: - name: Checkout uses: actions/checkout@v4 with: fetch-depth: 0 - name: Setup Python uses: actions/setup-python@v4 with: python-version: '3.11' - name: Install dependencies run: | pip install mkdocs-material pip install mkdocs-macros-plugin pip install markdown-link-check - name: Build docs run: mkdocs build --strict - name: Link Check run: | markdown-link-check --config .markdown-link-check.json "docs/**/*.md" - name: Deploy to Vercel (Preview) uses: amondnet/vercel-action@v20 with: vercel-token: ${{ secrets.VERCEL_TOKEN }} vercel-org-id: ${{ secrets.VERCEL_ORG_ID }} vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }} working-directory: ./site vercel-args: '--prebuilt' - name: Comment preview URL if: always() uses: actions/github-script@v7 with: script: | const previewUrl = process.env.VERCEL_PREVIEW_URL if (previewUrl) { github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: `🚀 Preview deployed at ${previewUrl}` }) }link-check.yml- Dedicated link validation:name: Link Check on: schedule: - cron: '0 0 * * *' # Daily at midnight push: branches: [main] paths: - 'docs/**' - '.markdown-link-check.json' jobs: check-links: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v4 with: python-version: '3.11' - name: Install dependencies run: pip install markdown-link-check - name: Check links run: | markdown-link-check \ --config .markdown-link-check.json \ --quiet \ "docs/**/*.md" || { echo "❌ Broken links found!" exit 1 } - name: Check for circular references run: | # Custom script to check for circular refs in nav python scripts/check_circular_refs.py docs/deploy.yml- Production deployment:name: Deploy to Production on: push: branches: [main] paths: - 'docs/**' - 'mkdocs.yml' jobs: deploy: runs-on: ubuntu-latest permissions: contents: read pages: write id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} steps: - name: Checkout uses: actions/checkout@v4 - name: Setup Python uses: actions/setup-python@v4 with: python-version: '3.11' - name: Install dependencies run: | pip install mkdocs-material pip install mkdocs-macros-plugin - name: Build run: mkdocs build --strict --dirty - name: Setup Pages uses: actions/configure-pages@v3 - name: Upload artifact uses: actions/upload-pages-artifact@v2 with: path: './site' - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v24. Review Gates Implementation
Branch Protection Rules (GitHub):
-
Require pull request reviews:
- At least 1 approving review
- Dismiss stale PR approvals when new commits are pushed
- Require review from code owners (if using CODEOWNERS)
-
Require status checks to pass:
Deploy Preview(from preview.yml)Link Check(from link-check.yml)Build(implicit from preview.yml)
-
Restrict pushes:
- No direct pushes to
main - Required linear history
- No direct pushes to
CODEOWNERS(optional):# Docs ownership /docs/ @docs-team @technical-writers5. Quality Gates Scripts
scripts/check_circular_refs.py- Prevent circular navigation:#!/usr/bin/env python3 """Check for circular references in MkDocs navigation.""" import sys import yaml from pathlib import Path def load_nav_structure(nav_file): """Load navigation structure from mkdocs.yml.""" with open(nav_file) as f: config = yaml.safe_load(f) return config.get('nav', []) def check_circular_refs(nav, path='', visited=None): """Recursively check for circular references.""" if visited is None: visited = set() current_path = path or 'root' if current_path in visited: print(f"❌ Circular reference detected at: {current_path}") return True visited.add(current_path) if isinstance(nav, list): for item in nav: if isinstance(item, dict): for key, value in item.items(): if isinstance(value, (list, dict)): if check_circular_refs(value, key, visited.copy()): return True elif isinstance(nav, dict): for key, value in nav.items(): if isinstance(value, (list, dict)): if check_circular_refs(value, key, visited.copy()): return True return False if __name__ == "__main__": mkdocs_yml = Path('mkdocs.yml') if not mkdocs_yml.exists(): print("❌ mkdocs.yml not found!") sys.exit(1) nav = load_nav_structure(mkdocs_yml) if check_circular_refs(nav): print("❌ Navigation contains circular references!") sys.exit(1) print("✅ No circular references found") sys.exit(0)6. Additional Utilities
scripts/generate_toc.py- Auto-generate table of contents:#!/usr/bin/env python3 """Generate table of contents for markdown files.""" import re from pathlib import Path def generate_toc(md_file): """Generate TOC from markdown headings.""" toc = ["## Table of Contents\n"] with open(md_file) as f: for line in f: match = re.match(r'^(#{1,6})\s+(.+)$', line) if match: level = len(match.group(1)) title = match.group(2) indent = ' ' * (level - 1) anchor = title.lower().replace(' ', '-').replace('.', '') toc.append(f"{indent}- [{title}](#{anchor})") return '\n'.join(toc) if __name__ == "__main__": for md_file in Path('docs').rglob('*.md'): print(f"Processing {md_file}...") # Insert TOC after first heading # Implementation depends on your preference7. Setup Instructions
# 1. Initialize the repository mkdir docs-repo && cd docs-repo git init # 2. Install dependencies pip install mkdocs-material mkdocs-macros-plugin markdown-link-check # 3. Create configuration files (from above) # 4. Set up GitHub Secrets: # VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID # (for preview deployments) # 5. Enable GitHub Pages in repo settings: # Source: GitHub Actions # 6. Push to GitHub and set up branch protection rules8. Advanced Features
mkdocs.ymlwith macros for dynamic content:plugins: - macros: module_name: docs/macros.py # Python file with custom macros # Example macro usage in markdown: {{ api_base_url() }}docs/macros.py:def api_base_url(): """Return API base URL based on environment.""" import os env = os.getenv('DOCS_ENV', 'production') if env == 'preview': return 'https://api-staging.example.com' return 'https://api.example.com'9. Monitoring & Alerts
Add to
link-check.ymlfor notifications:- name: Send Slack notification on failure if: failure() uses: slackapi/slack-github-action@v1 with: payload: | { "text": "❌ Link check failed for ${{ github.repository }}", "attachments": [ { "color": "danger", "fields": [ { "title": "PR/Commit", "value": "${{ github.event.pull_request.html_url || github.event.head_commit.url }}", "short": true }, { "title": "Author", "value": "${{ github.actor }}", "short": true } ] } ] } env: SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}10. Docker Support (Optional)
Dockerfile:FROM python:3.11-slim WORKDIR /docs COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8000 CMD ["mkdocs", "serve", "--dev-addr=0.0.0.0:8000"]Key Features Implemented:
✅ Previews: Vercel automatically creates preview URLs for every PR
✅ Review Gates:- Branch protection requiring PR approvals
- CI status checks before merge
- Link validation as required check
✅ Links:
- Automated link checking (external links)
- Internal navigation validation via
mkdocs build --strict - Circular reference detection
✅ Quality Gates:
- Build must succeed
- No broken links
- No circular nav references
- Strict markdown linting (via
--strict)
✅ Traceability:
- Preview URLs automatically commented on PRs
- Deployments tracked in GitHub Environments
- Full audit trail via Git history
Usage Workflow:
- Developer creates PR → Preview auto-deploys, comment with URL
- Reviewer checks preview → Verifies content/layout
- CI runs all checks → Fails if broken links or build errors
- PR approved and merged → Auto-deploys to production
- Daily link check → cron job validates all external links
This setup provides a robust docs-as-code pipeline with enterprise-grade quality gates, automated previews, and comprehensive link validation. You can adapt it to use Sphinx instead of MkDocs, or swap Vercel for Netlify/Cloudflare Pages as needed.
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.