Prompt
How do I build a docs workflow where code changes update the portal automatically?
Latest observation
A good docs workflow for “code changes automatically update the portal” usually has 4 parts:
- Docs live with the code
- A build step turns docs into a portal
- CI/CD publishes the portal on every merge
- A preview flow lets reviewers see docs before merging
Here’s a practical setup.
1) Keep docs in the same repo as the code
Typical patterns:
docs/for narrative docsapi/oropenapi/for generated API specsREADME.mdper package/moduledocs-site/if you need portal config and theme files
Example repo layout:
repo/
apps/
packages/
docs/
getting-started.md
architecture.md
openapi/
public.yaml
website/
docusaurus.config.js
This makes it easy to update docs in the same PR as code.
2) Decide what “automatic update” means
There are usually 3 levels:
A. Static docs portal
Docs are built from Markdown and published as a static site.
- Best for: guides, tutorials, reference docs
- Tools: Docusaurus, MkDocs, GitBook, Hugo, Nextra
B. Generated API docs
Docs are generated from source or schemas.
- Best for: endpoint docs, SDK reference
- Tools: OpenAPI/Swagger, Redoc, TypeDoc, JSDoc, Sphinx, Rustdoc, etc.
C. Mixed portal
A portal combines both hand-written docs and generated docs.
- Best for: most teams
- Common approach: Markdown + generated API reference in one site
3) Set up a build pipeline
Your pipeline should do these steps:
- Install dependencies
- Run tests/lint on docs if needed
- Generate docs from code/specs
- Build the portal
- Publish to hosting
Example CI flow:
push/PR -> build docs -> run checks -> deploy preview
main merge -> build docs -> deploy production portal
4) Use CI to rebuild on every change
GitHub Actions example
name: Build and Deploy Docs
on:
push:
branches: [main]
pull_request:
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
- name: Install deps
run: npm ci
- name: Generate API docs
run: npm run docs:generate
- name: Build site
run: npm run docs:build
- name: Deploy
if: github.ref == 'refs/heads/main'
run: npm run docs:deploy
If you want previews for pull requests, deploy to a preview environment instead of production.
5) Generate docs from code when possible
This keeps docs from drifting.
Examples:
- OpenAPI from backend code or schema files
- TypeScript API docs from TypeDoc
- Java/Kotlin docs from Javadoc/KDoc
- Python docs from docstrings with Sphinx
- Terraform docs from module metadata
Common pattern:
- source code or schema changes
- generator creates docs files
- portal build includes generated files
- deployment updates portal automatically
Example command:
npm run generate:openapi
npm run build:docs
6) Publish to a static host
Popular options:
- GitHub Pages
- Netlify
- Vercel
- Cloudflare Pages
- S3 + CloudFront
- Azure Static Web Apps
For a simple team portal, GitHub Pages or Netlify is often enough.
7) Add preview deployments for PRs
This is important for docs-heavy workflows.
Benefits:
- reviewers can click a live docs URL
- broken links or formatting issues are caught before merge
- product/tech writers can review together
Common tools:
- Netlify previews
- Vercel preview deployments
- GitHub Pages preview via branch or artifact
- Cloudflare Pages preview URLs
8) Make docs changes part of code review
Use PR checks like:
- docs build succeeds
- links are valid
- markdown lint passes
- API schema is valid
- generated docs are current
Helpful tools:
markdownlintlycheeorbroken-link-checkervalefor styleopenapi-clifor schema validation
9) If you want docs to update “automatically” from code, avoid manual duplication
Best practices:
- Don’t copy-paste API reference into Markdown if it can be generated
- Keep examples in test files or fixtures where possible
- Store schema examples next to code
- Use one source of truth for route definitions, config, enums, and data models
10) A simple recommended architecture
If you want a straightforward setup:
- Docs authoring: Markdown in
docs/ - API reference: OpenAPI generated from backend
- Portal: Docusaurus or MkDocs
- CI: GitHub Actions
- Hosting: Netlify or GitHub Pages
- Preview: PR preview deploys
Flow:
developer changes code/docs
-> PR opens
-> CI generates docs and builds portal
-> preview link posted
-> merge to main
-> production portal redeploys automatically
11) Minimal implementation checklist
- Put docs in the repo
- Add scripts for generate/build/deploy
- Configure CI to run on PRs and main
- Use generated docs for API/spec-heavy sections
- Add preview deployments
- Add broken-link and markdown checks
- Set a single source of truth for API/schema docs
12) Example package scripts
{
"scripts": {
"docs:generate": "node scripts/generate-docs.js",
"docs:build": "docusaurus build",
"docs:serve": "docusaurus start",
"docs:deploy": "npx netlify deploy --prod"
}
}
If you want, I can give you:
- a GitHub Actions template,
- a Docusaurus or MkDocs setup, or
- a fully automated docs pipeline for a specific stack like Node, Python, Java, or .NET.