Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Sample Technical Docs (Docs as Code)

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.

What's in here

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.

Local development

npm install
npm run start        # dev server at http://localhost:3000
npm run build        # production build into ./build
npm run serve        # preview the production build

Prose linting with Vale

The repo is configured to lint prose with Vale using the Microsoft and write-good style packages.

One-time setup

Install the Vale CLI:

# Windows (Chocolatey)
choco install vale

# macOS (Homebrew)
brew install vale

# Linux (Snap)
snap install vale

Run Vale locally

vale sync           # download style packages declared in .vale.ini
vale docs           # lint everything in the docs/ folder

Add project-specific words to styles/Vocab/Project/accept.txt (allowed) or styles/Vocab/Project/reject.txt (flagged).

Continuous integration

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.

Deploying to GitHub Pages

  1. In docusaurus.config.js, set url, baseUrl, organizationName, and projectName for your repo.
  2. In your GitHub repo, open Settings → Pages and set Source to GitHub Actions.
  3. Push to main. The deploy.yml workflow 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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages