@classic-homes/theme-docs 0.0.50 → 0.2.0

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

@@ -0,0 +1,90 @@
+/**
+ * Shapes of the docs content model built by `loadDocs` and `renderDocs`.
+ * Plain data: safe to serialize into a bundle and to import from client code.
+ */
+import type { FrontmatterData } from '../types/frontmatter.js';
+import type { TocEntry } from '../types/docs.js';
+/** One sidebar entry. A category's `route` is its linked doc or generated-index page. */
+export type NavItem = {
+    type: 'page';
+    title: string;
+    route: string;
+} | {
+    type: 'category';
+    label: string;
+    route?: string;
+    /** From `_category_.json`. Undefined means the site's default. */
+    collapsible?: boolean;
+    collapsed?: boolean;
+    items: NavItem[];
+};
+/** A markdown file, with its links rewritten to site routes. */
+export interface DocSource {
+    /** Site route, e.g. `/docs/it/network/vpn` (`index.md` maps to its folder) */
+    route: string;
+    /** Path under the docs directory, posix separators, e.g. `it/network/vpn/index.md` */
+    file: string;
+    /** ID of the sidebar the page belongs to, or null when it sits outside every sidebar root */
+    sidebar: string | null;
+    /** `title` front matter, else the first `# heading`, else the file name */
+    title: string;
+    /** `sidebar_label` front matter: the page's name in navigation (Docusaurus parity) */
+    sidebarLabel?: string;
+    description: string;
+    tags: string[];
+    /** `sidebar_position` front matter */
+    position?: number;
+    /** The page's full front matter, including fields this package doesn't know */
+    frontmatter: FrontmatterData;
+    /** Markdown body (no front matter), links resolved */
+    markdown: string;
+}
+/** A sidebar autogenerated from one directory, as Docusaurus `{type: 'autogenerated', dirName}` does. */
+export interface Sidebar {
+    /** The directory it was generated from (relative to the docs dir), or `default` for the root */
+    id: string;
+    /** The directory, relative to the docs dir ('' for the root) */
+    dir: string;
+    /** `_category_.json` label of the directory, else its name */
+    label: string;
+    /** `_category_.json` position of the directory */
+    position?: number;
+    /** Route of the directory itself */
+    route: string;
+    /** The directory's index page if it has one, else its shallowest, lowest-positioned page */
+    landingRoute: string;
+    items: NavItem[];
+}
+/** A generated-index page (`_category_.json` `link: { type: 'generated-index' }`). */
+export interface CategoryPage {
+    route: string;
+    sidebar: string;
+    title: string;
+    description: string;
+    /** The category's items, in sidebar order */
+    items: NavItem[];
+}
+export interface Tag {
+    id: string;
+    label: string;
+    description: string;
+}
+export interface DocsContent {
+    pages: DocSource[];
+    sidebars: Sidebar[];
+    categories: CategoryPage[];
+    /** The tag vocabulary when one was given, else every tag used, in first-use order */
+    tags: Tag[];
+    /** Non-fatal problems, e.g. broken links when `onBrokenLinks` is `'warn'` */
+    warnings: string[];
+}
+/** A page after `renderDocs`: HTML instead of markdown, plus what layouts and search need. */
+export interface RenderedDoc extends Omit<DocSource, 'markdown'> {
+    html: string;
+    /** Headings with IDs, all levels */
+    toc: TocEntry[];
+    /** Whether the body has its own `<h1>`. When it doesn't, the layout shows `title`. */
+    hasH1: boolean;
+    /** Searchable plain text: the page without markup, code blocks or diagrams */
+    text: string;
+}

package/dist/lib/content/types.js

@@ -0,0 +1,5 @@
+/**
+ * Shapes of the docs content model built by `loadDocs` and `renderDocs`.
+ * Plain data: safe to serialize into a bundle and to import from client code.
+ */
+export {};

package/dist/lib/index.d.ts

@@ -5,11 +5,15 @@
  * with syntax highlighting, frontmatter support, and rich markdown extensions.
  *
  * Supported Markdown Extensions:
