@clidey/dory 1.0.3 → 1.0.6

package/src/plugins/code-meta.ts

@@ -0,0 +1,23 @@
+import { visit } from 'unist-util-visit';
+
+interface CodeElement {
+  tagName?: string;
+  data?: { meta?: string };
+  properties?: Record<string, unknown>;
+}
+
+/**
+ * Rehype plugin that keeps a code fence's meta string (everything after the
+ * language, e.g. ```json dory.json {4-6}). MDX drops it by default; this
+ * exposes it to the `code` component as the `metastring` prop.
+ */
+export function rehypeCodeMeta() {
+  return (tree: Parameters<typeof visit>[0]) => {
+    visit(tree, 'element', (node: CodeElement) => {
+      const meta = node.data?.meta;
+      if (node.tagName === 'code' && meta) {
+        node.properties = { ...node.properties, metastring: meta };
+      }
+    });
+  };
+}

package/src/plugins/frontmatter-dev-server.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from 'vite';
 import path from 'path';
 import { generateFrontmatterJson, generateSearchContentJson } from './frontmatter-generator';
+import { getBasePath, readDoryConfig } from './shared';
 
 /**
  * Dev server plugin that serves frontmatter.json and search-content.json
@@ -10,8 +11,11 @@ export function frontmatterDevServer(): Plugin {
   return {
     name: 'frontmatter-dev-server',
     configureServer(server) {
+      // Plugin middlewares run before Vite strips `base`, so mount under it.
+      const basePath = getBasePath(readDoryConfig());
+
       // Serve search content for client-side indexing
-      server.middlewares.use('/search-content.json', (req, res, next) => {
+      server.middlewares.use(`${basePath}/search-content.json`, (req, res, next) => {
         if (req.method !== 'GET') return next();
         try {
           const docsDir = path.join(process.cwd(), 'docs');
@@ -27,7 +31,7 @@ export function frontmatterDevServer(): Plugin {
         }
       });
 
-      server.middlewares.use('/frontmatter.json', (req, res, next) => {
+      server.middlewares.use(`${basePath}/frontmatter.json`, (req, res, next) => {
         if (req.method !== 'GET') {
           return next();
         }

package/src/plugins/html-files-middleware.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from 'vite';
 import { readFileSync, existsSync, statSync } from 'fs';
 import { resolve, extname, sep } from 'path';
+import { getBasePath, readDoryConfig } from './shared';
 
 /**
  * Returns true if `target` is the `root` path itself or is contained within it.
@@ -50,14 +51,20 @@ export function htmlFilesMiddleware(): Plugin {
   return {
     name: 'html-files-middleware',
     configureServer(server) {
+      // Plugin middlewares run before Vite strips `base`, so strip it here.
+      const basePath = getBasePath(readDoryConfig());
+
       server.middlewares.use((req, res, next) => {
         if (!req.url) {
           next();
           return;
         }
 
-        // Remove query params
-        const url = req.url.split('?')[0];
+        // Remove query params and the base path prefix
+        let url = req.url.split('?')[0];
+        if (basePath && (url === basePath || url.startsWith(`${basePath}/`))) {
+          url = url.slice(basePath.length) || '/';
+        }
 
         // Check if the request is for a file in the dist directory
         if (url.startsWith('/dist/')) {

package/src/plugins/html-metadata-injector.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from 'vite';
-import { readDoryConfig, escapeHtml, applyTitleTemplate } from './shared';
+import { readDoryConfig, escapeHtml, applyTitleTemplate, getBasePath, getSiteUrl } from './shared';
 
 /**
  * Vite plugin that injects site metadata from dory.json into index.html.
@@ -20,7 +20,8 @@ export function htmlMetadataInjector(): Plugin {
         const siteName: string = config.name || 'Documentation';
         const defaultTitle = applyTitleTemplate(config.title || siteName, seo.titleTemplate, siteName);
         const defaultDescription: string = config.description || `${siteName} - Technical Documentation`;
-        const siteUrl: string = config.url || '';
+        const siteUrl: string = getSiteUrl(config);
+        const basePath = getBasePath(config);
         const twitterHandle: string = config.twitter || '';
 
         // Resolve image to absolute URL
@@ -33,7 +34,7 @@ export function htmlMetadataInjector(): Plugin {
         // fall back to the logo so sites without a dedicated favicon still
         // get an icon instead of a broken link.
         const rawFavicon: string = config.favicon || config.logo?.light || config.logo?.dark || '';
-        const faviconHref = rawFavicon ? `/${rawFavicon.replace(/^\.?\/*/, '')}` : '';
+        const faviconHref = rawFavicon ? `${basePath}/${rawFavicon.replace(/^\.?\/*/, '')}` : '';
 
         // Function replacements everywhere so `$&` etc. in config values
         // cannot corrupt the output.

package/src/plugins/llm-txt-dev-server.ts

@@ -1,6 +1,7 @@
 import type { Plugin } from 'vite';
 import path from 'path';
 import { generateLlmsIndex, generateLlmContent } from './llm-txt-generator';
+import { getBasePath, readDoryConfig } from './shared';
 
 /**
  * Dev server plugin that serves llms.txt and llms-full.txt on demand,
@@ -30,8 +31,10 @@ export function llmTxtDevServer(): Plugin {
   return {
     name: 'llm-txt-dev-server',
     configureServer(server) {
-      server.middlewares.use('/llms.txt', serveText(generateLlmsIndex));
-      server.middlewares.use('/llms-full.txt', serveText(generateLlmContent));
+      // Plugin middlewares run before Vite strips `base`, so mount under it.
+      const basePath = getBasePath(readDoryConfig());
+      server.middlewares.use(`${basePath}/llms.txt`, serveText(generateLlmsIndex));
+      server.middlewares.use(`${basePath}/llms-full.txt`, serveText(generateLlmContent));
     }
   };
 }

package/src/plugins/llm-txt-generator.ts

@@ -7,6 +7,7 @@ import {
   parseFrontmatter,
   findMdxFilesMap,
   pathFromFilename,
+  getSiteUrl,
 } from './shared';
 
 interface LlmTxtGeneratorOptions {
@@ -41,7 +42,7 @@ function resolveFileKey(navKey: string, mdxFilesMap: Record<string, string>): st
 export function generateLlmsIndex(docsDir: string): string {
   const config = readDoryConfig(docsDir) || {};
   const siteName: string = config.name || 'Documentation';
-  const baseUrl: string = config.url || '';
+  const baseUrl: string = getSiteUrl(config);
   const mdxFilesMap = findMdxFilesMap(docsDir, docsDir);
 
   let output = `# ${siteName}\n`;

package/src/plugins/prerender.ts

@@ -9,6 +9,8 @@ import {
   stripMdxToText,
   escapeHtml,
   applyTitleTemplate,
+  getBasePath,
+  getSiteUrl,
 } from './shared';
 
 /**
@@ -41,7 +43,7 @@ export function prerender(): Plugin {
 
         const siteConfig = readDoryConfig() || {};
         const seo = siteConfig.seo || {};
-        const baseUrl: string = siteConfig.url || '';
+        const baseUrl: string = getSiteUrl(siteConfig);
         const siteName: string = siteConfig.name || 'Documentation';
 
         if (!baseUrl) {
@@ -209,7 +211,7 @@ export function prerender(): Plugin {
           );
         }
 
-        write404(outDir, baseHtml, siteName, frontmatter);
+        write404(outDir, baseHtml, siteName, frontmatter, getBasePath(siteConfig));
 
         console.log(`✅ Prerendered ${count} routes with page-specific meta tags`);
       } catch (error) {
@@ -241,10 +243,11 @@ function write404(
   outDir: string,
   baseHtml: string,
   siteName: string,
-  frontmatter: Array<Record<string, any>>
+  frontmatter: Array<Record<string, any>>,
+  basePath: string
 ): void {
   const firstPage = frontmatter.find(page => page.path && page.path !== '/');
-  const firstHref: string = firstPage?.path || '/';
+  const firstHref: string = `${basePath}${firstPage?.path || '/'}`;
   const firstTitle: string = firstPage?.title || siteName;
 
   let html = baseHtml;

package/src/plugins/relative-assets.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+import { resolveAssetUrl } from './relative-assets';
+
+const docsDir = '/site/docs';
+
+describe('resolveAssetUrl', () => {
+  it('resolves against the MDX file directory', () => {
+    expect(resolveAssetUrl('./assets/a.png', '/site/docs/features.mdx', docsDir)).toBe('/assets/a.png');
+    expect(resolveAssetUrl('../assets/a.png', '/site/docs/components/images.mdx', docsDir)).toBe('/assets/a.png');
+    expect(resolveAssetUrl('shots/b.png', '/site/docs/guides/intro.mdx', docsDir)).toBe('/guides/shots/b.png');
+  });
+
+  it('keeps query strings and fragments', () => {
+    expect(resolveAssetUrl('./a.svg?v=2#icon', '/site/docs/page.mdx', docsDir)).toBe('/a.svg?v=2#icon');
+  });
+
+  it('leaves absolute, protocol and anchor URLs alone', () => {
+    for (const url of ['/assets/a.png', 'https://x.dev/a.png', '//cdn.dev/a.png', 'data:image/png;base64,AA', '#top']) {
+      expect(resolveAssetUrl(url, '/site/docs/page.mdx', docsDir)).toBeNull();
+    }
+  });
+
+  it('leaves paths that escape the docs directory alone', () => {
+    expect(resolveAssetUrl('../../outside.png', '/site/docs/components/x.mdx', docsDir)).toBeNull();
+  });
+});

package/src/plugins/relative-assets.ts

@@ -0,0 +1,80 @@
+import { existsSync } from 'node:fs';
+import { dirname, relative, resolve, sep } from 'node:path';
+import { visit } from 'unist-util-visit';
+
+interface ImageNode {
+  type: 'image';
+  url: string;
+}
+
+interface JsxElementNode {
+  type: 'mdxJsxFlowElement' | 'mdxJsxTextElement';
+  name: string | null;
+  attributes: Array<{ type: string; name?: string; value?: unknown }>;
+}
+
+// Absolute paths, protocol URLs (https:, data:, mailto:), protocol-relative URLs and anchors stay as written.
+const notRelative = /^(?:[a-z][a-z\d+.-]*:|\/|#)/i;
+
+/**
+ * Resolves a relative asset URL written in `mdxFile` to a root path on the
+ * built site (docs/ maps to /). Returns null for URLs that are not relative
+ * or that point outside the docs directory.
+ */
+export function resolveAssetUrl(url: string, mdxFile: string, docsDir: string): string | null {
+  if (!url || notRelative.test(url)) return null;
+
+  const suffixIndex = url.search(/[?#]/);
+  const pathPart = suffixIndex === -1 ? url : url.slice(0, suffixIndex);
+  const suffix = suffixIndex === -1 ? '' : url.slice(suffixIndex);
+
+  const target = resolve(dirname(mdxFile), pathPart);
+  const fromDocs = relative(docsDir, target);
+  if (fromDocs.startsWith('..') || fromDocs === '') return null;
+
+  return `/${fromDocs.split(sep).join('/')}${suffix}`;
+}
+
+/**
+ * Remark plugin that rewrites relative image paths to root paths, resolved
+ * against the MDX file's own directory. Pages are served as directories
+ * (/features/ after a trailing-slash redirect), so a relative path left in
+ * the HTML would resolve against the page URL instead of the file.
+ * Covers Markdown images and <img src="..."> in MDX, and warns when the
+ * target file does not exist.
+ */
+export function remarkRelativeAssets(options: { docsDir?: string } = {}) {
+  const docsDir = options.docsDir ?? resolve(process.cwd(), 'docs');
+
+  return (tree: Parameters<typeof visit>[0], file: { path?: string }) => {
+    const mdxFile = file.path;
+    if (!mdxFile) return;
+
+    const rewrite = (url: string): string | null => {
+      const resolved = resolveAssetUrl(url, mdxFile, docsDir);
+      if (resolved === null) return null;
+      const onDisk = resolve(docsDir, decodeURI(resolved.replace(/[?#].*$/, '')).slice(1));
+      if (!existsSync(onDisk)) {
+        console.warn(`⚠️  ${relative(docsDir, mdxFile)}: image "${url}" not found at ${relative(process.cwd(), onDisk)}`);
+      }
+      return resolved;
+    };
+
+    visit(tree, (node) => {
+      if (node.type === 'image') {
+        const image = node as unknown as ImageNode;
+        image.url = rewrite(image.url) ?? image.url;
+        return;
+      }
+
+      if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') {
+        const element = node as unknown as JsxElementNode;
+        if (element.name !== 'img') return;
+        const src = element.attributes.find((attr) => attr.type === 'mdxJsxAttribute' && attr.name === 'src');
+        if (src && typeof src.value === 'string') {
+          src.value = rewrite(src.value) ?? src.value;
+        }
+      }
+    });
+  };
+}

package/src/plugins/robots-generator.ts

@@ -1,5 +1,5 @@
 import type { Plugin } from 'vite';
-import { readDoryConfig } from './shared';
+import { readDoryConfig, getBasePath, getSiteUrl } from './shared';
 
 /**
  * Generates robots.txt at build time. Emits `Disallow: /` when seo.noindex
@@ -13,15 +13,17 @@ export function robotsGenerator(): Plugin {
       const config = readDoryConfig() || {};
       const seo = config.seo || {};
 
+      const basePath = getBasePath(config);
       const lines = ['User-agent: *'];
-      lines.push(seo.noindex ? 'Disallow: /' : 'Allow: /');
+      lines.push(seo.noindex ? `Disallow: ${basePath}/` : `Allow: ${basePath}/`);
 
       if (Array.isArray(seo.robotsTxt) && seo.robotsTxt.length > 0) {
         lines.push('', ...seo.robotsTxt);
       }
 
-      if (config.url && !seo.noindex) {
-        lines.push('', `Sitemap: ${config.url}/sitemap.xml`);
+      const siteUrl = getSiteUrl(config);
+      if (siteUrl && !seo.noindex) {
+        lines.push('', `Sitemap: ${siteUrl}/sitemap.xml`);
       }
 
       this.emitFile({

package/src/plugins/sanitize.test.ts

@@ -60,6 +60,11 @@ describe('preprocessMdxTags', () => {
     expect(run('<Note>hello</Note>')).toBe('<Note>hello</Note>');
   });
 
+  it('preserves explicit list components', () => {
+    const input = '<UnorderedList>\n  <ListItem>One</ListItem>\n</UnorderedList>\n<OrderedList><ListItem>Two</ListItem></OrderedList>';
+    expect(run(input)).toBe(input);
+  });
+
   it('escapes known components without a closing tag', () => {
     expect(run('<div>no closing tag')).toBe('`<div>`no closing tag');
   });

package/src/plugins/sanitize.ts

@@ -24,7 +24,9 @@ const KNOWN_COMPONENTS = [
   'Callout', 'Note', 'Warning', 'Info', 'Tip', 'Check',
   'Latex', 'API', 'Expandable', 'ResponseField', 'Properties', 'Property',
   'Steps', 'Step', 'table', 'th', 'td', 'ul', 'ol', 'li',
+  'UnorderedList', 'OrderedList', 'ListItem',
   'APIPlayground', 'WebSocketPlayground', 'AsyncAPI', 'Source', 'Tag',
+  'Specimen', 'SpecimenProps', 'Chip', 'ChipGroup', 'Tabs', 'Tab', 'IconGrid', 'TypeScale',
   // Common HTML elements that should be preserved
   'div', 'span', 'br', 'hr', 'strong', 'em', 'b', 'i', 'u', 's',
   'blockquote', 'nav', 'section', 'article', 'header', 'footer', 'main',

package/src/plugins/shared.ts

@@ -1,6 +1,7 @@
 import matter from 'gray-matter';
 import fs from 'fs';
 import path from 'path';
+import { normalizeBasePath } from '../utils/base-path';
 
 /**
  * Shared helpers for build plugins that read docs/*.mdx and docs/dory.json.
@@ -33,6 +34,22 @@ export function readDoryConfig(docsDir?: string): Record<string, any> | null {
   }
 }
 
+/**
+ * The base path the site is served under ("" or "/docs"), from `basePath`.
+ */
+export function getBasePath(config: Record<string, any> | null): string {
+  return normalizeBasePath(config?.basePath);
+}
+
+/**
+ * Absolute site URL including the base path, e.g. "https://x.dev/docs", for
+ * canonical, sitemap and llms.txt links. "" when `url` is not configured.
+ */
+export function getSiteUrl(config: Record<string, any> | null): string {
+  const url: string = typeof config?.url === 'string' ? config.url.trim().replace(/\/+$/, '') : '';
+  return url ? `${url}${getBasePath(config)}` : '';
+}
+
 /**
  * Reads dory.json navigation and returns the flat, ordered list of page keys.
  */

package/src/plugins/sitemap-generator.ts

@@ -7,6 +7,7 @@ import {
   pathFromFilename,
   parseFrontmatter,
   escapeHtml,
+  getSiteUrl,
 } from './shared';
 
 /**
@@ -26,7 +27,7 @@ export function sitemapGenerator(): Plugin {
         return;
       }
 
-      const baseUrl: string = config.url || '';
+      const baseUrl: string = getSiteUrl(config);
       if (!baseUrl) {
         console.warn(
           '⚠️  sitemap-generator: `url` is not set in dory.json — sitemap.xml will NOT be generated. Set `url` to enable it.'