A minimal Docusaurus site set up as a docs-as-code sample.
Documentation lives in version control alongside its tooling, gets linted by
Vale on every pull request, and is built and deployed by
GitHub Actions on every push to main.
| Path | Purpose |
|---|---|
docs/ |
Source MDX content (the docs themselves). |
src/ |
Homepage, custom React components, and CSS. |
static/ |
Static assets (logo, favicon, social card). |
docusaurus.config.js |
Site config — title, navbar, footer, plugins. |
sidebars.js |
Sidebar (autogenerated from docs/). |
.vale.ini |
Vale prose-linting config. |
styles/ |
Vale style packages (auto-synced) + project vocabulary. |
.github/workflows/vale.yml |
CI: lint prose on every PR. |
.github/workflows/deploy.yml |
CI: build and deploy to GitHub Pages on push to main. |
npm install
npm run start # dev server at http://localhost:3000
npm run build # production build into ./build
npm run serve # preview the production buildThe repo is configured to lint prose with Vale using the Microsoft and write-good style packages.
Install the Vale CLI:
# Windows (Chocolatey)
choco install vale
# macOS (Homebrew)
brew install vale
# Linux (Snap)
snap install valevale sync # download style packages declared in .vale.ini
vale docs # lint everything in the docs/ folderAdd project-specific words to styles/Vocab/Project/accept.txt (allowed) or
styles/Vocab/Project/reject.txt (flagged).
| Workflow | Trigger | What it does |
|---|---|---|
.github/workflows/vale.yml |
PRs to any branch, pushes to main |
Runs Vale via errata-ai/vale-action and posts review comments. |
.github/workflows/deploy.yml |
Pushes to main |
Builds the site and deploys it to GitHub Pages. |
- In
docusaurus.config.js, seturl,baseUrl,organizationName, andprojectNamefor your repo. - In your GitHub repo, open Settings → Pages and set Source to GitHub Actions.
- Push to
main. Thedeploy.ymlworkflow will publish to the Pages environment.
Prefer Netlify? Skip step 2-3, connect the repo on Netlify, set the build command
to npm run build and publish directory to build. Then you can safely delete
.github/workflows/deploy.yml.