From bf2736ca5527b231847c718d283909b12ad5e702 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Wed, 4 Feb 2026 09:20:17 +0100
Subject: [PATCH 01/30] add dev script

---
 packages/plugin-docs-renderer/package.json | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/plugin-docs-renderer/package.json b/packages/plugin-docs-renderer/package.json
index 91868abfaf..ad18210fb4 100644
--- a/packages/plugin-docs-renderer/package.json
+++ b/packages/plugin-docs-renderer/package.json
@@ -26,6 +26,7 @@
   },
   "scripts": {
     "build": "rollup -c ../../rollup.config.ts --configPlugin esbuild",
+    "dev": "rollup -c ../../rollup.config.ts --configPlugin esbuild --watch",
     "lint": "eslint --cache ./src",
     "lint:fix": "npm run lint -- --fix",
     "lint:package": "publint",

From 36f068370546be8a7d3cd64d96cd4a51fc47ad97 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Wed, 4 Feb 2026 09:45:09 +0100
Subject: [PATCH 02/30] add serve cmd

---
 packages/plugin-docs-renderer/src/bin/run.ts | 77 +++++++++++---------
 1 file changed, 42 insertions(+), 35 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/bin/run.ts b/packages/plugin-docs-renderer/src/bin/run.ts
index 5504e298e7..1b74d3a6b9 100644
--- a/packages/plugin-docs-renderer/src/bin/run.ts
+++ b/packages/plugin-docs-renderer/src/bin/run.ts
@@ -1,53 +1,60 @@
 #!/usr/bin/env node
 import { access } from 'node:fs/promises';
+import { resolve } from 'node:path';
 import minimist from 'minimist';
-import { loadDocsFolder } from '../loader.js';
-import { parseMarkdown } from '../parser.js';
+import { startServer } from '../server.js';
+
+async function commandServe(docsPath: string, port: number, liveReload: boolean) {
+  console.log('Starting development server...\n');
+
+  try {
+    startServer({
+      docsPath,
+      port,
+      liveReload,
+    });
+  } catch (error) {
+    if (error instanceof Error) {
+      console.error('Error starting server:', error.message);
+    } else {
+      console.error('Error starting server:', error);
+    }
+    process.exit(1);
+  }
+}
 
 async function main() {
-  const argv = minimist(process.argv.slice(2));
-  // get docs path from command line arguments or use default (./docs)
-  const docsPath = argv._[0] || './docs';
+  const argv = minimist(process.argv.slice(2), {
+    boolean: ['reload'],
+    string: ['port'],
+    alias: {
+      p: 'port',
+      r: 'reload',
+    },
+    default: {
+      port: '3001',
+      reload: false,
+    },
+  });
+
+  const docsPath = resolve(argv._[1] || './docs');
 
   // check if the path exists
   try {
     await access(docsPath);
   } catch {
-    console.error(`Path not found: ${docsPath}`);
-    console.error('Usage: npx @grafana/plugin-docs-renderer [docs-folder]');
-    console.error('Example: npx @grafana/plugin-docs-renderer ./docs');
+    console.error(`Error: Path not found: ${docsPath}`);
     process.exit(1);
   }
 
-  // load and parse documentation
-  try {
-    const { manifest, files } = await loadDocsFolder(docsPath);
-
-    // parse each markdown file
-    const pages: Record<string, { frontmatter: Record<string, unknown>; html: string }> = {};
-    for (const [filePath, content] of Object.entries(files)) {
-      const parsed = parseMarkdown(content);
-      pages[filePath] = {
-        frontmatter: parsed.frontmatter,
-        html: parsed.html,
-      };
-    }
-
-    // output to console
-    const result = {
-      manifest,
-      pages,
-    };
-
-    console.log(JSON.stringify(result, null, 2));
-  } catch (error) {
-    if (error instanceof Error) {
-      console.error('Error processing documentation:', error.message);
-    } else {
-      console.error('Error processing documentation:', error);
-    }
+  // parse port
+  const port = parseInt(argv.port, 10);
+  if (isNaN(port) || port < 1 || port > 65535) {
+    console.error(`Error: Invalid port: ${argv.port}`);
     process.exit(1);
   }
+
+  await commandServe(docsPath, port, argv.reload);
 }
 
 main();

From 9d7a3512084937f55de9f46fc6580f4377b1791a Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Wed, 4 Feb 2026 09:46:20 +0100
Subject: [PATCH 03/30] add very basic dev server

---
 packages/plugin-docs-renderer/src/index.ts  |   4 +
 packages/plugin-docs-renderer/src/server.ts | 172 ++++++++++++++++++++
 2 files changed, 176 insertions(+)
 create mode 100644 packages/plugin-docs-renderer/src/server.ts

diff --git a/packages/plugin-docs-renderer/src/index.ts b/packages/plugin-docs-renderer/src/index.ts
index 5a73e29cf6..f88cd2e52d 100644
--- a/packages/plugin-docs-renderer/src/index.ts
+++ b/packages/plugin-docs-renderer/src/index.ts
@@ -8,3 +8,7 @@ export type { ParsedMarkdown } from './parser.js';
 // export loader functions
 export { loadDocsFolder } from './loader.js';
 export type { LoadedDocs } from './loader.js';
+
+// export server functions
+export { startServer } from './server.js';
+export type { ServerOptions } from './server.js';
diff --git a/packages/plugin-docs-renderer/src/server.ts b/packages/plugin-docs-renderer/src/server.ts
new file mode 100644
index 0000000000..3ec96fee3f
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/server.ts
@@ -0,0 +1,172 @@
+import express, { type Express, type Request, type Response } from 'express';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { watch } from 'chokidar';
+import { parseMarkdown } from './parser.js';
+import type { Manifest, Page } from './types.js';
+
+export interface ServerOptions {
+  docsPath: string;
+  port?: number;
+  liveReload?: boolean;
+}
+
+function generateNavItems(pages: Page[]): string {
+  return pages.map((page) => `<li><a href="/${page.slug}">${page.title}</a></li>`).join('\n');
+}
+
+/**
+ * Generates an HTML template for a documentation page.
+ */
+function generatePageHTML(title: string, content: string, manifest: Manifest, liveReload: boolean): string {
+  // generate a simple navigation from manifest
+  const navItems = generateNavItems(manifest.pages);
+
+  // optional live reload script
+  const reloadScript = liveReload
+    ? `
+    <script>
+      let lastCheck = Date.now();
+      setInterval(async () => {
+        try {
+          const res = await fetch('/__reload__?t=' + lastCheck);
+          if (res.status === 205) {
+            location.reload();
+          }
+          lastCheck = Date.now();
+        } catch (e) {
+          // Ignore fetch errors
+        }
+      }, 1000);
+    </script>
+  `
+    : '';
+
+  return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${title} - ${manifest.title}</title>
+</head>
+<body>
+  <nav>
+    <h1>${manifest.title}</h1>
+    <ul>
+      ${navItems}
+    </ul>
+  </nav>
+  <hr>
+  <main>
+    ${content}
+  </main>
+  ${reloadScript}
+</body>
+</html>
+  `.trim();
+}
+
+/**
+ * Starts a development server for previewing plugin documentation.
+ *
+ * @param options - Server configuration options
+ * @returns The Express app instance
+ */
+export function startServer(options: ServerOptions): Express {
+  const { docsPath, port = 3000, liveReload = false } = options;
+
+  const app = express();
+  let lastModified = Date.now();
+
+  // setup file watcher
+  const watcher = watch([join(docsPath, '**/*.md'), join(docsPath, 'manifest.json')], {
+    ignoreInitial: true,
+  });
+
+  watcher.on('change', async (path) => {
+    console.log(`File changed: ${path}`);
+    lastModified = Date.now();
+    console.log('✓ Change detected');
+  });
+
+  // serve static assets (images, etc.)
+  app.use('/img', express.static(join(docsPath, 'img')));
+  app.use('/assets', express.static(join(docsPath, 'assets')));
+  app.use('/images', express.static(join(docsPath, 'images')));
+
+  // live reload endpoint (if enabled)
+  if (liveReload) {
+    app.get('/__reload__', (req: Request, res: Response) => {
+      const clientTime = parseInt(req.query.t as string, 10) || 0;
+      if (lastModified > clientTime) {
+        res.status(205).send(); // 205 = Reset Content (signals reload)
+      } else {
+        res.status(204).send(); // 204 = No Content (no changes)
+      }
+    });
+  }
+
+  // helper to find page by slug in manifest
+  function findPageBySlug(slug: string, pages: Page[]): string | null {
+    for (const page of pages) {
+      if (page.slug === slug) {
+        return page.file;
+      }
+      if (page.children) {
+        const found = findPageBySlug(slug, page.children);
+        if (found) {
+          return found;
+        }
+      }
+    }
+    return null;
+  }
+
+  // serve documentation pages
+  app.get('/:slug?', async (req: Request, res: Response) => {
+    try {
+      // load manifest from disk
+      const manifestPath = join(docsPath, 'manifest.json');
+      const manifestContent = await readFile(manifestPath, 'utf-8');
+      const manifest: Manifest = JSON.parse(manifestContent);
+
+      // default to first page in manifest
+      const slug = req.params.slug || manifest.pages[0]?.slug;
+      if (!slug) {
+        res.status(404).send('No pages found in manifest');
+        return;
+      }
+
+      // find the file for this slug
+      const fileName = findPageBySlug(slug, manifest.pages);
+      if (!fileName) {
+        res.status(404).send('Page not found');
+        return;
+      }
+
+      // read and parse the markdown file
+      const filePath = join(docsPath, fileName);
+      const fileContent = await readFile(filePath, 'utf-8');
+      const parsed = parseMarkdown(fileContent);
+
+      const title = (parsed.frontmatter.title as string) || slug;
+      const html = generatePageHTML(title, parsed.html, manifest, liveReload);
+      res.send(html);
+    } catch (error) {
+      console.error('Error serving page:', error);
+      res.status(500).send('Internal server error');
+    }
+  });
+
+  // start the server
+  app.listen(port, () => {
+    console.log(`\n📄 Plugin Documentation Server`);
+    console.log(`✓ Serving: ${docsPath}`);
+    console.log(`✓ URL: http://localhost:${port}`);
+    console.log(`✓ Live reload: ${liveReload ? 'enabled' : 'disabled'}`);
+    console.log(`\n🔍 Watching for changes...\n`);
+  });
+
+  return app;
+}

From 2c9cfad6bf21811ed1c03cd95ff5ff4da777b31c Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 07:54:27 +0100
Subject: [PATCH 04/30] fix argument parsing

---
 packages/plugin-docs-renderer/src/bin/run.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/plugin-docs-renderer/src/bin/run.ts b/packages/plugin-docs-renderer/src/bin/run.ts
index 1b74d3a6b9..edcdab4a19 100644
--- a/packages/plugin-docs-renderer/src/bin/run.ts
+++ b/packages/plugin-docs-renderer/src/bin/run.ts
@@ -37,7 +37,7 @@ async function main() {
     },
   });
 
-  const docsPath = resolve(argv._[1] || './docs');
+  const docsPath = resolve(argv._[0] || './docs');
 
   // check if the path exists
   try {

From e30ce36efe771704a34ea58256fee41ec8ce7241 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 08:10:45 +0100
Subject: [PATCH 05/30] add server/api test

---
 .../src/__fixtures__/test-docs/advanced.md    |   3 +
 .../src/__fixtures__/test-docs/guide.md       |   7 +
 .../src/__fixtures__/test-docs/home.md        |   8 ++
 .../src/__fixtures__/test-docs/img/test.png   |   1 +
 .../src/__fixtures__/test-docs/manifest.json  |  23 ++++
 .../plugin-docs-renderer/src/server.test.ts   | 130 ++++++++++++++++++
 6 files changed, 172 insertions(+)
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs/advanced.md
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs/guide.md
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs/home.md
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs/img/test.png
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs/manifest.json
 create mode 100644 packages/plugin-docs-renderer/src/server.test.ts

diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/advanced.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/advanced.md
new file mode 100644
index 0000000000..9652de2cc8
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/advanced.md
@@ -0,0 +1,3 @@
+# Advanced Topics
+
+This covers advanced topics.
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/guide.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/guide.md
new file mode 100644
index 0000000000..069356d512
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/guide.md
@@ -0,0 +1,7 @@
+---
+title: User Guide
+---
+
+# User Guide
+
+This is a guide page.
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/home.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/home.md
new file mode 100644
index 0000000000..afe70d0eaf
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/home.md
@@ -0,0 +1,8 @@
+---
+title: Home Page
+description: Welcome to the test docs
+---
+
+# Welcome
+
+This is the home page of the test documentation.
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/img/test.png b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/img/test.png
new file mode 100644
index 0000000000..cd69803d6a
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/img/test.png
@@ -0,0 +1 @@
+test-image
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/manifest.json b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/manifest.json
new file mode 100644
index 0000000000..fe31a9bd5c
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/manifest.json
@@ -0,0 +1,23 @@
+{
+  "version": "1.0",
+  "title": "Test Plugin Documentation",
+  "pages": [
+    {
+      "title": "Home",
+      "slug": "home",
+      "file": "home.md"
+    },
+    {
+      "title": "Guide",
+      "slug": "guide",
+      "file": "guide.md",
+      "children": [
+        {
+          "title": "Advanced",
+          "slug": "advanced",
+          "file": "advanced.md"
+        }
+      ]
+    }
+  ]
+}
diff --git a/packages/plugin-docs-renderer/src/server.test.ts b/packages/plugin-docs-renderer/src/server.test.ts
new file mode 100644
index 0000000000..95283b31e0
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/server.test.ts
@@ -0,0 +1,130 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import request from 'supertest';
+import { join } from 'node:path';
+import type { Express } from 'express';
+import { startServer } from './server.js';
+
+describe('startServer', () => {
+  const testDocsPath = join(__dirname, '__fixtures__', 'test-docs');
+  let app: Express;
+
+  afterEach(() => {
+    // cleanup: close any open connections
+    if (app) {
+      const server = (app as any).server;
+      if (server?.close) {
+        server.close();
+      }
+    }
+  });
+
+  it('should serve the homepage (first page in manifest)', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0 });
+
+    const response = await request(app).get('/');
+
+    expect(response.status).toBe(200);
+    expect(response.text).toContain('<title>Home Page - Test Plugin Documentation</title>');
+    expect(response.text).toContain('<h1>Welcome</h1>');
+    expect(response.text).toContain('This is the home page of the test documentation.');
+  });
+
+  it('should serve a specific page by slug', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0 });
+
+    const response = await request(app).get('/guide');
+
+    expect(response.status).toBe(200);
+    expect(response.text).toContain('<title>User Guide - Test Plugin Documentation</title>');
+    expect(response.text).toContain('<h1>User Guide</h1>');
+    expect(response.text).toContain('This is a guide page.');
+  });
+
+  it('should serve a nested page by slug', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0 });
+
+    const response = await request(app).get('/advanced');
+
+    expect(response.status).toBe(200);
+    expect(response.text).toContain('<h1>Advanced Topics</h1>');
+    expect(response.text).toContain('This covers advanced topics.');
+  });
+
+  it('should return 404 for non-existent page', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0 });
+
+    const response = await request(app).get('/non-existent');
+
+    expect(response.status).toBe(404);
+    expect(response.text).toContain('Page not found');
+  });
+
+  it('should include navigation links', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0 });
+
+    const response = await request(app).get('/');
+
+    expect(response.status).toBe(200);
+    expect(response.text).toContain('<nav>');
+    expect(response.text).toContain('<a href="/home">Home</a>');
+    expect(response.text).toContain('<a href="/guide">Guide</a>');
+  });
+
+  it('should serve static assets from img directory', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0 });
+
+    const response = await request(app).get('/img/test.png');
+
+    expect(response.status).toBe(200);
+    // check that the file was served (binary content)
+    expect(response.body).toBeDefined();
+  });
+
+  it('should not include live reload script by default', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0, liveReload: false });
+
+    const response = await request(app).get('/');
+
+    expect(response.status).toBe(200);
+    expect(response.text).not.toContain('__reload__');
+    expect(response.text).not.toContain('location.reload()');
+  });
+
+  it('should include live reload script when enabled', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0, liveReload: true });
+
+    const response = await request(app).get('/');
+
+    expect(response.status).toBe(200);
+    expect(response.text).toContain('__reload__');
+    expect(response.text).toContain('location.reload()');
+  });
+
+  it('should have live reload endpoint when enabled', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0, liveReload: true });
+
+    const response = await request(app).get('/__reload__?t=0');
+
+    // should return 204 (no changes) or 205 (reset content)
+    expect([204, 205]).toContain(response.status);
+  });
+
+  it('should use frontmatter title when available', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0 });
+
+    const response = await request(app).get('/home');
+
+    expect(response.status).toBe(200);
+    expect(response.text).toContain('<title>Home Page - Test Plugin Documentation</title>');
+  });
+
+  it('should fallback to slug when no frontmatter title', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0 });
+
+    const response = await request(app).get('/advanced');
+
+    expect(response.status).toBe(200);
+    // should use slug as fallback since advanced.md has no frontmatter title
+    expect(response.text).toContain('<title>advanced - Test Plugin Documentation</title>');
+  });
+});

