Docs as code
Understand how the documentation ships: a public repository, an issue-first review flow, and automated checks on every pull request.
The documentation is a codebase. Each page is a file in a public repository, and a change reaches the site as a pull request. Automated checks run on the pull request before it merges.
The site ships in two languages: US English (EN) and Brazilian Portuguese (PT-BR). EN is the source, and PT-BR is its translation.
One repository, one review
The source lives at aziontech/docs on GitHub, open to external contributions. For significant changes, an issue comes before the pull request, so a maintainer can weigh in on the approach before the work starts. A new page, a page that moves or is deleted, a permalink change, and a navigation restructure are significant. A typo, a broken link, or a formatting fix can go straight to a pull request.
Two teams review the changes. Developer Relations reviews and approves the content, and UX Engineering reviews and approves the structure code. The issue templates route each request: report an error, request an addition, update content, or ask a question.
The checks on a pull request
The checks run in GitHub Actions on each pull request against main, in three workflows. The repository governance asks for all three to pass before a merge; the branch rules on main enforce Design system adoption, and reviewers hold the line on the other two.
CI gate groups four jobs. A first job reads the diff and runs only the jobs whose paths the change touches, so not every pull request runs every check. The Build job runs on every pull request.
| Job | What runs | What it catches |
|---|---|---|
| Security scans | A dependency audit, and TruffleHog over the diff | More high or critical vulnerabilities than the baseline, and verified secrets in the change |
| Content integrity | lint:navcheck, and a translation slug check |
A navigation row that points at an unknown page or tree, an EN page in no navigation row, and more PT-BR pages without an EN page of the same namespace than the baseline |
| Code quality | ESLint, Prettier, and Stylelint on the files the pull request changes, and astro check |
A lint or format error in a changed file, and more type errors than the baseline |
| Build | astro build, then test:frontmatter |
A page that does not compile, and a permalink that is missing, malformed, or duplicated, or a duplicated namespace |
Internal links builds the site and runs the link checker. The checker follows internal links only. It reports a link to a page or a fragment that does not exist, a link to a redirect page instead of the canonical URL, an absolute URL where a relative one belongs, and a link to a page in the other language. The vague-text check covers every link, internal or external: it reports link text such as “here” or “read more”.
Design system adoption runs the design system lint rules over the UI and the MDX content, and writes a report to the run summary.
Five checks are ratchets: the dependency audit, the translation slug check, astro check, the link checker, and the design system check. Each one compares a count with its baseline in ci/baselines.json and fails only when the count exceeds the baseline. A pull request that lowers a count updates the baseline with pnpm ci:ratchet <check> --update. Every other check fails on any error.
Run the checks locally before you open the pull request:
Redirects
A permalink that changes or disappears ships its redirect in the same pull request. Without the redirect, the old URL returns an error to every bookmark, search result, and external link that points at it.
Where redirects live
Redirects live in four JSON files, two per language:
apps/docs/redirects/en/00.jsonandapps/docs/redirects/en/01.jsonfor EN URLsapps/docs/redirects/pt-br/00.jsonandapps/docs/redirects/pt-br/01.jsonfor PT-BR URLs
Each file is an array of objects. Each object pairs a full source URL with a full destination URL:
Each object carries exactly one source field and exactly one destination field:
| Field | Meaning |
|---|---|
from |
The exact source URL |
from_regex |
A regular expression that matches source URLs |
moved |
The destination of a permanent redirect, HTTP 301 |
found |
The destination of a temporary redirect, HTTP 302 |
Add a redirect
- Add the pair to the file of the page’s language, in the same pull request that changes or removes the permalink. Add new pairs to the highest-numbered file of that language.
- Search the redirect files for the old URL as a destination. Point those entries at the new URL, so a reader never passes through a chain of redirects.
- Declare the change in the pull request, under URL changes and redirects in the pull request template: the old URL, the new URL, and the redirects added.
How a redirect goes live
Each redirect file is the argument list of one Massive Redirect function instance on the Azion application that serves the site. pnpm --filter docs redirects:publish validates the four files, checks each target instance, and writes the files that changed to their instances. The --dry-run flag reports what would change and writes nothing. Both modes read the live instances, so both need the AZION_TOKEN and AZION_APPLICATION_ID environment variables.
The production deploy workflow runs the publish step after each production deploy. A merge to main alone does not publish a redirect: the redirect goes live with the next production deploy.
When a file fills up
A function instance accepts at most 300 KB of arguments, and the publish step rejects a file over that size. When a file nears the limit, start the next numbered file, such as en/02.json. The files do not map to instances automatically, so a new file is a platform change in three parts:
- Create a Massive Redirect function instance on the Azion application.
- Load the file in
apps/docs/redirects/index.js. - Add the file as a target in
apps/docs/cicd/massive-redirects/update-function-instances.mjs, with the instance ID and name.
No pull request check validates the redirect files yet. The publish step is the first to read them, at the production deploy, so check the format and the file size by hand before you merge. A file that index.js does not load never publishes.
Metadata
Every page carries five frontmatter fields: title, description, meta_tags, namespace, and permalink. Two of them are contracts. The permalink is unique per language, and the namespace pairs the EN page with its PT-BR translation. The rules for each field are in Frontmatter.