- * - Admonitions/Callouts: :::note, :::tip, :::warning, :::important, :::caution
+ * - Admonitions/Callouts: :::note, :::info, :::tip, :::warning, :::important, :::caution, :::danger
  * - Footnotes: [^1] references and [^1]: definitions
  * - Definition Lists: Term followed by : Definition
  * - Mermaid Diagrams: ```mermaid code blocks (rendered client-side)
  *
+ * Node/server code (build scripts, loaders) should import the pipeline from
+ * `@classic-homes/theme-docs/parser`, which has no Svelte imports, and sanitize
+ * rendered HTML with `@classic-homes/theme-docs/sanitize`.
+ *
  * @packageDocumentation
  */
 export { default as MarkdownPage } from './components/MarkdownPage.svelte';
@@ -20,10 +24,20 @@ export { default as TableOfContents } from './components/TableOfContents.svelte'
 export { default as TocPanel } from './components/TocPanel.svelte';
 export { default as MermaidDiagram } from './components/MermaidDiagram.svelte';
 export { default as MermaidInit } from './components/MermaidInit.svelte';
+export { default as DocPage } from './components/DocPage.svelte';
+export { default as CategoryIndex } from './components/CategoryIndex.svelte';
+export { default as Breadcrumbs } from './components/Breadcrumbs.svelte';
+export { default as DocPager } from './components/DocPager.svelte';
+export { default as TagList } from './components/TagList.svelte';
+export { default as TagIndex } from './components/TagIndex.svelte';
+export { mountComponents } from './components/mount.js';
+export { enhanceCodeBlocks, highlightTerms, labelDiagram } from './components/enhance.js';
+export { toSidebarNav, revealActive, type ToSidebarNavOptions } from './components/sidebar.js';
 export type { AuthorInfo, FrontmatterData, ParsedMarkdown, ParseOptions, MarkdownPageProps, } from './types/frontmatter.js';
 export type { DocsItem, DocsSection, DocsHubConfig, DocsHubProps, DocsCardProps, TocEntry, TableOfContentsProps, } from './types/docs.js';
 export { parseMarkdown, extractToc } from './parser/index.js';
+export { createSlugger, type HeadingIdStyle } from './parser/slug.js';
 export { highlightCode, getHighlighter, escapeHtml } from './highlighter/index.js';
 export { cn } from './utils.js';
-export { ADMONITION_TYPES, type AdmonitionType, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, getAllExtensions, resetFootnoteStore, renderFootnotes, } from './parser/extensions.js';
+export { ADMONITION_TYPES, type AdmonitionType, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, componentExtension, getAllExtensions, createFootnoteStore, type FootnoteStore, resetFootnoteStore, renderFootnotes, renderMermaidPlaceholder, } from './parser/extensions.js';
 export { tv, type VariantProps } from 'tailwind-variants';

package/dist/lib/index.js

@@ -5,11 +5,15 @@
  * with syntax highlighting, frontmatter support, and rich markdown extensions.
  *
  * Supported Markdown Extensions:
- * - Admonitions/Callouts: :::note, :::tip, :::warning, :::important, :::caution
+ * - Admonitions/Callouts: :::note, :::info, :::tip, :::warning, :::important, :::caution, :::danger
  * - Footnotes: [^1] references and [^1]: definitions
  * - Definition Lists: Term followed by : Definition
  * - Mermaid Diagrams: ```mermaid code blocks (rendered client-side)
  *
+ * Node/server code (build scripts, loaders) should import the pipeline from
+ * `@classic-homes/theme-docs/parser`, which has no Svelte imports, and sanitize
+ * rendered HTML with `@classic-homes/theme-docs/sanitize`.
+ *
  * @packageDocumentation
  */
 // Components
@@ -21,11 +25,21 @@ export { default as TableOfContents } from './components/TableOfContents.svelte'
 export { default as TocPanel } from './components/TocPanel.svelte';
 export { default as MermaidDiagram } from './components/MermaidDiagram.svelte';
 export { default as MermaidInit } from './components/MermaidInit.svelte';
