Docs Renderer: Add local preview server #2437

sunker · 2026-02-05T07:18:46Z

What this PR does / why we need it:

This PR introduces a local development server for the new @grafana/plugin-docs-renderer package, enabling plugin developers to preview their multi-page documentation locally before publishing/submitting to the catalog. The server uses the plugin-docs-renderer lib to generate GH flavoured markdown and serves pages based on a manifest.json structure. The server has optional live reload functionality through file watching. Also adding a couple of simple api tests for the express server.

Also replacing the manually edited manifest.json file with an auto-generated file. There's a new scanner file that uses globby to recursively find all markdown files inside the docs folder. It does some light validation, but much more validation will be added in the next PR.

The following things will be addressed in upcoming PRs:

navigation - currently renders a flat, ugly-lookfing list.
html - the basic layout file will be replaced by something that looks similar to the plugin page in the catalog
styling - no proper css theming yet. grafana website styling will be added later on
validation - a bunch of validation steps, inc manifest schema verificaiton, will be added in follow-up prs
can also look into more advanced live-reload functionality using vite or web-workers

Example usage:

npx @grafana/plugin-docs-renderer ./docs --reload

Which issue(s) this PR fixes:

Part of the rich plugin documentation initiative. This implements the local preview workflow described in the design doc, allowing plugin authors to iterate on documentation with immediate visual feedback.

Fixes https://github.com/grafana/grafana-community-team/issues/739

Special notes for your reviewer:

packages/plugin-docs-renderer/src/server.ts

github-actions · 2026-02-05T08:19:46Z

Hello! 👋 This repository uses Auto for releasing packages using PR labels.

✨ This PR can be merged. It will not be considered when calculating future versions of the npm packages and will not appear in the changelogs.

packages/plugin-docs-renderer/src/server.ts

packages/plugin-docs-renderer/src/server/server.ts

packages/plugin-docs-renderer/src/server.ts

packages/plugin-docs-renderer/src/server/server.ts

Copilot

Pull request overview

This PR introduces a local development server for the @grafana/plugin-docs-renderer package, enabling plugin developers to preview multi-page documentation locally with optional live reload functionality. The server uses Express to serve GitHub-flavored markdown content based on a manifest.json structure.

Changes:

Added Express-based development server with file watching and live reload capabilities
Implemented recursive page lookup supporting nested documentation structures
Added comprehensive test suite using supertest to validate server functionality

Reviewed changes

Copilot reviewed 8 out of 11 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
`packages/plugin-docs-renderer/src/server.ts`	New Express server implementation with route handlers, file watching, and HTML generation
`packages/plugin-docs-renderer/src/server.test.ts`	Test suite covering server routes, static assets, live reload, and error cases
`packages/plugin-docs-renderer/src/index.ts`	Exports server functions and types for public API
`packages/plugin-docs-renderer/src/bin/run.ts`	CLI completely rewritten to start development server instead of processing docs
`packages/plugin-docs-renderer/src/__fixtures__/test-docs/*`	Test fixtures including manifest, markdown files, and static assets
`packages/plugin-docs-renderer/package.json`	Added express, chokidar, supertest dependencies and dev script
`package-lock.json`	Lock file updates for new dependencies

packages/plugin-docs-renderer/src/server.ts

packages/plugin-docs-renderer/src/server/server.test.ts

packages/plugin-docs-renderer/src/server/server.ts

packages/plugin-docs-renderer/src/server.test.ts

packages/plugin-docs-renderer/src/server/server.ts

packages/plugin-docs-renderer/src/server.ts

academo · 2026-02-05T14:40:24Z

packages/plugin-docs-renderer/src/__fixtures__/test-docs/manifest.json

@@ -0,0 +1,23 @@
+{


I am assuming this will be generated from the docs when we actually run the renderer?

In that case we should have the renderer generate the manifest on the fly instead of having it here hardcoded.

Definitely! To prevent this pr from becoming massive I'll handle that in a follow-up, ok?

Decided to push code that scans the docs folder and generates a manifest based on the filesystem structure + markdown metadata after all. Proper validation will be added in a follow up pr.

academo · 2026-02-05T15:11:18Z

packages/plugin-docs-renderer/src/server.ts

+  `
+    : '';
+
+  return `


I am not a fan of having an html template here. there are some minimal template engines that we can use for express js and we are going to eventually have to generate more and more htlm that we won't want to write here in JS files

Done in 1d583f9. Went with EJS only because I've used it before.

packages/plugin-docs-renderer/src/server.ts

packages/plugin-docs-renderer/src/server/server.ts

+        return;
+      }
+
+      debug('Request for slug: %s', slug);


