@classic-homes/theme-docs 0.0.50 → 0.2.0

package/dist/lib/parser/slug.js

@@ -0,0 +1,55 @@
+/**
+ * Heading ID generation.
+ *
+ * Two styles:
+ * - `default`: this package's original slugs (periods become hyphens, so `v2.0` → `v2-0`).
+ * - `github`: GitHub's algorithm (github-slugger), which Docusaurus, VitePress and GitHub
+ *   itself use. Pick it when migrating content whose `#anchor` links must keep working.
+ *
+ * Both styles dedupe repeated headings with a `-1`, `-2`… suffix (an explicit ID is never
+ * suffixed), and both honour an explicit `{#custom-id}` at the end of a heading.
+ */
+/** Trailing `{#custom-id}` on a heading, as Docusaurus and Pandoc write it. */
+export const EXPLICIT_ID_PATTERN = /\s*\{#([^}\s]+)\}\s*$/;
+function defaultSlug(text) {
+    return text
+        .toLowerCase()
+        .replace(/\./g, '-') // Convert periods to hyphens (preserves version numbers like v2.0 → v2-0)
+        .replace(/[^\w\s-]+/g, '') // Remove other special characters
+        .replace(/\s+/g, '-') // Convert spaces to hyphens
+        .replace(/-+/g, '-') // Collapse multiple hyphens
+        .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
+}
+/**
+ * github-slugger: lowercase, drop everything but letters, marks, numbers, connector
+ * punctuation, hyphens and spaces, then turn each space into a hyphen. Hyphens are
+ * deliberately not collapsed — `A & B` is `a--b` on GitHub too.
+ */
+function githubSlug(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, '')
+        .replace(/ /g, '-');
+}
+/**
+ * Create a slugger for one document. IDs are unique within it: the second
+ * `## Setup` becomes `setup-1`, matching github-slugger.
+ */
+export function createSlugger(style = 'default') {
+    const slugify = style === 'github' ? githubSlug : defaultSlug;
+    const seen = new Map();
+    return function slug(text, explicitId) {
+        // An explicit ID is the author's choice: used verbatim and not counted, as in Docusaurus.
+        if (explicitId)
+            return explicitId;
+        const base = slugify(text);
+        let id = base;
+        let count = seen.get(base) ?? 0;
+        while (seen.has(id)) {
+            id = `${base}-${++count}`;
+        }
+        seen.set(base, count);
+        seen.set(id, 0);
+        return id;
+    };
+}

package/dist/lib/sanitize/index.d.ts

@@ -0,0 +1,11 @@
+export interface SanitizeResult {
+    /** The cleaned HTML */
+    html: string;
+    /**
+     * What was removed, e.g. `<script>`, `p[onclick]`, `a[href=javascript:]`. Report these
+     * from a build so a page that loses markup says so instead of quietly rendering differently.
+     */
+    removed: string[];
+}
+/** Sanitize one page's rendered HTML. */
+export declare function sanitizeDocsHtml(html: string): SanitizeResult;

package/dist/lib/sanitize/index.js

