markupress 0.0.2 → 0.1.0

package/dist/controllers/shell.js

@@ -1,44 +1,39 @@
-/** Native controls and storage own interaction; HTML Next owns reactive state and cleanup. */
+/**
+ * Native controls and storage own interaction; HTML Next owns reactive state and cleanup. The drawer is a
+ * native popover and the dropdowns are native details, which open without this controller. HTMLKit keeps
+ * the shell across client navigation, so a followed link here closes the drawer and any open dropdown, as a
+ * document load would.
+ */
 export default function shell(host) {
     host.on('connect', () => {
         const document = host.root.ownerDocument;
         const window = document.defaultView;
-        let saved = null;
-        try {
-            saved = window.localStorage.getItem('markupress:theme');
-        }
-        catch { /* Storage can be disabled while native controls remain usable. */ }
-        host.state.dark = saved === 'dark' || (saved === null && window.matchMedia('(prefers-color-scheme: dark)').matches);
-        const actions = host.root.querySelector(':scope > header > .actions');
-        const applyTheme = () => {
-            document.documentElement.dataset.theme = host.state.dark ? 'dark' : 'light';
+        // The plugin's head script chose the theme before first paint.
+        host.state.dark = document.documentElement.dataset.theme === 'dark';
+        const close = (except) => {
+            for (const open of host.root.querySelectorAll('header details[open]'))
+                if (!open.contains(except ?? null))
+                    open.removeAttribute('open');
         };
-        applyTheme();
-        // HTMLKit head metadata admits no script, so a saved theme lands after first paint. Settle it
-        // at once instead of animating controls out of the default theme; user toggles still animate.
-        for (const transition of document.getAnimations())
-            if (transition instanceof window.CSSTransition)
-                transition.finish();
         const click = (event) => {
             const target = event.target;
             if (!(target instanceof window.Element))
                 return;
-            if (!actions.contains(target))
-                return;
-            const action = target.closest('[data-action]')?.getAttribute('data-action');
-            if (action === 'theme') {
+            if (target.closest('[data-action="theme"]')) {
                 host.state.dark = !host.state.dark;
-                applyTheme();
                 const theme = host.state.dark ? 'dark' : 'light';
+                document.documentElement.dataset.theme = theme;
                 try {
                     window.localStorage.setItem('markupress:theme', theme);
                 }
                 catch { /* Theme still applies for this page. */ }
             }
-            if (action === 'menu') {
-                host.state.menu = !host.state.menu;
-            }
+            const link = target.closest('a[href]');
+            close(link ? undefined : target);
+            if (link)
+                host.root.querySelector('#documentation-navigation:popover-open')?.hidePopover();
         };
+        // The page sits inside the shell, so this sees every click: one outside a dropdown closes it.
         host.root.addEventListener('click', click);
         return () => host.root.removeEventListener('click', click);
     });

package/dist/controllers/shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/controllers/shell.ts"],"names":[],"mappings":"AAGA,8FAA8F;AAC9F,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,IAAmB;IAC/C,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;QACzC,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAY,CAAC;QACrC,IAAI,KAAK,GAAkB,IAAI,CAAC;QAChC,IAAI,CAAC;YAAC,KAAK,GAAG,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,kEAAkE,CAAC,CAAC;QAC7I,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,KAAK,KAAK,MAAM,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,MAAM,CAAC,UAAU,CAAC,8BAA8B,CAAC,CAAC,OAAO,CAAC,CAAC;QACpH,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,4BAA4B,CAAE,CAAC;QACvE,MAAM,UAAU,GAAG,GAAG,EAAE;YACtB,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;QAC9E,CAAC,CAAC;QACF,UAAU,EAAE,CAAC;QACb,8FAA8F;QAC9F,8FAA8F;QAC9F,KAAK,MAAM,UAAU,IAAI,QAAQ,CAAC,aAAa,EAAE;YAAE,IAAI,UAAU,YAAY,MAAM,CAAC,aAAa;gBAAE,UAAU,CAAC,MAAM,EAAE,CAAC;QACvH,MAAM,KAAK,GAAG,CAAC,KAAY,EAAE,EAAE;YAC7B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YAC5B,IAAI,CAAC,CAAC,MAAM,YAAY,MAAM,CAAC,OAAO,CAAC;gBAAE,OAAO;YAChD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC;gBAAE,OAAO;YACtC,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,YAAY,CAAC,aAAa,CAAC,CAAC;YAC5E,IAAI,MAAM,KAAK,OAAO,EAAE,CAAC;gBACvB,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;gBACnC,UAAU,EAAE,CAAC;gBACb,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;gBACjD,IAAI,CAAC;oBAAC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,wCAAwC,CAAC,CAAC;YACpH,CAAC;YACD,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;gBACtB,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;YACrC,CAAC;QACH,CAAC,CAAC;QACF,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../../src/controllers/shell.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,CAAC,OAAO,UAAU,KAAK,CAAC,IAAmB;IAC/C,IAAI,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE;QACtB,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC;QACzC,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAY,CAAC;QACrC,+DAA+D;QAC/D,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,KAAK,MAAM,CAAC;QACpE,MAAM,KAAK,GAAG,CAAC,MAAgB,EAAE,EAAE;YACjC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,sBAAsB,CAAC;gBAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,IAAI,IAAI,CAAC;oBAAE,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;QAC1I,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,CAAC,KAAY,EAAE,EAAE;YAC7B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;YAC5B,IAAI,CAAC,CAAC,MAAM,YAAY,MAAM,CAAC,OAAO,CAAC;gBAAE,OAAO;YAChD,IAAI,MAAM,CAAC,OAAO,CAAC,uBAAuB,CAAC,EAAE,CAAC;gBAC5C,IAAI,CAAC,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;gBACnC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;gBACjD,QAAQ,CAAC,eAAe,CAAC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC;gBAC/C,IAAI,CAAC;oBAAC,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,kBAAkB,EAAE,KAAK,CAAC,CAAC;gBAAC,CAAC;gBAAC,MAAM,CAAC,CAAC,wCAAwC,CAAC,CAAC;YACpH,CAAC;YACD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;YACvC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;YACjC,IAAI,IAAI;gBAAE,IAAI,CAAC,IAAI,CAAC,aAAa,CAAc,wCAAwC,CAAC,EAAE,WAAW,EAAE,CAAC;QAC1G,CAAC,CAAC;QACF,8FAA8F;QAC9F,IAAI,CAAC,IAAI,CAAC,gBAAgB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC3C,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC7D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 export { compileMarkdown } from './content.js';
-export type { CompiledMarkdown, MarkdownOptions } from './content.js';
-export { buildSite, devSite, prepareSite, previewSite } from './site.js';
-export type { DocumentationPage, DocumentationVersion, MarkupressOptions, PreparedSite } from './site.js';
+export type { CompiledMarkdown, FrontMatter, MarkdownOptions, OutlineItem } from './content.js';
+export { markdown } from './markdown.js';
+export type { MarkdownPluginOptions } from './markdown.js';
+export type { Link, NavItem, SidebarItem, SidebarNode } from './navigation.js';
+export { buildSite, devSite, markupress, previewSite, siteOptions } from './site.js';
+export type { DocumentationPage, DocumentationVersion, MarkupressOptions } from './site.js';
 export { snapshotVersion, versionLinks } from './versions.js';
 export type { VersionLink } from './versions.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACzE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAC1G,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAChG,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,YAAY,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACrF,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 // Public exports are introduced with implemented, verified product behavior.
 export { compileMarkdown } from './content.js';
-export { buildSite, devSite, prepareSite, previewSite } from './site.js';
+export { markdown } from './markdown.js';
+export { buildSite, devSite, markupress, previewSite, siteOptions } from './site.js';
 export { snapshotVersion, versionLinks } from './versions.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAEzE,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE/C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGzC,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAErF,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/markdown.d.ts

@@ -0,0 +1,24 @@
+import type { HtmlKitPlugin } from '@nextwebwg/htmlkit';
+import { type CompiledMarkdown, type FrontMatter } from './content.js';
+export interface MarkdownPluginOptions {
+    /** Directory that a page's root-relative images and files (/logo.svg) come from; without one they stay site URLs. */
+    readonly publicDir?: (file: string) => string | undefined;
+    /** Called with each compiled page and its URL, for example to catalog documents. */
+    readonly onPage?: (page: CompiledMarkdown & {
+        readonly file: string;
+        readonly href: string | undefined;
+    }) => void;
+    /** Stylesheet files every Markdown page component imports, such as a theme's prose styles. */
+    readonly styles?: readonly string[];
+    /** Number the lines of every highlighted code block unless its fence says `:no-line-numbers`. */
+    readonly lineNumbers?: boolean;
+    /** Front matter for a page that its own fields override, such as a folder's label and position on its index page. */
+    readonly frontmatter?: (file: string) => FrontMatter | undefined;
+}
+/**
+ * An HTMLKit page plugin: each .md file compiles to an HTML Next page, which HTMLKit routes, orders,
+ * renders, and builds like an .html page. Links to other .md files and referenced files resolve
+ * through HTMLKit, so the plugin holds no routing of its own.
+ */
+export declare function markdown(options?: MarkdownPluginOptions): HtmlKitPlugin;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/markdown.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAmB,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAExF,MAAM,WAAW,qBAAqB;IACpC,qHAAqH;IACrH,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC1D,oFAAoF;IACpF,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,KAAK,IAAI,CAAC;IAClH,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,iGAAiG;IACjG,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;IAC/B,qHAAqH;IACrH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;CAClE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,qBAA0B,GAAG,aAAa,CAkB3E"}

package/dist/markdown.js

@@ -0,0 +1,54 @@
+import { createHash } from 'node:crypto';
+import { dirname, resolve } from 'node:path';
+import { compileMarkdown } from './content.js';
+/**
+ * An HTMLKit page plugin: each .md file compiles to an HTML Next page, which HTMLKit routes, orders,
+ * renders, and builds like an .html page. Links to other .md files and referenced files resolve
+ * through HTMLKit, so the plugin holds no routing of its own.
+ */
+export function markdown(options = {}) {
+    return { name: 'markdown', pages: { extensions: ['.md'], async compile(source, page) {
+                const href = page.href(page.file);
+                // The URL, not the machine's path, names the page, so builds are reproducible.
+                const pageName = 'page-md-' + createHash('sha256').update(href ?? page.file).digest('hex').slice(0, 20);
+                // compileMarkdown also passes through links it already resolved; return those unchanged.
+                const resolved = new Set();
+                const frontmatter = options.frontmatter?.(page.file);
+                const compiled = await compileMarkdown(source, { file: page.file, pageName, ...(options.styles ? { styles: options.styles } : {}),
+                    ...(options.lineNumbers === undefined ? {} : { lineNumbers: options.lineNumbers }), ...(frontmatter ? { frontmatter } : {}), resolveLink(target, kind) {
+                        if (resolved.has(target))
+                            return target;
+                        const url = link(target, kind, page, options);
+                        resolved.add(url);
+                        return url;
+                    } });
+                options.onPage?.({ ...compiled, file: page.file, href });
+                return compiled.resource;
+            } } };
+}
+function link(href, kind, page, options) {
+    if (/^(?:[A-Za-z][A-Za-z\d+.-]*:|#|\/\/)/.test(href))
+        return href;
+    if (href.startsWith('/') && kind === 'link')
+        return href;
+    const [path, suffix = ''] = href.split(/(?=[?#])/, 2);
+    let target;
+    if (path.startsWith('/')) {
+        const directory = options.publicDir?.(page.file);
+        if (directory === undefined)
+            return href;
+        target = resolve(directory, '.' + decodeURIComponent(path));
+    }
+    else
+        target = resolve(dirname(page.file), decodeURIComponent(path));
+    if (path.endsWith('.md')) {
+        const url = page.href(target);
+        if (url === undefined)
+            throw new Error(`${page.file}: missing document ${href}.`);
+        return url + suffix;
+    }
+    if (kind === 'asset' || path.includes('.'))
+        return page.asset(target) + suffix;
+    return href;
+}
+//# sourceMappingURL=markdown.js.map

package/dist/markdown.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown.js","sourceRoot":"","sources":["../src/markdown.ts"],"names":[],"mappings":"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"}

package/dist/navigation.d.ts

@@ -0,0 +1,51 @@
+import type { NavigationItem, NavigationNode } from '@nextwebwg/htmlkit';
+import type { FrontMatter } from './content.js';
+/** A top navigation or footer link. A path starting with `/` is a page of the selected version. */
+export interface Link {
+    readonly label: string;
+    readonly href: string;
+}
+/** A top navigation entry: a link, or a dropdown of links. */
+export type NavItem = Link | {
+    readonly label: string;
+    readonly items: readonly Link[];
+};
+/** An explicit sidebar entry: a page by its path in the version (`/guide/install/`), a link, or a group. */
+export type SidebarItem = string | Link | {
+    readonly label: string;
+    readonly items: readonly SidebarItem[];
+    readonly collapsed?: boolean;
+};
+/** A sidebar entry as `<hk-nav>` renders it: a page or link with `href`, and a folder or group with `children`. */
+export interface SidebarNode {
+    readonly label: string;
+    readonly href?: string;
+    readonly current: string;
+    readonly open: boolean;
+    readonly depth: number;
+    readonly children: readonly SidebarNode[];
+}
+/** Whether a Markdown file is its folder's index page. */
+export declare const isIndex: (file: string) => boolean;
+interface Category {
+    readonly label?: string;
+    readonly position?: number;
+    readonly collapsed?: boolean;
+}
+/** A folder's group metadata. YAML also reads Docusaurus's JSON. */
+export declare function category(directory: string): Category;
+/**
+ * The front matter a folder's `_category` gives its index page: the label and position that HTMLKit's navigation
+ * tree reads from the index page as the folder's own. `top` is the version's content directory, whose index page
+ * is the version home and has no folder to order.
+ */
+export declare function categoryFrontMatter(file: string, top: string): FrontMatter | undefined;
+/**
+ * HTMLKit's navigation tree with Markupress's group policy: a folder stays open unless its `_category` collapses
+ * it, and one holding the current page is always open. `collapsed` tells whether a folder's index page URL starts closed.
+ */
+export declare function generatedSidebar(tree: readonly NavigationNode[], collapsed: (href: string) => boolean): SidebarNode[];
+/** A configured sidebar, resolved against the version's pages so entries get their labels and current page. */
+export declare function configuredSidebar(entries: readonly SidebarItem[], items: readonly NavigationItem[], href: (path: string) => string, current: string, depth?: number): SidebarNode[];
+export {};
+//# sourceMappingURL=navigation.d.ts.map

package/dist/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../src/navigation.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,mGAAmG;AACnG,MAAM,WAAW,IAAI;IAAG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AACvE,8DAA8D;AAC9D,MAAM,MAAM,OAAO,GAAG,IAAI,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAA;CAAE,CAAC;AACzF,4GAA4G;AAC5G,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,IAAI,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAE3I,mHAAmH;AACnH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;CAC3C;AAGD,0DAA0D;AAC1D,eAAO,MAAM,OAAO,SAAU,MAAM,YAA+B,CAAC;AAIpE,UAAU,QAAQ;IAAG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAAE;AACxG,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,QAAQ,CAYpD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAWtF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,EAAE,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,WAAW,EAAE,CAGrH;AAED,+GAA+G;AAC/G,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,SAAS,WAAW,EAAE,EAAE,KAAK,EAAE,SAAS,cAAc,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,WAAW,EAAE,CAc9K"}

package/dist/navigation.js

@@ -0,0 +1,71 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { parse } from 'yaml';
+const index = /^(?:\d+\.)?index\.md$/;
+/** Whether a Markdown file is its folder's index page. */
+export const isIndex = (file) => index.test(basename(file));
+// Markupress's own name, and Docusaurus's, so a migrated folder keeps its metadata.
+const categoryFiles = ['_category.yml', '_category_.yml', '_category_.json'];
+/** A folder's group metadata. YAML also reads Docusaurus's JSON. */
+export function category(directory) {
+    const file = categoryFiles.map(name => join(directory, name)).find(existsSync);
+    if (file === undefined)
+        return {};
+    const value = parse(readFileSync(file, 'utf8'));
+    const fields = (value ?? {});
+    if (typeof fields !== 'object' || Array.isArray(fields))
+        throw new Error(`${file}: must be a mapping.`);
+    for (const [name, type] of [['label', 'string'], ['position', 'number'], ['collapsed', 'boolean']]) {
+        if (fields[name] !== undefined && typeof fields[name] !== type)
+            throw new Error(`${file}: ${name} must be a ${type}.`);
+    }
+    // HTMLKit's hk:order is a whole number, as a file's number prefix is.
+    if (fields.position !== undefined && !(Number.isSafeInteger(fields.position) && fields.position >= 0))
+        throw new Error(`${file}: position must be a whole number.`);
+    return fields;
+}
+/**
+ * The front matter a folder's `_category` gives its index page: the label and position that HTMLKit's navigation
+ * tree reads from the index page as the folder's own. `top` is the version's content directory, whose index page
+ * is the version home and has no folder to order.
+ */
+export function categoryFrontMatter(file, top) {
+    // HTMLKit labels and orders a folder only through its index page, so a _category without one could not apply.
+    for (let directory = dirname(file); directory.length > top.length; directory = dirname(directory)) {
+        const metadata = categoryFiles.map(name => join(directory, name)).find(existsSync);
+        if (metadata !== undefined && !readdirSync(directory).some(name => index.test(name))) {
+            throw new Error(`${metadata}: a folder's label, position and collapsed state apply through its index page; add an index.md to ${directory}.`);
+        }
+    }
+    if (!isIndex(file) || dirname(file) === top)
+        return undefined;
+    const { label, position } = category(dirname(file));
+    return { ...(label === undefined ? {} : { sidebarLabel: label }), ...(position === undefined ? {} : { sidebarPosition: position }) };
+}
+/**
+ * HTMLKit's navigation tree with Markupress's group policy: a folder stays open unless its `_category` collapses
+ * it, and one holding the current page is always open. `collapsed` tells whether a folder's index page URL starts closed.
+ */
+export function generatedSidebar(tree, collapsed) {
+    return tree.map(node => ({ ...node, open: node.open || (node.children.length > 0 && !(node.href !== undefined && collapsed(node.href))),
+        children: generatedSidebar(node.children, collapsed) }));
+}
+/** A configured sidebar, resolved against the version's pages so entries get their labels and current page. */
+export function configuredSidebar(entries, items, href, current, depth = 0) {
+    return entries.map(entry => {
+        if (typeof entry === 'string') {
+            const page = items.find(item => item.href === href(entry));
+            if (page === undefined)
+                throw new Error(`sidebar: no page at ${entry}.`);
+            return { label: page.label, href: page.href, current: page.current, open: false, depth, children: [] };
+        }
+        if ('items' in entry) {
+            const children = configuredSidebar(entry.items, items, href, current, depth + 1);
+            return { label: entry.label, current: 'false', open: entry.collapsed !== true || children.some(holdsCurrent), depth, children };
+        }
+        const target = href(entry.href);
+        return { label: entry.label, href: target, current: target === current ? 'page' : 'false', open: false, depth, children: [] };
+    });
+}
+const holdsCurrent = (node) => node.current === 'page' || node.children.some(holdsCurrent);
+//# sourceMappingURL=navigation.js.map

package/dist/navigation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.js","sourceRoot":"","sources":["../src/navigation.ts"],"names":[],"mappings":"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"}

package/dist/site.d.ts

@@ -1,4 +1,5 @@
-import { type ApplicationOptions, type ApplicationServer, type BuildResult } from '@nextwebwg/htmlkit';
+import { type ApplicationOptions, type ApplicationServer, type BuildResult, type HtmlKitPlugin, type ServerOptions } from '@nextwebwg/htmlkit';
+import { type Link, type NavItem, type SidebarItem } from './navigation.js';
 export interface DocumentationVersion {
     readonly id: string;
     readonly label?: string;
@@ -16,23 +17,59 @@ export interface MarkupressOptions {
     readonly defaultVersion?: string;
     readonly host?: string;
     readonly port?: number;
+    /** Number the lines of every highlighted code block unless its fence says `:no-line-numbers`. */
+    readonly lineNumbers?: boolean;
+    /**
+     * An HTML Next layout component, relative to the root, that replaces the Markupress shell. It receives the
+     * loader data its `<prop>` declarations name: see "Layout data" in the README.
+     */
+    readonly layout?: string;
+    /** The logo before the title: one image, or one per theme. Paths starting with `/` are files in `public/`. */
+    readonly logo?: string | {
+        readonly light: string;
+        readonly dark?: string;
+    };
+    /** The site's icon, such as `/favicon.svg` from `public/`. */
+    readonly favicon?: string;
+    /** Top navigation: links, and dropdowns of links. A path starting with `/` is a page of the version being read. */
+    readonly nav?: readonly NavItem[];
+    /** Links at the end of the top navigation, each shown as its `icon` image (from `public/`) or its label. */
+    readonly social?: readonly (Link & {
+        readonly icon?: string;
+    })[];
+    /** Text of the badge beside the title. Without it, a site with several versions shows the selected version's label. */
+    readonly versionBadge?: string;
+    /** Explicit sidebars by section path (`/`, `/editor/`). Every other section's sidebar is generated from its folder. */
+    readonly sidebar?: Readonly<Record<string, readonly SidebarItem[]>>;
+    /** Footer link columns and a copyright line. */
+    readonly footer?: {
+        readonly columns?: readonly {
+            readonly title: string;
+            readonly items: readonly Link[];
+        }[];
+        readonly copyright?: string;
+    };
 }
 export interface DocumentationPage {
     readonly id: string;
     readonly version: string;
     readonly source: string;
+    /** Application-relative URL in its version, such as /v/current/guide/install/. */
     readonly pathname: string;
-    readonly label: string;
-    readonly pageName: string;
 }
-export interface PreparedSite {
-    readonly application: ApplicationOptions;
-    readonly documents: readonly DocumentationPage[];
-    readonly sourceFiles: readonly string[];
-}
-/** Compile author content into an owned HTMLKit application, preserving original import locations. */
-export declare function prepareSite(options?: MarkupressOptions): Promise<PreparedSite>;
+/**
+ * Versioned documentation as an HTMLKit plugin. Markdown pages come from the markdown plugin, and
+ * HTMLKit routes them: each version's directory serves /v/<id>/, and the default version's also
+ * serves the site root. Markupress keeps only the version catalog its switcher needs.
+ */
+export declare function markupress(options?: MarkupressOptions): HtmlKitPlugin;
+/**
+ * HTMLKit options for a Markupress site, as the CLI runs it: the site's own HTMLKit options (its `htmlkit.config.ts`)
+ * with `markupress()` added after their plugins. Markupress's own `base` and `outDir`, when set, win over HTMLKit's.
+ */
+export declare function siteOptions(options?: MarkupressOptions, htmlkit?: ApplicationOptions): ServerOptions;
 export declare function buildSite(options?: MarkupressOptions): Promise<BuildResult>;
 export declare function previewSite(options?: MarkupressOptions): Promise<ApplicationServer>;
+/** HTMLKit's watcher recompiles Markdown and reloads open pages after each edit. */
 export declare function devSite(options?: MarkupressOptions): Promise<ApplicationServer>;
 //# sourceMappingURL=site.d.ts.map

package/dist/site.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"site.d.ts","sourceRoot":"","sources":["../src/site.ts"],"names":[],"mappings":"AAKA,OAAO,EAAwD,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAI7J,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AACD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACpD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AACD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AACD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,WAAW,EAAE,kBAAkB,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACjD,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC;AAiCD,sGAAsG;AACtG,wBAAsB,WAAW,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,YAAY,CAAC,CAAoC;AAoI7H,wBAAsB,SAAS,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,WAAW,CAAC,CAUrF;AACD,wBAAsB,WAAW,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE7F;AACD,wBAAsB,OAAO,CAAC,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0BzF"}
+{"version":3,"file":"site.d.ts","sourceRoot":"","sources":["../src/site.ts"],"names":[],"mappings":"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"}