+export { default as DocPage } from './components/DocPage.svelte';
+export { default as CategoryIndex } from './components/CategoryIndex.svelte';
+export { default as Breadcrumbs } from './components/Breadcrumbs.svelte';
+export { default as DocPager } from './components/DocPager.svelte';
+export { default as TagList } from './components/TagList.svelte';
+export { default as TagIndex } from './components/TagIndex.svelte';
+export { mountComponents } from './components/mount.js';
+export { enhanceCodeBlocks, highlightTerms, labelDiagram } from './components/enhance.js';
+export { toSidebarNav, revealActive } from './components/sidebar.js';
 // Utilities
 export { parseMarkdown, extractToc } from './parser/index.js';
+export { createSlugger } from './parser/slug.js';
 export { highlightCode, getHighlighter, escapeHtml } from './highlighter/index.js';
 export { cn } from './utils.js';
 // Markdown Extensions
-export { ADMONITION_TYPES, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, getAllExtensions, resetFootnoteStore, renderFootnotes, } from './parser/extensions.js';
+export { ADMONITION_TYPES, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, componentExtension, getAllExtensions, createFootnoteStore, resetFootnoteStore, renderFootnotes, renderMermaidPlaceholder, } from './parser/extensions.js';
 // Re-export tailwind-variants types for consumer convenience
 export { tv } from 'tailwind-variants';

