smplkit docs

Developer documentation site for docs.smplkit.com, built as a static site with VitePress and deployable via AWS Amplify Hosting.

Why VitePress

VitePress is used for long-term maintainability and developer experience:

• Static-first architecture with fast local development
• Built-in local search support
• Minimal JavaScript payload for fast documentation pages
• First-class markdown authoring and syntax highlighting

Project structure

• .vitepress/config.ts: site config, top nav, sidebar, search
• .vitepress/theme/: minimal brand styling overrides
• index.md: docs homepage (redirects to Getting Started)
• getting-started/: install, init, configuration
• config/: Smpl Config developer guide (management + runtime)
• flags/: Smpl Flags developer guide (management + runtime)
• logging/: Smpl Logging developer guide (management + runtime)
• api-reference/: REST API reference (renders OpenAPI specs per service)
• infrastructure.md: composite SLA and AWS infrastructure overview
• public/: static assets such as logos
• amplify.yml: AWS Amplify build and deploy settings

Run locally

npm install
npm run docs:dev

Open the local URL shown by VitePress (typically http://localhost:5173).

Build docs

npm run docs:build

VitePress outputs static files to .vitepress/dist.

AWS Amplify deployment

Amplify is configured to:

1. Install dependencies
2. Build the static docs site
3. Publish .vitepress/dist as the deploy artifact

Connect the GitHub repository in Amplify and set the production branch to main.

CI and automated releases

This repository includes GitHub Actions workflows that mirror the website repo setup:

• validate.yml: runs on every push and pull request
  • Conventional Commit linting
  • Static docs build (npm run build)
• release.yml: runs on pushes to main
  • Installs dependencies and builds docs
  • Runs semantic-release to calculate the next semantic version from Conventional Commits
  • Publishes GitHub release notes and creates version tags

Add new documentation pages

1. Create a new markdown file in the relevant section directory.
2. Add the page to .vitepress/config.ts sidebar under the correct section.
3. Run npm run docs:dev and verify navigation and rendering.
4. Commit changes to main to trigger Amplify deployment.

Performance notes

• Static generation only; no backend services required
• Optimized for CDN delivery through Amplify Hosting
• Local search avoids external search dependencies
• Minimal theme customization to keep assets lightweight