Stirling-Tools · Frooodle · Aug 8, 2026 · Jul 1, 2026 · Jul 1, 2026 · Jul 1, 2026
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
@@ -1,7 +1,6 @@
 {
   "permissions": {
     "allow": [
-      "Bash(npm run docusaurus:*)",
       "Bash(cat:*)",
       "Bash(tree:*)",
       "Bash(find:*)",

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -29,13 +29,16 @@ jobs:
         run: cp ./CNAME ./build/CNAME
 
       # Popular action to deploy to GitHub Pages:
-      # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
+      # Docs: https://github.com/peaceiris/actions-gh-pages
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           # Build output to publish to the `gh-pages` branch:
           publish_dir: ./build
+          # The build ships content fragments as well as HTML; keeping only
+          # the latest commit stops gh-pages history growing unboundedly.
+          force_orphan: true
           # The following lines assign commit authorship to the official
           # GH-Actions bot for deploys to `gh-pages` branch:
           # https://github.com/actions/checkout/issues/13#issuecomment-724415212

diff --git a/.gitignore b/.gitignore
@@ -4,9 +4,6 @@
 # Production
 /build
 
-# Generated files
-.docusaurus
-.cache-loader
 
 # Misc
 .DS_Store

diff --git a/README.md b/README.md
@@ -1,11 +1,13 @@
 # Stirling-PDF-Docs
-Documentation for Stirling-PDF using [Docusaurus](https://docusaurus.io/)
-Final version is hosted [here](https://docs.stirlingpdf.com/)
+
+Documentation for Stirling PDF, hosted at [docs.stirlingpdf.com](https://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](https://nodejs.org/en/download) version 16.14 or above
-- npm or yarn package manager
+- [Node.js](https://nodejs.org/en/download) 20 or above
+- npm
 
 ## Setup
 
@@ -14,20 +16,43 @@ Final version is hosted [here](https://docs.stirlingpdf.com/)
 npm install
 ```
 
-2. Start the development server:
+2. Build the site and start the preview server:
 ```bash
+npm run build
 npm start
 ```
 
-3. Edit files
-   All our files are within the ``/docs`` directory, any edit made to the files here should instantly show on your local site
+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
 
-The site will be available at `http://localhost:3000`
+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 using `npm start`
+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`).
diff --git a/docs/API.md b/docs/API.md
@@ -1,13 +1,11 @@
 ---
-sidebar_position: 7
+sidebar_position: 6
 id: API
 title: API
 description: Overview of API offering in S-PDF
 tags:
   - API
 ---
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
 
 # Stirling PDF API
 
@@ -73,7 +71,7 @@ Every operation lives under `/api/v1/<category>/<operation>`, where the category
 
 ### AI assistants / MCP
 
-To drive these endpoints from an AI assistant (Claude Desktop, Cursor, etc.) over the Model Context Protocol, see [MCP Server](./Advanced%20Configuration/MCP-Server.md).
+To drive these endpoints from an AI assistant (Claude Desktop, Cursor, etc.) over the Model Context Protocol, see [MCP Server](./Configuration/Automation/MCP-Server.md).
 
 ## API Limitations
 
@@ -137,7 +135,7 @@ Rather than wiring 5 separate HTTP nodes for "OCR then compress then watermark t
 - Request: multipart with one or more `fileInput` parts plus a `json` field containing the full pipeline configuration
 - Response: a single processed file, or a ZIP if the pipeline produced multiple outputs
 
-Full schema, operation list, parameter reference, and curl examples: see **[Pipeline Automation](./Configuration/Pipeline.md#rest-api-post-apiv1pipelinehandledata)**.
+Full schema, operation list, parameter reference, and curl examples: see **[Pipeline Automation](./Configuration/Automation/Pipeline.md#rest-api-post-apiv1pipelinehandledata)**.
 
 ### Building the pipeline JSON
 

diff --git a/docs/Advanced Configuration/Other Customisations.md b/docs/Advanced Configuration/Other Customisations.md
diff --git a/docs/Analytics-and-telemetry.md b/docs/Analytics-and-telemetry.md
@@ -1,16 +1,11 @@
 ---
-sidebar_position: 9
+sidebar_position: 11
 title: Analytics and Telemetry
 id: analytics-telemetry
 ---
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
 
 # Analytics and Telemetry
 
-> Please note all the following applies to version 1.5.0 onward due to be released 16th October
-
-
 Stirling‑PDF uses analytics to understand usage patterns and improve the application. This page explains what data is collected, why we collect it, and how to disable analytics if desired.
 
 > **User control**: All analytics are **opt‑in via a consent banner** (disabled until a user allows it). A self‑hosted administrator can also turn all analytics off system‑wide. If analytics are disabled system‑wide, no banner is shown.

diff --git a/docs/Advanced Configuration/MCP-Server.md → docs/Configuration/Automation/MCP-Server.md b/docs/Advanced Configuration/MCP-Server.md → docs/Configuration/Automation/MCP-Server.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 14
+sidebar_position: 2
 id: MCP Server
 title: MCP Server
 description: Expose Stirling PDF's tools to MCP clients over a built-in Model Context Protocol server
@@ -17,7 +17,7 @@ Stirling PDF ships a built-in [Model Context Protocol (MCP)](https://modelcontex
 The MCP server is built into the Stirling PDF self-hosted server and the desktop app in Local / Self-hosted modes. It is **off by default** and must be enabled and configured per deployment.
 
 :::info Self-hosted capability
-This page documents the MCP server you run on your own Stirling PDF instance. The per-user MCP tab in Stirling Cloud is a separate, cloud-only surface and is not covered here. For where each deployment mode applies, see [Modes](../Modes-and-Licensing.md).
+This page documents the MCP server you run on your own Stirling PDF instance. The per-user MCP tab in Stirling Cloud is a separate, cloud-only surface and is not covered here. For where each deployment mode applies, see [Modes](../../Modes-and-Licensing.md).
 :::
 
 ---
@@ -100,20 +100,20 @@ or
 Authorization: Bearer <your-stirling-api-key>
 ```
 
-The key must belong to an existing, enabled account (generate one under **Account → API Keys** - see [API documentation](../API.md)). No external IdP, OAuth, or JWKS configuration is needed.
+The key must belong to an existing, enabled account (generate one under **Account → API Keys** - see [API documentation](../../API.md)). No external IdP, OAuth, or JWKS configuration is needed.
 
 ---
 
 ## Restrict which operations are exposed
 
-Two MCP-level lists control which operations clients can see and call. They use the same kebab-case operation ids as the [Endpoint or Feature Customisation](../Configuration/Endpoint%20or%20Feature%20Customisation.md) page (e.g. `compress-pdf`).
+Two MCP-level lists control which operations clients can see and call. They use the same kebab-case operation ids as the [Endpoint or Feature Customisation](../Customisation/Endpoint%20or%20Feature%20Customisation.md) page (e.g. `compress-pdf`).
 
 | Key | Env | Default | Behaviour |
 |---|---|---|---|
 | `mcp.allowedOperations` | `MCP_ALLOWEDOPERATIONS` | `[]` | When **non-empty**, acts as a strict allow-list - only these operations are exposed over MCP; everything else is hidden, undescribable, and uninvocable. Empty means allow all. |
 | `mcp.blockedOperations` | `MCP_BLOCKEDOPERATIONS` | `[]` | A deny-list. Anything listed is always removed, applied **after** the allow-list, so a blocked id wins even if it is also allowed. |
 
-These lists layer **on top of** the global [`endpoints.toRemove` / `endpoints.groupsToRemove`](../Configuration/Endpoint%20or%20Feature%20Customisation.md) configuration. An operation disabled globally is never exposed over MCP regardless of these lists.
+These lists layer **on top of** the global [`endpoints.toRemove` / `endpoints.groupsToRemove`](../Customisation/Endpoint%20or%20Feature%20Customisation.md) configuration. An operation disabled globally is never exposed over MCP regardless of these lists.
 
 ---
 
@@ -172,6 +172,6 @@ In OAuth mode, drop the `X-API-KEY` header and let `mcp-remote` complete the OAu
 
 ## Related Documentation
 
-- **[API documentation](../API.md)** - generate the per-user API key used in API-key mode
-- **[Endpoint or Feature Customisation](../Configuration/Endpoint%20or%20Feature%20Customisation.md)** - the operation ids and global enable/disable config the MCP lists build on
-- **[Modes](../Modes-and-Licensing.md)** - where each deployment mode and feature applies
+- **[API documentation](../../API.md)** - generate the per-user API key used in API-key mode
+- **[Endpoint or Feature Customisation](../Customisation/Endpoint%20or%20Feature%20Customisation.md)** - the operation ids and global enable/disable config the MCP lists build on
+- **[Modes](../../Modes-and-Licensing.md)** - where each deployment mode and feature applies
diff --git a/docs/Configuration/Pipeline.md → docs/Configuration/Automation/Pipeline.md b/docs/Configuration/Pipeline.md → docs/Configuration/Automation/Pipeline.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 11
+sidebar_position: 1
 id: Pipeline
 title: Pipeline Automation (Automate)
 description: Create automated multi-step PDF workflows with the Automate tool
@@ -320,7 +320,7 @@ For the canonical list of operations and the full parameter schema for each, see
 - **Local Swagger UI** at `/swagger-ui.html` on your instance - includes every endpoint, parameter types, and lets you try requests live
 - **Online API reference** - the [Stirling PDF API documentation](https://app.swaggerhub.com/apis-docs/Frooodle/Stirling-PDF/) and the [Scalar API registry](https://registry.scalar.com/@stirlingpdf/apis/stirling-pdf-processing-api/)
 
-See [API Documentation](../API.md) for authentication and general API usage.
+See [API Documentation](../../API.md) for authentication and general API usage.
 
 Pipelines can only call endpoints under `/api/v1/general/...`, `/api/v1/misc/...`, `/api/v1/security/...`, `/api/v1/convert/...`, `/api/v1/filter/...`, and `/api/v1/ai/tools/...`. Anything outside those namespaces is rejected by the pipeline processor with a `SecurityException` - this includes `/api/v1/info/...`, `/api/v1/auth/...`, `/api/v1/admin/...`, and `/api/v1/pipeline/handleData` itself (pipelines cannot recursively call themselves).
 
@@ -377,7 +377,7 @@ Trigger a pipeline programmatically via the REST API. Use this from scripts, aut
 - **Method**: `POST`
 - **URL**: `/api/v1/pipeline/handleData`
 - **Content-Type**: `multipart/form-data`
-- **Authentication**: When security is enabled, set the `X-API-KEY` header. See [API Documentation](../API.md) for details.
+- **Authentication**: When security is enabled, set the `X-API-KEY` header. See [API Documentation](../../API.md) for details.
 
 ### Multipart fields
 
@@ -492,7 +492,7 @@ PDFs go directly in the watched folder root (NOT in an `input/` subdirectory). T
 
 The watched-folder scanner runs every 60 seconds.
 
-**Learn more:** [Folder Scanning Guide](./FolderScanning.md)
+**Learn more:** [Folder Scanning Guide](../Storage/FolderScanning.md)
 
 ---
 
@@ -684,11 +684,11 @@ The watched-folder scanner runs every 60 seconds.
 
 ## Related Documentation
 
-- **[Folder Scanning Setup](./FolderScanning.md)** - Detailed folder scanning guide
-- **[Multi-Tool](../Functionality/Multi-Tool.md)** - Interactive multi-operation tool
-- **[Endpoint Customisation](./Endpoint%20or%20Feature%20Customisation.md)** - Operation names and IDs
-- **[API Documentation](../API.md)** - Programmatic pipeline execution
-- **[Advanced Tools](../Functionality/Advanced-Tools.md)** - Other automation features
+- **[Folder Scanning Setup](../Storage/FolderScanning.md)** - Detailed folder scanning guide
+- **[Multi-Tool](../../Functionality/Multi-Tool.md)** - Interactive multi-operation tool
+- **[Endpoint Customisation](../Customisation/Endpoint%20or%20Feature%20Customisation.md)** - Operation names and IDs
+- **[API Documentation](../../API.md)** - Programmatic pipeline execution
+- **[Advanced Tools](../../Functionality/Advanced-Tools.md)** - Other automation features
 
 ---
 

diff --git a/docs/Configuration/Telegram Bot.md → .../Configuration/Automation/Telegram Bot.md b/docs/Configuration/Telegram Bot.md → .../Configuration/Automation/Telegram Bot.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 15
+sidebar_position: 3
 id: Telegram Bot
 title: Telegram Bot Integration
 description: Process PDFs through a Telegram bot powered by Stirling PDF pipelines
@@ -21,7 +21,7 @@ The Telegram bot integration is a **community-built feature** in **beta**. It is
 
 1. A user, channel, or group sends a PDF file to your Telegram bot.
 2. The bot saves the file into a watched pipeline inbox folder.
-3. Stirling PDF processes the file using the pipeline JSON in that folder (see [Folder Scanning](./FolderScanning.md)).
+3. Stirling PDF processes the file using the pipeline JSON in that folder (see [Folder Scanning](../Storage/FolderScanning.md)).
 4. The bot sends the result back to the chat.
 
 The bot talks to Telegram outbound only - no inbound port or webhook setup required, just outbound HTTPS to `api.telegram.org`.
@@ -166,5 +166,5 @@ For production deployments, always enable the user or channel allowlist.
 ## Related Documentation
 
 - **[Pipeline Automation](./Pipeline.md)** - Build the pipeline JSONs the bot uses
-- **[Folder Scanning](./FolderScanning.md)** - The processing engine the bot relies on
-- **[API Documentation](../API.md)** - Trigger pipelines without Telegram
+- **[Folder Scanning](../Storage/FolderScanning.md)** - The processing engine the bot relies on
+- **[API Documentation](../../API.md)** - Trigger pipelines without Telegram
diff --git a/docs/Configuration/Usage Monitoring.md → ...figuration/Automation/Usage Monitoring.md b/docs/Configuration/Usage Monitoring.md → ...figuration/Automation/Usage Monitoring.md
@@ -1,10 +1,8 @@
 ---
-sidebar_position: 5
+sidebar_position: 4
 title: Usage Monitoring
 tags: [enterprise, management, feature, advanced feature]
 ---
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
 
 # Usage Monitoring
 > **Tier**: Enterprise
@@ -77,14 +75,14 @@ Configure Prometheus monitoring using your preferred method:
     docker run -d \
       -p 8080:8080 \
       -e JAVA_CUSTOM_OPTS="-Dmanagement.endpoints.web.exposure.include=prometheus,health,info -Dmanagement.endpoint.health.show-details=always -Dmanagement.metrics.export.prometheus.enabled=true -Denterprisemanagement.metrics.enabled=true" \
-      stirlingtools/stirling-pdf:latest
+      docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
     ```
   </TabItem>
   <TabItem value="docker-compose" label="Docker Compose">
     ```yaml
     services:
       stirling-pdf:
-        image: stirlingtools/stirling-pdf:latest
+        image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
         environment:
           JAVA_CUSTOM_OPTS: "-Dmanagement.endpoints.web.exposure.include=prometheus,health,info -Dmanagement.endpoint.health.show-details=always -Dmanagement.metrics.export.prometheus.enabled=true -Denterprisemanagement.metrics.enabled=true"
     ```

diff --git a/docs/Configuration/Automation/_category_.json b/docs/Configuration/Automation/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Automation & Integrations",
+  "position": 3
+}