@fusion.dev/helix-docs 0.0.0-dev

package/dist/registry.js

@@ -0,0 +1,70 @@
+/**
+ * Documentation registry for Helix.
+ *
+ * Docs are a package rather than a folder inside a site so that the docs are
+ * pinned to the version of the code they describe. A site renders this
+ * registry; it does not own it.
+ *
+ * **There is no version axis in here.** The package version is the version:
+ * `@fusion.dev/helix-docs@0.2.0` documents Helix 0.2.0, because every package in a
+ * domain moves in lockstep. A `versions` array beside that would be a second
+ * source of truth with nothing keeping the two in step, and the first time they
+ * disagreed the registry would win over the package that shipped it.
+ *
+ * A site serving several versions installs several versions, which is the
+ * mechanism npm already provides and the only one that cannot drift.
+ *
+ * **Nothing about a page is written here.** `pages.generated.ts` is derived
+ * from each file's frontmatter by `bun run docs`, because the frontmatter is
+ * what a `.md` consumer receives and a second copy would be a second source of
+ * truth. This module is the types and the reading of them; `sections.ts` is the
+ * spine that frontmatter has nowhere to live.
+ */
+import { docPages } from './pages.generated.js';
+import { docSections } from './sections.js';
+export { docPages as pages, docSections as sections };
+export const findPage = (slug) => docPages.find((page) => page.slug === slug);
+/** Case-insensitive, so `Tokens` and `tokens` do not sort into two groups. */
+const byTitle = (a, b) => a.title.toLowerCase() < b.title.toLowerCase() ? -1 : 1;
+/**
+ * The pages of one section, in the order a sidebar renders them.
+ *
+ * **Alphabetical, except a section that is a path, and except one pinned entry
+ * page where a section has one.** The exemption is the same one `CLAUDE.md`
+ * grants positional arguments and middleware chains, that ordering is skipped
+ * where order is semantic. Written down so a section is not silently reordered
+ * by whoever next notices it is not alphabetical.
+ */
+const ordered = (pages, section) => {
+    if (section.path) {
+        return [...pages].sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+    }
+    const pinned = pages.filter((page) => page.pinned);
+    const rest = pages.filter((page) => !page.pinned).sort(byTitle);
+    return [...pinned, ...rest];
+};
+/**
+ * The whole sidebar: every declared section, its pages in render order, and
+ * each page's children beneath it.
+ *
+ * A section with no pages cannot appear, because `bun run check:docs` refuses
+ * to generate one. Children are alphabetical, because nesting exists for the
+ * per-framework installation pages and a reader picking their framework out of
+ * a list is looking one up rather than reading a sequence, and then the
+ * `trailing` ones, which are the pages that answer "none of the above" and
+ * which the alphabet was interleaving with the answers they follow from.
+ */
+export const navigation = () => docSections.map((section) => {
+    const own = docPages.filter((page) => page.section === section.title && page.parent === undefined);
+    return {
+        ...section,
+        pages: ordered(own, section).map((page) => ({
+            ...page,
+            children: docPages
+                .filter((child) => child.parent === page.slug)
+                .sort((a, b) => Number(a.trailing ?? false) - Number(b.trailing ?? false) || byTitle(a, b)),
+        })),
+    };
+});
+/** Path to a page's MDX, relative to the package root. */
+export const contentPath = (page) => `content/${page.slug}.mdx`;

package/dist/sections.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The navigation's spine: which sections exist, in what order, and how each
+ * one orders the pages inside it.
+ *
+ * **Hand-authored, where the pages are not.** A page's own facts come from its
+ * frontmatter and are generated into `pages.generated.ts`, because the
+ * frontmatter is what a `.md` consumer actually receives and a second copy in
+ * a registry is a second source of truth. A section is not a page and has no
+ * frontmatter to derive from, so it is written here.
+ *
+ * **A section with no pages is not declared.** A navigation entry is the
+ * strongest existence claim a site can make, and the sections this library
+ * intends to grow (Foundations, Components, Tooling) have nothing in them yet.
+ * `bun run check:docs` fails on an empty section rather than rendering a
+ * heading with nothing under it.
+ *
+ * See [`plan/23-helix-docs.md`](plan/23-helix-docs.md) for the
+ * navigation this is a subset of.
+ */
+/** A top-level grouping in the sidebar. */
+export interface DocSection {
+    /**
+     * Whether this section is a sequence rather than a lookup table.
+     *
+     * A path is read in order and its pages carry an explicit `order`. Every
+     * other section sorts its pinned entry first and the rest alphabetically,
+     * which is the right shape when a reader arrives knowing what they are
+     * looking for. Getting started is the only path today.
+     */
+    path?: boolean;
+    /** Display name, and the value a page's `section` frontmatter matches. */
+    title: string;
+}
+/**
+ * Every section, in the order the sidebar renders them.
+ *
+ * Deliberately an array rather than an alphabetized record: this is the one
+ * place where order is the content. Foundations sits above Theming because a
+ * reader needs the vocabulary before the thing that changes it, and no
+ * alphabetization expresses that.
+ */
+export declare const docSections: DocSection[];
+/** The section of a given name, if it is declared. */
+export declare const findSection: (title: string) => DocSection | undefined;

package/dist/sections.js

@@ -0,0 +1,36 @@
+/**
+ * The navigation's spine: which sections exist, in what order, and how each
+ * one orders the pages inside it.
+ *
+ * **Hand-authored, where the pages are not.** A page's own facts come from its
+ * frontmatter and are generated into `pages.generated.ts`, because the
+ * frontmatter is what a `.md` consumer actually receives and a second copy in
+ * a registry is a second source of truth. A section is not a page and has no
+ * frontmatter to derive from, so it is written here.
+ *
+ * **A section with no pages is not declared.** A navigation entry is the
+ * strongest existence claim a site can make, and the sections this library
+ * intends to grow (Foundations, Components, Tooling) have nothing in them yet.
+ * `bun run check:docs` fails on an empty section rather than rendering a
+ * heading with nothing under it.
+ *
+ * See [`plan/23-helix-docs.md`](plan/23-helix-docs.md) for the
+ * navigation this is a subset of.
+ */
+/**
+ * Every section, in the order the sidebar renders them.
+ *
+ * Deliberately an array rather than an alphabetized record: this is the one
+ * place where order is the content. Foundations sits above Theming because a
+ * reader needs the vocabulary before the thing that changes it, and no
+ * alphabetization expresses that.
+ */
+export const docSections = [
+    { path: true, title: 'Getting started' },
+    { title: 'Foundations' },
+    { title: 'Theming' },
+    { title: 'Essentials' },
+    { title: 'Tooling' },
+];
+/** The section of a given name, if it is declared. */
+export const findSection = (title) => docSections.find((section) => section.title === title);

package/dist/sources.generated.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Every page's MDX, inlined by `bun run docs`. Do not edit: the files in
+ * `content/` are the source, and `bun run check:docs` fails when this module
+ * and they disagree.
+ */
+export declare const docSources: Record<string, string>;