From 92dff3540249e607b6daba88c42e425507e1ba7c Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 08:53:00 +0100
Subject: [PATCH 06/30] remove process exit

---
 packages/plugin-docs-renderer/src/bin/run.ts | 1 -
 1 file changed, 1 deletion(-)

diff --git a/packages/plugin-docs-renderer/src/bin/run.ts b/packages/plugin-docs-renderer/src/bin/run.ts
index edcdab4a19..6a63c0442a 100644
--- a/packages/plugin-docs-renderer/src/bin/run.ts
+++ b/packages/plugin-docs-renderer/src/bin/run.ts
@@ -19,7 +19,6 @@ async function commandServe(docsPath: string, port: number, liveReload: boolean)
     } else {
       console.error('Error starting server:', error);
     }
-    process.exit(1);
   }
 }
 

From 84c6e502b45c04259a3e503de6909d51f3c0c8ff Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 08:54:18 +0100
Subject: [PATCH 07/30] fix image

---
 .../src/__fixtures__/test-docs/img/test.png       | Bin 11 -> 70 bytes
 packages/plugin-docs-renderer/src/server.test.ts  |   2 +-
 2 files changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/img/test.png b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/img/test.png
index cd69803d6abb2e4480777e816c7071cee052b447..613754cfaf74a7a2d86984231479d5671731f18a 100644
GIT binary patch
literal 70
zcmeAS@N?(olHy`uVBq!ia0vp^j3CUx1|;Q0k92}1TpU9xZY8HA{D|jgU}|S<c<sJx
Q5>SG{)78&qol`;+0KfSU_W%F@

literal 11
ScmXR(EiTc`%uP&B<pKa20|Wa2

diff --git a/packages/plugin-docs-renderer/src/server.test.ts b/packages/plugin-docs-renderer/src/server.test.ts
index 95283b31e0..6fad069253 100644
--- a/packages/plugin-docs-renderer/src/server.test.ts
+++ b/packages/plugin-docs-renderer/src/server.test.ts
@@ -76,7 +76,7 @@ describe('startServer', () => {
     const response = await request(app).get('/img/test.png');
 
     expect(response.status).toBe(200);
-    // check that the file was served (binary content)
+    expect(response.type).toBe('image/png');
     expect(response.body).toBeDefined();
   });
 

From be6e56710e3089861f167b180103e16df1e6ffc0 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 09:19:19 +0100
Subject: [PATCH 08/30] use debug logger in server

---
 packages/plugin-docs-renderer/src/bin/run.ts | 13 ++++++++++++-
 packages/plugin-docs-renderer/src/server.ts  | 18 ++++++++++++++++--
 2 files changed, 28 insertions(+), 3 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/bin/run.ts b/packages/plugin-docs-renderer/src/bin/run.ts
index 6a63c0442a..1eb0e204d3 100644
--- a/packages/plugin-docs-renderer/src/bin/run.ts
+++ b/packages/plugin-docs-renderer/src/bin/run.ts
@@ -2,10 +2,13 @@
 import { access } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import minimist from 'minimist';
+import createDebug from 'debug';
 import { startServer } from '../server.js';
 
+const debug = createDebug('plugin-docs-renderer:cli');
+
 async function commandServe(docsPath: string, port: number, liveReload: boolean) {
-  console.log('Starting development server...\n');
+  debug('Command serve: docsPath=%s, port=%d, liveReload=%s', docsPath, port, liveReload);
 
   try {
     startServer({
@@ -14,6 +17,7 @@ async function commandServe(docsPath: string, port: number, liveReload: boolean)
       liveReload,
     });
   } catch (error) {
+    debug('Failed to start server: %O', error);
     if (error instanceof Error) {
       console.error('Error starting server:', error.message);
     } else {
@@ -23,6 +27,8 @@ async function commandServe(docsPath: string, port: number, liveReload: boolean)
 }
 
 async function main() {
+  debug('CLI invoked with args: %O', process.argv.slice(2));
+
   const argv = minimist(process.argv.slice(2), {
     boolean: ['reload'],
     string: ['port'],
@@ -37,11 +43,14 @@ async function main() {
   });
 
   const docsPath = resolve(argv._[0] || './docs');
+  debug('Resolved docs path: %s', docsPath);
 
   // check if the path exists
   try {
     await access(docsPath);
+    debug('Docs path exists');
   } catch {
+    debug('Docs path not found: %s', docsPath);
     console.error(`Error: Path not found: ${docsPath}`);
     process.exit(1);
   }
@@ -49,9 +58,11 @@ async function main() {
   // parse port
   const port = parseInt(argv.port, 10);
   if (isNaN(port) || port < 1 || port > 65535) {
+    debug('Invalid port: %s', argv.port);
     console.error(`Error: Invalid port: ${argv.port}`);
     process.exit(1);
   }
+  debug('Validated port: %d', port);
 
   await commandServe(docsPath, port, argv.reload);
 }
diff --git a/packages/plugin-docs-renderer/src/server.ts b/packages/plugin-docs-renderer/src/server.ts
index 3ec96fee3f..758e738d42 100644
--- a/packages/plugin-docs-renderer/src/server.ts
+++ b/packages/plugin-docs-renderer/src/server.ts
@@ -2,9 +2,12 @@ import express, { type Express, type Request, type Response } from 'express';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { watch } from 'chokidar';
+import createDebug from 'debug';
 import { parseMarkdown } from './parser.js';
 import type { Manifest, Page } from './types.js';
 
+const debug = createDebug('plugin-docs-renderer:server');
+
 export interface ServerOptions {
   docsPath: string;
   port?: number;
@@ -76,6 +79,8 @@ function generatePageHTML(title: string, content: string, manifest: Manifest, li
 export function startServer(options: ServerOptions): Express {
   const { docsPath, port = 3000, liveReload = false } = options;
 
+  debug('Starting server with options: docsPath=%s, port=%d, liveReload=%s', docsPath, port, liveReload);
+
   const app = express();
   let lastModified = Date.now();
 
@@ -83,11 +88,11 @@ export function startServer(options: ServerOptions): Express {
   const watcher = watch([join(docsPath, '**/*.md'), join(docsPath, 'manifest.json')], {
     ignoreInitial: true,
   });
+  debug('File watcher initialized for %s', docsPath);
 
   watcher.on('change', async (path) => {
-    console.log(`File changed: ${path}`);
+    debug('File changed: %s', path);
     lastModified = Date.now();
-    console.log('✓ Change detected');
   });
 
   // serve static assets (images, etc.)
@@ -125,6 +130,9 @@ export function startServer(options: ServerOptions): Express {
 
   // serve documentation pages
   app.get('/:slug?', async (req: Request, res: Response) => {
+    const requestedSlug = req.params.slug || 'index';
+    debug('Request for slug: %s', requestedSlug);
+
     try {
       // load manifest from disk
       const manifestPath = join(docsPath, 'manifest.json');
@@ -134,6 +142,7 @@ export function startServer(options: ServerOptions): Express {
       // default to first page in manifest
       const slug = req.params.slug || manifest.pages[0]?.slug;
       if (!slug) {
+        debug('No pages found in manifest');
         res.status(404).send('No pages found in manifest');
         return;
       }
@@ -141,10 +150,13 @@ export function startServer(options: ServerOptions): Express {
       // find the file for this slug
       const fileName = findPageBySlug(slug, manifest.pages);
       if (!fileName) {
+        debug('Page not found for slug: %s', slug);
         res.status(404).send('Page not found');
         return;
       }
 
+      debug('Serving page: %s -> %s', slug, fileName);
+
       // read and parse the markdown file
       const filePath = join(docsPath, fileName);
       const fileContent = await readFile(filePath, 'utf-8');
@@ -154,6 +166,7 @@ export function startServer(options: ServerOptions): Express {
       const html = generatePageHTML(title, parsed.html, manifest, liveReload);
       res.send(html);
     } catch (error) {
+      debug('Error serving page: %O', error);
       console.error('Error serving page:', error);
       res.status(500).send('Internal server error');
     }
@@ -161,6 +174,7 @@ export function startServer(options: ServerOptions): Express {
 
   // start the server
   app.listen(port, () => {
+    debug('Server listening on port %d', port);
     console.log(`\n📄 Plugin Documentation Server`);
     console.log(`✓ Serving: ${docsPath}`);
     console.log(`✓ URL: http://localhost:${port}`);

From f83dc4402af9f0f7d528327b931356fdc5cfb9c6 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 09:23:15 +0100
Subject: [PATCH 09/30] cleanup

---
 packages/plugin-docs-renderer/src/bin/run.ts |  4 ----
 packages/plugin-docs-renderer/src/server.ts  | 10 +++-------
 2 files changed, 3 insertions(+), 11 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/bin/run.ts b/packages/plugin-docs-renderer/src/bin/run.ts
index 1eb0e204d3..bb30b512dd 100644
--- a/packages/plugin-docs-renderer/src/bin/run.ts
+++ b/packages/plugin-docs-renderer/src/bin/run.ts
@@ -48,9 +48,7 @@ async function main() {
   // check if the path exists
   try {
     await access(docsPath);
-    debug('Docs path exists');
   } catch {
-    debug('Docs path not found: %s', docsPath);
     console.error(`Error: Path not found: ${docsPath}`);
     process.exit(1);
   }
@@ -58,11 +56,9 @@ async function main() {
   // parse port
   const port = parseInt(argv.port, 10);
   if (isNaN(port) || port < 1 || port > 65535) {
-    debug('Invalid port: %s', argv.port);
     console.error(`Error: Invalid port: ${argv.port}`);
     process.exit(1);
   }
-  debug('Validated port: %d', port);
 
   await commandServe(docsPath, port, argv.reload);
 }
diff --git a/packages/plugin-docs-renderer/src/server.ts b/packages/plugin-docs-renderer/src/server.ts
index 758e738d42..3952ffae20 100644
--- a/packages/plugin-docs-renderer/src/server.ts
+++ b/packages/plugin-docs-renderer/src/server.ts
@@ -95,7 +95,7 @@ export function startServer(options: ServerOptions): Express {
     lastModified = Date.now();
   });
 
-  // serve static assets (images, etc.)
+  // serve static assets
   app.use('/img', express.static(join(docsPath, 'img')));
   app.use('/assets', express.static(join(docsPath, 'assets')));
   app.use('/images', express.static(join(docsPath, 'images')));
@@ -105,9 +105,9 @@ export function startServer(options: ServerOptions): Express {
     app.get('/__reload__', (req: Request, res: Response) => {
       const clientTime = parseInt(req.query.t as string, 10) || 0;
       if (lastModified > clientTime) {
-        res.status(205).send(); // 205 = Reset Content (signals reload)
+        res.status(205).send(); //signals reload
       } else {
-        res.status(204).send(); // 204 = No Content (no changes)
+        res.status(204).send(); // no changes
       }
     });
   }
@@ -155,8 +155,6 @@ export function startServer(options: ServerOptions): Express {
         return;
       }
 
-      debug('Serving page: %s -> %s', slug, fileName);
-
       // read and parse the markdown file
       const filePath = join(docsPath, fileName);
       const fileContent = await readFile(filePath, 'utf-8');
@@ -166,7 +164,6 @@ export function startServer(options: ServerOptions): Express {
       const html = generatePageHTML(title, parsed.html, manifest, liveReload);
       res.send(html);
     } catch (error) {
-      debug('Error serving page: %O', error);
       console.error('Error serving page:', error);
       res.status(500).send('Internal server error');
     }
@@ -174,7 +171,6 @@ export function startServer(options: ServerOptions): Express {
 
   // start the server
   app.listen(port, () => {
-    debug('Server listening on port %d', port);
     console.log(`\n📄 Plugin Documentation Server`);
     console.log(`✓ Serving: ${docsPath}`);
     console.log(`✓ URL: http://localhost:${port}`);

From 91dcca2c1daba1545627025ea6e41a7071ece63a Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 09:26:48 +0100
Subject: [PATCH 10/30] more cleanup

---
 packages/plugin-docs-renderer/src/bin/run.ts | 2 +-
 packages/plugin-docs-renderer/src/server.ts  | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/bin/run.ts b/packages/plugin-docs-renderer/src/bin/run.ts
index bb30b512dd..50f949618c 100644
--- a/packages/plugin-docs-renderer/src/bin/run.ts
+++ b/packages/plugin-docs-renderer/src/bin/run.ts
@@ -55,7 +55,7 @@ async function main() {
 
   // parse port
   const port = parseInt(argv.port, 10);
-  if (isNaN(port) || port < 1 || port > 65535) {
+  if (isNaN(port)) {
     console.error(`Error: Invalid port: ${argv.port}`);
     process.exit(1);
   }
diff --git a/packages/plugin-docs-renderer/src/server.ts b/packages/plugin-docs-renderer/src/server.ts
index 3952ffae20..f16882d736 100644
--- a/packages/plugin-docs-renderer/src/server.ts
+++ b/packages/plugin-docs-renderer/src/server.ts
@@ -10,10 +10,11 @@ const debug = createDebug('plugin-docs-renderer:server');
 
 export interface ServerOptions {
   docsPath: string;
-  port?: number;
+  port: number;
   liveReload?: boolean;
 }
 
+// will support nested pages in the future
 function generateNavItems(pages: Page[]): string {
   return pages.map((page) => `<li><a href="/${page.slug}">${page.title}</a></li>`).join('\n');
 }

From 1b1ddb0270545ec179b1dc46424729dc179afd3d Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 12:45:18 +0100
Subject: [PATCH 11/30] escape html

---
 packages/plugin-docs-renderer/src/server.test.ts | 14 ++++++++++++++
 packages/plugin-docs-renderer/src/server.ts      |  7 ++++---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/server.test.ts b/packages/plugin-docs-renderer/src/server.test.ts
index 6fad069253..2af5bf0261 100644
--- a/packages/plugin-docs-renderer/src/server.test.ts
+++ b/packages/plugin-docs-renderer/src/server.test.ts
@@ -127,4 +127,18 @@ describe('startServer', () => {
     // should use slug as fallback since advanced.md has no frontmatter title
     expect(response.text).toContain('<title>advanced - Test Plugin Documentation</title>');
   });
+
+  it('should escape HTML entities in titles to prevent XSS', async () => {
+    app = startServer({ docsPath: testDocsPath, port: 0 });
+
+    const response = await request(app).get('/');
+
+    expect(response.status).toBe(200);
+    // verify that if manifest or page titles contained HTML, it would be escaped
+    // manifest title should appear escaped in title tag and h1
+    expect(response.text).toMatch(/<title>[^<]*<\/title>/);
+    expect(response.text).toMatch(/<h1>[^<]*<\/h1>/);
+    // navigation links should not contain unescaped HTML
+    expect(response.text).not.toMatch(/<a[^>]*>[^<]*<script/i);
+  });
 });
diff --git a/packages/plugin-docs-renderer/src/server.ts b/packages/plugin-docs-renderer/src/server.ts
index f16882d736..5a8ff82095 100644
--- a/packages/plugin-docs-renderer/src/server.ts
+++ b/packages/plugin-docs-renderer/src/server.ts
@@ -3,6 +3,7 @@ import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { watch } from 'chokidar';
 import createDebug from 'debug';
+import escapeHtml from 'escape-html';
 import { parseMarkdown } from './parser.js';
 import type { Manifest, Page } from './types.js';
 
@@ -16,7 +17,7 @@ export interface ServerOptions {
 
 // will support nested pages in the future
 function generateNavItems(pages: Page[]): string {
-  return pages.map((page) => `<li><a href="/${page.slug}">${page.title}</a></li>`).join('\n');
+  return pages.map((page) => `<li><a href="/${escapeHtml(page.slug)}">${escapeHtml(page.title)}</a></li>`).join('\n');
 }
 
 /**
@@ -52,11 +53,11 @@ function generatePageHTML(title: string, content: string, manifest: Manifest, li
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${title} - ${manifest.title}</title>
+  <title>${escapeHtml(title)} - ${escapeHtml(manifest.title)}</title>
 </head>
 <body>
   <nav>
-    <h1>${manifest.title}</h1>
+    <h1>${escapeHtml(manifest.title)}</h1>
     <ul>
       ${navItems}
     </ul>

From 1d2d35b6eba98d769fb044ebda9dea5a20ede474 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 12:46:26 +0100
Subject: [PATCH 12/30] remove redundant debug log for requested slug in
 startServer

---
 packages/plugin-docs-renderer/src/server.ts | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/server.ts b/packages/plugin-docs-renderer/src/server.ts
index 5a8ff82095..68acc9a8b6 100644
--- a/packages/plugin-docs-renderer/src/server.ts
+++ b/packages/plugin-docs-renderer/src/server.ts
@@ -132,9 +132,6 @@ export function startServer(options: ServerOptions): Express {
 
   // serve documentation pages
   app.get('/:slug?', async (req: Request, res: Response) => {
-    const requestedSlug = req.params.slug || 'index';
-    debug('Request for slug: %s', requestedSlug);
-
     try {
       // load manifest from disk
       const manifestPath = join(docsPath, 'manifest.json');
@@ -149,6 +146,8 @@ export function startServer(options: ServerOptions): Express {
         return;
       }
 
+      debug('Request for slug: %s', slug);
+
       // find the file for this slug
       const fileName = findPageBySlug(slug, manifest.pages);
       if (!fileName) {

From d69672d8bab8b4bbd56db1b6eb2beaaee5fafb7a Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 12:54:34 +0100
Subject: [PATCH 13/30] update startServer to return Server instance with close
 method

---
 .../plugin-docs-renderer/src/server.test.ts   | 62 +++++++++++++------
 packages/plugin-docs-renderer/src/server.ts   | 20 ++++--
 2 files changed, 58 insertions(+), 24 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/server.test.ts b/packages/plugin-docs-renderer/src/server.test.ts
index 2af5bf0261..2eeea58464 100644
--- a/packages/plugin-docs-renderer/src/server.test.ts
+++ b/packages/plugin-docs-renderer/src/server.test.ts
@@ -2,24 +2,24 @@ import { describe, it, expect, afterEach } from 'vitest';
 import request from 'supertest';
 import { join } from 'node:path';
 import type { Express } from 'express';
-import { startServer } from './server.js';
+import { startServer, type Server } from './server.js';
 
 describe('startServer', () => {
   const testDocsPath = join(__dirname, '__fixtures__', 'test-docs');
   let app: Express;
+  let server: Server | null = null;
 
-  afterEach(() => {
-    // cleanup: close any open connections
-    if (app) {
-      const server = (app as any).server;
-      if (server?.close) {
-        server.close();
-      }
+  afterEach(async () => {
+    if (server) {
+      await server.close();
+      server = null;
     }
   });
 
   it('should serve the homepage (first page in manifest)', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/');
 
@@ -30,7 +30,9 @@ describe('startServer', () => {
   });
 
   it('should serve a specific page by slug', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/guide');
 
@@ -41,7 +43,9 @@ describe('startServer', () => {
   });
 
   it('should serve a nested page by slug', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/advanced');
 
@@ -51,7 +55,9 @@ describe('startServer', () => {
   });
 
   it('should return 404 for non-existent page', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/non-existent');
 
@@ -60,7 +66,9 @@ describe('startServer', () => {
   });
 
   it('should include navigation links', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/');
 
@@ -71,7 +79,9 @@ describe('startServer', () => {
   });
 
   it('should serve static assets from img directory', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/img/test.png');
 
@@ -81,7 +91,9 @@ describe('startServer', () => {
   });
 
   it('should not include live reload script by default', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0, liveReload: false });
+    const result = startServer({ docsPath: testDocsPath, port: 0, liveReload: false });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/');
 
@@ -91,7 +103,9 @@ describe('startServer', () => {
   });
 
   it('should include live reload script when enabled', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0, liveReload: true });
+    const result = startServer({ docsPath: testDocsPath, port: 0, liveReload: true });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/');
 
@@ -101,7 +115,9 @@ describe('startServer', () => {
   });
 
   it('should have live reload endpoint when enabled', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0, liveReload: true });
+    const result = startServer({ docsPath: testDocsPath, port: 0, liveReload: true });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/__reload__?t=0');
 
@@ -110,7 +126,9 @@ describe('startServer', () => {
   });
 
   it('should use frontmatter title when available', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/home');
 
@@ -119,7 +137,9 @@ describe('startServer', () => {
   });
 
   it('should fallback to slug when no frontmatter title', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/advanced');
 
@@ -129,7 +149,9 @@ describe('startServer', () => {
   });
 
   it('should escape HTML entities in titles to prevent XSS', async () => {
-    app = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    server = result;
+    app = result.app;
 
     const response = await request(app).get('/');
 
diff --git a/packages/plugin-docs-renderer/src/server.ts b/packages/plugin-docs-renderer/src/server.ts
index 68acc9a8b6..440d30c998 100644
--- a/packages/plugin-docs-renderer/src/server.ts
+++ b/packages/plugin-docs-renderer/src/server.ts
@@ -15,6 +15,11 @@ export interface ServerOptions {
   liveReload?: boolean;
 }
 
+export interface Server {
+  app: Express;
+  close: () => Promise<void>;
+}
+
 // will support nested pages in the future
 function generateNavItems(pages: Page[]): string {
   return pages.map((page) => `<li><a href="/${escapeHtml(page.slug)}">${escapeHtml(page.title)}</a></li>`).join('\n');
@@ -76,9 +81,9 @@ function generatePageHTML(title: string, content: string, manifest: Manifest, li
  * Starts a development server for previewing plugin documentation.
  *
  * @param options - Server configuration options
- * @returns The Express app instance
+ * @returns Server instance with app and close method
  */
-export function startServer(options: ServerOptions): Express {
+export function startServer(options: ServerOptions): Server {
   const { docsPath, port = 3000, liveReload = false } = options;
 
   debug('Starting server with options: docsPath=%s, port=%d, liveReload=%s', docsPath, port, liveReload);
@@ -171,7 +176,7 @@ export function startServer(options: ServerOptions): Express {
   });
 
   // start the server
-  app.listen(port, () => {
+  const server = app.listen(port, () => {
     console.log(`\n📄 Plugin Documentation Server`);
     console.log(`✓ Serving: ${docsPath}`);
     console.log(`✓ URL: http://localhost:${port}`);
@@ -179,5 +184,12 @@ export function startServer(options: ServerOptions): Express {
     console.log(`\n🔍 Watching for changes...\n`);
   });
 
-  return app;
+  const close = async () => {
+    await watcher.close();
+    return new Promise<void>((resolve, reject) => {
+      server.close((err) => (err ? reject(err) : resolve()));
+    });
+  };
+
+  return { app, close };
 }

From a8ff3927e1a51dff859f0af525d38c78af61fa84 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 20:42:04 +0100
Subject: [PATCH 14/30] adding ejs templates

---
 packages/plugin-docs-renderer/src/server.ts   | 88 +++++--------------
 .../src/views/plugin-details-page.ejs         | 38 ++++++++
 2 files changed, 59 insertions(+), 67 deletions(-)
 create mode 100644 packages/plugin-docs-renderer/src/views/plugin-details-page.ejs

diff --git a/packages/plugin-docs-renderer/src/server.ts b/packages/plugin-docs-renderer/src/server.ts
index 440d30c998..9cfe9b563f 100644
--- a/packages/plugin-docs-renderer/src/server.ts
+++ b/packages/plugin-docs-renderer/src/server.ts
@@ -1,12 +1,16 @@
 import express, { type Express, type Request, type Response } from 'express';
 import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { watch } from 'chokidar';
 import createDebug from 'debug';
-import escapeHtml from 'escape-html';
 import { parseMarkdown } from './parser.js';
 import type { Manifest, Page } from './types.js';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
 const debug = createDebug('plugin-docs-renderer:server');
 
 export interface ServerOptions {
@@ -20,63 +24,6 @@ export interface Server {
   close: () => Promise<void>;
 }
 
-// will support nested pages in the future
-function generateNavItems(pages: Page[]): string {
-  return pages.map((page) => `<li><a href="/${escapeHtml(page.slug)}">${escapeHtml(page.title)}</a></li>`).join('\n');
-}
-
-/**
- * Generates an HTML template for a documentation page.
- */
-function generatePageHTML(title: string, content: string, manifest: Manifest, liveReload: boolean): string {
-  // generate a simple navigation from manifest
-  const navItems = generateNavItems(manifest.pages);
-
-  // optional live reload script
-  const reloadScript = liveReload
-    ? `
-    <script>
-      let lastCheck = Date.now();
-      setInterval(async () => {
-        try {
-          const res = await fetch('/__reload__?t=' + lastCheck);
-          if (res.status === 205) {
-            location.reload();
-          }
-          lastCheck = Date.now();
-        } catch (e) {
-          // Ignore fetch errors
-        }
-      }, 1000);
-    </script>
-  `
-    : '';
-
-  return `
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>${escapeHtml(title)} - ${escapeHtml(manifest.title)}</title>
-</head>
-<body>
-  <nav>
-    <h1>${escapeHtml(manifest.title)}</h1>
-    <ul>
-      ${navItems}
-    </ul>
-  </nav>
-  <hr>
-  <main>
-    ${content}
-  </main>
-  ${reloadScript}
-</body>
-</html>
-  `.trim();
-}
-
 /**
  * Starts a development server for previewing plugin documentation.
  *
@@ -91,13 +38,20 @@ export function startServer(options: ServerOptions): Server {
   const app = express();
   let lastModified = Date.now();
 
+  // configure EJS
+  app.set('view engine', 'ejs');
+  app.set('views', join(__dirname, 'views'));
+
+  const manifestPath = join(docsPath, 'manifest.json');
+  let manifest: Manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+
   // setup file watcher
   const watcher = watch([join(docsPath, '**/*.md'), join(docsPath, 'manifest.json')], {
     ignoreInitial: true,
   });
   debug('File watcher initialized for %s', docsPath);
 
-  watcher.on('change', async (path) => {
+  watcher.on('change', (path) => {
     debug('File changed: %s', path);
     lastModified = Date.now();
   });
@@ -138,11 +92,6 @@ export function startServer(options: ServerOptions): Server {
   // serve documentation pages
   app.get('/:slug?', async (req: Request, res: Response) => {
     try {
-      // load manifest from disk
-      const manifestPath = join(docsPath, 'manifest.json');
-      const manifestContent = await readFile(manifestPath, 'utf-8');
-      const manifest: Manifest = JSON.parse(manifestContent);
-
       // default to first page in manifest
       const slug = req.params.slug || manifest.pages[0]?.slug;
       if (!slug) {
@@ -167,8 +116,13 @@ export function startServer(options: ServerOptions): Server {
       const parsed = parseMarkdown(fileContent);
 
       const title = (parsed.frontmatter.title as string) || slug;
-      const html = generatePageHTML(title, parsed.html, manifest, liveReload);
-      res.send(html);
+
+      res.render('plugin-details-page', {
+        title,
+        content: parsed.html,
+        manifest,
+        liveReload,
+      });
     } catch (error) {
       console.error('Error serving page:', error);
       res.status(500).send('Internal server error');
diff --git a/packages/plugin-docs-renderer/src/views/plugin-details-page.ejs b/packages/plugin-docs-renderer/src/views/plugin-details-page.ejs
new file mode 100644
index 0000000000..adc7bc2159
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/views/plugin-details-page.ejs
@@ -0,0 +1,38 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title><%= title %> - <%= manifest.title %></title>
+</head>
+<body>
+  <nav>
+    <h1><%= manifest.title %></h1>
+    <ul>
+      <% manifest.pages.forEach(page => { %>
+        <li><a href="/<%= page.slug %>"><%= page.title %></a></li>
+      <% }); %>
+    </ul>
+  </nav>
+  <hr>
+  <main>
+    <%- content %>
+  </main>
+  <% if (liveReload) { %>
+  <script>
+    let lastCheck = Date.now();
+    setInterval(async () => {
+      try {
+        const res = await fetch('/__reload__?t=' + lastCheck);
+        if (res.status === 205) {
+          location.reload();
+        }
+        lastCheck = Date.now();
+      } catch (e) {
+        // Ignore fetch errors
+      }
+    }, 1000);
+  </script>
+  <% } %>
+</body>
+</html>

From 8ad1322eb45cd81f57403102befc63f49b1cf59e Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 20:42:18 +0100
Subject: [PATCH 15/30] add copyAssets function to rollup config for static
 asset handling

---
 rollup.config.ts | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/rollup.config.ts b/rollup.config.ts
index 9a2fd089a2..df0f1b7e0f 100644
--- a/rollup.config.ts
+++ b/rollup.config.ts
@@ -3,7 +3,7 @@ import json from '@rollup/plugin-json';
 import { nodeResolve } from '@rollup/plugin-node-resolve';
 import { glob, GlobOptions } from 'glob';
 import { readFileSync } from 'node:fs';
-import { chmod } from 'node:fs/promises';
+import { chmod, cp } from 'node:fs/promises';
 import { join } from 'node:path';
 import { inspect } from 'node:util';
 import { defineConfig, ExternalOption, Plugin, RollupOptions } from 'rollup';
@@ -76,6 +76,7 @@ const defaultOptions: Array<Partial<RollupOptions>> = [
         tsconfig: tsconfigPath,
       }),
       shebang(),
+      copyAssets(),
     ],
   },
 ];
@@ -126,3 +127,17 @@ function shebang(): Plugin {
     },
   };
 }
+
+// Copy static assets to dist
+function copyAssets(): Plugin {
+  return {
+    name: 'copy-assets',
+    async writeBundle() {
+      if (pkg.name === '@grafana/plugin-docs-renderer') {
+        const srcViews = join(projectRoot, 'src', 'views');
+        const distViews = join(projectRoot, 'dist', 'views');
+        await cp(srcViews, distViews, { recursive: true });
+      }
+    },
+  };
+}

From b6b0f45f60e017870f7ef3c44579971c26ac9923 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 20:54:58 +0100
Subject: [PATCH 16/30] put devtools inside cli folder

---
 packages/plugin-docs-renderer/src/bin/run.ts     |  2 +-
 packages/plugin-docs-renderer/src/index.ts       | 16 ++++------------
 .../src/{ => server}/server.test.ts              |  2 +-
 .../src/{ => server}/server.ts                   |  4 ++--
 .../{ => server}/views/plugin-details-page.ejs   |  0
 rollup.config.ts                                 |  4 ++--
 6 files changed, 10 insertions(+), 18 deletions(-)
 rename packages/plugin-docs-renderer/src/{ => server}/server.test.ts (98%)
 rename packages/plugin-docs-renderer/src/{ => server}/server.ts (97%)
 rename packages/plugin-docs-renderer/src/{ => server}/views/plugin-details-page.ejs (100%)

diff --git a/packages/plugin-docs-renderer/src/bin/run.ts b/packages/plugin-docs-renderer/src/bin/run.ts
index 50f949618c..7eb2f85f1e 100644
--- a/packages/plugin-docs-renderer/src/bin/run.ts
+++ b/packages/plugin-docs-renderer/src/bin/run.ts
@@ -3,7 +3,7 @@ import { access } from 'node:fs/promises';
 import { resolve } from 'node:path';
 import minimist from 'minimist';
 import createDebug from 'debug';
-import { startServer } from '../server.js';
+import { startServer } from '../server/server.js';
 
 const debug = createDebug('plugin-docs-renderer:cli');
 
diff --git a/packages/plugin-docs-renderer/src/index.ts b/packages/plugin-docs-renderer/src/index.ts
index f88cd2e52d..33578cc438 100644
--- a/packages/plugin-docs-renderer/src/index.ts
+++ b/packages/plugin-docs-renderer/src/index.ts
@@ -1,14 +1,6 @@
-// export types
-export type { Manifest, Page, MarkdownFiles } from './types.js';
-
-// export parser functions
-export { parseMarkdown } from './parser.js';
-export type { ParsedMarkdown } from './parser.js';
-
-// export loader functions
+// Library exports (server/CLI functions are not exported from main package)
 export { loadDocsFolder } from './loader.js';
 export type { LoadedDocs } from './loader.js';
-
-// export server functions
-export { startServer } from './server.js';
-export type { ServerOptions } from './server.js';
+export { parseMarkdown } from './parser.js';
+export type { ParsedMarkdown } from './parser.js';
+export type { Manifest, Page, MarkdownFiles } from './types.js';
diff --git a/packages/plugin-docs-renderer/src/server.test.ts b/packages/plugin-docs-renderer/src/server/server.test.ts
similarity index 98%
rename from packages/plugin-docs-renderer/src/server.test.ts
rename to packages/plugin-docs-renderer/src/server/server.test.ts
index 2eeea58464..4998233b5b 100644
--- a/packages/plugin-docs-renderer/src/server.test.ts
+++ b/packages/plugin-docs-renderer/src/server/server.test.ts
@@ -5,7 +5,7 @@ import type { Express } from 'express';
 import { startServer, type Server } from './server.js';
 
 describe('startServer', () => {
-  const testDocsPath = join(__dirname, '__fixtures__', 'test-docs');
+  const testDocsPath = join(__dirname, '..', '__fixtures__', 'test-docs');
   let app: Express;
   let server: Server | null = null;
 
diff --git a/packages/plugin-docs-renderer/src/server.ts b/packages/plugin-docs-renderer/src/server/server.ts
similarity index 97%
rename from packages/plugin-docs-renderer/src/server.ts
rename to packages/plugin-docs-renderer/src/server/server.ts
index 9cfe9b563f..d2faa765b8 100644
--- a/packages/plugin-docs-renderer/src/server.ts
+++ b/packages/plugin-docs-renderer/src/server/server.ts
@@ -5,8 +5,8 @@ import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { watch } from 'chokidar';
 import createDebug from 'debug';
-import { parseMarkdown } from './parser.js';
-import type { Manifest, Page } from './types.js';
+import { parseMarkdown } from '../parser.js';
+import type { Manifest, Page } from '../types.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
diff --git a/packages/plugin-docs-renderer/src/views/plugin-details-page.ejs b/packages/plugin-docs-renderer/src/server/views/plugin-details-page.ejs
similarity index 100%
rename from packages/plugin-docs-renderer/src/views/plugin-details-page.ejs
rename to packages/plugin-docs-renderer/src/server/views/plugin-details-page.ejs
diff --git a/rollup.config.ts b/rollup.config.ts
index df0f1b7e0f..a5db4b8de9 100644
--- a/rollup.config.ts
+++ b/rollup.config.ts
@@ -134,8 +134,8 @@ function copyAssets(): Plugin {
     name: 'copy-assets',
     async writeBundle() {
       if (pkg.name === '@grafana/plugin-docs-renderer') {
-        const srcViews = join(projectRoot, 'src', 'views');
-        const distViews = join(projectRoot, 'dist', 'views');
+        const srcViews = join(projectRoot, 'src', 'server', 'views');
+        const distViews = join(projectRoot, 'dist', 'server', 'views');
         await cp(srcViews, distViews, { recursive: true });
       }
     },

From 245a65fd0f61ff5c0b16650f978b0a10ce882392 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 21:24:07 +0100
Subject: [PATCH 17/30] add Frontmatter interface for markdown file metadata

---
 packages/plugin-docs-renderer/src/types.ts | 31 ++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/packages/plugin-docs-renderer/src/types.ts b/packages/plugin-docs-renderer/src/types.ts
index 4e9b7f5d25..4cc383f7df 100644
--- a/packages/plugin-docs-renderer/src/types.ts
+++ b/packages/plugin-docs-renderer/src/types.ts
@@ -55,3 +55,34 @@ export interface Manifest {
 export interface MarkdownFiles {
   [filePath: string]: string;
 }
+
+/**
+ * Frontmatter metadata from a markdown file.
+ */
+export interface Frontmatter {
+  /**
+   * The display title of the page.
+   */
+  title: string;
+
+  /**
+   * A brief description of the page content.
+   */
+  description: string;
+
+  /**
+   * The position of this page in the sidebar navigation (used for sorting).
+   * Pages with lower numbers appear first.
+   */
+  sidebar_position: number;
+
+  /**
+   * Optional custom URL slug. If not provided, generated from file path.
+   */
+  slug?: string;
+
+  /**
+   * Optional tags for SEO and categorization.
+   */
+  tags?: string[];
+}

From 25e85befd75d80df30be63866e4e16dcdaaa929c Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 21:26:21 +0100
Subject: [PATCH 18/30] moved loader out of lib and into cli

---
 packages/plugin-docs-renderer/src/{ => cli}/loader.ts | 0
 packages/plugin-docs-renderer/src/index.ts            | 7 +++----
 2 files changed, 3 insertions(+), 4 deletions(-)
 rename packages/plugin-docs-renderer/src/{ => cli}/loader.ts (100%)

diff --git a/packages/plugin-docs-renderer/src/loader.ts b/packages/plugin-docs-renderer/src/cli/loader.ts
similarity index 100%
rename from packages/plugin-docs-renderer/src/loader.ts
rename to packages/plugin-docs-renderer/src/cli/loader.ts
diff --git a/packages/plugin-docs-renderer/src/index.ts b/packages/plugin-docs-renderer/src/index.ts
index 33578cc438..aeda3d5aad 100644
--- a/packages/plugin-docs-renderer/src/index.ts
+++ b/packages/plugin-docs-renderer/src/index.ts
@@ -1,6 +1,5 @@
-// Library exports (server/CLI functions are not exported from main package)
-export { loadDocsFolder } from './loader.js';
-export type { LoadedDocs } from './loader.js';
+// Library exports - pure markdown parsing functions only
+// (CLI utilities like filesystem scanning are not exported)
 export { parseMarkdown } from './parser.js';
 export type { ParsedMarkdown } from './parser.js';
-export type { Manifest, Page, MarkdownFiles } from './types.js';
+export type { Manifest, Page, MarkdownFiles, Frontmatter } from './types.js';

From db0ba97d145867f774e644d960fed58c409b2e09 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Thu, 5 Feb 2026 22:05:56 +0100
Subject: [PATCH 19/30] add scanner functionality to process markdown files and
 generate documentation manifest

---
 .../plugin-docs-renderer/src/cli/scanner.ts   | 261 ++++++++++++++++++
 packages/plugin-docs-renderer/src/types.ts    |  11 -
 2 files changed, 261 insertions(+), 11 deletions(-)
 create mode 100644 packages/plugin-docs-renderer/src/cli/scanner.ts

diff --git a/packages/plugin-docs-renderer/src/cli/scanner.ts b/packages/plugin-docs-renderer/src/cli/scanner.ts
new file mode 100644
index 0000000000..5e0dec2070
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/cli/scanner.ts
@@ -0,0 +1,261 @@
+import { readFile } from 'node:fs/promises';
+import { join, relative, parse, sep } from 'node:path';
+import globby from 'globby';
+import GithubSlugger from 'github-slugger';
+import matter from 'gray-matter';
+import createDebug from 'debug';
+import type { Manifest, Page, MarkdownFiles, Frontmatter } from '../types.js';
+
+const debug = createDebug('plugin-docs-renderer:scanner');
+
+/**
+ * A scanned markdown file with parsed frontmatter.
+ */
+interface ScannedFile {
+  /**
+   * Absolute path to the file.
+   */
+  absolutePath: string;
+
+  /**
+   * Relative path from docs root (e.g., "01-overview.md" or "config/01-auth.md").
+   */
+  relativePath: string;
+
+  /**
+   * Parsed frontmatter metadata.
+   */
+  frontmatter: Frontmatter;
+
+  /**
+   * Raw markdown content (without frontmatter).
+   */
+  content: string;
+}
+
+/**
+ * Result of scanning a docs folder.
+ */
+export interface ScannedDocs {
+  /**
+   * Generated manifest from filesystem structure.
+   */
+  manifest: Manifest;
+
+  /**
+   * All markdown files indexed by their relative path.
+   */
+  files: MarkdownFiles;
+}
+
+/**
+ * Strips number prefix from a filename or folder name.
+ * Examples: "01-overview.md" → "overview.md", "02-config" → "config"
+ */
+function stripNumberPrefix(name: string): string {
+  return name.replace(/^\d+-/, '');
+}
+
+/**
+ * Generates a URL slug from a file path.
+ * Examples:
+ *   "01-overview.md" → "overview"
+ *   "config/01-auth.md" → "config/auth"
+ */
+function generateSlug(filePath: string): string {
+  const slugger = new GithubSlugger();
+  const parsed = parse(filePath);
+  const dir = parsed.dir ? parsed.dir.split(sep).map(stripNumberPrefix).join('/') : '';
+  const name = stripNumberPrefix(parsed.name);
+  const fullPath = dir ? `${dir}/${name}` : name;
+  return slugger.slug(fullPath);
+}
+
+/**
+ * Recursively scans a directory for markdown files and parses their frontmatter.
+ *
+ * @param docsPath - Absolute path to the docs folder
+ * @returns Array of scanned files with frontmatter
+ */
+async function scanMarkdownFiles(docsPath: string): Promise<ScannedFile[]> {
+  debug('Scanning for markdown files in: %s', docsPath);
+
+  // Find all .md files recursively
+  const pattern = join(docsPath, '**/*.md');
+  const filePaths = await globby(pattern, {
+    ignore: ['**/node_modules/**', '**/dist/**'],
+  });
+
+  debug('Found %d markdown file(s)', filePaths.length);
+
+  const scannedFiles: ScannedFile[] = [];
+
+  for (const absolutePath of filePaths) {
+    const relativePath = relative(docsPath, absolutePath);
+
+    // Read and parse the file
+    const fileContent = await readFile(absolutePath, 'utf-8');
+    const parsed = matter(fileContent);
+
+    // Validate frontmatter has required fields
+    const frontmatter = parsed.data as Partial<Frontmatter>;
+    if (!frontmatter.title || !frontmatter.description || frontmatter.sidebar_position === undefined) {
+      console.warn(
+        `Warning: ${relativePath} missing required frontmatter fields (title, description, sidebar_position)`
+      );
+      continue;
+    }
+
+    scannedFiles.push({
+      absolutePath,
+      relativePath,
+      frontmatter: frontmatter as Frontmatter,
+      content: parsed.content,
+    });
+  }
+
+  debug('Successfully scanned %d file(s) with valid frontmatter', scannedFiles.length);
+  return scannedFiles;
+}
+
+/**
+ * Tree node for building hierarchical structure.
+ */
+interface TreeNode {
+  name: string;
+  file?: ScannedFile;
+  children: Map<string, TreeNode>;
+}
+
+/**
+ * Builds a tree from file paths.
+ */
+function buildTree(scannedFiles: ScannedFile[]): TreeNode {
+  const root: TreeNode = { name: '', children: new Map() };
+
+  for (const file of scannedFiles) {
+    const parts = file.relativePath.split(sep);
+    let current = root;
+
+    // Navigate/create tree structure
+    for (let i = 0; i < parts.length - 1; i++) {
+      const part = parts[i];
+      if (!current.children.has(part)) {
+        current.children.set(part, { name: part, children: new Map() });
+      }
+      current = current.children.get(part)!;
+    }
+
+    // Add the file at the leaf
+    const fileName = parts[parts.length - 1];
+    current.children.set(fileName, {
+      name: fileName,
+      file,
+      children: new Map(),
+    });
+  }
+
+  return root;
+}
+
+/**
+ * Converts a tree node to Page array (recursively).
+ */
+function treeToPages(node: TreeNode): Page[] {
+  const pages: Page[] = [];
+
+  // Convert children to array and sort by sidebar_position
+  const childEntries = Array.from(node.children.entries());
+  const sortedEntries = childEntries.sort((a, b) => {
+    const aPos = a[1].file?.frontmatter.sidebar_position ?? Infinity;
+    const bPos = b[1].file?.frontmatter.sidebar_position ?? Infinity;
+    return aPos - bPos;
+  });
+
+  for (const [name, child] of sortedEntries) {
+    if (child.file) {
+      // It's a markdown file
+      const page: Page = {
+        title: child.file.frontmatter.title,
+        slug: child.file.frontmatter.slug || generateSlug(child.file.relativePath),
+        file: child.file.relativePath,
+      };
+
+      // If this file has children (folder with same name), add them
+      if (child.children.size > 0) {
+        page.children = treeToPages(child);
+      }
+
+      pages.push(page);
+    } else if (child.children.size > 0) {
+      // It's a directory without a file - create category
+      const categoryName = stripNumberPrefix(name);
+      const page: Page = {
+        title: categoryName.charAt(0).toUpperCase() + categoryName.slice(1).replace(/-/g, ' '),
+        slug: categoryName,
+        file: '',
+        children: treeToPages(child),
+      };
+      pages.push(page);
+    }
+  }
+
+  return pages;
+}
+
+/**
+ * Builds a hierarchical manifest from scanned files based on folder structure.
+ *
+ * @param scannedFiles - Array of scanned markdown files
+ * @returns Generated manifest
+ */
+function buildManifest(scannedFiles: ScannedFile[]): Manifest {
+  debug('Building manifest from %d file(s)', scannedFiles.length);
+
+  // Build tree structure from file paths
+  const tree = buildTree(scannedFiles);
+
+  // Convert tree to pages array
+  const pages = treeToPages(tree);
+
+  const manifest: Manifest = {
+    title: 'Plugin Documentation',
+    pages,
+  };
+
+  debug('Generated manifest with %d top-level page(s)', pages.length);
+  return manifest;
+}
+
+/**
+ * Scans a docs folder and generates a manifest from the filesystem structure.
+ *
+ * @param docsPath - Absolute path to the docs folder
+ * @returns Scanned docs with generated manifest and file contents
+ */
+export async function scanDocsFolder(docsPath: string): Promise<ScannedDocs> {
+  debug('Starting scan of docs folder: %s', docsPath);
+
+  // Scan all markdown files
+  const scannedFiles = await scanMarkdownFiles(docsPath);
+
+  if (scannedFiles.length === 0) {
+    throw new Error(`No valid markdown files found in ${docsPath}`);
+  }
+
+  // Build manifest from scanned files
+  const manifest = buildManifest(scannedFiles);
+
+  // Create files map
+  const files: MarkdownFiles = {};
+  for (const file of scannedFiles) {
+    files[file.relativePath] = file.content;
+  }
+
+  debug('Scan complete: %d files, %d pages', Object.keys(files).length, manifest.pages.length);
+
+  return {
+    manifest,
+    files,
+  };
+}
diff --git a/packages/plugin-docs-renderer/src/types.ts b/packages/plugin-docs-renderer/src/types.ts
index 4cc383f7df..8a5c10137d 100644
--- a/packages/plugin-docs-renderer/src/types.ts
+++ b/packages/plugin-docs-renderer/src/types.ts
@@ -1,9 +1,3 @@
-/**
- * Core types for the plugin documentation renderer.
- *
- * These types define the structure of documentation manifests and pages.
- */
-
 /**
  * Represents a documentation page in the manifest.
  */
@@ -33,11 +27,6 @@ export interface Page {
  * The documentation manifest that defines the structure and navigation.
  */
 export interface Manifest {
-  /**
-   * The manifest format version.
-   */
-  version: string;
-
   /**
    * The title of the documentation.
    */

From 70fa59154318a09ff3b403fd01b826275aa9709e Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Fri, 6 Feb 2026 07:03:39 +0100
Subject: [PATCH 20/30] update startServer to be async and integrate docs
 folder scanning for manifest generation

---
 packages/plugin-docs-renderer/src/bin/run.ts  |  3 +-
 .../plugin-docs-renderer/src/cli/scanner.ts   | 15 ++++++--
 .../plugin-docs-renderer/src/server/server.ts | 34 +++++++++++++------
 3 files changed, 37 insertions(+), 15 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/bin/run.ts b/packages/plugin-docs-renderer/src/bin/run.ts
index 7eb2f85f1e..b84dd8b115 100644
--- a/packages/plugin-docs-renderer/src/bin/run.ts
+++ b/packages/plugin-docs-renderer/src/bin/run.ts
@@ -11,7 +11,7 @@ async function commandServe(docsPath: string, port: number, liveReload: boolean)
   debug('Command serve: docsPath=%s, port=%d, liveReload=%s', docsPath, port, liveReload);
 
   try {
-    startServer({
+    await startServer({
       docsPath,
       port,
       liveReload,
@@ -23,6 +23,7 @@ async function commandServe(docsPath: string, port: number, liveReload: boolean)
     } else {
       console.error('Error starting server:', error);
     }
+    process.exit(1);
   }
 }
 
diff --git a/packages/plugin-docs-renderer/src/cli/scanner.ts b/packages/plugin-docs-renderer/src/cli/scanner.ts
index 5e0dec2070..841ac89317 100644
--- a/packages/plugin-docs-renderer/src/cli/scanner.ts
+++ b/packages/plugin-docs-renderer/src/cli/scanner.ts
@@ -65,10 +65,19 @@ function stripNumberPrefix(name: string): string {
 function generateSlug(filePath: string): string {
   const slugger = new GithubSlugger();
   const parsed = parse(filePath);
-  const dir = parsed.dir ? parsed.dir.split(sep).map(stripNumberPrefix).join('/') : '';
+
+  // Build slug parts by slugifying each segment separately
+  const parts: string[] = [];
+
+  if (parsed.dir) {
+    const dirParts = parsed.dir.split(sep).map(stripNumberPrefix);
+    parts.push(...dirParts.map((part) => slugger.slug(part)));
+  }
+
   const name = stripNumberPrefix(parsed.name);
-  const fullPath = dir ? `${dir}/${name}` : name;
-  return slugger.slug(fullPath);
+  parts.push(slugger.slug(name));
+
+  return parts.join('/');
 }
 
 /**
diff --git a/packages/plugin-docs-renderer/src/server/server.ts b/packages/plugin-docs-renderer/src/server/server.ts
index d2faa765b8..ec4150aaa8 100644
--- a/packages/plugin-docs-renderer/src/server/server.ts
+++ b/packages/plugin-docs-renderer/src/server/server.ts
@@ -1,11 +1,11 @@
 import express, { type Express, type Request, type Response } from 'express';
 import { readFile } from 'node:fs/promises';
-import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { watch } from 'chokidar';
 import createDebug from 'debug';
 import { parseMarkdown } from '../parser.js';
+import { scanDocsFolder } from '../cli/scanner.js';
 import type { Manifest, Page } from '../types.js';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -30,7 +30,7 @@ export interface Server {
  * @param options - Server configuration options
  * @returns Server instance with app and close method
  */
-export function startServer(options: ServerOptions): Server {
+export async function startServer(options: ServerOptions): Promise<Server> {
   const { docsPath, port = 3000, liveReload = false } = options;
 
   debug('Starting server with options: docsPath=%s, port=%d, liveReload=%s', docsPath, port, liveReload);
@@ -42,18 +42,29 @@ export function startServer(options: ServerOptions): Server {
   app.set('view engine', 'ejs');
   app.set('views', join(__dirname, 'views'));
 
-  const manifestPath = join(docsPath, 'manifest.json');
-  let manifest: Manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  // Scan filesystem and generate manifest
+  debug('Scanning docs folder: %s', docsPath);
+  const scanned = await scanDocsFolder(docsPath);
+  let manifest: Manifest = scanned.manifest;
+  debug('Manifest generated with %d pages', manifest.pages.length);
 
-  // setup file watcher
-  const watcher = watch([join(docsPath, '**/*.md'), join(docsPath, 'manifest.json')], {
+  // setup file watcher for markdown files
+  const watcher = watch(join(docsPath, '**/*.md'), {
     ignoreInitial: true,
   });
   debug('File watcher initialized for %s', docsPath);
 
-  watcher.on('change', (path) => {
+  watcher.on('change', async (path) => {
     debug('File changed: %s', path);
     lastModified = Date.now();
+
+    // scan again to update manifest
+    try {
+      const rescanned = await scanDocsFolder(docsPath);
+      manifest = rescanned.manifest;
+    } catch (error) {
+      console.error('Error re-scanning docs folder:', error);
+    }
   });
 
   // serve static assets
@@ -89,11 +100,12 @@ export function startServer(options: ServerOptions): Server {
     return null;
   }
 
-  // serve documentation pages
-  app.get('/:slug?', async (req: Request, res: Response) => {
+  // serve documentation pages (matches single and nested paths)
+  app.get('*', async (req: Request, res: Response) => {
     try {
-      // default to first page in manifest
-      const slug = req.params.slug || manifest.pages[0]?.slug;
+      // Extract slug from path (remove leading slash)
+      const slug = req.path === '/' ? manifest.pages[0]?.slug || '' : req.path.slice(1);
+
       if (!slug) {
         debug('No pages found in manifest');
         res.status(404).send('No pages found in manifest');

From 6a6e1d15823789edd76cdf952e8fc37e1e186c90 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Fri, 6 Feb 2026 07:13:50 +0100
Subject: [PATCH 21/30] load markdown files into memory and improve manifest
 logging

---
 .../plugin-docs-renderer/src/server/server.ts | 20 ++++++++++++-------
 1 file changed, 13 insertions(+), 7 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/server/server.ts b/packages/plugin-docs-renderer/src/server/server.ts
index ec4150aaa8..10fddbf1ef 100644
--- a/packages/plugin-docs-renderer/src/server/server.ts
+++ b/packages/plugin-docs-renderer/src/server/server.ts
@@ -1,12 +1,11 @@
 import express, { type Express, type Request, type Response } from 'express';
-import { readFile } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { watch } from 'chokidar';
 import createDebug from 'debug';
 import { parseMarkdown } from '../parser.js';
 import { scanDocsFolder } from '../cli/scanner.js';
-import type { Manifest, Page } from '../types.js';
+import type { Manifest, Page, MarkdownFiles } from '../types.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -42,11 +41,12 @@ export async function startServer(options: ServerOptions): Promise<Server> {
   app.set('view engine', 'ejs');
   app.set('views', join(__dirname, 'views'));
 
-  // Scan filesystem and generate manifest
+  // Scan filesystem and generate manifest + load files into memory
   debug('Scanning docs folder: %s', docsPath);
   const scanned = await scanDocsFolder(docsPath);
   let manifest: Manifest = scanned.manifest;
-  debug('Manifest generated with %d pages', manifest.pages.length);
+  let files: MarkdownFiles = scanned.files;
+  debug('Manifest generated with %d pages, %d files loaded', manifest.pages.length, Object.keys(files).length);
 
   // setup file watcher for markdown files
   const watcher = watch(join(docsPath, '**/*.md'), {
@@ -62,6 +62,7 @@ export async function startServer(options: ServerOptions): Promise<Server> {
     try {
       const rescanned = await scanDocsFolder(docsPath);
       manifest = rescanned.manifest;
+      files = rescanned.files;
     } catch (error) {
       console.error('Error re-scanning docs folder:', error);
     }
@@ -122,9 +123,14 @@ export async function startServer(options: ServerOptions): Promise<Server> {
         return;
       }
 
-      // read and parse the markdown file
-      const filePath = join(docsPath, fileName);
-      const fileContent = await readFile(filePath, 'utf-8');
+      // get markdown content from memory
+      const fileContent = files[fileName];
+      if (!fileContent) {
+        debug('File content not found in memory for: %s', fileName);
+        res.status(404).send('File content not found');
+        return;
+      }
+
       const parsed = parseMarkdown(fileContent);
 
       const title = (parsed.frontmatter.title as string) || slug;

From 62ecb867ce1b5d0dc0397b980711e8e409f58407 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Fri, 6 Feb 2026 07:34:42 +0100
Subject: [PATCH 22/30] fix tests and self review

---
 .../src/__fixtures__/test-docs/advanced.md    |  6 +++
 .../src/__fixtures__/test-docs/guide.md       |  2 +
 .../src/__fixtures__/test-docs/home.md        |  1 +
 .../plugin-docs-renderer/src/cli/loader.ts    |  4 +-
 .../plugin-docs-renderer/src/cli/scanner.ts   | 54 ++++++++-----------
 .../plugin-docs-renderer/src/index.test.ts    |  3 +-
 .../src/server/server.test.ts                 | 40 +++++++-------
 7 files changed, 54 insertions(+), 56 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/advanced.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/advanced.md
index 9652de2cc8..e8c13a1826 100644
--- a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/advanced.md
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/advanced.md
@@ -1,3 +1,9 @@
+---
+title: Advanced Topics
+description: Advanced topics for experienced users
+sidebar_position: 3
+---
+
 # Advanced Topics
 
 This covers advanced topics.
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/guide.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/guide.md
index 069356d512..04f22a6cde 100644
--- a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/guide.md
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/guide.md
@@ -1,5 +1,7 @@
 ---
 title: User Guide
+description: A guide page for users
+sidebar_position: 2
 ---
 
 # User Guide
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/home.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/home.md
index afe70d0eaf..fb408829af 100644
--- a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/home.md
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/home.md
@@ -1,6 +1,7 @@
 ---
 title: Home Page
 description: Welcome to the test docs
+sidebar_position: 1
 ---
 
 # Welcome
diff --git a/packages/plugin-docs-renderer/src/cli/loader.ts b/packages/plugin-docs-renderer/src/cli/loader.ts
index d8d782d5d3..be0f85a25d 100644
--- a/packages/plugin-docs-renderer/src/cli/loader.ts
+++ b/packages/plugin-docs-renderer/src/cli/loader.ts
@@ -1,7 +1,7 @@
 import { readFile, readdir } from 'node:fs/promises';
 import { join, relative } from 'node:path';
 import createDebug from 'debug';
-import type { Manifest, MarkdownFiles } from './types.js';
+import type { Manifest, MarkdownFiles } from '../types.js';
 
 const debug = createDebug('plugin-docs-renderer:loader');
 
@@ -82,7 +82,7 @@ export async function loadDocsFolder(rootPath: string): Promise<LoadedDocs> {
   let manifest;
   try {
     manifest = JSON.parse(manifestContent) as Manifest;
-    debug('Parsed manifest: title=%s, version=%s, pages=%d', manifest.title, manifest.version, manifest.pages.length);
+    debug('Parsed manifest: title=%s, pages=%d', manifest.title, manifest.pages.length);
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(`Failed to parse manifest.json: ${message}`);
diff --git a/packages/plugin-docs-renderer/src/cli/scanner.ts b/packages/plugin-docs-renderer/src/cli/scanner.ts
index 841ac89317..420185c03d 100644
--- a/packages/plugin-docs-renderer/src/cli/scanner.ts
+++ b/packages/plugin-docs-renderer/src/cli/scanner.ts
@@ -48,34 +48,25 @@ export interface ScannedDocs {
   files: MarkdownFiles;
 }
 
-/**
- * Strips number prefix from a filename or folder name.
- * Examples: "01-overview.md" → "overview.md", "02-config" → "config"
- */
-function stripNumberPrefix(name: string): string {
-  return name.replace(/^\d+-/, '');
-}
-
 /**
  * Generates a URL slug from a file path.
  * Examples:
- *   "01-overview.md" → "overview"
- *   "config/01-auth.md" → "config/auth"
+ *   "overview.md" → "overview"
+ *   "config/auth.md" → "config/auth"
  */
 function generateSlug(filePath: string): string {
   const slugger = new GithubSlugger();
   const parsed = parse(filePath);
 
-  // Build slug parts by slugifying each segment separately
+  // build slug parts by slugifying each segment separately
   const parts: string[] = [];
 
   if (parsed.dir) {
-    const dirParts = parsed.dir.split(sep).map(stripNumberPrefix);
+    const dirParts = parsed.dir.split(sep);
     parts.push(...dirParts.map((part) => slugger.slug(part)));
   }
 
-  const name = stripNumberPrefix(parsed.name);
-  parts.push(slugger.slug(name));
+  parts.push(slugger.slug(parsed.name));
 
   return parts.join('/');
 }
@@ -89,7 +80,7 @@ function generateSlug(filePath: string): string {
 async function scanMarkdownFiles(docsPath: string): Promise<ScannedFile[]> {
   debug('Scanning for markdown files in: %s', docsPath);
 
-  // Find all .md files recursively
+  // find all .md files recursively
   const pattern = join(docsPath, '**/*.md');
   const filePaths = await globby(pattern, {
     ignore: ['**/node_modules/**', '**/dist/**'],
@@ -102,11 +93,11 @@ async function scanMarkdownFiles(docsPath: string): Promise<ScannedFile[]> {
   for (const absolutePath of filePaths) {
     const relativePath = relative(docsPath, absolutePath);
 
-    // Read and parse the file
+    // read and parse the file
     const fileContent = await readFile(absolutePath, 'utf-8');
     const parsed = matter(fileContent);
 
-    // Validate frontmatter has required fields
+    // validate frontmatter has required fields
     const frontmatter = parsed.data as Partial<Frontmatter>;
     if (!frontmatter.title || !frontmatter.description || frontmatter.sidebar_position === undefined) {
       console.warn(
@@ -119,7 +110,7 @@ async function scanMarkdownFiles(docsPath: string): Promise<ScannedFile[]> {
       absolutePath,
       relativePath,
       frontmatter: frontmatter as Frontmatter,
-      content: parsed.content,
+      content: fileContent, // store original content with frontmatter
     });
   }
 
@@ -146,7 +137,7 @@ function buildTree(scannedFiles: ScannedFile[]): TreeNode {
     const parts = file.relativePath.split(sep);
     let current = root;
 
-    // Navigate/create tree structure
+    // navigate/create tree structure
     for (let i = 0; i < parts.length - 1; i++) {
       const part = parts[i];
       if (!current.children.has(part)) {
@@ -155,7 +146,7 @@ function buildTree(scannedFiles: ScannedFile[]): TreeNode {
       current = current.children.get(part)!;
     }
 
-    // Add the file at the leaf
+    // add the file at the leaf
     const fileName = parts[parts.length - 1];
     current.children.set(fileName, {
       name: fileName,
@@ -173,7 +164,7 @@ function buildTree(scannedFiles: ScannedFile[]): TreeNode {
 function treeToPages(node: TreeNode): Page[] {
   const pages: Page[] = [];
 
-  // Convert children to array and sort by sidebar_position
+  // convert children to array and sort by sidebar_position
   const childEntries = Array.from(node.children.entries());
   const sortedEntries = childEntries.sort((a, b) => {
     const aPos = a[1].file?.frontmatter.sidebar_position ?? Infinity;
@@ -183,25 +174,24 @@ function treeToPages(node: TreeNode): Page[] {
 
   for (const [name, child] of sortedEntries) {
     if (child.file) {
-      // It's a markdown file
+      // it's a markdown file
       const page: Page = {
         title: child.file.frontmatter.title,
         slug: child.file.frontmatter.slug || generateSlug(child.file.relativePath),
         file: child.file.relativePath,
       };
 
-      // If this file has children (folder with same name), add them
+      // if this file has children (folder with same name), add them
       if (child.children.size > 0) {
         page.children = treeToPages(child);
       }
 
       pages.push(page);
     } else if (child.children.size > 0) {
-      // It's a directory without a file - create category
-      const categoryName = stripNumberPrefix(name);
+      // it's a directory without a file - create category
       const page: Page = {
-        title: categoryName.charAt(0).toUpperCase() + categoryName.slice(1).replace(/-/g, ' '),
-        slug: categoryName,
+        title: name.charAt(0).toUpperCase() + name.slice(1).replace(/-/g, ' '),
+        slug: name,
         file: '',
         children: treeToPages(child),
       };
@@ -221,10 +211,10 @@ function treeToPages(node: TreeNode): Page[] {
 function buildManifest(scannedFiles: ScannedFile[]): Manifest {
   debug('Building manifest from %d file(s)', scannedFiles.length);
 
-  // Build tree structure from file paths
+  // build tree structure from file paths
   const tree = buildTree(scannedFiles);
 
-  // Convert tree to pages array
+  // convert tree to pages array
   const pages = treeToPages(tree);
 
   const manifest: Manifest = {
@@ -245,17 +235,17 @@ function buildManifest(scannedFiles: ScannedFile[]): Manifest {
 export async function scanDocsFolder(docsPath: string): Promise<ScannedDocs> {
   debug('Starting scan of docs folder: %s', docsPath);
 
-  // Scan all markdown files
+  // scan all markdown files
   const scannedFiles = await scanMarkdownFiles(docsPath);
 
   if (scannedFiles.length === 0) {
     throw new Error(`No valid markdown files found in ${docsPath}`);
   }
 
-  // Build manifest from scanned files
+  // build manifest from scanned files
   const manifest = buildManifest(scannedFiles);
 
-  // Create files map
+  // create files map
   const files: MarkdownFiles = {};
   for (const file of scannedFiles) {
     files[file.relativePath] = file.content;
diff --git a/packages/plugin-docs-renderer/src/index.test.ts b/packages/plugin-docs-renderer/src/index.test.ts
index 4c3cfed236..e810a42989 100644
--- a/packages/plugin-docs-renderer/src/index.test.ts
+++ b/packages/plugin-docs-renderer/src/index.test.ts
@@ -4,7 +4,6 @@ import type { Manifest, Page, MarkdownFiles } from './index.js';
 describe('@grafana/plugin-docs-renderer', () => {
   it('should export core types', () => {
     const manifest: Manifest = {
-      version: '1.0',
       title: 'Test Documentation',
       pages: [],
     };
@@ -19,7 +18,7 @@ describe('@grafana/plugin-docs-renderer', () => {
       'index.md': '# Overview',
     };
 
-    expect(manifest.version).toBe('1.0');
+    expect(manifest.title).toBe('Test Documentation');
     expect(page.title).toBe('Overview');
     expect(files['index.md']).toBe('# Overview');
   });
diff --git a/packages/plugin-docs-renderer/src/server/server.test.ts b/packages/plugin-docs-renderer/src/server/server.test.ts
index 4998233b5b..32cd7d318e 100644
--- a/packages/plugin-docs-renderer/src/server/server.test.ts
+++ b/packages/plugin-docs-renderer/src/server/server.test.ts
@@ -17,33 +17,33 @@ describe('startServer', () => {
   });
 
   it('should serve the homepage (first page in manifest)', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = await startServer({ docsPath: testDocsPath, port: 0 });
     server = result;
     app = result.app;
 
     const response = await request(app).get('/');
 
     expect(response.status).toBe(200);
-    expect(response.text).toContain('<title>Home Page - Test Plugin Documentation</title>');
+    expect(response.text).toContain('<title>Home Page - Plugin Documentation</title>');
     expect(response.text).toContain('<h1>Welcome</h1>');
     expect(response.text).toContain('This is the home page of the test documentation.');
   });
 
   it('should serve a specific page by slug', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = await startServer({ docsPath: testDocsPath, port: 0 });
     server = result;
     app = result.app;
 
     const response = await request(app).get('/guide');
 
     expect(response.status).toBe(200);
-    expect(response.text).toContain('<title>User Guide - Test Plugin Documentation</title>');
+    expect(response.text).toContain('<title>User Guide - Plugin Documentation</title>');
     expect(response.text).toContain('<h1>User Guide</h1>');
     expect(response.text).toContain('This is a guide page.');
   });
 
   it('should serve a nested page by slug', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = await startServer({ docsPath: testDocsPath, port: 0 });
     server = result;
     app = result.app;
 
@@ -55,7 +55,7 @@ describe('startServer', () => {
   });
 
   it('should return 404 for non-existent page', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = await startServer({ docsPath: testDocsPath, port: 0 });
     server = result;
     app = result.app;
 
@@ -66,7 +66,7 @@ describe('startServer', () => {
   });
 
   it('should include navigation links', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = await startServer({ docsPath: testDocsPath, port: 0 });
     server = result;
     app = result.app;
 
@@ -74,12 +74,12 @@ describe('startServer', () => {
 
     expect(response.status).toBe(200);
     expect(response.text).toContain('<nav>');
-    expect(response.text).toContain('<a href="/home">Home</a>');
-    expect(response.text).toContain('<a href="/guide">Guide</a>');
+    expect(response.text).toContain('<a href="/home">Home Page</a>');
+    expect(response.text).toContain('<a href="/guide">User Guide</a>');
   });
 
   it('should serve static assets from img directory', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = await startServer({ docsPath: testDocsPath, port: 0 });
     server = result;
     app = result.app;
 
@@ -91,7 +91,7 @@ describe('startServer', () => {
   });
 
   it('should not include live reload script by default', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0, liveReload: false });
+    const result = await startServer({ docsPath: testDocsPath, port: 0, liveReload: false });
     server = result;
     app = result.app;
 
@@ -103,7 +103,7 @@ describe('startServer', () => {
   });
 
   it('should include live reload script when enabled', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0, liveReload: true });
+    const result = await startServer({ docsPath: testDocsPath, port: 0, liveReload: true });
     server = result;
     app = result.app;
 
@@ -115,7 +115,7 @@ describe('startServer', () => {
   });
 
   it('should have live reload endpoint when enabled', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0, liveReload: true });
+    const result = await startServer({ docsPath: testDocsPath, port: 0, liveReload: true });
     server = result;
     app = result.app;
 
@@ -126,30 +126,30 @@ describe('startServer', () => {
   });
 
   it('should use frontmatter title when available', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = await startServer({ docsPath: testDocsPath, port: 0 });
     server = result;
     app = result.app;
 
     const response = await request(app).get('/home');
 
     expect(response.status).toBe(200);
-    expect(response.text).toContain('<title>Home Page - Test Plugin Documentation</title>');
+    expect(response.text).toContain('<title>Home Page - Plugin Documentation</title>');
   });
 
-  it('should fallback to slug when no frontmatter title', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0 });
+  it('should use frontmatter title from advanced page', async () => {
+    const result = await startServer({ docsPath: testDocsPath, port: 0 });
     server = result;
     app = result.app;
 
     const response = await request(app).get('/advanced');
 
     expect(response.status).toBe(200);
-    // should use slug as fallback since advanced.md has no frontmatter title
-    expect(response.text).toContain('<title>advanced - Test Plugin Documentation</title>');
+    // advanced.md now has frontmatter with title
+    expect(response.text).toContain('<title>Advanced Topics - Plugin Documentation</title>');
   });
 
   it('should escape HTML entities in titles to prevent XSS', async () => {
-    const result = startServer({ docsPath: testDocsPath, port: 0 });
+    const result = await startServer({ docsPath: testDocsPath, port: 0 });
     server = result;
     app = result.app;
 

From 70fa36305b31eeed46a90ae75f76e2f5f29d0319 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Fri, 6 Feb 2026 07:53:32 +0100
Subject: [PATCH 23/30] add scanner tests

---
 .../src/cli/scanner.test.ts                   | 70 +++++++++++++++++++
 .../plugin-docs-renderer/src/cli/scanner.ts   | 16 ++---
 2 files changed, 75 insertions(+), 11 deletions(-)
 create mode 100644 packages/plugin-docs-renderer/src/cli/scanner.test.ts

diff --git a/packages/plugin-docs-renderer/src/cli/scanner.test.ts b/packages/plugin-docs-renderer/src/cli/scanner.test.ts
new file mode 100644
index 0000000000..da0d6ae916
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/cli/scanner.test.ts
@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest';
+import { join } from 'node:path';
+import { scanDocsFolder } from './scanner.js';
+
+describe('scanDocsFolder', () => {
+  const testDocsPath = join(__dirname, '..', '__fixtures__', 'test-docs');
+
+  it('should scan markdown files and generate manifest', async () => {
+    const result = await scanDocsFolder(testDocsPath);
+
+    expect(result.manifest).toBeDefined();
+    expect(result.manifest.title).toBe('Plugin Documentation');
+    expect(result.manifest.pages).toHaveLength(3);
+  });
+
+  it('should sort pages by sidebar_position', async () => {
+    const result = await scanDocsFolder(testDocsPath);
+
+    const pages = result.manifest.pages;
+    expect(pages[0].title).toBe('Home Page');
+    expect(pages[0].slug).toBe('home');
+    expect(pages[1].title).toBe('User Guide');
+    expect(pages[1].slug).toBe('guide');
+    expect(pages[2].title).toBe('Advanced Topics');
+    expect(pages[2].slug).toBe('advanced');
+  });
+
+  it('should generate slugs from file paths', async () => {
+    const result = await scanDocsFolder(testDocsPath);
+
+    const pages = result.manifest.pages;
+    expect(pages[0].slug).toBe('home');
+    expect(pages[1].slug).toBe('guide');
+    expect(pages[2].slug).toBe('advanced');
+  });
+
+  it('should load file contents into memory', async () => {
+    const result = await scanDocsFolder(testDocsPath);
+
+    expect(result.files).toBeDefined();
+    expect(Object.keys(result.files)).toHaveLength(3);
+    expect(result.files['home.md']).toContain('---');
+    expect(result.files['home.md']).toContain('title: Home Page');
+    expect(result.files['home.md']).toContain('# Welcome');
+  });
+
+  it('should preserve frontmatter in file contents', async () => {
+    const result = await scanDocsFolder(testDocsPath);
+
+    const homeContent = result.files['home.md'];
+    expect(homeContent).toContain('title: Home Page');
+    expect(homeContent).toContain('description: Welcome to the test docs');
+    expect(homeContent).toContain('sidebar_position: 1');
+  });
+
+  it('should include file reference in page object', async () => {
+    const result = await scanDocsFolder(testDocsPath);
+
+    const pages = result.manifest.pages;
+    expect(pages[0].file).toBe('home.md');
+    expect(pages[1].file).toBe('guide.md');
+    expect(pages[2].file).toBe('advanced.md');
+  });
+
+  it('should throw error when no valid markdown files found', async () => {
+    const emptyPath = join(__dirname, '..', '__fixtures__', 'non-existent');
+
+    await expect(scanDocsFolder(emptyPath)).rejects.toThrow('No valid markdown files found');
+  });
+});
diff --git a/packages/plugin-docs-renderer/src/cli/scanner.ts b/packages/plugin-docs-renderer/src/cli/scanner.ts
index 420185c03d..1c0a04d661 100644
--- a/packages/plugin-docs-renderer/src/cli/scanner.ts
+++ b/packages/plugin-docs-renderer/src/cli/scanner.ts
@@ -127,9 +127,6 @@ interface TreeNode {
   children: Map<string, TreeNode>;
 }
 
-/**
- * Builds a tree from file paths.
- */
 function buildTree(scannedFiles: ScannedFile[]): TreeNode {
   const root: TreeNode = { name: '', children: new Map() };
 
@@ -158,19 +155,16 @@ function buildTree(scannedFiles: ScannedFile[]): TreeNode {
   return root;
 }
 
-/**
- * Converts a tree node to Page array (recursively).
- */
+// converts a tree node to Page array (recursively).
 function treeToPages(node: TreeNode): Page[] {
   const pages: Page[] = [];
 
   // convert children to array and sort by sidebar_position
   const childEntries = Array.from(node.children.entries());
-  const sortedEntries = childEntries.sort((a, b) => {
-    const aPos = a[1].file?.frontmatter.sidebar_position ?? Infinity;
-    const bPos = b[1].file?.frontmatter.sidebar_position ?? Infinity;
-    return aPos - bPos;
-  });
+  const sortedEntries = childEntries.sort(
+    (a, b) =>
+      (a[1].file?.frontmatter.sidebar_position ?? Infinity) - (b[1].file?.frontmatter.sidebar_position ?? Infinity)
+  );
 
   for (const [name, child] of sortedEntries) {
     if (child.file) {

From d9eb066ea233c597622421a7a627eec28977ec21 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Fri, 6 Feb 2026 07:55:14 +0100
Subject: [PATCH 24/30] remove ununsed loader file

---
 .../plugin-docs-renderer/src/cli/loader.ts    | 121 ------------------
 1 file changed, 121 deletions(-)
 delete mode 100644 packages/plugin-docs-renderer/src/cli/loader.ts

diff --git a/packages/plugin-docs-renderer/src/cli/loader.ts b/packages/plugin-docs-renderer/src/cli/loader.ts
deleted file mode 100644
index be0f85a25d..0000000000
--- a/packages/plugin-docs-renderer/src/cli/loader.ts
+++ /dev/null
@@ -1,121 +0,0 @@
-import { readFile, readdir } from 'node:fs/promises';
-import { join, relative } from 'node:path';
-import createDebug from 'debug';
-import type { Manifest, MarkdownFiles } from '../types.js';
-
-const debug = createDebug('plugin-docs-renderer:loader');
-
-/**
- * Result of loading a docs folder.
- */
-export interface LoadedDocs {
-  /**
-   * The parsed manifest.json.
-   */
-  manifest: Manifest;
-
-  /**
-   * All markdown files indexed by their relative path.
-   */
-  files: MarkdownFiles;
-}
-
-/**
- * Recursively finds all markdown files in a directory.
- *
- * @param dir - The directory to search
- * @param baseDir - The base directory for calculating relative paths
- * @returns Array of absolute file paths
- */
-async function findMarkdownFiles(dir: string, baseDir: string): Promise<string[]> {
-  const files: string[] = [];
-  debug('Searching for markdown files in %s', dir);
-
-  let entries;
-  try {
-    entries = await readdir(dir, { withFileTypes: true });
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to read directory ${dir}: ${message}`);
-  }
-
-  for (const entry of entries) {
-    const fullPath = join(dir, entry.name);
-
-    if (entry.isDirectory()) {
-      // recursively search subdirectories
-      debug('Found subdirectory: %s', entry.name);
-      const subFiles = await findMarkdownFiles(fullPath, baseDir);
-      files.push(...subFiles);
-    } else if (entry.isFile() && entry.name.endsWith('.md')) {
-      debug('Found markdown file: %s', entry.name);
-      files.push(fullPath);
-    }
-  }
-
-  debug('Found %d markdown file(s) in %s', files.length, dir);
-  return files;
-}
-
-/**
- * Loads a documentation folder containing manifest.json and markdown files.
- *
- * @param rootPath - The absolute path to the docs folder
- * @returns The loaded manifest and markdown files
- * @throws {Error} If manifest.json is not found or invalid
- */
-export async function loadDocsFolder(rootPath: string): Promise<LoadedDocs> {
-  debug('Loading docs folder: %s', rootPath);
-
-  // read and parse manifest.json
-  const manifestPath = join(rootPath, 'manifest.json');
-  debug('Reading manifest from: %s', manifestPath);
-
-  let manifestContent;
-  try {
-    manifestContent = await readFile(manifestPath, 'utf-8');
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to read manifest.json at ${manifestPath}: ${message}`);
-  }
-
-  let manifest;
-  try {
-    manifest = JSON.parse(manifestContent) as Manifest;
-    debug('Parsed manifest: title=%s, pages=%d', manifest.title, manifest.pages.length);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to parse manifest.json: ${message}`);
-  }
-
-  // find all markdown files
-  let markdownPaths;
-  try {
-    markdownPaths = await findMarkdownFiles(rootPath, rootPath);
-    debug('Found %d total markdown file(s)', markdownPaths.length);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to find markdown files in ${rootPath}: ${message}`);
-  }
-
-  // read all markdown files
-  const files: MarkdownFiles = {};
-  for (const filePath of markdownPaths) {
-    const relativePath = relative(rootPath, filePath);
-    debug('Reading markdown file: %s', relativePath);
-
-    try {
-      const content = await readFile(filePath, 'utf-8');
-      files[relativePath] = content;
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`Failed to read markdown file ${relativePath}: ${message}`);
-    }
-  }
-
-  debug('Successfully loaded docs folder with %d file(s)', Object.keys(files).length);
-  return {
-    manifest,
-    files,
-  };
-}

From 0c60c8f3f74c9a887b9a8a37f569f8456b91c930 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Fri, 6 Feb 2026 08:00:25 +0100
Subject: [PATCH 25/30] update tests for nested directory handling

---
 .../__fixtures__/test-docs/config/database.md |  9 +++
 .../__fixtures__/test-docs/config/settings.md |  9 +++
 .../src/__fixtures__/test-docs/manifest.json  | 23 --------
 .../src/cli/scanner.test.ts                   | 55 ++++++++++++++++++-
 4 files changed, 71 insertions(+), 25 deletions(-)
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs/config/database.md
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs/config/settings.md
 delete mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs/manifest.json

diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/config/database.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/config/database.md
new file mode 100644
index 0000000000..ccf14c8e5c
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/config/database.md
@@ -0,0 +1,9 @@
+---
+title: Database
+description: Database configuration options
+sidebar_position: 2
+---
+
+# Database
+
+Configure database connections.
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/config/settings.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/config/settings.md
new file mode 100644
index 0000000000..0dbb492f7e
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/config/settings.md
@@ -0,0 +1,9 @@
+---
+title: Settings
+description: Configuration settings
+sidebar_position: 1
+---
+
+# Settings
+
+Configure your plugin settings here.
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/manifest.json b/packages/plugin-docs-renderer/src/__fixtures__/test-docs/manifest.json
deleted file mode 100644
index fe31a9bd5c..0000000000
--- a/packages/plugin-docs-renderer/src/__fixtures__/test-docs/manifest.json
+++ /dev/null
@@ -1,23 +0,0 @@
-{
-  "version": "1.0",
-  "title": "Test Plugin Documentation",
-  "pages": [
-    {
-      "title": "Home",
-      "slug": "home",
-      "file": "home.md"
-    },
-    {
-      "title": "Guide",
-      "slug": "guide",
-      "file": "guide.md",
-      "children": [
-        {
-          "title": "Advanced",
-          "slug": "advanced",
-          "file": "advanced.md"
-        }
-      ]
-    }
-  ]
-}
diff --git a/packages/plugin-docs-renderer/src/cli/scanner.test.ts b/packages/plugin-docs-renderer/src/cli/scanner.test.ts
index da0d6ae916..ffc6e77d03 100644
--- a/packages/plugin-docs-renderer/src/cli/scanner.test.ts
+++ b/packages/plugin-docs-renderer/src/cli/scanner.test.ts
@@ -10,7 +10,7 @@ describe('scanDocsFolder', () => {
 
     expect(result.manifest).toBeDefined();
     expect(result.manifest.title).toBe('Plugin Documentation');
-    expect(result.manifest.pages).toHaveLength(3);
+    expect(result.manifest.pages).toHaveLength(4); // home, guide, advanced, config
   });
 
   it('should sort pages by sidebar_position', async () => {
@@ -38,7 +38,7 @@ describe('scanDocsFolder', () => {
     const result = await scanDocsFolder(testDocsPath);
 
     expect(result.files).toBeDefined();
-    expect(Object.keys(result.files)).toHaveLength(3);
+    expect(Object.keys(result.files)).toHaveLength(5); // includes nested config files
     expect(result.files['home.md']).toContain('---');
     expect(result.files['home.md']).toContain('title: Home Page');
     expect(result.files['home.md']).toContain('# Welcome');
@@ -67,4 +67,55 @@ describe('scanDocsFolder', () => {
 
     await expect(scanDocsFolder(emptyPath)).rejects.toThrow('No valid markdown files found');
   });
+
+  describe('nested directories', () => {
+    it('should create category page for directories with files', async () => {
+      const result = await scanDocsFolder(testDocsPath);
+
+      const configPage = result.manifest.pages.find((p) => p.slug === 'config');
+      expect(configPage).toBeDefined();
+      expect(configPage?.title).toBe('Config');
+      expect(configPage?.children).toBeDefined();
+      expect(configPage?.children).toHaveLength(2);
+    });
+
+    it('should generate slugs with directory prefixes', async () => {
+      const result = await scanDocsFolder(testDocsPath);
+
+      const configPage = result.manifest.pages.find((p) => p.slug === 'config');
+      const children = configPage?.children || [];
+
+      expect(children[0].slug).toBe('config/settings');
+      expect(children[1].slug).toBe('config/database');
+    });
+
+    it('should sort nested pages by sidebar_position', async () => {
+      const result = await scanDocsFolder(testDocsPath);
+
+      const configPage = result.manifest.pages.find((p) => p.slug === 'config');
+      const children = configPage?.children || [];
+
+      expect(children[0].title).toBe('Settings');
+      expect(children[1].title).toBe('Database');
+    });
+
+    it('should store nested files with relative paths', async () => {
+      const result = await scanDocsFolder(testDocsPath);
+
+      expect(result.files['config/settings.md']).toBeDefined();
+      expect(result.files['config/settings.md']).toContain('title: Settings');
+      expect(result.files['config/database.md']).toBeDefined();
+      expect(result.files['config/database.md']).toContain('title: Database');
+    });
+
+    it('should reference nested files correctly in page objects', async () => {
+      const result = await scanDocsFolder(testDocsPath);
+
+      const configPage = result.manifest.pages.find((p) => p.slug === 'config');
+      const children = configPage?.children || [];
+
+      expect(children[0].file).toBe('config/settings.md');
+      expect(children[1].file).toBe('config/database.md');
+    });
+  });
 });

From c5910db184b3deee1653ca5e4e71b3f8b6a86453 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Tue, 10 Feb 2026 10:38:04 +0100
Subject: [PATCH 26/30] add missing dependencies for plugin-docs-renderer

- Add express and ejs for server functionality
- Add chokidar for file watching
- Add github-slugger and globby for scanner
- Add supertest for testing HTTP endpoints
- Add all corresponding @types packages

These dependencies were lost during the rebase conflict resolution.
---
 package-lock.json                          | 243 ++++++++++++++++++++-
 packages/plugin-docs-renderer/package.json |  12 +-
 2 files changed, 250 insertions(+), 5 deletions(-)

diff --git a/package-lock.json b/package-lock.json
index cffab339fe..008efb7fc2 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7952,6 +7952,19 @@
         "@tybys/wasm-util": "^0.9.0"
       }
     },
+    "node_modules/@noble/hashes": {
+      "version": "1.8.0",
+      "resolved": "https://registry.npmjs.org/@noble/hashes/-/hashes-1.8.0.tgz",
+      "integrity": "sha512-jCs9ldd7NwzpgXDIf6P3+NrHh9/sD6CQdxHyjQI+h/6rDNo88ypBxxz45UDuZHz9r3tNz7N/VInSVoVdtXEI4A==",
+      "devOptional": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^14.21.3 || >=16"
+      },
+      "funding": {
+        "url": "https://paulmillr.com/funding/"
+      }
+    },
     "node_modules/@nodelib/fs.scandir": {
       "version": "2.1.5",
       "license": "MIT",
@@ -9470,6 +9483,16 @@
         "node": ">=14"
       }
     },
+    "node_modules/@paralleldrive/cuid2": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/@paralleldrive/cuid2/-/cuid2-2.3.1.tgz",
+      "integrity": "sha512-XO7cAxhnTZl0Yggq6jOgjiOHhbgcO4NqFqwSmQpjK3b6TEE6Uj/jfSk6wzYyemh3+I0sHirKSetjQwn5cZktFw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@noble/hashes": "^1.1.5"
+      }
+    },
     "node_modules/@petamoriken/float16": {
       "version": "3.9.1",
       "dev": true,
@@ -11834,6 +11857,13 @@
         "@types/node": "*"
       }
     },
+    "node_modules/@types/cookiejar": {
+      "version": "2.1.5",
+      "resolved": "https://registry.npmjs.org/@types/cookiejar/-/cookiejar-2.1.5.tgz",
+      "integrity": "sha512-he+DHOWReW0nghN24E1WUqM0efK4kI9oTqDm6XmK8ZPe2djZ90BSNdGnIyCLzCPw7/pogPlGbzI2wHGGmi4O/Q==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/d3-color": {
       "version": "3.1.3",
       "dev": true,
@@ -11934,6 +11964,13 @@
         "@types/send": "*"
       }
     },
+    "node_modules/@types/github-slugger": {
+      "version": "1.3.0",
+      "resolved": "https://registry.npmjs.org/@types/github-slugger/-/github-slugger-1.3.0.tgz",
+      "integrity": "sha512-J/rMZa7RqiH/rT29TEVZO4nBoDP9XJOjnbbIofg7GQKs4JIduEO3WLpte+6WeUz/TcrXKlY+bM7FYrp8yFB+3g==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/glob": {
       "version": "9.0.0",
       "resolved": "https://registry.npmjs.org/@types/glob/-/glob-9.0.0.tgz",
@@ -12055,6 +12092,13 @@
       "version": "2.0.13",
       "license": "MIT"
     },
+    "node_modules/@types/methods": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/@types/methods/-/methods-1.1.4.tgz",
+      "integrity": "sha512-ymXWVrDiCxTBE3+RIrrP533E70eA+9qu7zdWoHuOmGujkYtzf4HQF96b8nwHLqhuf4ykX61IGRIB38CC6/sImQ==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/mime": {
       "version": "1.3.5",
       "resolved": "https://registry.npmjs.org/@types/mime/-/mime-1.3.5.tgz",
@@ -12253,6 +12297,30 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/superagent": {
+      "version": "8.1.9",
+      "resolved": "https://registry.npmjs.org/@types/superagent/-/superagent-8.1.9.tgz",
+      "integrity": "sha512-pTVjI73witn+9ILmoJdajHGW2jkSaOzhiFYF1Rd3EQ94kymLqB9PjD9ISg7WaALC7+dCHT0FGe9T2LktLq/3GQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/cookiejar": "^2.1.5",
+        "@types/methods": "^1.1.4",
+        "@types/node": "*",
+        "form-data": "^4.0.0"
+      }
+    },
+    "node_modules/@types/supertest": {
+      "version": "6.0.3",
+      "resolved": "https://registry.npmjs.org/@types/supertest/-/supertest-6.0.3.tgz",
+      "integrity": "sha512-8WzXq62EXFhJ7QsH3Ocb/iKQ/Ty9ZVWnVzoTKc9tyyFRRF3a74Tk2+TLFgaFFw364Ere+npzHKEJ6ga2LzIL7w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/methods": "^1.1.4",
+        "@types/superagent": "^8.1.0"
+      }
+    },
     "node_modules/@types/supports-color": {
       "version": "8.1.3",
       "resolved": "https://registry.npmjs.org/@types/supports-color/-/supports-color-8.1.3.tgz",
@@ -13887,6 +13955,13 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/asap": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/asap/-/asap-2.0.6.tgz",
+      "integrity": "sha512-BSHWgDSAiKs50o2Re8ppvp3seVHXSRM44cdSsT9FfNEUUZLOGWVCsiWaRPWM1Znn+mqZ1OfVZ3z3DWEzSp7hRA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/ast-types": {
       "version": "0.13.4",
       "license": "MIT",
@@ -15668,6 +15743,16 @@
         "dot-prop": "^5.1.0"
       }
     },
+    "node_modules/component-emitter": {
+      "version": "1.3.1",
+      "resolved": "https://registry.npmjs.org/component-emitter/-/component-emitter-1.3.1.tgz",
+      "integrity": "sha512-T0+barUSQRTUQASh8bx02dl+DhF54GtIDY13Y3m9oWTklKbb3Wv974meRpeZ3lp1JpLVECWWNHC4vaG2XHXouQ==",
+      "dev": true,
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/compressible": {
       "version": "2.0.18",
       "resolved": "https://registry.npmjs.org/compressible/-/compressible-2.0.18.tgz",
@@ -16122,6 +16207,13 @@
       "integrity": "sha512-QADzlaHc8icV8I7vbaJXJwod9HWYp8uCqf1xa4OfNu1T7JVxQIrUgOWtHdNDtPiywmFbiS12VjotIXLrKM3orQ==",
       "license": "MIT"
     },
+    "node_modules/cookiejar": {
+      "version": "2.1.4",
+      "resolved": "https://registry.npmjs.org/cookiejar/-/cookiejar-2.1.4.tgz",
+      "integrity": "sha512-LDx6oHrK+PhzLKJU9j5S7/Y3jM/mUHvD/DeI1WQmJn652iPC5Y4TBzC9l+5OMOXlyTTA+SmVUPm0HQUwpD5Jqw==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/cookiejs": {
       "version": "2.1.3",
       "license": "MIT",
@@ -17467,6 +17559,17 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/dezalgo": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/dezalgo/-/dezalgo-1.0.4.tgz",
+      "integrity": "sha512-rXSP0bf+5n0Qonsb+SVVfNfIsimO4HEtmnIpPHY8Q1UCzKlQrDMfdobr8nJOOsRgWCyMRqeSBQzmWUMq7zvVig==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "asap": "^2.0.0",
+        "wrappy": "1"
+      }
+    },
     "node_modules/didyoumean": {
       "version": "1.2.2",
       "resolved": "https://registry.npmjs.org/didyoumean/-/didyoumean-1.2.2.tgz",
@@ -19273,6 +19376,13 @@
       "version": "2.0.6",
       "license": "MIT"
     },
+    "node_modules/fast-safe-stringify": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/fast-safe-stringify/-/fast-safe-stringify-2.1.1.tgz",
+      "integrity": "sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/fast-shallow-equal": {
       "version": "1.0.0",
       "dev": true
@@ -19433,7 +19543,6 @@
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/filelist/-/filelist-1.0.4.tgz",
       "integrity": "sha512-w1cEuf3S+DrLCQL7ET6kz+gmlJdbq9J7yXCSjK/OZCPA+qEN1WyF4ZAf0YYJa4/shHJra2t/d/r8SV4Ji+x+8Q==",
-      "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
         "minimatch": "^5.0.1"
@@ -19443,7 +19552,6 @@
       "version": "5.1.6",
       "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-5.1.6.tgz",
       "integrity": "sha512-lKwV/1brpG6mBUFHtb7NUmtABCb2WZZmm2wNiOA5hAb8VdCS4B3dtMWyvcoViccwAW/COERjXLt0zP1zXUN26g==",
-      "dev": true,
       "license": "ISC",
       "dependencies": {
         "brace-expansion": "^2.0.1"
@@ -19663,6 +19771,24 @@
         "node": ">=12.20.0"
       }
     },
+    "node_modules/formidable": {
+      "version": "3.5.4",
+      "resolved": "https://registry.npmjs.org/formidable/-/formidable-3.5.4.tgz",
+      "integrity": "sha512-YikH+7CUTOtP44ZTnUhR7Ic2UASBPOqmaRkRKxRbywPTe5VxF7RRCck4af9wutiZ/QKM5nME9Bie2fFaPz5Gug==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@paralleldrive/cuid2": "^2.2.2",
+        "dezalgo": "^1.0.4",
+        "once": "^1.4.0"
+      },
+      "engines": {
+        "node": ">=14.0.0"
+      },
+      "funding": {
+        "url": "https://ko-fi.com/tunnckoCore/commissions"
+      }
+    },
     "node_modules/forwarded": {
       "version": "0.2.0",
       "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz",
@@ -23802,7 +23928,6 @@
       "version": "10.9.4",
       "resolved": "https://registry.npmjs.org/jake/-/jake-10.9.4.tgz",
       "integrity": "sha512-wpHYzhxiVQL+IV05BLE2Xn34zW1S223hvjtqk0+gsPrwd/8JNLXJgZZM/iPFsYc1xyphF+6M6EvdE5E9MBGkDA==",
-      "dev": true,
       "license": "Apache-2.0",
       "dependencies": {
         "async": "^3.2.6",
@@ -36424,6 +36549,81 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/superagent": {
+      "version": "10.3.0",
+      "resolved": "https://registry.npmjs.org/superagent/-/superagent-10.3.0.tgz",
+      "integrity": "sha512-B+4Ik7ROgVKrQsXTV0Jwp2u+PXYLSlqtDAhYnkkD+zn3yg8s/zjA2MeGayPoY/KICrbitwneDHrjSotxKL+0XQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "component-emitter": "^1.3.1",
+        "cookiejar": "^2.1.4",
+        "debug": "^4.3.7",
+        "fast-safe-stringify": "^2.1.1",
+        "form-data": "^4.0.5",
+        "formidable": "^3.5.4",
+        "methods": "^1.1.2",
+        "mime": "2.6.0",
+        "qs": "^6.14.1"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
+    "node_modules/superagent/node_modules/mime": {
+      "version": "2.6.0",
+      "resolved": "https://registry.npmjs.org/mime/-/mime-2.6.0.tgz",
+      "integrity": "sha512-USPkMeET31rOMiarsBNIHZKLGgvKc/LrjofAnBlOttf5ajRvqiRA8QsenbcooctK6d6Ts6aqZXBA+XbkKthiQg==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "mime": "cli.js"
+      },
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/superagent/node_modules/qs": {
+      "version": "6.14.1",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.1.tgz",
+      "integrity": "sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "side-channel": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=0.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/supertest": {
+      "version": "7.2.2",
+      "resolved": "https://registry.npmjs.org/supertest/-/supertest-7.2.2.tgz",
+      "integrity": "sha512-oK8WG9diS3DlhdUkcFn4tkNIiIbBx9lI2ClF8K+b2/m8Eyv47LSawxUzZQSNKUrVb2KsqeTDCcjAAVPYaSLVTA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cookie-signature": "^1.2.2",
+        "methods": "^1.1.2",
+        "superagent": "^10.3.0"
+      },
+      "engines": {
+        "node": ">=14.18.0"
+      }
+    },
+    "node_modules/supertest/node_modules/cookie-signature": {
+      "version": "1.2.2",
+      "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz",
+      "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.6.0"
+      }
+    },
     "node_modules/supports-color": {
       "version": "7.2.0",
       "license": "MIT",
@@ -40351,7 +40551,12 @@
       "version": "0.0.3",
       "license": "Apache-2.0",
       "dependencies": {
+        "chokidar": "^3.6.0",
         "debug": "^4.3.7",
+        "ejs": "^4.0.1",
+        "express": "^4.21.2",
+        "github-slugger": "^1.5.0",
+        "globby": "^11.1.0",
         "gray-matter": "^4.0.3",
         "isomorphic-dompurify": "^2.16.0",
         "marked": "^13.0.0",
@@ -40363,12 +40568,42 @@
       "devDependencies": {
         "@types/debug": "^4.1.12",
         "@types/dompurify": "^3.2.0",
-        "@types/minimist": "^1.2.5"
+        "@types/express": "^4.17.23",
+        "@types/github-slugger": "^1.3.0",
+        "@types/minimist": "^1.2.5",
+        "@types/node": "^25.2.2",
+        "@types/supertest": "^6.0.3",
+        "supertest": "^7.2.2"
       },
       "engines": {
         "node": ">=24"
       }
     },
+    "packages/plugin-docs-renderer/node_modules/@types/node": {
+      "version": "25.2.2",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.2.2.tgz",
+      "integrity": "sha512-BkmoP5/FhRYek5izySdkOneRyXYN35I860MFAGupTdebyE66uZaR+bXLHq8k4DirE5DwQi3NuhvRU1jqTVwUrQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "undici-types": "~7.16.0"
+      }
+    },
+    "packages/plugin-docs-renderer/node_modules/ejs": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/ejs/-/ejs-4.0.1.tgz",
+      "integrity": "sha512-krvQtxc0btwSm/nvnt1UpnaFDFVJpJ0fdckmALpCgShsr/iGYHTnJiUliZTgmzq/UxTX33TtOQVKaNigMQp/6Q==",
+      "license": "Apache-2.0",
+      "dependencies": {
+        "jake": "^10.9.1"
+      },
+      "bin": {
+        "ejs": "bin/cli.js"
+      },
+      "engines": {
+        "node": ">=0.12.18"
+      }
+    },
     "packages/plugin-docs-renderer/node_modules/marked": {
       "version": "13.0.3",
       "resolved": "https://registry.npmjs.org/marked/-/marked-13.0.3.tgz",
diff --git a/packages/plugin-docs-renderer/package.json b/packages/plugin-docs-renderer/package.json
index ad18210fb4..e344a57cb2 100644
--- a/packages/plugin-docs-renderer/package.json
+++ b/packages/plugin-docs-renderer/package.json
@@ -47,7 +47,12 @@
     "node": ">=24"
   },
   "dependencies": {
+    "chokidar": "^3.6.0",
     "debug": "^4.3.7",
+    "ejs": "^4.0.1",
+    "express": "^4.21.2",
+    "github-slugger": "^1.5.0",
+    "globby": "^11.1.0",
     "gray-matter": "^4.0.3",
     "isomorphic-dompurify": "^2.16.0",
     "marked": "^13.0.0",
@@ -56,6 +61,11 @@
   "devDependencies": {
     "@types/debug": "^4.1.12",
     "@types/dompurify": "^3.2.0",
-    "@types/minimist": "^1.2.5"
+    "@types/express": "^4.17.23",
+    "@types/github-slugger": "^1.3.0",
+    "@types/minimist": "^1.2.5",
+    "@types/node": "^25.2.2",
+    "@types/supertest": "^6.0.3",
+    "supertest": "^7.2.2"
   }
 }

From 9473b9bb3746f6027e5ffa226a8a75deb106e4fd Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Tue, 10 Feb 2026 14:55:21 +0100
Subject: [PATCH 27/30] make sidebar pos optional

---
 .../plugin-docs-renderer/src/cli/scanner.ts   | 29 ++++++++++++-------
 packages/plugin-docs-renderer/src/types.ts    |  5 ++--
 2 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/cli/scanner.ts b/packages/plugin-docs-renderer/src/cli/scanner.ts
index 1c0a04d661..31ab87316a 100644
--- a/packages/plugin-docs-renderer/src/cli/scanner.ts
+++ b/packages/plugin-docs-renderer/src/cli/scanner.ts
@@ -95,14 +95,19 @@ async function scanMarkdownFiles(docsPath: string): Promise<ScannedFile[]> {
 
     // read and parse the file
     const fileContent = await readFile(absolutePath, 'utf-8');
-    const parsed = matter(fileContent);
+
+    let parsed;
+    try {
+      parsed = matter(fileContent);
+    } catch (error) {
+      debug('Failed to parse frontmatter for %s: %s', relativePath, error);
+      continue;
+    }
 
     // validate frontmatter has required fields
     const frontmatter = parsed.data as Partial<Frontmatter>;
-    if (!frontmatter.title || !frontmatter.description || frontmatter.sidebar_position === undefined) {
-      console.warn(
-        `Warning: ${relativePath} missing required frontmatter fields (title, description, sidebar_position)`
-      );
+    if (!frontmatter.title || !frontmatter.description) {
+      console.warn(`Warning: ${relativePath} missing required frontmatter fields (title, description)`);
       continue;
     }
 
@@ -159,12 +164,16 @@ function buildTree(scannedFiles: ScannedFile[]): TreeNode {
 function treeToPages(node: TreeNode): Page[] {
   const pages: Page[] = [];
 
-  // convert children to array and sort by sidebar_position
+  // convert children to array and sort by sidebar_position, then alphabetically by name
   const childEntries = Array.from(node.children.entries());
-  const sortedEntries = childEntries.sort(
-    (a, b) =>
-      (a[1].file?.frontmatter.sidebar_position ?? Infinity) - (b[1].file?.frontmatter.sidebar_position ?? Infinity)
-  );
+  const sortedEntries = childEntries.sort((a, b) => {
+    const posA = a[1].file?.frontmatter.sidebar_position ?? Infinity;
+    const posB = b[1].file?.frontmatter.sidebar_position ?? Infinity;
+    if (posA !== posB) {
+      return posA - posB;
+    }
+    return a[0].localeCompare(b[0]);
+  });
 
   for (const [name, child] of sortedEntries) {
     if (child.file) {
diff --git a/packages/plugin-docs-renderer/src/types.ts b/packages/plugin-docs-renderer/src/types.ts
index 8a5c10137d..95cee86ef7 100644
--- a/packages/plugin-docs-renderer/src/types.ts
+++ b/packages/plugin-docs-renderer/src/types.ts
@@ -61,9 +61,10 @@ export interface Frontmatter {
 
   /**
    * The position of this page in the sidebar navigation (used for sorting).
-   * Pages with lower numbers appear first.
+   * Pages with lower numbers appear first. When omitted, the page sorts
+   * after positioned pages, alphabetically by filename.
    */
-  sidebar_position: number;
+  sidebar_position?: number;
 
   /**
    * Optional custom URL slug. If not provided, generated from file path.

From b690561afb36232c0758349e16048525c3ab6995 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Tue, 10 Feb 2026 14:55:51 +0100
Subject: [PATCH 28/30] add error handling for scanner

---
 packages/plugin-docs-renderer/src/server/server.ts | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/plugin-docs-renderer/src/server/server.ts b/packages/plugin-docs-renderer/src/server/server.ts
index 10fddbf1ef..04357ae736 100644
--- a/packages/plugin-docs-renderer/src/server/server.ts
+++ b/packages/plugin-docs-renderer/src/server/server.ts
@@ -43,7 +43,13 @@ export async function startServer(options: ServerOptions): Promise<Server> {
 
   // Scan filesystem and generate manifest + load files into memory
   debug('Scanning docs folder: %s', docsPath);
-  const scanned = await scanDocsFolder(docsPath);
+  let scanned;
+  try {
+    scanned = await scanDocsFolder(docsPath);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to scan docs folder "${docsPath}": ${message}`);
+  }
   let manifest: Manifest = scanned.manifest;
   let files: MarkdownFiles = scanned.files;
   debug('Manifest generated with %d pages, %d files loaded', manifest.pages.length, Object.keys(files).length);

From fcef3a9cec2594824f64ebbd802b1decbd3e220a Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Tue, 10 Feb 2026 14:56:10 +0100
Subject: [PATCH 29/30] add tests for malformed yaml

---
 .../test-docs-malformed/malformed-yaml.md     |  9 +++++++++
 .../test-docs-malformed/missing-fields.md     |  7 +++++++
 .../test-docs-malformed/no-frontmatter.md     |  3 +++
 .../__fixtures__/test-docs-malformed/valid.md |  9 +++++++++
 .../src/cli/scanner.test.ts                   | 20 +++++++++++++++++++
 5 files changed, 48 insertions(+)
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/malformed-yaml.md
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/missing-fields.md
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/no-frontmatter.md
 create mode 100644 packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/valid.md

diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/malformed-yaml.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/malformed-yaml.md
new file mode 100644
index 0000000000..dd93fa739d
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/malformed-yaml.md
@@ -0,0 +1,9 @@
+---
+title: [unclosed bracket
+description: this: is: bad: yaml: {{{
+sidebar_position: not a number
+---
+
+# Malformed YAML
+
+This file has broken YAML in its frontmatter.
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/missing-fields.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/missing-fields.md
new file mode 100644
index 0000000000..44e9027ef4
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/missing-fields.md
@@ -0,0 +1,7 @@
+---
+title: Missing Fields Page
+---
+
+# Missing Fields
+
+This page has a title but is missing description and sidebar_position.
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/no-frontmatter.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/no-frontmatter.md
new file mode 100644
index 0000000000..66fdfaa6b5
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/no-frontmatter.md
@@ -0,0 +1,3 @@
+# No Frontmatter
+
+This markdown file has no frontmatter at all.
diff --git a/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/valid.md b/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/valid.md
new file mode 100644
index 0000000000..63789ba52b
--- /dev/null
+++ b/packages/plugin-docs-renderer/src/__fixtures__/test-docs-malformed/valid.md
@@ -0,0 +1,9 @@
+---
+title: Valid Page
+description: This page has correct frontmatter
+sidebar_position: 1
+---
+
+# Valid Page
+
+This is a valid page with proper frontmatter.
diff --git a/packages/plugin-docs-renderer/src/cli/scanner.test.ts b/packages/plugin-docs-renderer/src/cli/scanner.test.ts
index ffc6e77d03..213d0d1e29 100644
--- a/packages/plugin-docs-renderer/src/cli/scanner.test.ts
+++ b/packages/plugin-docs-renderer/src/cli/scanner.test.ts
@@ -68,6 +68,26 @@ describe('scanDocsFolder', () => {
     await expect(scanDocsFolder(emptyPath)).rejects.toThrow('No valid markdown files found');
   });
 
+  describe('malformed metadata', () => {
+    const malformedDocsPath = join(__dirname, '..', '__fixtures__', 'test-docs-malformed');
+
+    it('should skip files with malformed YAML frontmatter and process valid ones', async () => {
+      const result = await scanDocsFolder(malformedDocsPath);
+
+      expect(result.manifest.pages).toHaveLength(1);
+      expect(result.manifest.pages[0].title).toBe('Valid Page');
+    });
+
+    it('should not include malformed or incomplete files in the files map', async () => {
+      const result = await scanDocsFolder(malformedDocsPath);
+
+      expect(result.files['valid.md']).toBeDefined();
+      expect(result.files['malformed-yaml.md']).toBeUndefined();
+      expect(result.files['no-frontmatter.md']).toBeUndefined();
+      expect(result.files['missing-fields.md']).toBeUndefined();
+    });
+  });
+
   describe('nested directories', () => {
     it('should create category page for directories with files', async () => {
       const result = await scanDocsFolder(testDocsPath);

From eeb13cc05543147971098709996b338855d84b84 Mon Sep 17 00:00:00 2001
From: Erik Sundell <erik.sundell87@gmail.com>
Date: Tue, 10 Feb 2026 15:47:54 +0100
Subject: [PATCH 30/30] copilot feedback

---
 packages/plugin-docs-renderer/src/server/server.ts | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/packages/plugin-docs-renderer/src/server/server.ts b/packages/plugin-docs-renderer/src/server/server.ts
index 04357ae736..99f451803a 100644
--- a/packages/plugin-docs-renderer/src/server/server.ts
+++ b/packages/plugin-docs-renderer/src/server/server.ts
@@ -60,11 +60,10 @@ export async function startServer(options: ServerOptions): Promise<Server> {
   });
   debug('File watcher initialized for %s', docsPath);
 
-  watcher.on('change', async (path) => {
-    debug('File changed: %s', path);
+  const rescan = async (event: string, path: string) => {
+    debug('File %s: %s', event, path);
     lastModified = Date.now();
 
-    // scan again to update manifest
     try {
       const rescanned = await scanDocsFolder(docsPath);
       manifest = rescanned.manifest;
@@ -72,7 +71,11 @@ export async function startServer(options: ServerOptions): Promise<Server> {
     } catch (error) {
       console.error('Error re-scanning docs folder:', error);
     }
-  });
+  };
+
+  watcher.on('change', (path) => rescan('changed', path));
+  watcher.on('add', (path) => rescan('added', path));
+  watcher.on('unlink', (path) => rescan('removed', path));
 
   // serve static assets
   app.use('/img', express.static(join(docsPath, 'img')));