render-directives.mjs

Functions

Imports

It imports render-error.mjs. Imported by render-nomath.mjs, render-packs.mjs.

Source

1// The directives every site gets (:::figure, :::details), the guard that refuses an unknown one, and the two building blocks a site pack
2// writes its own directives with. Nothing here imports site code; a site's extra directives are registered as a pack (render-packs.mjs).
3
4import { visit } from "unist-util-visit";
5
6import { ContentError, errorMessage } from "./render-error.mjs";
7
8/**
9 * Valueless attributes are dropped: they are indistinguishable from absent ones.
10 *
11 * @param {{ attributes?: Record<string, string | null | undefined> | null | undefined }} node
12 * @returns {Record<string, string>}
13 */
14function attributesOf(node) {
15  /** @type {Record<string, string>} */
16  const out = {};
17  for (const [key, value] of Object.entries(node.attributes ?? {})) {
18    if (typeof value === "string") out[key] = value;
19  }
20  return out;
21}
22
23/**
24 * @param {string} file
25 */
26export function remarkFigure(file) {
27  return (/** @type {import("mdast").Root} */ tree) => {
28    visit(tree, (node) => {
29      if (node.type !== "containerDirective" || node.name !== "figure") return;
30
31      const attrs = node.attributes ?? {};
32      if (!attrs.src) {
33        throw new ContentError(file, ":::figure requires a src attribute");
34      }
35      if (!attrs.alt) {
36        // A figcaption is announced separately, so it is no substitute for alt.
37        throw new ContentError(file, `:::figure ${attrs.src} requires an alt attribute`);
38      }
39
40      /** @type {any[]} */
41      const captionChildren = [...(node.children ?? [])];
42
43      /** @type {any[]} */
44      const figureChildren = [
45        {
46          type: "paragraph",
47          data: { hName: "img", hProperties: { src: attrs.src, alt: attrs.alt } },
48          children: [],
49        },
50      ];
51
52      if (captionChildren.length > 0 || attrs.credit) {
53        /** @type {any[]} */
54        const caption = [...captionChildren];
55        if (attrs.credit) {
56          caption.push({
57            type: "paragraph",
58            data: { hName: "span", hProperties: { className: ["figure-credit"] } },
59            children: [{ type: "text", value: attrs.credit }],
60          });
61        }
62        figureChildren.push({
63          type: "paragraph",
64          data: { hName: "figcaption" },
65          children: caption,
66        });
67      }
68
69      node.data = { ...node.data, hName: "figure" };
70      node.children = figureChildren;
71    });
72  };
73}
74
75/**
76 * remark-directive parses prose such as 4.5:1 and localhost:8080 as directives, and every real directive name is a word. Sliced from
77 * the source so a label or attributes come back as written.
78 *
79 * @param {string} source the markdown these positions refer to
80 */
81export function remarkNumericTextDirectives(source) {
82  return (/** @type {import("mdast").Root} */ tree) => {
83    visit(tree, "textDirective", (node, index, parent) => {
84      if (!parent || index === undefined || index === null) return;
85      if (!/^\d/.test(node.name ?? "")) return;
86      const { start, end } = node.position ?? {};
87      if (start?.offset === undefined || end?.offset === undefined) return;
88      parent.children[index] = {
89        type: "text",
90        value: source.slice(start.offset, end.offset),
91        position: node.position,
92      };
93    });
94  };
95}
96
97/**
98 * Refuses a heading directly inside a container directive, naming the directive and the line.
99 *
100 * @param {string} file
101 * @param {any} node the directive
102 * @param {string} why completes the sentence that names the heading
103 */
104export function refuseHeading(file, node, why) {
105  const heading = (node.children ?? []).find((/** @type {any} */ child) => child.type === "heading");
106  if (!heading) return;
107  const line = heading.position?.start?.line;
108  throw new ContentError(file, `:::${node.name} holds a heading${line ? ` on line ${line}` : ""}${why}`);
109}
110
111/**
112 * A heading inside is refused: it would put a hidden section in the table of contents. Native
113 * <details>, so the text is in the HTML without script.
114 *
115 * @param {string} file
116 */
117export function remarkDetails(file) {
118  return (/** @type {import("mdast").Root} */ tree) => {
119    visit(tree, (node) => {
120      if (node.type !== "containerDirective" || node.name !== "details") return;
121
122      const summary = (node.attributes ?? {}).summary;
123      if (!summary) {
124        throw new ContentError(file, ":::details requires a summary attribute");
125      }
126
127      refuseHeading(
128        file,
129        node,
130        ", which makes it a section of the argument rather than supplementary material. A " +
131          "heading is in the table of contents and is a link target, so collapsing it hides a " +
132          "section a reader was sent to. Use it for long methods, raw data or an appendix, and " +
133          "leave the argument open.",
134      );
135
136      node.data = { ...node.data, hName: "details", hProperties: { className: ["post-details"] } };
137      node.children = [
138        {
139          type: "paragraph",
140          data: { hName: "summary" },
141          children: [{ type: "text", value: String(summary) }],
142        },
143        .../** @type {any[]} */ (node.children ?? []),
144      ];
145    });
146  };
147}
148
149/** The directives the core handles itself. A pack adds its own names to the list the guard checks. */
150export const CORE_DIRECTIVES = ["details", "figure"];
151
152/**
153 * An unhandled directive becomes a silent empty <div>, so a typo such as :::figrue loses the figure. Runs after
154 * remarkNumericTextDirectives, so prose like 12:30 is already text.
155 *
156 * @param {string} file
157 * @param {readonly string[]} known every directive name the renderer and its packs handle
158 */
159export function remarkUnknownDirectives(file, known) {
160  return (/** @type {import("mdast").Root} */ tree) => {
161    visit(tree, (node) => {
162      // Named rather than matched on a suffix, so TypeScript narrows the union.
163      if (
164        node.type !== "containerDirective" &&
165        node.type !== "leafDirective" &&
166        node.type !== "textDirective"
167      ) {
168        return;
169      }
170      const type = node.type;
171      const name = node.name ?? "";
172      if (known.includes(name)) return;
173
174      const marker =
175        type === "containerDirective" ? ":::" : type === "leafDirective" ? "::" : ":";
176      const line = node.position?.start?.line;
177      throw new ContentError(
178        file,
179        `unknown directive "${marker}${name}"${line ? ` on line ${line}` : ""}. ` +
180          `Known directives: ${known.join(", ")}. ` +
181          "If this is ordinary prose, escape the colon as \\: or wrap it in a code span.",
182      );
183    });
184  };
185}
186
187/**
188 * Split across remark and rehype: validation must fail the build in remark, but the caption only
189 * becomes hast after remark-rehype. The remark half of a model directive: a container holding
190 * exactly one fenced block, built into a model and marked with the model's index for the rehype half.
191 *
192 * @param {{
193 *   name: string,
194 *   marker: string,
195 *   className: string,
196 *   what: string,
197 *   lang?: string,
198 *   build: (attributes: any, source: string) => any,
199 * }} kind `what` names the fence's content in the refusal; `lang` is the fence language required, if any
200 */
201export function remarkModelDirective(kind) {
202  /**
203   * @param {string} file
204   * @param {any[]} sink models, indexed by the marker written onto the node
205   */
206  return (file, sink) =>
207    (/** @type {import("mdast").Root} */ tree) => {
208      visit(tree, (node) => {
209        if (node.type !== "containerDirective" || node.name !== kind.name) return;
210
211        const children = node.children ?? [];
212        const fences = children.filter((c) => c.type === "code");
213        const fence = fences[0];
214        if (fences.length !== 1 || !fence) {
215          throw new ContentError(
216            file,
217            `:::${kind.name} requires exactly one fenced code block of ${kind.what}, found ${fences.length}`,
218          );
219        }
220        // The mermaid fence is also what renders the source as a diagram in the .md twin and on GitHub.
221        const lang = fence.lang ?? "";
222        if (kind.lang !== undefined && lang !== kind.lang) {
223          throw new ContentError(
224            file,
225            `:::${kind.name} source must be a \`\`\`${kind.lang} fenced block, found \`\`\`${lang || "(none)"}`,
226          );
227        }
228
229        /** @type {any} */
230        let model;
231        try {
232          model = kind.build(attributesOf(node), fence.value);
233        } catch (error) {
234          throw new ContentError(file, errorMessage(error));
235        }
236
237        const index = sink.push(model) - 1;
238        node.data = {
239          ...node.data,
240          hName: "figure",
241          hProperties: { className: [kind.className], [kind.marker]: String(index) },
242        };
243        node.children = children.filter((/** @type {any} */ c) => c.type !== "code");
244      });
245    };
246}
247
248/**
249 * The rehype half: renders each marked figure from its model and drops the marker.
250 *
251 * @param {string} marker
252 * @param {(model: any, caption: any[], node: any) => any[]} render
253 */
254export function rehypeModelMarker(marker, render) {
255  /** @param {any[]} models */
256  return (models) =>
257    (/** @type {import("hast").Root} */ tree) => {
258      visit(tree, "element", (node) => {
259        const at = node.properties?.[marker];
260        if (at === undefined) return;
261        const model = models[Number(at)];
262        delete node.properties[marker];
263        node.children = render(model, node.children ?? [], node);
264      });
265    };
266}