To fix the problem, sanitize the user-controlled slug before logging it. For plain-text logging, the key step is to remove newline and carriage-return characters (and optionally other non-printable control characters) so an attacker cannot create extra log lines or otherwise break log structure. We should perform this sanitization only for the log message, leaving the actual routing logic unchanged so functionality is preserved.

The best minimal fix here is to introduce a sanitized variant of slug right before logging: e.g. const safeSlugForLog = slug.replace(/[\r\n]/g, ''); and then pass safeSlugForLog to the debug calls that log the slug. This avoids changing how slug is used to look up pages, but ensures log output does not contain embedded newlines. We do not need extra libraries: a simple String.prototype.replace with a small regex is sufficient. Concretely:

In packages/plugin-docs-renderer/src/server/server.ts, within the route handler (app.get('*', ...)), after computing slug and before the debug('Request for slug: %s', slug); call, compute safeSlugForLog by stripping \r and \n.

Use safeSlugForLog instead of slug in that debug call, and in the later debug('Page not found for slug: %s', ...) call as well (since that also logs the slug).

No new imports, methods, or types are required.

packages/plugin-docs-renderer/src/server/server.ts

+      // find the file for this slug
+      const fileName = findPageBySlug(slug, manifest.pages);
+      if (!fileName) {
+        debug('Page not found for slug: %s', slug);


To fix this class of problem, any user-controlled value that is written to logs should be sanitized so that it cannot inject new log entries or otherwise break the log format. For plain-text logs, the main concern is removing newline (\n) and carriage return (\r) characters (and optionally other control characters). The safest and least intrusive fix here is to create a small helper that normalizes/sanitizes strings before they are logged and apply it to the slug (and any similar user-derived values) used in logging statements.

Concretely for this file, we can add a local utility function, for example sanitizeForLog, near the top of the file. This helper will take a string (or unknown) and return a string with \r and \n removed (you can also strip other control chars if desired, but we’ll keep the minimal change). Then, on line 130, instead of passing slug directly into debug, we pass sanitizeForLog(slug). This preserves all existing behavior except that line breaks in the slug will be removed before being logged. No external dependencies are required; we can implement the sanitizer with String.prototype.replace. We will keep the rest of the logic (including how slugs are used to look up pages) unchanged to avoid altering runtime behavior outside logging.

…mentation manifest

… manifest generation

- 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.

academo · 2026-02-10T13:30:14Z

packages/plugin-docs-renderer/src/cli/scanner.test.ts

+      expect(children[1].title).toBe('Database');
+    });
+
+    it('should store nested files with relative paths', async () => {


we should have a test case for a markdown file with broken or malformed metadata.

academo · 2026-02-10T13:31:06Z

packages/plugin-docs-renderer/src/cli/scanner.ts

+
+    // read and parse the file
+    const fileContent = await readFile(absolutePath, 'utf-8');
+    const parsed = matter(fileContent);


can matter throw an error if it fails to parse?

yep invoking matter on malformed yaml throws. captured in unit tests now.

academo · 2026-02-10T13:32:04Z

packages/plugin-docs-renderer/src/cli/scanner.ts

+
+    // validate frontmatter has required fields
+    const frontmatter = parsed.data as Partial<Frontmatter>;
+    if (!frontmatter.title || !frontmatter.description || frontmatter.sidebar_position === undefined) {


are we making sidebar_position mandatory? IMO it should be optional and we just order on whatever order the come from the file system if not defined.

also not 100% sure why description is a mandatory field. do we display it in the sidebar?

SGTM to make description optional and fallback on fs order

description it's not used right now in the preview server, but for SEO reasons I think we need a meta description for the actual website.

academo · 2026-02-10T13:32:41Z

packages/plugin-docs-renderer/src/cli/scanner.ts

+    // validate frontmatter has required fields
+    const frontmatter = parsed.data as Partial<Frontmatter>;
+    if (!frontmatter.title || !frontmatter.description || frontmatter.sidebar_position === undefined) {
+      console.warn(


this is almost silently failing. we should be more aggressive on the feedback that the markdowns file are being ignored

In a future PR coming soon, all validation rules will be added. those will run before the first thing in the serve command so we'll provide clear user feedback then

academo

my main concerns:

review what we should actually make mandatory in the markdown frontmatter
better error handling, things like scanDocsFolder are called without a try/catch that could show us a readable error of what's failing
add test cases for error states (e.g. corrupted markdown, no files, etc..)

Copilot

Pull request overview

Copilot reviewed 20 out of 23 changed files in this pull request and generated 10 comments.

packages/plugin-docs-renderer/src/cli/scanner.ts

packages/plugin-docs-renderer/src/server/server.ts

packages/plugin-docs-renderer/src/cli/scanner.ts

packages/plugin-docs-renderer/src/server/views/plugin-details-page.ejs

packages/plugin-docs-renderer/src/server/server.test.ts

github-project-automation bot added this to Grafana Catalog Team Feb 5, 2026

github-project-automation bot moved this to 📬 Triage in Grafana Catalog Team Feb 5, 2026

github-advanced-security bot found potential problems Feb 5, 2026

View reviewed changes

packages/plugin-docs-renderer/src/server.ts Fixed Show fixed Hide fixed

packages/plugin-docs-renderer/src/server.ts Fixed Show fixed Hide fixed

grafana-plugins-platform-bot bot moved this from 📬 Triage to 🔬 In review in Grafana Catalog Team Feb 5, 2026

github-advanced-security bot found potential problems Feb 5, 2026

View reviewed changes

packages/plugin-docs-renderer/src/server/server.ts Fixed Show fixed Hide fixed

sunker self-assigned this Feb 5, 2026

sunker added the no-changelog Don't include in changelog and version calculations label Feb 5, 2026

sunker marked this pull request as ready for review February 5, 2026 08:30

sunker requested review from a team as code owners February 5, 2026 08:30

sunker requested review from academo, andresmgot, Copilot, jackw, s4kh and wbrowne February 5, 2026 08:30

Copilot started reviewing on behalf of sunker February 5, 2026 08:30 View session

Copilot AI reviewed Feb 5, 2026

View reviewed changes

academo reviewed Feb 5, 2026

View reviewed changes

github-advanced-security bot found potential problems Feb 5, 2026

View reviewed changes

packages/plugin-docs-renderer/src/server.ts Fixed Show fixed Hide fixed

packages/plugin-docs-renderer/src/server/server.ts Fixed Show fixed Hide fixed

sunker requested a review from academo February 5, 2026 21:12

github-advanced-security bot found potential problems Feb 6, 2026

View reviewed changes

sunker added 5 commits February 10, 2026 10:33

add dev script

bf2736c

add serve cmd

36f0683

add very basic dev server

9d7a351

fix argument parsing

2c9cfad

add server/api test

e30ce36

sunker added 16 commits February 10, 2026 10:33

escape html

1b1ddb0

remove redundant debug log for requested slug in startServer

1d2d35b

update startServer to return Server instance with close method

d69672d

adding ejs templates

a8ff392

add copyAssets function to rollup config for static asset handling

8ad1322

put devtools inside cli folder

b6b0f45

add Frontmatter interface for markdown file metadata

245a65f

moved loader out of lib and into cli

25e85be

add scanner functionality to process markdown files and generate docu…

db0ba97

…mentation manifest

update startServer to be async and integrate docs folder scanning for…

70fa591

… manifest generation

load markdown files into memory and improve manifest logging

6a6e1d1

fix tests and self review

62ecb86

add scanner tests

70fa363

remove ununsed loader file

d9eb066

update tests for nested directory handling

0c60c8f

sunker force-pushed the docs-parser/local-preview branch from e7fbf3d to c5910db Compare February 10, 2026 09:39

academo reviewed Feb 10, 2026

View reviewed changes

sunker added 3 commits February 10, 2026 14:55

make sidebar pos optional

9473b9b

add error handling for scanner

b690561

add tests for malformed yaml

fcef3a9

sunker requested review from academo and Copilot February 10, 2026 13:58

Copilot started reviewing on behalf of sunker February 10, 2026 13:59 View session

Copilot AI reviewed Feb 10, 2026

View reviewed changes

copilot feedback

eeb13cc

@@ -12,6 +12,12 @@
             const debug = createDebug('plugin-docs-renderer:server');
+            function sanitizeForLog(value: unknown): string {
+              const str = String(value);
+              // Remove newline and carriage return characters to prevent log injection
+              return str.replace(/[\r\n]+/g, '');
+            }
             export interface ServerOptions {
               docsPath: string;
               port: number;
@@ -127,7 +133,7 @@
                   // find the file for this slug
                   const fileName = findPageBySlug(slug, manifest.pages);
                   if (!fileName) {
-                    debug('Page not found for slug: %s', slug);
+                    debug('Page not found for slug: %s', sanitizeForLog(slug));
                     res.status(404).send('Page not found');
                     return;
                   }

Docs Renderer: Add local preview server #2437

Are you sure you want to change the base?

Docs Renderer: Add local preview server #2437

Uh oh!

Conversation

sunker commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Feb 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Check warning

Uh oh!

Copilot Autofix

Uh oh!

Check warning

Uh oh!

Copilot Autofix

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

academo Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

academo left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

sunker commented Feb 5, 2026 •

edited

Loading

github-actions bot commented Feb 5, 2026 •

edited

Loading

academo Feb 10, 2026 •

edited

Loading