package/dist/lib/parser/api.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@classic-homes/theme-docs/parser` — the markdown pipeline without any Svelte imports.
+ *
+ * Safe to load in Node (build scripts, server loaders, workers) and in non-Svelte bundles
+ * such as a CMS preview. The package root re-exports all of this alongside the components.
+ */
+export { parseMarkdown, extractToc } from './index.js';
+export { createSlugger, type HeadingIdStyle } from './slug.js';
+export { ADMONITION_TYPES, type AdmonitionType, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, componentExtension, getAllExtensions, createFootnoteStore, type FootnoteStore, resetFootnoteStore, renderFootnotes, renderMermaidPlaceholder, } from './extensions.js';
+export { highlightCode, getHighlighter, escapeHtml } from '../highlighter/index.js';
+export type { AuthorInfo, FrontmatterData, ParsedMarkdown, ParseOptions, } from '../types/frontmatter.js';
+export type { TocEntry } from '../types/docs.js';

package/dist/lib/parser/api.js

@@ -0,0 +1,10 @@
+/**
+ * `@classic-homes/theme-docs/parser` — the markdown pipeline without any Svelte imports.
+ *
+ * Safe to load in Node (build scripts, server loaders, workers) and in non-Svelte bundles
+ * such as a CMS preview. The package root re-exports all of this alongside the components.
+ */
+export { parseMarkdown, extractToc } from './index.js';
+export { createSlugger } from './slug.js';
+export { ADMONITION_TYPES, admonitionExtension, footnoteExtension, definitionListExtension, mermaidExtension, componentExtension, getAllExtensions, createFootnoteStore, resetFootnoteStore, renderFootnotes, renderMermaidPlaceholder, } from './extensions.js';
+export { highlightCode, getHighlighter, escapeHtml } from '../highlighter/index.js';

package/dist/lib/parser/extensions.d.ts

@@ -2,16 +2,17 @@
  * Marked Extensions for Enhanced Markdown Features
  *
  * Provides support for:
- * - Admonitions/Callouts (note, tip, warning, important, caution)
+ * - Admonitions/Callouts (note, info, tip, warning, important, caution, danger)
  * - Footnotes
  * - Definition Lists
  * - Mermaid diagram placeholders (rendered client-side)
+ * - Component placeholders for allowlisted `<Name prop="…" />` tags (mounted client-side)
  */
-import type { MarkedExtension } from 'marked';
+import type { MarkedExtension, Tokens } from 'marked';
 /**
  * Admonition types and their corresponding icons/classes
  */
-export declare const ADMONITION_TYPES: readonly ["note", "tip", "warning", "important", "caution"];
+export declare const ADMONITION_TYPES: readonly ["note", "info", "tip", "warning", "important", "caution", "danger"];
 export type AdmonitionType = (typeof ADMONITION_TYPES)[number];
 /**
  * Admonition extension for marked
@@ -24,10 +25,33 @@ export type AdmonitionType = (typeof ADMONITION_TYPES)[number];
  * :::warning Title Here
  * This is a warning with a custom title
  * :::
+ *
+ * :::tip[Title Here]
+ * The bracketed title form, as written for Docusaurus (remark-directive)
+ * :::
+ *
+ * Titles are inline markdown, so `code` and *emphasis* render.
  */
 export declare function admonitionExtension(): MarkedExtension;
 /**
- * Reset footnote store (call before parsing a new document)
+ * Footnotes collected while parsing one document.
+ *
+ * Each `parseMarkdown` call creates its own store, so concurrent parses (e.g. a server
+ * rendering many pages at once) never mix up each other's footnotes.
+ */
+export interface FootnoteStore {
+    definitions: Map<string, {
+        content: string;
+        tokens: Tokens.Generic[];
+    }>;
+    references: Set<string>;
+}
+export declare function createFootnoteStore(): FootnoteStore;
+/**
+ * Reset the default footnote store.
+ *
+ * @deprecated `parseMarkdown` now keeps a store per call. Only needed if you build a
+ * `Marked` instance yourself from `footnoteExtension()` without passing a store.
  */
 export declare function resetFootnoteStore(): void;
 /**
@@ -38,23 +62,16 @@ export declare function resetFootnoteStore(): void;
  *
  * [^1]: This is the footnote content.
  */
-export declare function footnoteExtension(): MarkedExtension;
+export declare function footnoteExtension(store?: FootnoteStore): MarkedExtension;
 /**
  * Render collected footnotes as a section
  * Call this after parsing to get the footnotes HTML
- */
-export declare function renderFootnotes(): string;
-/**
- * Definition list extension for marked
  *
- * Syntax:
- * Term 1
- * : Definition for term 1
- *
- * Term 2
- * : Definition for term 2
- * : Another definition for term 2
+ * @param store - The store the footnote extension wrote to (default: the shared store)
+ * @param renderInline - Renders a footnote's inline tokens to HTML. Without it the
+ *   footnote text is escaped and shown as written.
  */
+export declare function renderFootnotes(store?: FootnoteStore, renderInline?: (tokens: Tokens.Generic[]) => string): string;
 export declare function definitionListExtension(): MarkedExtension;
 /**
  * Mermaid code block extension for marked
@@ -68,8 +85,25 @@ export declare function definitionListExtension(): MarkedExtension;
  *   A --> B
  * ```
  */
+export declare function renderMermaidPlaceholder(code: string): string;
 export declare function mermaidExtension(): MarkedExtension;
+/**
+ * Component placeholder extension for marked
+ *
+ * Syntax (on a line of its own, string props only):
+ * <RequestForm id="ai-use-request" />
+ *
+ * Renders an empty placeholder that `mountComponents` fills with the real component:
+ * <div data-component="RequestForm" data-props="{&quot;id&quot;:&quot;ai-use-request&quot;}"></div>
+ *
+ * Only names in `names` are recognised, so any other tag stays ordinary HTML. This lets
+ * MDX-style pages render without an MDX compiler.
+ */
+export declare function componentExtension(names: readonly string[]): MarkedExtension;
 /**
  * Get all markdown extensions
+ *
+ * @param components - Names of components to render as placeholders (see `componentExtension`)
+ * @param footnotes - Store for this document's footnotes (default: the shared store)
  */
-export declare function getAllExtensions(): MarkedExtension[];
+export declare function getAllExtensions(components?: readonly string[], footnotes?: FootnoteStore): MarkedExtension[];