Docs as code
Understand how the documentation ships: a public repository, an issue-first review flow, and automated checks on every change.
The documentation is a codebase. Every page is a file in a public repository, and every change is a pull request. Every pull request passes the same automated checks before it ships.
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. Minor fixes can go straight to a pull request.
Two teams own the reviews: Developer Education gatekeeps the content, and UX Engineering gatekeeps the structure code. The issue templates on the repository route each request: report an error, request an addition, update content, or ask a question.
The checks every change passes
The build gates a change four ways:
| Check | What it catches |
|---|---|
| Site build | A page that does not compile: a broken component, malformed MDX, an invalid import |
| Frontmatter validator | A missing, malformed, or duplicated namespace or permalink |
| Sidebar check | A menu entry pointing at a permalink that does not exist, and a page unreachable from any menu |
| Link checker | An internal link whose target page does not exist |
A change that fails any of them does not merge.
Redirects
A permalink that changes or disappears ships its redirect in the same change. Redirect pairs are declared in the repository and applied by the platform layer that serves the site.
Metadata
Every page carries the same five frontmatter fields, and two of them are contracts. The permalink is unique per language, and the namespace pairs the page with its translation. The full contract is in File conventions.