@@ -0,0 +1,122 @@
+/**
+ * `@classic-homes/theme-docs/sanitize` — allowlist sanitizer for HTML from `parseMarkdown`.
+ *
+ * `parseMarkdown` passes raw HTML in markdown straight through. When pages are written by
+ * more than a few trusted people (a git repo with many authors, a browser editor), run its
+ * output through `sanitizeDocsHtml` so markup cannot run script, embed frames or set event
+ * handlers for every reader.
+ *
+ * The allowlist is what the parser itself produces — GFM tables and task lists, footnotes,
+ * definition lists, Shiki highlighting, admonition icons, heading permalinks, mermaid and
+ * component placeholders — plus the safe inline HTML authors commonly write
+ * (details/summary, kbd, sub/sup, br, mark).
+ *
+ * Server/build-time only: it depends on `sanitize-html` (and through it, postcss), which
+ * you don't want in a browser bundle.
+ */
+import sanitizeHtml from 'sanitize-html';
+const SVG = ['svg', 'path', 'circle', 'line', 'polyline', 'polygon', 'rect', 'g'];
+const OPTIONS = {
+    allowedTags: [
+        ...sanitizeHtml.defaults.allowedTags, // p, a, lists, tables, code, pre, headings, blockquote, …
+        'img',
+        'details',
+        'summary',
+        'kbd',
+        'sup',
+        'sub',
+        'del',
+        's',
+        'ins',
+        'mark',
+        'dl',
+        'dt',
+        'dd',
+        'section',
+        'input',
+        'br',
+        'hr',
+        ...SVG,
+    ],
+    allowedAttributes: {
+        '*': ['class', 'id', 'title', 'aria-hidden', 'aria-label', 'role'],
+        a: ['href', 'name', 'target', 'rel'],
+        img: ['src', 'alt', 'width', 'height', 'loading', 'decoding'],
+        pre: ['style', 'tabindex'],
+        span: ['style'],
+        code: ['style'],
+        div: ['data-component', 'data-props', 'data-mermaid'],
+        input: ['type', 'checked', 'disabled'],
+        ol: ['start', 'type'],
+        td: ['align', 'colspan', 'rowspan'],
+        th: ['align', 'colspan', 'rowspan', 'scope'],
+        details: ['open'],
+        svg: [
+            'viewBox',
+            'fill',
+            'stroke',
+            'stroke-width',
+            'stroke-linecap',
+            'stroke-linejoin',
+            'width',
+            'height',
+            'xmlns',
+        ],
+        path: ['d', 'fill', 'stroke'],
+        circle: ['cx', 'cy', 'r', 'fill', 'stroke'],
+        line: ['x1', 'x2', 'y1', 'y2'],
+        polyline: ['points'],
+        polygon: ['points'],
+        rect: ['x', 'y', 'width', 'height', 'rx', 'ry'],
+    },
+    // Shiki colours code by inline style; nothing else may set styles.
+    allowedStyles: {
+        '*': {
+            color: [/^#[0-9a-f]{3,8}$/i, /^var\(--[\w-]+\)$/],
+            'background-color': [/^#[0-9a-f]{3,8}$/i, /^var\(--[\w-]+\)$/],
+            'font-style': [/^italic$/],
+            'font-weight': [/^(bold|\d{3})$/],
+            'text-decoration': [/^(underline|line-through)$/],
+        },
+    },
+    allowedSchemes: ['http', 'https', 'mailto', 'tel'],
+    allowProtocolRelative: false,
+    // Keep the text of a dropped element (e.g. an unknown wrapper) but never of script/style.
+    disallowedTagsMode: 'discard',
+    nonTextTags: ['script', 'style', 'textarea', 'option', 'noscript', 'iframe', 'object', 'embed'],
+    parser: { lowerCaseAttributeNames: false },
+};
+const SVG_TAGS = new Set(SVG);
+const allowedTags = new Set(OPTIONS.allowedTags);
+const allowedAttributes = OPTIONS.allowedAttributes;
+const allowedAttrs = (tag) => [
+    ...allowedAttributes['*'],
+    ...(allowedAttributes[tag] ?? []),
+];
+/** Sanitize one page's rendered HTML. */
+export function sanitizeDocsHtml(html) {
+    const removed = new Set();
+    const clean = sanitizeHtml(html, {
+        ...OPTIONS,
+        transformTags: {
+            '*': (tagName, rawAttribs) => {
+                // HTML attribute names are case-insensitive, and content written as MDX uses JSX
+                // casing (`colSpan`, `rowSpan`). Lowercase them so the allowlist matches; SVG keeps
+                // its case-sensitive names (`viewBox`).
+                const attribs = SVG_TAGS.has(tagName)
+                    ? rawAttribs
+                    : Object.fromEntries(Object.entries(rawAttribs).map(([name, value]) => [name.toLowerCase(), value]));
+                if (!allowedTags.has(tagName))
+                    removed.add(`<${tagName}>`);
+                else
+                    for (const name of Object.keys(attribs))
+                        if (!allowedAttrs(tagName).includes(name))
+                            removed.add(`${tagName}[${name}]`);
+                if (attribs.href && /^\s*(javascript|data|vbscript):/i.test(attribs.href))
+                    removed.add(`${tagName}[href=${attribs.href.split(':')[0].trim()}:]`);
+                return { tagName, attribs };
+            },
+        },
+    });
+    return { html: clean, removed: [...removed] };
+}

package/dist/lib/search/index.d.ts

@@ -0,0 +1,57 @@
+/**
+ * `@classic-homes/theme-docs/search` — full-text search over rendered docs (MiniSearch).
+ *
+ * Build the index at build time with `buildSearchIndex`, ship its JSON, and query it on
+ * the server or in the browser with `createSearch`. A `filter` runs inside MiniSearch,
+ * before results and snippets are built, so access rules can drop hits a reader may not
+ * see without their text ever leaving the index.
+ */
+import { type Options } from 'minisearch';
+import type { RenderedDoc } from '../content/types.js';
+/** Fields stored with each hit, available to `filter` and in results. */
+export interface StoredFields {
+    title: string;
+    description: string;
+    sidebar: string | null;
+}
+/**
+ * Index options. `buildSearchIndex` and `createSearch` must use the same ones, so both
+ * read them from here.
+ */
+export declare const SEARCH_OPTIONS: Options;
+type Indexable = Pick<RenderedDoc, 'route' | 'title' | 'description' | 'sidebar' | 'toc' | 'text'>;
+/** Index every page. Returns MiniSearch's serialized form; write it out as JSON. */
+export declare function buildSearchIndex(pages: Indexable[]): string;
+export interface SearchHit {
+    route: string;
+    title: string;
+    description: string;
+    sidebar: string | null;
+    /** About 160 characters of the page around the first match (or its description) */
+    snippet: string;
+    /** Terms that matched, for highlighting */
+    terms: string[];
+    score: number;
+}
+export interface SearchQueryOptions {
+    /** Keep a hit only when this returns true. Runs before snippets are built. */
+    filter?: (hit: StoredFields & {
+        route: string;
+    }) => boolean;
+    /** Maximum hits. Default: 12 */
+    limit?: number;
+    /** Queries shorter than this return nothing. Default: 2 */
+    minLength?: number;
+}
+/**
+ * Load a serialized index for querying.
+ *
+ * @param indexJson - What `buildSearchIndex` returned (string or parsed object)
+ * @param texts - Page text by route, for snippets. Without it, snippets use descriptions.
+ */
+export declare function createSearch(indexJson: string | object, texts?: Map<string, string> | Record<string, string>): {
+    search(query: string, options?: SearchQueryOptions): SearchHit[];
+};
+/** About 160 characters around the first matched term. */
+export declare function snippet(text: string, terms: string[]): string;
+export {};

package/dist/lib/search/index.js

@@ -0,0 +1,82 @@
+/**
+ * `@classic-homes/theme-docs/search` — full-text search over rendered docs (MiniSearch).
+ *
+ * Build the index at build time with `buildSearchIndex`, ship its JSON, and query it on
+ * the server or in the browser with `createSearch`. A `filter` runs inside MiniSearch,
+ * before results and snippets are built, so access rules can drop hits a reader may not
+ * see without their text ever leaving the index.
+ */
+import MiniSearch from 'minisearch';
+/**
+ * Index options. `buildSearchIndex` and `createSearch` must use the same ones, so both
+ * read them from here.
+ */
+export const SEARCH_OPTIONS = {
+    fields: ['title', 'headings', 'description', 'text'],
+    storeFields: ['title', 'description', 'sidebar'],
+    searchOptions: {
+        boost: { title: 4, headings: 2, description: 1.5 },
+        prefix: true,
+        fuzzy: 0.15,
+        combineWith: 'AND',
+    },
+};
+/** Index every page. Returns MiniSearch's serialized form; write it out as JSON. */
+export function buildSearchIndex(pages) {
+    const index = new MiniSearch(SEARCH_OPTIONS);
+    index.addAll(pages.map((page) => ({
+        id: page.route,
+        title: page.title,
+        description: page.description,
+        sidebar: page.sidebar,
+        headings: page.toc.map((entry) => entry.text).join(' '),
+        text: page.text,
+    })));
+    return JSON.stringify(index);
+}
+/**
+ * Load a serialized index for querying.
+ *
+ * @param indexJson - What `buildSearchIndex` returned (string or parsed object)
+ * @param texts - Page text by route, for snippets. Without it, snippets use descriptions.
+ */
+export function createSearch(indexJson, texts) {
+    const index = MiniSearch.loadJSON(typeof indexJson === 'string' ? indexJson : JSON.stringify(indexJson), SEARCH_OPTIONS);
+    const textOf = (route) => texts instanceof Map ? texts.get(route) : texts?.[route];
+    return {
+        search(query, options = {}) {
+            const { filter, limit = 12, minLength = 2 } = options;
+            const trimmed = query.trim();
+            if (trimmed.length < minLength)
+                return [];
+            const results = index.search(trimmed, {
+                ...(filter && {
+                    filter: (hit) => filter({ ...hit, route: String(hit.id) }),
+                }),
+            });
+            return results.slice(0, limit).map((hit) => {
+                const route = String(hit.id);
+                const stored = hit;
+                return {
+                    route,
+                    title: stored.title,
+                    description: stored.description,
+                    sidebar: stored.sidebar,
+                    snippet: snippet(textOf(route) ?? stored.description ?? '', hit.terms),
+                    terms: hit.terms,
+                    score: hit.score,
+                };
+            });
+        },
+    };
+}
+/** About 160 characters around the first matched term. */
+export function snippet(text, terms) {
+    const lower = text.toLowerCase();
+    const at = Math.min(...terms.map((term) => lower.indexOf(term.toLowerCase())).filter((i) => i >= 0));
+    if (!Number.isFinite(at))
+        return text.length > 160 ? `${text.slice(0, 160).trim()}…` : text;
+    const start = Math.max(0, at - 60);
+    const end = start + 160;
+    return `${start > 0 ? '…' : ''}${text.slice(start, end).trim()}${end < text.length ? '…' : ''}`;
+}

package/dist/lib/styles/markdown.css

@@ -35,7 +35,7 @@
 .markdown-content h1 {
   font-size: 1.875rem;
   line-height: 2.25rem;
-  font-weight: 700;
+  font-weight: 500; /* Spectral italic is loaded at 400/500/600 only */
   color: hsl(var(--foreground));
   margin-top: 2rem;
   margin-bottom: 1rem;
@@ -272,6 +272,135 @@
   border-top-right-radius: 0;
 }
 
+/* Fence titles (```bash title="install.sh") rendered by parseMarkdown */
+.markdown-content .code-block-filename {
+  padding: 0.5rem 1rem;
+  font-size: 0.875rem;
+  font-family:
+    ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  color: hsl(var(--muted-foreground));
+  background-color: hsl(var(--muted) / 0.5);
+  border: 1px solid hsl(var(--border));
+  border-bottom: 0;
+  border-top-left-radius: 0.5rem;
+  border-top-right-radius: 0.5rem;
+}
+
+/* Copy buttons (enhanceCodeBlocks / DocPage) */
+.code-block-wrapper.has-copy-button {
+  position: relative;
+}
+
+.code-copy-button {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  padding: 0.375rem;
+  border-radius: 0.375rem;
+  border: 1px solid hsl(0 0% 100% / 0.2);
+  background-color: hsl(0 0% 0% / 0.4);
+  color: hsl(0 0% 100% / 0.85);
+  cursor: pointer;
+  opacity: 0;
+  transition: opacity 150ms;
+}
+
+.code-block-filename + .shiki + .code-copy-button {
+  top: calc(0.5rem + 2.3rem);
+}
+
+.code-block-wrapper:hover .code-copy-button,
+.code-copy-button:focus-visible,
+.code-copy-button[data-copied] {
+  opacity: 1;
+}
+
+.code-copy-button:focus-visible {
+  outline: 2px solid hsl(var(--ring));
+  outline-offset: 2px;
+}
+
+.code-copy-button svg {
+  width: 100%;
+  height: 100%;
+}
+
+@media (hover: none) {
+  .code-copy-button {
+    opacity: 1;
+  }
+}
+
+.docs-sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+}
+
+/* Search terms carried over from a search result (?highlight=) */
+.markdown-content mark.search-highlight {
+  background-color: hsl(var(--warning) / 0.35);
+  color: inherit;
+  border-radius: 0.125rem;
+  padding: 0 0.0625rem;
+}
+
+/* ==========================================================================
+   Heading permalinks (headingAnchors option)
+   ========================================================================== */
+
+/* Anchor targets clear a fixed header when jumped to (DocPage sets the variable) */
+.markdown-content [id] {
+  scroll-margin-top: var(--docs-header-offset, 5rem);
+}
+
+.markdown-content .hash-link {
+  margin-left: 0.5rem;
+  color: hsl(var(--primary));
+  text-decoration: none;
+  opacity: 0;
+}
+
+.markdown-content .hash-link::before {
+  content: '#';
+}
+
+.markdown-content :is(h1, h2, h3, h4, h5, h6):hover .hash-link,
+.markdown-content .hash-link:focus-visible {
+  opacity: 1;
+}
+
+/* ==========================================================================
+   External links (externalLinks option)
+   ========================================================================== */
+
+.markdown-content .external-link::after {
+  content: '\2197';
+  margin-left: 0.125rem;
+  font-size: 0.75em;
+}
+
+.markdown-content .external-link-hint {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
 /* ==========================================================================
    Admonitions / Callouts
    ========================================================================== */
@@ -321,6 +450,17 @@
   color: hsl(210 100% 40%);
 }
 
+/* Info - Sky */
+.markdown-content .admonition-info {
+  border-color: hsl(199 89% 48% / 0.3);
+  background: hsl(199 89% 48% / 0.05);
+}
+
+.markdown-content .admonition-info .admonition-heading {
+  background: hsl(199 89% 48% / 0.1);
+  color: hsl(199 89% 32%);
+}
+
 /* Tip - Green */
 .markdown-content .admonition-tip {
   border-color: hsl(142 71% 45% / 0.3);
@@ -365,6 +505,17 @@
   color: hsl(0 84% 45%);
 }
 
+/* Danger - Deep red */
+.markdown-content .admonition-danger {
+  border-color: hsl(0 72% 42% / 0.45);
+  background: hsl(0 72% 42% / 0.08);
+}
+
+.markdown-content .admonition-danger .admonition-heading {
+  background: hsl(0 72% 42% / 0.16);
+  color: hsl(0 72% 35%);
+}
+
 /* ==========================================================================
    Footnotes
    ========================================================================== */
@@ -455,6 +606,15 @@
   height: auto;
 }
 
