@dogsbay/format-openknowledge 0.2.0-beta.101

package/dist/serialize.d.ts

@@ -0,0 +1,70 @@
+/**
+ * OpenKnowledge serializer — TreeNode[] → MDX in the dialect Inkeep
+ * OpenKnowledge parses (remark-parse + gfm + github-alerts + math +
+ * frontmatter + mdx-jsx; NO remark-directive, wikilinks deprecated).
+ *
+ * The three blockers the research measured on a real corpus
+ * (dogsbay-research/plans/format-openknowledge.md §2) are decided here:
+ *   1. links are ROOT-ABSOLUTE with `.md` and a HEADING-SLUG fragment
+ *      (`/ai/kueue/install.md#installing-kueue`), because OpenKnowledge
+ *      resolves extension-less paths source-relative and shows `^anchor`
+ *      block ids as text;
+ *   2. NO `^anchor` markers are emitted at all;
+ *   3. code blocks are PLAIN fences (`lang` on the info string, `title` as
+ *      fence meta) — never the `dogsbay-code` envelope.
+ *
+ * Rich components use the FUMADOCS VOCABULARY (§3.0) with OpenKnowledge's
+ * prop names: `<Callout>` (or GFM `> [!note]` when it has no title),
+ * `<Accordion title defaultOpen>`, `<Tabs><Tab label>` render natively;
+ * `<Steps><Step>`, `<Cards><Card>` land on OpenKnowledge's wildcard
+ * (editable raw-MDX blocks — content survives, rendering does not).
+ * `deflist` — 13,614 instances on the reference corpus, prose not code —
+ * is emitted as READABLE MARKDOWN (a term list), never as a code block.
+ * Navigational nodes become plain markdown links (their graph/backlinks
+ * feed on links, and a rendered block that cannot navigate is worse).
+ *
+ * MDX is stricter than markdown: `{` `}` `<` in prose are escaped, and raw
+ * HTML is converted to markdown (unbalanced HTML breaks an MDX parse).
+ * Everything the target cannot represent is recorded in the ExportLedger
+ * against `OPENKNOWLEDGE_CAPABILITIES` — a loss is declared, never silent.
+ */
+import type { TreeNode } from "@dogsbay/types";
+import { ExportLedger } from "@dogsbay/serialize-core";
+export interface OpenKnowledgeSerializeOptions {
+    /**
+     * Rewrites a link target for the exported corpus (root-absolute `.md` +
+     * heading fragment). The project layer supplies it with knowledge of every
+     * page; the default only normalizes the shape.
+     */
+    href?: (href: string) => string;
+    /** Records degradations; a fresh ledger is used when none is given. */
+    ledger?: ExportLedger;
+    /** Page path recorded with ledger entries. */
+    page?: string;
+}
+export declare function treeToOpenKnowledge(nodes: TreeNode[], options?: OpenKnowledgeSerializeOptions): string;
+/** Root-absolute `.md` shape without page knowledge: `/a/b/` → `/a/b.md`, `#x` kept, external kept. */
+export declare function defaultHref(href: string): string;
+export declare function splitFragment(href: string): [string, string];
+/**
+ * MDX treats `{`/`}` as expressions and `<` followed by anything but
+ * whitespace as a tag start (`<3`, `<=`, `<-` are all errors); a backslash
+ * escape renders literally in both the strict MDX stack and OpenKnowledge's
+ * (which restores backslash escapes). Backslashes are escaped FIRST so a
+ * literal `\{` in prose does not become `\\{` (= escaped backslash + a LIVE
+ * expression). Text starting a paragraph with `import`/`export` is ESM in
+ * strict MDX — see `noEsmStart`.
+ */
+export declare function escapeMdxText(text: string): string;
+/**
+ * The headings a page WILL emit, in emit order, as OpenKnowledge will see
+ * their text — headings nested in callouts/tabs/lists included, and the
+ * `### class \`name\`` lines api-class/api-member emit (whose textContent
+ * is "class name"). Anchors must be computed from THIS, not from an
+ * importer's `page.headings` (top-level only, importer-defined text).
+ */
+export declare function collectEmittedHeadings(nodes: TreeNode[]): Array<{
+    slug: string;
+    text: string;
+}>;
+//# sourceMappingURL=serialize.d.ts.map

package/dist/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../src/serialize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAc,MAAM,gBAAgB,CAAC;AAC3D,OAAO,EAcL,YAAY,EAEb,MAAM,yBAAyB,CAAC;AAEjC,MAAM,WAAW,6BAA6B;IAC5C;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IAChC,uEAAuE;IACvE,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA8BD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE,OAAO,GAAE,6BAAkC,GAAG,MAAM,CAQ1G;AAED,uGAAuG;AACvG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAG5D;AAID;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAMlD;AAukBD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAiB/F"}