fix(markdown,ui): route guides by stable IDs

night-slayer18 · night-slayer18 · commit 752822eb47ed · 2026-02-09T20:40:19.000+05:30
generate deterministic guide IDs from relative markdown paths
encode/decode route IDs safely in UI links and page params
switch guide route to /guide/:id/:slug and keep readable slugs
add unit/e2e coverage for guide navigation and section edge branches

Signed-off-by: night-slayer18 &lt;samanuaia257@gmail.com&gt;
diff --git a/e2e/guides.spec.ts b/e2e/guides.spec.ts
@@ -0,0 +1,14 @@
+import { test, expect } from './coverage';
+
+test('guide navigation uses stable short IDs', async ({ page }) => {
+  await page.goto('/');
+
+  const openNav = page.getByRole('button', { name: /open navigation/i });
+  if (await openNav.isVisible()) {
+    await openNav.click();
+  }
+
+  await page.getByRole('link', { name: 'README' }).first().click();
+
+  await expect(page).toHaveURL(/\/guide\/[0-9a-f]{8}\/readme$/i);
+});
diff --git a/packages/core/tests/markdown-plugin.test.ts b/packages/core/tests/markdown-plugin.test.ts
@@ -45,7 +45,12 @@ Some content.`,
 
     const guide = docs[0];
     expect(guide.kind).toBe('guide');
+    expect(guide.id).toMatch(/^[0-9a-f]{8}$/);
+    expect(guide.id).not.toContain(':');
+    expect(guide.id).not.toContain('/');
     expect(guide.name).toBe('Getting Started');
+    expect(guide.fileName).toBe('guide.md');
+    expect(guide.source?.file).toBe('guide.md');
     expect(guide.documentation?.summary).toBe('Intro guide');
     const metadata = guide.metadata as { markdown?: string; html?: string };
     expect(metadata.markdown).toContain('Some content');
diff --git a/packages/plugins/markdown/src/index.ts b/packages/plugins/markdown/src/index.ts
@@ -1,5 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
+import crypto from 'crypto';
 import matter from 'gray-matter';
 import { marked } from 'marked';
 import { glob } from 'glob';
@@ -13,11 +14,21 @@ export interface MarkdownPluginOptions {
 
 interface MarkdownFile {
   path: string;
+  relativePath: string;
   frontMatter: Record<string, unknown>;
   markdown: string;
   html: string;
 }
 
+function normalizePath(input: string): string {
+  return input.replace(/\\/g, '/');
+}
+
+function generateGuideId(relativePath: string): string {
+  const content = `guide|${normalizePath(relativePath)}`;
+  return crypto.createHash('md5').update(content).digest('hex').slice(0, 8);
+}
+
 export default function markdownPlugin(options: MarkdownPluginOptions): Plugin {
   const files: MarkdownFile[] = [];
 
@@ -37,6 +48,7 @@ export default function markdownPlugin(options: MarkdownPluginOptions): Plugin {
 
       for (const file of foundFiles) {
         const content = await fs.readFile(file, 'utf-8');
+        const relativePath = normalizePath(path.relative(options.sourceDir, file));
         let frontMatter: Record<string, unknown> = {};
         let markdown = content;
 
@@ -51,6 +63,7 @@ export default function markdownPlugin(options: MarkdownPluginOptions): Plugin {
 
         files.push({
           path: file,
+          relativePath,
           frontMatter,
           markdown,
           html,
@@ -64,17 +77,19 @@ export default function markdownPlugin(options: MarkdownPluginOptions): Plugin {
     afterExtract(docs: DocEntry[]) {
       const guideDocs: DocEntry[] = files.map((file) => {
         const fileName = path.basename(file.path, path.extname(file.path));
+        const modulePath = file.relativePath.replace(/\.[^/.]+$/, '');
         const title =
           typeof file.frontMatter.title === 'string' ? file.frontMatter.title : fileName;
         const description =
           typeof file.frontMatter.description === 'string' ? file.frontMatter.description : '';
 
         return {
-          id: `guide:${file.path}`,
+          id: generateGuideId(file.relativePath),
           name: title,
           kind: 'guide',
-          fileName: file.path,
-          source: { file: file.path, line: 1, column: 0 },
+          fileName: file.relativePath,
+          module: modulePath,
+          source: { file: file.relativePath, line: 1, column: 0 },
           position: { line: 1, column: 0 },
           signature: '',
           documentation: {
diff --git a/packages/ui/src/App.tsx b/packages/ui/src/App.tsx
@@ -98,7 +98,7 @@ export function App() {
           <Route element={<AppShell />}>
             <Route path="/" element={<HomePage />} />
             <Route path="/docs/*" element={<MarkdownPage />} />
-            <Route path="/guide/:name" element={<GuidePage />} />
+            <Route path="/guide/:id/:slug?" element={<GuidePage />} />
             <Route path="/section/:slug" element={<SectionPage />} />
             <Route path="/:kind/:id/:slug?" element={<TypePage />} />
           </Route>
diff --git a/packages/ui/src/lib/routes.ts b/packages/ui/src/lib/routes.ts
@@ -3,5 +3,6 @@ import type { DocEntry } from '../store';
 
 export function docPath(entry: Pick<DocEntry, 'kind' | 'id' | 'name'>): string {
   const slug = slugify(entry.name) || 'entry';
-  return `/${entry.kind}/${entry.id}/${slug}`;
+  const encodedId = encodeURIComponent(entry.id);
+  return `/${entry.kind}/${encodedId}/${slug}`;
 }
diff --git a/packages/ui/src/pages/GuidePage.tsx b/packages/ui/src/pages/GuidePage.tsx
@@ -11,12 +11,13 @@ interface GuideMetadata {
 }
 
 export function GuidePage() {
-  const { name } = useParams<{ name: string }>();
+  const { id } = useParams<{ id: string; slug?: string }>();
   const docs = useStore((state) => state.docs);
+  const decodedId = id ? decodeURIComponent(id) : id;
 
   const entry = useMemo(
-    () => docs.find((doc) => doc.kind === 'guide' && doc.name === name),
-    [docs, name]
+    () => docs.find((doc) => doc.kind === 'guide' && doc.id === decodedId),
+    [docs, decodedId]
   );
 
   if (!entry) {
diff --git a/packages/ui/src/pages/TypePage.tsx b/packages/ui/src/pages/TypePage.tsx
@@ -5,15 +5,17 @@ import { TypeView } from '../components/Documentation/TypeView';
 export function TypePage() {
   const { kind, id } = useParams<{ kind: string; id: string; slug?: string }>();
   const docs = useStore((state) => state.docs);
+  const decodedId = id ? decodeURIComponent(id) : id;
 
-  const entry = kind && id ? docs.find((d) => d.id === id && d.kind === kind) : undefined;
+  const entry =
+    kind && decodedId ? docs.find((d) => d.id === decodedId && d.kind === kind) : undefined;
 
   if (!entry) {
     return (
       <div className="text-center">
         <h1 className="text-2xl font-bold text-foreground">Not Found</h1>
         <p className="mt-2 text-muted-foreground">
-          Could not find documentation for {kind ?? 'unknown'}/{id ?? 'unknown'}
+          Could not find documentation for {kind ?? 'unknown'}/{decodedId ?? 'unknown'}
         </p>
       </div>
     );
diff --git a/packages/ui/tests/components/Layout/Sidebar.test.tsx b/packages/ui/tests/components/Layout/Sidebar.test.tsx
@@ -20,6 +20,15 @@ const docs: DocEntry[] = [
     position: { line: 1, column: 0 },
     signature: 'class Beta {}',
   },
+  {
+    id: 'a1b2c3d4',
+    name: 'README',
+    kind: 'guide',
+    fileName: 'docs/README.md',
+    module: 'docs/README',
+    position: { line: 1, column: 0 },
+    signature: 'markdown README',
+  },
 ];
 
 describe('Sidebar', () => {
@@ -59,4 +68,14 @@ describe('Sidebar', () => {
     expect(queryByText(/functions/i)).not.toBeInTheDocument();
     expect(queryByText(/classes/i)).not.toBeInTheDocument();
   });
+
+  it('uses clean guide IDs in links', () => {
+    const { getByRole } = renderWithStore(<Sidebar />, {
+      initialState: { docs },
+      route: '/',
+    });
+
+    const link = getByRole('link', { name: 'README' });
+    expect(link.getAttribute('href')).toBe('/guide/a1b2c3d4/readme');
+  });
 });
diff --git a/packages/ui/tests/lib/routes.test.ts b/packages/ui/tests/lib/routes.test.ts
@@ -0,0 +1,14 @@
+import { describe, expect, it } from 'vitest';
+import { docPath } from '@/lib/routes';
+
+describe('docPath', () => {
+  it('builds clean guide URLs with stable short IDs', () => {
+    const path = docPath({
+      kind: 'guide',
+      id: 'a1b2c3d4',
+      name: 'Intro',
+    });
+
+    expect(path).toBe('/guide/a1b2c3d4/intro');
+  });
+});
diff --git a/packages/ui/tests/pages/GuidePage.test.tsx b/packages/ui/tests/pages/GuidePage.test.tsx
@@ -11,11 +11,12 @@ describe('GuidePage', () => {
     });
   });
   it('renders markdown guides from metadata', async () => {
+    const guideId = 'a1b2c3d4';
     act(() => {
       useStore.setState({
         docs: [
           {
-            id: 'guide:1',
+            id: guideId,
             name: 'Getting Started',
             kind: 'guide',
             fileName: 'guide.md',
@@ -28,13 +29,60 @@ describe('GuidePage', () => {
     });
 
     render(
-      <MemoryRouter initialEntries={['/guide/Getting%20Started']}>
+      <MemoryRouter initialEntries={[`/guide/${guideId}/getting-started`]}>
         <Routes>
-          <Route path="/guide/:name" element={<GuidePage />} />
+          <Route path="/guide/:id/:slug?" element={<GuidePage />} />
         </Routes>
       </MemoryRouter>
     );
 
     expect(await screen.findByText('Hello guide')).toBeInTheDocument();
   });
+
+  it('renders HTML guides from metadata when html is present', async () => {
+    const guideId = 'd4c3b2a1';
+    act(() => {
+      useStore.setState({
+        docs: [
+          {
+            id: guideId,
+            name: 'HTML Guide',
+            kind: 'guide',
+            fileName: 'html-guide.md',
+            position: { line: 1, column: 0 },
+            signature: '',
+            metadata: { html: '<h2>Rendered HTML guide</h2><p>Body</p>' },
+          },
+        ],
+      });
+    });
+
+    render(
+      <MemoryRouter initialEntries={[`/guide/${guideId}/html-guide`]}>
+        <Routes>
+          <Route path="/guide/:id/:slug?" element={<GuidePage />} />
+        </Routes>
+      </MemoryRouter>
+    );
+
+    expect(await screen.findByText('Rendered HTML guide')).toBeInTheDocument();
+    expect(screen.getByText('Body')).toBeInTheDocument();
+  });
+
+  it('renders a not found state for unknown guides', () => {
+    act(() => {
+      useStore.setState({ docs: [] });
+    });
+
+    render(
+      <MemoryRouter initialEntries={['/guide/ffffffff/missing']}>
+        <Routes>
+          <Route path="/guide/:id/:slug?" element={<GuidePage />} />
+        </Routes>
+      </MemoryRouter>
+    );
+
+    expect(screen.getByText('Guide not found')).toBeInTheDocument();
+    expect(screen.getByText(/does not exist/i)).toBeInTheDocument();
+  });
 });
diff --git a/packages/ui/tests/pages/SectionPage.test.tsx b/packages/ui/tests/pages/SectionPage.test.tsx

Original file line number	Diff line number	Diff line change
`@@ -3,5 +3,6 @@ import type { DocEntry } from '../store';`
`3`	`3`
`4`	`4`	`export function docPath(entry: Pick<DocEntry, 'kind' \| 'id' \| 'name'>): string {`
`5`	`5`	`const slug = slugify(entry.name) \|\| 'entry';`
`6`		- return `/${entry.kind}/${entry.id}/${slug}`;
	`6`	`+ const encodedId = encodeURIComponent(entry.id);`
	`7`	+ return `/${entry.kind}/${encodedId}/${slug}`;
`7`	`8`	`}`