@intellectual-frontiers/docs 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/LICENSE +75 -0
  2. package/README.md +8 -2
  3. package/dist/build.d.ts +63 -0
  4. package/dist/build.js +103 -0
  5. package/dist/check.d.ts +63 -0
  6. package/dist/check.js +54 -0
  7. package/dist/cli.d.ts +51 -0
  8. package/dist/cli.js +165 -0
  9. package/dist/config.d.ts +196 -0
  10. package/dist/config.js +229 -0
  11. package/dist/emit/html.d.ts +67 -0
  12. package/dist/emit/html.js +338 -0
  13. package/dist/emit/markdown.d.ts +19 -0
  14. package/dist/emit/markdown.js +124 -0
  15. package/dist/emit/search.d.ts +15 -0
  16. package/dist/emit/search.js +29 -0
  17. package/dist/extract/api.d.ts +74 -0
  18. package/dist/extract/api.js +261 -0
  19. package/dist/extract/specs.d.ts +141 -0
  20. package/dist/extract/specs.js +208 -0
  21. package/dist/highlight.d.ts +22 -0
  22. package/dist/highlight.js +77 -0
  23. package/dist/layered.d.ts +94 -0
  24. package/dist/layered.js +14 -0
  25. package/dist/lens/guides.d.ts +23 -0
  26. package/dist/lens/guides.js +49 -0
  27. package/dist/lens/layered.d.ts +16 -0
  28. package/dist/lens/layered.js +354 -0
  29. package/dist/lens/program.d.ts +23 -0
  30. package/dist/lens/program.js +124 -0
  31. package/dist/lens/releases.d.ts +10 -0
  32. package/dist/lens/releases.js +37 -0
  33. package/dist/lens.d.ts +30 -0
  34. package/dist/lens.js +1 -0
  35. package/dist/links.d.ts +96 -0
  36. package/dist/links.js +182 -0
  37. package/dist/main.d.ts +1 -0
  38. package/dist/main.js +12 -0
  39. package/dist/markdown.d.ts +43 -0
  40. package/dist/markdown.js +301 -0
  41. package/dist/mod.d.ts +32 -0
  42. package/dist/mod.js +9 -0
  43. package/dist/model.d.ts +159 -0
  44. package/dist/model.js +39 -0
  45. package/dist/pages/api.d.ts +41 -0
  46. package/dist/pages/api.js +162 -0
  47. package/dist/pages/areas.d.ts +39 -0
  48. package/dist/pages/areas.js +119 -0
  49. package/dist/pages/overview.d.ts +24 -0
  50. package/dist/pages/overview.js +283 -0
  51. package/dist/pages/specs.d.ts +31 -0
  52. package/dist/pages/specs.js +358 -0
  53. package/dist/site.d.ts +31 -0
  54. package/dist/site.js +288 -0
  55. package/dist/sources.d.ts +53 -0
  56. package/dist/sources.js +159 -0
  57. package/dist/theme/site.css +275 -0
  58. package/dist/theme/site.js +174 -0
  59. package/dist/tsdoc.d.ts +67 -0
  60. package/dist/tsdoc.js +94 -0
  61. package/ifc-docs.mjs +4 -0
  62. package/package.json +66 -4
  63. package/src/build.ts +117 -0
  64. package/src/check.ts +84 -0
  65. package/src/cli.ts +145 -0
  66. package/src/config.ts +370 -0
  67. package/src/emit/html.ts +398 -0
  68. package/src/emit/markdown.ts +129 -0
  69. package/src/emit/search.ts +38 -0
  70. package/src/extract/api.ts +297 -0
  71. package/src/extract/specs.ts +299 -0
  72. package/src/highlight.ts +98 -0
  73. package/src/layered.ts +102 -0
  74. package/src/lens/guides.ts +70 -0
  75. package/src/lens/layered.ts +341 -0
  76. package/src/lens/program.ts +137 -0
  77. package/src/lens/releases.ts +54 -0
  78. package/src/lens.ts +34 -0
  79. package/src/links.ts +234 -0
  80. package/src/main.ts +12 -0
  81. package/src/markdown.ts +320 -0
  82. package/src/mod.ts +53 -0
  83. package/src/model.ts +154 -0
  84. package/src/pages/api.ts +179 -0
  85. package/src/pages/areas.ts +133 -0
  86. package/src/pages/overview.ts +276 -0
  87. package/src/pages/specs.ts +366 -0
  88. package/src/site.ts +285 -0
  89. package/src/sources.ts +157 -0
  90. package/src/theme/site.css +275 -0
  91. package/src/theme/site.js +174 -0
  92. package/src/tsdoc.ts +131 -0