+/* Mermaid writes a diagram's classDef names onto its SVG nodes, so a diagram
+   with `classDef hidden …` gets nodes classed `hidden` — which Tailwind's
+   .hidden utility collapses. Not scoped to .markdown-content: mermaid measures
+   labels in a temporary SVG appended to <body> before placing the diagram. */
+svg g.node.hidden,
+svg g.cluster.hidden {
+  display: inline;
+}
+
 .markdown-content .mermaid-diagram pre.mermaid {
   margin: 0;
   padding: 0;

package/dist/lib/types/frontmatter.d.ts

@@ -1,6 +1,7 @@
 /**
  * Frontmatter Types for Documentation
  */
+import type { HeadingIdStyle } from '../parser/slug.js';
 /** Author information as an object */
 export interface AuthorInfo {
     /** Author's display name */
@@ -49,6 +50,12 @@ export interface ParsedMarkdown {
     markdown: string;
     /** Rendered HTML content */
     html: string;
+    /** Every heading with an ID, in document order (all levels; filter by `level` as needed) */
+    toc: {
+        text: string;
+        level: number;
+        id: string;
+    }[];
 }
 /** Parser options */
 export interface ParseOptions {
@@ -56,6 +63,31 @@ export interface ParseOptions {
     theme?: string;
     /** Whether to generate heading IDs */
     generateHeadingIds?: boolean;
+    /**
+     * Heading ID algorithm. `github` matches GitHub and Docusaurus (github-slugger), for
+     * content whose existing `#anchor` links must keep working. Default: `default`.
+     */
+    headingIdStyle?: HeadingIdStyle;
+    /**
+     * Component names to render as placeholders when written as a self-closing tag on a
+     * line of its own (`<RequestForm id="x" />`). Mount them with `mountComponents`.
+     */
+    components?: readonly string[];
+    /** Append a `#` permalink (`a.hash-link`) to each heading, as Docusaurus does. Default: false */
+    headingAnchors?: boolean;
+    /**
+     * Open `http(s)` links in a new tab with a visually hidden "(opens in new tab)" note.
+     * `true` uses `target="_blank" rel="noopener noreferrer"`. Default: false
+     */
+    externalLinks?: boolean | {
+        target?: string;
+        rel?: string;
+    };
+    /**
+     * Map code fence names to Shiki languages, e.g. `{ ios: 'text', caddyfile: 'nginx' }`.
+     * Languages Shiki doesn't know render as plain code.
+     */
+    langAlias?: Record<string, string>;
 }
 /** MarkdownPage component props */
 export interface MarkdownPageProps {

package/dist/lib/vite/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `@classic-homes/theme-docs/vite` — regenerate docs content while you write.
+ *
+ * Runs your `generate` step (typically `loadDocs` → `renderDocs` → write JSON) when the
+ * dev server starts and whenever a file under `watch` changes, then reloads the page.
+ * Builds run it once before bundling, so the generated files are always current.
+ */
+import type { Plugin } from 'vite';
+export interface DocsContentPluginOptions {
+    /** Directories (or files) whose changes trigger `generate` */
+    watch: string | string[];
+    /** Produce the content the app imports. Throw to report a failure. */
+    generate: () => void | Promise<void>;
+    /** Wait this long after the last change before regenerating. Default: 200ms */
+    debounce?: number;
+}
+export declare function docsContent(options: DocsContentPluginOptions): Plugin;

package/dist/lib/vite/index.js

@@ -0,0 +1,38 @@
+/**
+ * `@classic-homes/theme-docs/vite` — regenerate docs content while you write.
+ *
+ * Runs your `generate` step (typically `loadDocs` → `renderDocs` → write JSON) when the
+ * dev server starts and whenever a file under `watch` changes, then reloads the page.
+ * Builds run it once before bundling, so the generated files are always current.
+ */
+import path from 'node:path';
+export function docsContent(options) {
+    const { generate, debounce = 200 } = options;
+    const watched = (Array.isArray(options.watch) ? options.watch : [options.watch]).map((p) => path.resolve(p));
+    const isWatched = (file) => watched.some((w) => file === w || file.startsWith(w + path.sep));
+    let timer;
+    return {
+        name: 'classic-theme-docs:content',
+        async buildStart() {
+            await generate();
+        },
+        configureServer(server) {
+            server.watcher.add(watched);
+            server.watcher.on('all', (_event, file) => {
+                if (!isWatched(path.resolve(file)))
+                    return;
+                clearTimeout(timer);
+                timer = setTimeout(async () => {
+                    try {
+                        await generate();
+                        server.config.logger.info('[docs] content regenerated', { timestamp: true });
+                        server.ws.send({ type: 'full-reload' });
+                    }
+                    catch (err) {
+                        server.config.logger.error(`[docs] content regeneration failed:\n${err.stack ?? err}`);
+                    }
+                }, debounce);
+            });
+        },
+    };
+}