Stirling-PDF-Docs

Documentation for Stirling PDF, hosted at docs.stirlingpdf.com.

The site is generated by a small custom static site generator (scripts/build.mjs) - no framework. It renders the markdown in /docs into static HTML.

Prerequisites

• Node.js 20 or above
• npm

Setup

1. Install dependencies:

npm install

2. Build the site and start the preview server:

npm run build
npm start

The site will be available at http://localhost:3000. Re-run npm run build after editing to see changes.

Editing content

All content lives in /docs as extended markdown. Supported syntax:

• Frontmatter: title, id, slug, sidebar_position, sidebar_label, description
• Folders become sidebar categories; _category_.json sets the label and order; a file named like its folder is the category index page
• Admonitions: :::note, :::tip, :::info, :::warning, :::caution, :::danger (with optional [Title])
• Tabs: <Tabs groupId="..."> / <TabItem value="..." label="..."> (selection syncs across groups and persists)
• Code fences with syntax highlighting (Shiki, light + dark) and copy buttons

URLs match the scheme the site has always used, so existing links and the Algolia index keep working.

Layout / design

• scripts/build.mjs - build entry: walks /docs, resolves links, writes ./build
• scripts/lib/content.mjs - content walker, nav tree, URL computation
• scripts/lib/markdown.mjs - markdown rendering (admonitions, tabs, Shiki)
• scripts/lib/template.mjs - page shell (navbar, sidebar, ToC, footer, integrations)
• site/assets/styles.css - all styling (design tokens mirrored from the Stirling portal)
• site/assets/main.js - theme toggle, tabs, drawer, copy buttons, scroll-spy

Contributing

Contributions are welcome! To add or update documentation:

1. Create or edit markdown files in the docs/ directory
2. Preview changes locally (npm run build then npm start)
3. Submit a pull request

Deployment

Pushes to main build and deploy to GitHub Pages via .github/workflows/deploy.yml (npm run build outputs ./build).