@@ -0,0 +1,398 @@
1
+ // Spec: 0001-docs FR-001
2
+ /**
3
+ * The page model written as HTML (commons 0011-documentation FR-009, FR-017): one static file for each page, whose links are all
4
+ * relative so that the site works under any path, with the sections that have a page in its top bar, the site's stylesheet and its one
5
+ * script, and Mermaid only where a page has a diagram, all served by the site itself. Every case of the model is matched by a `switch`
6
+ * that ends in `absurd`. Code is highlighted here, when the site is built.
7
+ *
8
+ * @module
9
+ */
10
+ import { absurd } from "@intellectual-frontiers/core";
11
+ import { highlightedHtml } from "../highlight.ts";
12
+ import { renderMermaidSVG } from "beautiful-mermaid";
13
+ import type { Badge, Block, Card, Href, Inline, Lang, Page, Section, TreeNode } from "../model.ts";
14
+ import { plain } from "../model.ts";
15
+
16
+ /** What every page shares: the site's name, the navigation of each section, and the address of the repository. */
17
+ export interface Site {
18
+ /** The site's name, at the top of every page. */
19
+ readonly name: string;
20
+ /** The repository's address, for the link at the top. */
21
+ readonly repository: string;
22
+ /** Every page, for the navigation. */
23
+ readonly pages: readonly Page[];
24
+ /** The sections the top bar shows, where not all four: a site leaves out a section with no page (FR-009). */
25
+ readonly sections?: readonly Section[];
26
+ }
27
+
28
+ /** The names of the sections, in the order the top bar shows them, and the page each opens on. */
29
+ export const SECTIONS: readonly { readonly section: Section; readonly label: string; readonly home: string }[] = [
30
+ { section: "start", label: "Start here", home: "start/index.html" },
31
+ { section: "concepts", label: "Concepts", home: "concepts/index.html" },
32
+ { section: "overview", label: "Libraries", home: "index.html" },
33
+ { section: "howto", label: "How-to", home: "how-to/index.html" },
34
+ { section: "specs", label: "Specifications", home: "specs/index.html" },
35
+ { section: "api", label: "API", home: "api/index.html" },
36
+ { section: "models", label: "Models", home: "models/index.html" },
37
+ { section: "programs", label: "Programs", home: "programs/index.html" },
38
+ ];
39
+
40
+ /** Text made safe for HTML. */
41
+ export function escape(s: string): string {
42
+ return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
43
+ }
44
+
45
+ /**
46
+ * The relative address from one page of the site to another.
47
+ *
48
+ * @param from - the path of the page the link is on
49
+ * @param to - the path of the page it goes to
50
+ */
51
+ export function relative(from: string, to: string): string {
52
+ const a = from.split("/").slice(0, -1);
53
+ const b = to.split("/");
54
+ let i = 0;
55
+ while (i < a.length && i < b.length - 1 && a[i] === b[i]) i++;
56
+ const up = a.length - i;
57
+ return `${"../".repeat(up)}${b.slice(i).join("/")}` || "index.html";
58
+ }
59
+
60
+ /** The address an `Href` is, seen from a page. */
61
+ export function hrefOf(h: Href, from: string): string {
62
+ switch (h.kind) {
63
+ case "page": {
64
+ const target = h.path === from ? "" : relative(from, h.path);
65
+ return `${target}${h.anchor === undefined ? "" : `#${h.anchor}`}` || "#";
66
+ }
67
+ case "external":
68
+ return h.url;
69
+ default:
70
+ return absurd(h);
71
+ }
72
+ }
73
+
74
+ /** The length past which inline code may wrap (in a table, shorter code stays on one line). */
75
+ const LONG_CODE = 48;
76
+
77
+ function inline(i: Inline, from: string): string {
78
+ switch (i.kind) {
79
+ case "text":
80
+ return escape(i.text);
81
+ case "code":
82
+ return `<code${i.text.length > LONG_CODE ? ' class="long"' : ""}>${escape(i.text)}</code>`;
83
+ case "emphasis":
84
+ return `<em>${inlines(i.children, from)}</em>`;
85
+ case "strong":
86
+ return `<strong>${inlines(i.children, from)}</strong>`;
87
+ case "link": {
88
+ const external = i.href.kind === "external";
89
+ return `<a href="${escape(hrefOf(i.href, from))}"${external ? ' rel="noopener" class="ext"' : ""}>${inlines(i.children, from)}</a>`;
90
+ }
91
+ default:
92
+ return absurd(i);
93
+ }
94
+ }
95
+
96
+ /** Inlines without their links, for text that is itself inside a link (a card), where a link may not be. */
97
+ export function unlinked(xs: readonly Inline[]): Inline[] {
98
+ return xs.map((i): Inline => {
99
+ switch (i.kind) {
100
+ case "link":
101
+ return { kind: "emphasis", children: unlinked(i.children) };
102
+ case "emphasis":
103
+ case "strong":
104
+ return { ...i, children: unlinked(i.children) };
105
+ case "text":
106
+ case "code":
107
+ return i;
108
+ default:
109
+ return absurd(i);
110
+ }
111
+ });
112
+ }
113
+
114
+ /** Inlines as HTML. */
115
+ export const inlines = (xs: readonly Inline[], from: string): string => xs.map((i) => inline(i, from)).join("");
116
+
117
+ /** Code as highlighted HTML, coloured when the site is built (FR-037). */
118
+ export function highlighted(code: string, lang: Lang): string {
119
+ return highlightedHtml(code, lang);
120
+ }
121
+
122
+ /** Whether a diagram can be drawn: its source is of a type the renderer draws (flowchart, state, sequence, class, entity-relationship). */
123
+ export function drawable(source: string): boolean {
124
+ try {
125
+ renderMermaidSVG(source);
126
+ return true;
127
+ } catch {
128
+ return false;
129
+ }
130
+ }
131
+
132
+ /** The sources of the diagrams in blocks, at any depth. */
133
+ export function diagramSources(bs: readonly Block[]): string[] {
134
+ return bs.flatMap((b): string[] => {
135
+ switch (b.kind) {
136
+ case "diagram":
137
+ return [b.source];
138
+ case "list":
139
+ return b.items.flatMap(diagramSources);
140
+ case "callout":
141
+ case "entry":
142
+ return diagramSources(b.blocks);
143
+ case "tabs":
144
+ return b.tabs.flatMap((t) => diagramSources(t.blocks));
145
+ default:
146
+ return [];
147
+ }
148
+ });
149
+ }
150
+
151
+ /**
152
+ * A diagram as SVG, drawn when the site is built (FR-037): in the colours of the page, as custom properties, so that the light and the dark scheme need no second drawing; where the diagram cannot be drawn, its source in a code block.
153
+ */
154
+ export function diagramSvg(source: string): string {
155
+ try {
156
+ return renderMermaidSVG(source, { bg: "var(--page)", fg: "var(--text)", line: "var(--muted)", accent: "var(--link)", muted: "var(--faint)", surface: "var(--chrome)", border: "var(--border-strong)", transparent: true, font: "inherit" });
157
+ } catch {
158
+ return `<pre class="lang-mermaid"><code>${escape(source)}</code></pre>`;
159
+ }
160
+ }
161
+
162
+ const badge = (b: Badge): string => `<span class="badge badge-${b.tone}">${escape(b.text)}</span>`;
163
+ const badges = (bs: readonly Badge[] | undefined): string => (bs === undefined || bs.length === 0 ? "" : `<span class="badges">${bs.map(badge).join("")}</span>`);
164
+
165
+ const LONG_SIGNATURE = 400;
166
+
167
+ function card(c: Card, from: string): string {
168
+ const kids = c.children === undefined || c.children.length === 0
169
+ ? ""
170
+ : `<div class="card-children">${c.children.map((k) => card(k, from)).join("")}</div>`;
171
+ return `<div class="card"><a class="card-link" href="${escape(hrefOf(c.href, from))}"><span class="card-title">${escape(c.title)}</span>${
172
+ badges(c.badges)
173
+ }<span class="card-text">${inlines(unlinked(c.text), from)}</span></a>${kids}</div>`;
174
+ }
175
+
176
+ function tree(nodes: readonly TreeNode[], from: string): string {
177
+ return `<ul>${
178
+ nodes
179
+ .map(
180
+ (n) =>
181
+ `<li><span class="tree-node"><code>${escape(n.label)}</code>${n.note === undefined ? "" : `<span class="tree-note">${inlines(n.note, from)}</span>`}</span>${
182
+ n.children.length === 0 ? "" : tree(n.children, from)
183
+ }</li>`,
184
+ )
185
+ .join("")
186
+ }</ul>`;
187
+ }
188
+
189
+ /** A block as HTML. */
190
+ export function block(b: Block, from: string): string {
191
+ switch (b.kind) {
192
+ case "heading":
193
+ return `<h${b.level} id="${escape(b.id)}"><a class="anchor" href="#${escape(b.id)}" aria-hidden="true">#</a>${inlines(b.text, from)}</h${b.level}>`;
194
+ case "paragraph":
195
+ return `<p>${inlines(b.inlines, from)}</p>`;
196
+ case "meta":
197
+ return `<p class="meta">${inlines(b.inlines, from)}</p>`;
198
+ case "list": {
199
+ const tag = b.ordered ? "ol" : "ul";
200
+ return `<${tag}>${b.items.map((it) => `<li>${blocks(it, from, true)}</li>`).join("")}</${tag}>`;
201
+ }
202
+ case "code":
203
+ return `<figure class="code">${b.title === undefined ? "" : `<figcaption>${escape(b.title)}</figcaption>`}<pre class="lang-${b.lang}"><code>${
204
+ highlighted(b.text, b.lang)
205
+ }</code></pre></figure>`;
206
+ case "table":
207
+ return `${b.filter === undefined ? "" : `<input type="search" class="table-filter" placeholder="${escape(b.filter)}" aria-label="${escape(b.filter)}">`}<div class="table-wrap${b.compact === true ? " compact" : ""}"><table><thead><tr>${b.head.map((h) => `<th>${inlines(h, from)}</th>`).join("")}</tr></thead><tbody>${
208
+ b.rows.map((r) => `<tr>${r.map((c) => `<td>${inlines(c, from)}</td>`).join("")}</tr>`).join("")
209
+ }</tbody></table></div>`;
210
+ case "callout":
211
+ return `<aside class="callout callout-${b.tone}"><p class="callout-title">${escape(b.title)}</p>${blocks(b.blocks, from)}</aside>`;
212
+ case "entry": {
213
+ const sig = b.signature === undefined
214
+ ? ""
215
+ : b.signature.length > LONG_SIGNATURE
216
+ ? `<details class="sig-long"><summary><code>${escape(b.signature.slice(0, 120))}…</code> <span class="muted">(${b.signature.length} characters)</span></summary><pre class="sig lang-ts"><code>${
217
+ highlighted(b.signature, "ts")
218
+ }</code></pre></details>`
219
+ : `<pre class="sig lang-ts"><code>${highlighted(b.signature, "ts")}</code></pre>`;
220
+ return `<section class="entry" id="${escape(b.id)}"><div class="entry-head"><a class="entry-name" href="#${escape(b.id)}"><code>${
221
+ escape(b.name)
222
+ }</code></a>${badges(b.badges)}</div>${sig}<div class="entry-body">${blocks(b.blocks, from)}</div></section>`;
223
+ }
224
+ case "tabs":
225
+ return `<div class="tabs" data-tabs><div class="tab-list" role="tablist">${
226
+ b.tabs
227
+ .map((t, i) =>
228
+ `<button type="button" role="tab" id="${escape(`${b.id}-tab-${i}`)}" aria-controls="${escape(`${b.id}-panel-${i}`)}" aria-selected="${
229
+ i === 0 ? "true" : "false"
230
+ }">${escape(t.label)}</button>`
231
+ )
232
+ .join("")
233
+ }</div>${
234
+ b.tabs
235
+ .map((t, i) =>
236
+ `<div class="tab-panel" role="tabpanel" id="${escape(`${b.id}-panel-${i}`)}" aria-labelledby="${escape(`${b.id}-tab-${i}`)}"${
237
+ i === 0 ? "" : " hidden"
238
+ }>${blocks(t.blocks, from)}</div>`
239
+ )
240
+ .join("")
241
+ }</div>`;
242
+ case "diagram":
243
+ return `<figure class="diagram"><div class="diagram-wrap">${diagramSvg(b.source)}</div><figcaption>${
244
+ escape(b.caption)
245
+ }</figcaption><details class="diagram-source"><summary>Diagram source</summary><pre class="lang-text"><code>${escape(b.source)}</code></pre></details></figure>`;
246
+ case "cards":
247
+ return `<div class="cards">${b.cards.map((c) => card(c, from)).join("")}</div>`;
248
+ case "badges":
249
+ return `<p class="badge-row">${b.badges.map(badge).join("")}</p>`;
250
+ case "tree":
251
+ return `<div class="tree">${tree(b.nodes, from)}</div>`;
252
+ default:
253
+ return absurd(b);
254
+ }
255
+ }
256
+
257
+ /** Blocks as HTML; a list item's single paragraph is written without its `<p>`. */
258
+ export function blocks(bs: readonly Block[], from: string, tight = false): string {
259
+ const only = bs[0];
260
+ if (tight && bs.length === 1 && only !== undefined && only.kind === "paragraph") return inlines(only.inlines, from);
261
+ return bs.map((b) => block(b, from)).join("");
262
+ }
263
+
264
+ /** Whether blocks hold a diagram, anywhere in them. */
265
+ export function hasDiagram(bs: readonly Block[]): boolean {
266
+ return bs.some((b) => {
267
+ switch (b.kind) {
268
+ case "diagram":
269
+ return true;
270
+ case "list":
271
+ return b.items.some(hasDiagram);
272
+ case "callout":
273
+ case "entry":
274
+ return hasDiagram(b.blocks);
275
+ case "tabs":
276
+ return b.tabs.some((t) => hasDiagram(t.blocks));
277
+ case "heading":
278
+ case "paragraph":
279
+ case "meta":
280
+ case "code":
281
+ case "table":
282
+ case "cards":
283
+ case "badges":
284
+ case "tree":
285
+ return false;
286
+ default:
287
+ return absurd(b);
288
+ }
289
+ });
290
+ }
291
+
292
+ /** The headings and entries of a page, for its table of contents. */
293
+ export function outline(bs: readonly Block[]): { readonly id: string; readonly text: string; readonly level: number }[] {
294
+ const out: { id: string; text: string; level: number }[] = [];
295
+ for (const b of bs) {
296
+ if (b.kind === "heading" && b.level <= 3) out.push({ id: b.id, text: plain(b.text), level: b.level });
297
+ else if (b.kind === "entry") out.push({ id: b.id, text: b.name, level: 3 });
298
+ }
299
+ return out;
300
+ }
301
+
302
+ /** The navigation of a section: its groups, in the order of their pages, and the pages of each. */
303
+ export function navigation(pages: readonly Page[], section: Section): { readonly group: string; readonly pages: readonly Page[] }[] {
304
+ const groups = new Map<string, Page[]>();
305
+ for (const p of pages.filter((q) => q.section === section)) groups.set(p.group, [...(groups.get(p.group) ?? []), p]);
306
+ const firstOrder = (ps: readonly Page[]): number => Math.min(...ps.map((p) => p.order));
307
+ return [...groups]
308
+ .map(([group, ps]) => ({ group, pages: [...ps].sort((a, b) => a.order - b.order || (a.title < b.title ? -1 : a.title > b.title ? 1 : 0)) }))
309
+ .sort((a, b) => firstOrder(a.pages) - firstOrder(b.pages) || (a.group < b.group ? -1 : 1));
310
+ }
311
+
312
+ /** The navigation of a section as HTML (FR-040): each group is a `details` element that is open where it holds the page being read, a page lists beneath it the pages whose `parent` it is only while it or one of them is being read, and no script is needed. */
313
+ function navHtml(pages: readonly Page[], current: Page, from: string): string {
314
+ const inSection = pages.filter((q) => q.section === current.section);
315
+ const byPath = new Map(inSection.map((p) => [p.path, p] as const));
316
+ const childrenOf = new Map<string, Page[]>();
317
+ for (const p of inSection) if (p.parent !== undefined && byPath.has(p.parent)) childrenOf.set(p.parent, [...(childrenOf.get(p.parent) ?? []), p]);
318
+ const trail = new Set<string>();
319
+ for (let at: Page | undefined = current; at !== undefined; at = at.parent === undefined ? undefined : byPath.get(at.parent)) trail.add(at.path);
320
+ const order = (a: Page, b: Page): number => a.order - b.order || (a.title < b.title ? -1 : a.title > b.title ? 1 : 0);
321
+ const item = (p: Page): string => {
322
+ const kids = (childrenOf.get(p.path) ?? []).sort(order);
323
+ const link = `<a href="${escape(relative(from, p.path))}"${p.path === from ? ' class="current" aria-current="page"' : ""}>${escape(p.navTitle ?? p.title)}</a>`;
324
+ if (kids.length === 0 || !trail.has(p.path)) return `<li>${link}</li>`;
325
+ let kind: string | undefined;
326
+ const inner = kids.map((k) => {
327
+ const head = k.navKind !== undefined && k.navKind !== kind ? `<li class="nav-kind">${escape(k.navKind)}</li>` : "";
328
+ kind = k.navKind;
329
+ return `${head}${item(k)}`;
330
+ }).join("");
331
+ return `<li>${link}<ul class="nav-sub">${inner}</ul></li>`;
332
+ };
333
+ const roots = navigation(inSection, current.section).map((g) => ({ group: g.group, pages: g.pages.filter((p) => p.parent === undefined || !byPath.has(p.parent)) }));
334
+ const small = roots.length <= 4;
335
+ return roots
336
+ .map((g) => {
337
+ const open = small || g.pages.some((p) => trail.has(p.path) || [...trail].some((t) => (childrenOf.get(p.path) ?? []).some((k) => k.path === t)));
338
+ return `<details class="nav-group"${open ? " open" : ""}><summary><span class="nav-title">${escape(g.group)}</span><span class="nav-count">${g.pages.length}</span></summary><ul>${g.pages.map(item).join("")}</ul></details>`;
339
+ })
340
+ .join("");
341
+ }
342
+
343
+ /**
344
+ * A page as a whole HTML document.
345
+ *
346
+ * @param page - the page
347
+ * @param site - what every page shares
348
+ */
349
+ export function document(page: Page, site: Site): string {
350
+ const from = page.path;
351
+ const root = relative(from, "index.html").replace(/index\.html$/, "");
352
+ const asset = (name: string): string => `${root}assets/${name}`;
353
+ const top = SECTIONS.filter((s) => site.sections === undefined || site.sections.includes(s.section)).map((s) =>
354
+ `<a class="section-link${s.section === page.section ? " current" : ""}" href="${escape(relative(from, s.home))}">${escape(s.label)}</a>`
355
+ ).join("");
356
+ const nav = navHtml(site.pages, page, from);
357
+ const toc = outline(page.blocks);
358
+ const tocHtml = toc.length < 2
359
+ ? ""
360
+ : `<nav class="toc" aria-label="On this page"><p class="toc-title">On this page</p><ul>${
361
+ toc.map((t) => `<li class="toc-${t.level}"><a href="#${escape(t.id)}">${escape(t.text)}</a></li>`).join("")
362
+ }</ul></nav>`;
363
+ return `<!doctype html>
364
+ <html lang="en" data-root="${escape(root)}">
365
+ <head>
366
+ <meta charset="utf-8">
367
+ <meta name="viewport" content="width=device-width, initial-scale=1">
368
+ <title>${escape(page.title)} · ${escape(site.name)}</title>
369
+ <meta name="description" content="${escape(page.description)}">
370
+ <script>try{var t=localStorage.getItem("theme");if(t==="dark"||t==="light")document.documentElement.dataset.theme=t}catch(e){}</script>
371
+ <link rel="stylesheet" href="${asset("site.css")}">
372
+ <script src="${asset("site.js")}" defer></script>
373
+ </head>
374
+ <body>
375
+ <a class="skip" href="#content">Skip to the content</a>
376
+ <header class="top">
377
+ <button type="button" class="menu-button" aria-controls="sidebar" aria-expanded="false" aria-label="Menu"><span></span></button>
378
+ <a class="brand" href="${escape(relative(from, "index.html"))}">${escape(site.name)}</a>
379
+ <nav class="sections" aria-label="Sections">${top}</nav>
380
+ <button type="button" class="search-button" aria-haspopup="dialog"><span>Search</span><kbd>/</kbd></button>
381
+ <button type="button" class="theme-button" aria-label="Switch between the light and the dark theme" title="Theme (t)"><svg width="16" height="16" viewBox="0 0 16 16" aria-hidden="true"><circle cx="8" cy="8" r="6.5" fill="none" stroke="currentColor" stroke-width="1.5"/><path d="M8 1.5a6.5 6.5 0 0 1 0 13z" fill="currentColor"/></svg></button>
382
+ <a class="repo" href="${escape(site.repository)}" rel="noopener">GitHub</a>
383
+ </header>
384
+ <div class="layout">
385
+ <aside class="sidebar" id="sidebar"><nav aria-label="${escape(SECTIONS.find((s) => s.section === page.section)?.label ?? "")}">${nav}</nav></aside>
386
+ <main id="content" class="content">
387
+ <article>
388
+ <header class="page-head"><h1>${escape(page.title)}</h1>${badges(page.badges)}</header>
389
+ ${blocks(page.blocks, from)}
390
+ </article>
391
+ </main>
392
+ ${tocHtml}
393
+ </div>
394
+ <dialog class="search" aria-label="Search"><form method="dialog"><input type="search" placeholder="Search the documentation" aria-label="Search" autocomplete="off"><select class="search-kind" aria-label="Filter by kind"><option value="">Everything</option></select></form><ul class="results" role="listbox"></ul><p class="search-hint">Titles, headings, exports, tables, columns and requirements. <kbd>Esc</kbd> closes.</p></dialog>
395
+ </body>
396
+ </html>
397
+ `;
398
+ }
@@ -0,0 +1,129 @@
1
+ // Spec: 0001-docs FR-001
2
+ /**
3
+ * The Markdown twin of a page (commons 0011-documentation FR-028): every page of the site is also written as Markdown beside its HTML, from the same page model, so that a reader that is a program (an agent) reads
4
+ * the words and the structure and not the markup. Every case of a block and an inline is matched with a `switch` that ends in `absurd`, so that a case added to the model and left out here does not compile. Links
5
+ * to pages of the site point at the Markdown twin of the page.
6
+ *
7
+ * @module
8
+ */
9
+ import { absurd } from "@intellectual-frontiers/core";
10
+ import type { Block, Card, Href, Inline, Page, TreeNode } from "../model.ts";
11
+
12
+ /** The path of the Markdown twin of a page: its own with `.md` for `.html`. */
13
+ export const twinOf = (path: string): string => path.replace(/\.html$/, ".md");
14
+
15
+ const href = (h: Href, from: string): string => {
16
+ if (h.kind === "external") return h.url;
17
+ const target = twinOf(h.path);
18
+ const up = from.split("/").length - 1;
19
+ return `${"../".repeat(up)}${target}${h.anchor === undefined ? "" : `#${h.anchor}`}`;
20
+ };
21
+
22
+ /** Inlines as Markdown. */
23
+ export function inlinesMd(xs: readonly Inline[], from: string): string {
24
+ return xs
25
+ .map((i): string => {
26
+ switch (i.kind) {
27
+ case "text":
28
+ return i.text;
29
+ case "code":
30
+ return `\`${i.text}\``;
31
+ case "emphasis":
32
+ return `*${inlinesMd(i.children, from)}*`;
33
+ case "strong":
34
+ return `**${inlinesMd(i.children, from)}**`;
35
+ case "link":
36
+ return `[${inlinesMd(i.children, from)}](${href(i.href, from)})`;
37
+ default:
38
+ return absurd(i);
39
+ }
40
+ })
41
+ .join("");
42
+ }
43
+
44
+ const cell = (xs: readonly Inline[], from: string): string => inlinesMd(xs, from).replaceAll("|", "\\|").replaceAll("\n", " ");
45
+
46
+ function cards(cs: readonly Card[], from: string, depth: number): string[] {
47
+ return cs.flatMap((c) => [
48
+ `${" ".repeat(depth)}- [${c.title}](${href(c.href, from)})${c.badges === undefined || c.badges.length === 0 ? "" : ` (${c.badges.map((b) => b.text).join(", ")})`}: ${inlinesMd(c.text, from)}`,
49
+ ...cards(c.children ?? [], from, depth + 1),
50
+ ]);
51
+ }
52
+
53
+ const tree = (ns: readonly TreeNode[], from: string, depth: number): string[] =>
54
+ ns.flatMap((n) => [`${" ".repeat(depth)}- \`${n.label}\`${n.note === undefined ? "" : `: ${inlinesMd(n.note, from)}`}`, ...tree(n.children, from, depth + 1)]);
55
+
56
+ function block(b: Block, from: string, level: number): string[] {
57
+ switch (b.kind) {
58
+ case "heading":
59
+ return ["", `${"#".repeat(Math.min(6, b.level + level))} ${inlinesMd(b.text, from)}`, ""];
60
+ case "paragraph":
61
+ return [inlinesMd(b.inlines, from), ""];
62
+ case "meta":
63
+ return [`*${inlinesMd(b.inlines, from)}*`, ""];
64
+ case "list":
65
+ return [...b.items.flatMap((item, i) => {
66
+ const lines = item.flatMap((x) => block(x, from, level)).filter((l, j, a) => !(l === "" && (j === a.length - 1 || j === 0)));
67
+ return lines.map((l, j) => `${j === 0 ? (b.ordered ? `${i + 1}. ` : "- ") : " "}${l}`);
68
+ }), ""];
69
+ case "code":
70
+ return [...(b.title === undefined ? [] : [`*${b.title}*`, ""]), `\`\`\`${b.lang === "text" ? "" : b.lang}`, b.text, "```", ""];
71
+ case "table":
72
+ return b.head.length === 0 ? [] : [`| ${b.head.map((h) => cell(h, from)).join(" | ")} |`, `| ${b.head.map(() => "---").join(" | ")} |`, ...b.rows.map((r) => `| ${r.map((c) => cell(c, from)).join(" | ")} |`), ""];
73
+ case "callout":
74
+ return [`> **${b.title}**`, ...b.blocks.flatMap((x) => block(x, from, level)).filter((l) => l !== "").map((l) => `> ${l}`), ""];
75
+ case "entry":
76
+ return ["", `${"#".repeat(Math.min(6, 3 + level))} ${b.name}${b.badges.length === 0 ? "" : ` (${b.badges.map((x) => x.text).join(", ")})`}`, "", ...(b.signature === undefined ? [] : ["```ts", b.signature, "```", ""]), ...b.blocks.flatMap((x) => block(x, from, level + 1))];
77
+ case "tabs":
78
+ return b.tabs.flatMap((t) => ["", `${"#".repeat(Math.min(6, 4 + level))} ${t.label}`, "", ...t.blocks.flatMap((x) => block(x, from, level + 1))]);
79
+ case "diagram":
80
+ return [...(b.caption === "" ? [] : [`*${b.caption}*`, ""]), "```mermaid", b.source, "```", ""];
81
+ case "cards":
82
+ return [...cards(b.cards, from, 0), ""];
83
+ case "badges":
84
+ return [b.badges.map((x) => `\`${x.text}\``).join(" "), ""];
85
+ case "tree":
86
+ return [...tree(b.nodes, from, 0), ""];
87
+ default:
88
+ return absurd(b);
89
+ }
90
+ }
91
+
92
+ /**
93
+ * A page as Markdown: its title, its description and its blocks.
94
+ *
95
+ * @param page - the page
96
+ */
97
+ export function markdownOf(page: Page): string {
98
+ const first = page.blocks[0];
99
+ // a page whose first paragraph is its description says it once
100
+ const repeated = first?.kind === "paragraph" && inlinesMd(first.inlines, page.path).trim() === page.description.trim();
101
+ const lines = [`# ${page.title}`, "", ...(page.description === "" || repeated ? [] : [page.description, ""]), ...page.blocks.flatMap((b) => block(b, page.path, 0))];
102
+ const out: string[] = [];
103
+ for (const l of lines) if (!(l === "" && out[out.length - 1] === "")) out.push(l);
104
+ return `${out.join("\n").trim()}\n`;
105
+ }
106
+
107
+ /**
108
+ * The index of the site for a program, `llms.txt`: the name, what the site is, and every page as a link to its Markdown twin with its description, by section.
109
+ *
110
+ * @param name - the site's name
111
+ * @param pages - the pages
112
+ * @param extras - other files an agent is told of (the JSON of a model), by path and what they are
113
+ */
114
+ export function llmsIndex(name: string, pages: readonly Page[], extras: readonly (readonly [path: string, what: string])[] = []): string {
115
+ const bySection = new Map<string, Page[]>();
116
+ for (const p of [...pages].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) bySection.set(p.section, [...(bySection.get(p.section) ?? []), p]);
117
+ const out = [`# ${name}`, "", `> Every page of this site is also written as Markdown beside its HTML (the same path with \`.md\`), and the models as JSON. This file lists them for a program.`, ""];
118
+ for (const [section, ps] of [...bySection].sort(([a], [b]) => (a < b ? -1 : 1))) {
119
+ out.push(`## ${section}`, "");
120
+ for (const p of ps) out.push(`- [${p.title}](${twinOf(p.path)})${p.description === "" ? "" : `: ${p.description.replace(/\s+/g, " ")}`}`);
121
+ out.push("");
122
+ }
123
+ if (extras.length > 0) {
124
+ out.push("## Data", "");
125
+ for (const [path, what] of extras) out.push(`- [${path}](${path}): ${what}`);
126
+ out.push("");
127
+ }
128
+ return `${out.join("\n").trimEnd()}\n`;
129
+ }
@@ -0,0 +1,38 @@
1
+ // Spec: 0001-docs FR-001
2
+ /**
3
+ * The search index of the site (commons 0011-documentation FR-017): one row for each page, heading and entry (an export, a requirement, a
4
+ * table or a column), as `[title, address, where, kind]`, which the site's script loads from `search.json` when a reader first searches.
5
+ *
6
+ * @module
7
+ */
8
+ import type { Block, Page } from "../model.ts";
9
+ import { plain } from "../model.ts";
10
+ import { SECTIONS } from "./html.ts";
11
+
12
+ /** A row of the index: what to show, where it goes from the site's root, where it is, and what kind of thing it is. */
13
+ export type SearchRow = readonly [title: string, url: string, where: string, kind: string];
14
+
15
+ function walk(bs: readonly Block[], page: Page, where: string, out: SearchRow[]): void {
16
+ for (const b of bs) {
17
+ if (b.kind === "heading") out.push([plain(b.text), `${page.path}#${b.id}`, where, "Section"]);
18
+ else if (b.kind === "entry") {
19
+ out.push([b.name, `${page.path}#${b.id}`, where, b.badges[0]?.text ?? "Entry"]);
20
+ walk(b.blocks, page, where, out);
21
+ } else if (b.kind === "tabs") for (const t of b.tabs) walk(t.blocks, page, where, out);
22
+ }
23
+ }
24
+
25
+ /**
26
+ * The index of every page, in the order of the pages.
27
+ *
28
+ * @param pages - the pages of the site
29
+ */
30
+ export function searchIndex(pages: readonly Page[]): SearchRow[] {
31
+ const out: SearchRow[] = [];
32
+ for (const p of pages) {
33
+ const section = SECTIONS.find((s) => s.section === p.section)?.label ?? p.section;
34
+ out.push([p.title, p.path, `${section} › ${p.group}`, "Page"]);
35
+ walk(p.blocks, p, `${section} › ${p.title}`, out);
36
+ }
37
+ return out;
38
+ }