@memorysmithapp/markdown-renderer 0.1.2 → 0.3.0

package/dist/diagnose.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The notices of a note (§7.13): where what is drawn will not be what was most likely typed.
+ *
+ * There is no invalid note (§6.4), so nothing here accepts or refuses: it reads a note the way the
+ * reading surface reads it — the same frontmatter cut, its comments taken out (`hideComments`), the
+ * same parser and the same remark plugins (`reading.ts`) — and reports, by a stable code, the places where the page will differ from the
+ * text, or where the note lacks something the specification reserves a place for. A notice never
+ * blocks a save and never changes a byte.
+ *
+ * It runs with no DOM and no React, so a host can call it on a server, from a tool that writes a
+ * note, or beside an editor. KaTeX checks a formula as `rehype-katex` would typeset it, and Mermaid
+ * reads a diagram as the page would draw it, loaded only when a note carries one.
+ */
+import type { NoteHost } from './host.js';
+/** The codes of §7.13, which `spec.json` declares as `notices`. */
+export type NoticeCode = 'fence-unclosed' | 'math-unclosed' | 'formula-invalid' | 'diagram-invalid' | 'frontmatter-unclosed' | 'name-missing' | 'name-unusable' | 'reserved-not-a-list' | 'aliases-missing' | 'tags-missing' | 'heading-first-level' | 'heading-skipped-level' | 'footnote-undefined' | 'footnote-unreferenced' | 'raw-html' | 'strikethrough-single-tilde' | 'link-pending' | 'embed-pending';
+/** `notice`: the page will differ from what was typed. `hint`: nothing is drawn wrong. */
+export type NoticeSeverity = 'notice' | 'hint';
+/** One place in a note, by a code of §7.13. Lines and columns count from 1 over the whole note. */
+export interface Notice {
+    readonly code: NoticeCode;
+    readonly severity: NoticeSeverity;
+    /** The section of the specification that decides what happens there. */
+    readonly section: string;
+    /** What a reader gets, in English; a host words it in its own language from `code`. */
+    readonly message: string;
+    readonly line: number;
+    readonly column: number;
+    readonly endLine: number;
+    readonly endColumn: number;
+}
+/**
+ * What the notebook answers, as `NoteBody` asks it. With neither `resolve` nor `reaches`, nothing
+ * is known about the notebook and no link is reported as pending.
+ */
+export interface DiagnoseOptions extends Pick<NoteHost, 'resolve' | 'reaches' | 'keeps'> {
+    /** Whether to read each `mermaid` block with Mermaid, which is loaded for it. Defaults to true. */
+    readonly diagrams?: boolean;
+}
+/** The table of §7.13, as `spec.json` carries it: a test holds the two equal. */
+export declare const NOTICES: Readonly<Record<NoticeCode, {
+    readonly severity: NoticeSeverity;
+    readonly section: string;
+    readonly message: string;
+}>>;
+/**
+ * The notices of a note, in the order of the note. `markdown` is the note as a host keeps it,
+ * frontmatter included; the positions are into it.
+ */
+export declare function diagnose(markdown: string, options?: DiagnoseOptions): Promise<Notice[]>;

package/dist/diagnose.js

@@ -0,0 +1,304 @@
+/**
+ * The notices of a note (§7.13): where what is drawn will not be what was most likely typed.
+ *
+ * There is no invalid note (§6.4), so nothing here accepts or refuses: it reads a note the way the
+ * reading surface reads it — the same frontmatter cut, its comments taken out (`hideComments`), the
+ * same parser and the same remark plugins (`reading.ts`) — and reports, by a stable code, the places where the page will differ from the
+ * text, or where the note lacks something the specification reserves a place for. A notice never
+ * blocks a save and never changes a byte.
+ *
+ * It runs with no DOM and no React, so a host can call it on a server, from a tool that writes a
+ * note, or beside an editor. KaTeX checks a formula as `rehype-katex` would typeset it, and Mermaid
+ * reads a diagram as the page would draw it, loaded only when a note carries one.
+ */
+import katex from 'katex';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import { bodyStart, codeRegions, hideComments, insideCode, toUnixNewlines } from './markdown.js';
+import { readProperties } from './properties.js';
+import { readingPlugins } from './reading.js';
+/** The table of §7.13, as `spec.json` carries it: a test holds the two equal. */
+export const NOTICES = {
+    'fence-unclosed': { severity: 'notice', section: '3.7', message: 'This fence is never closed: it runs to the end of its block, and everything after it is code.' },
+    'math-unclosed': { severity: 'notice', section: '7.8', message: 'This $$ block is never closed: it runs to the end of its block, and everything after it is a formula.' },
+    'formula-invalid': { severity: 'notice', section: '7.8', message: 'This formula cannot be typeset, and is shown as its source.' },
+    'diagram-invalid': { severity: 'notice', section: '7.2', message: 'This diagram cannot be read, and is shown as its source or its error.' },
+    'frontmatter-unclosed': { severity: 'notice', section: '6.1', message: 'This frontmatter is never closed by a ---: the note has no properties, and its lines are body text.' },
+    'name-missing': { severity: 'notice', section: '6.5', message: 'The note has no name: a link reaches it only through an alias.' },
+    'name-unusable': { severity: 'notice', section: '6.5', message: 'This name is not a single text value, so the note is unnamed.' },
+    'reserved-not-a-list': { severity: 'notice', section: '6.4', message: 'This value is not a list, so it is an ordinary attribute.' },
+    'aliases-missing': { severity: 'hint', section: '6.4', message: 'The note has no aliases: only its name catches a link.' },
+    'tags-missing': { severity: 'hint', section: '6.4', message: 'The note has no tags: it has no subjects to be filtered by.' },
+    'heading-first-level': { severity: 'notice', section: '3.3', message: 'The first heading of the body is not level one.' },
+    'heading-skipped-level': { severity: 'notice', section: '3.3', message: 'This heading skips a level below the heading before it.' },
+    'footnote-undefined': { severity: 'notice', section: '7.12', message: 'This footnote has no definition, and is drawn as its characters.' },
+    'footnote-unreferenced': { severity: 'notice', section: '7.12', message: 'Nothing references this footnote, so it is not drawn.' },
+    'raw-html': { severity: 'notice', section: '7.9', message: 'Raw HTML is drawn as text, tags and all.' },
+    'strikethrough-single-tilde': { severity: 'notice', section: '4.3', message: 'One tilde strikes nothing: the tildes stay on the page. Strikethrough is ~~two~~.' },
+    'link-pending': { severity: 'hint', section: '7.4', message: 'No note answers this link yet, so it is drawn as pending.' },
+    'embed-pending': { severity: 'hint', section: '7.3', message: 'No note and no kept file answers this embed, so it is drawn as a pending link.' },
+};
+/** A footnote reference left as text, which is one with no definition (§7.12). */
+const UNDEFINED_REFERENCE = /\[\^[^\]\s]+\]/g;
+/** A run between single tildes, which GFM as read here leaves as characters (§4.3). */
+const SINGLE_TILDE = /(?<![~\\])~(?!~)(?=\S)[^~\n]*?\S~(?!~)/g;
+/** A wikilink, with the bang of an embed: the shape `resolveWikilinks` reads. */
+const WIKILINK = /(!)?\[\[([^\]|]+?)(?:\|([^\]]+?))?\]\]/g;
+/** A closing fence or `$$`, once the markers of its container are taken off. */
+const CONTAINER_PREFIX = /^[ \t>]*/;
+const KEY = /^([A-Za-z0-9_-]+)\s*:/;
+/**
+ * The notices of a note, in the order of the note. `markdown` is the note as a host keeps it,
+ * frontmatter included; the positions are into it.
+ */
+export async function diagnose(markdown, options = {}) {
+    const text = toUnixNewlines(markdown);
+    const lineStarts = [0];
+    for (let index = 0; index < text.length; index++)
+        if (text[index] === '\n')
+            lineStarts.push(index + 1);
+    const pointOf = (offset) => {
+        let low = 0;
+        let high = lineStarts.length - 1;
+        while (low < high) {
+            const middle = (low + high + 1) >> 1;
+            if ((lineStarts[middle] ?? 0) <= offset)
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        return { line: low + 1, column: offset - (lineStarts[low] ?? 0) + 1 };
+    };
+    const found = [];
+    const report = (code, start, end = start, detail) => {
+        const from = pointOf(start);
+        const to = pointOf(end);
+        const { severity, section, message } = NOTICES[code];
+        found.push({
+            at: start,
+            notice: {
+                code,
+                severity,
+                section,
+                message: detail ? `${message} (${detail})` : message,
+                line: from.line,
+                column: from.column,
+                endLine: to.line,
+                endColumn: to.column,
+            },
+        });
+    };
+    const split = bodyStart(text);
+    frontmatter(text, split, report);
+    // A comment is never drawn, so nothing it holds raises a notice; positions are mapped back over it.
+    const hidden = hideComments(text.slice(split));
+    const body = hidden.text;
+    const processor = unified().use(remarkParse).use(readingPlugins(() => undefined));
+    const parsed = processor.parse(body);
+    // The text as the parser found it, before a plugin cut a run of it and dropped its position.
+    const read = structuredClone(parsed);
+    const tree = processor.runSync(parsed, body);
+    const span = (node) => {
+        const start = node.position?.start.offset;
+        const end = node.position?.end.offset;
+        return start === undefined || end === undefined ? null : [split + hidden.original(start), split + hidden.original(end, true)];
+    };
+    const diagrams = [];
+    const referenced = new Set();
+    const definitions = [];
+    walk(tree, (node) => {
+        const at = span(node);
+        if (!at)
+            return;
+        const source = text.slice(at[0], at[1]);
+        if (node.type === 'code' && /^\s*(`{3,}|~{3,})/.test(source)) {
+            if (!closes(source, /^(`{3,}|~{3,})/))
+                report('fence-unclosed', at[0], at[1]);
+            else if (node.lang === 'mermaid')
+                diagrams.push({ source: node.value ?? '', at });
+        }
+        else if (node.type === 'math') {
+            if (!closes(source, /^(\${2,})/))
+                report('math-unclosed', at[0], at[1]);
+            else if (!typesets(node.value ?? '', true))
+                report('formula-invalid', at[0], at[1]);
+        }
+        else if (node.type === 'inlineMath') {
+            if (!typesets(node.value ?? '', false))
+                report('formula-invalid', at[0], at[1]);
+        }
+        else if (node.type === 'html') {
+            report('raw-html', at[0], at[1]);
+        }
+        else if (node.type === 'footnoteReference') {
+            referenced.add(String(node.identifier ?? '').toUpperCase());
+        }
+        else if (node.type === 'footnoteDefinition') {
+            definitions.push(node);
+        }
+    });
+    for (const definition of definitions) {
+        const at = span(definition);
+        if (at && !referenced.has(String(definition.identifier ?? '').toUpperCase())) {
+            report('footnote-unreferenced', at[0], at[1]);
+        }
+    }
+    outline(tree, span, report);
+    // What stays characters on the page is found in the text the parser read.
+    walk(read, (node) => {
+        if (node.type !== 'text')
+            return;
+        const start = node.position?.start.offset;
+        const end = node.position?.end.offset;
+        if (start === undefined || end === undefined)
+            return;
+        const source = body.slice(start, end);
+        for (const [pattern, code] of [
+            [UNDEFINED_REFERENCE, 'footnote-undefined'],
+            [SINGLE_TILDE, 'strikethrough-single-tilde'],
+        ]) {
+            for (const match of source.matchAll(pattern)) {
+                const from = start + match.index;
+                report(code, split + hidden.original(from), split + hidden.original(from + match[0].length, true));
+            }
+        }
+    });
+    pending(hidden, split, options, report);
+    if (diagrams.length > 0 && options.diagrams !== false) {
+        const mermaid = (await import('mermaid')).default;
+        for (const diagram of diagrams) {
+            try {
+                await mermaid.parse(diagram.source);
+            }
+            catch (error) {
+                if (unreadable(error))
+                    report('diagram-invalid', diagram.at[0], diagram.at[1]);
+            }
+        }
+    }
+    return found.sort((a, b) => a.at - b.at).map(({ notice }) => notice);
+}
+function walk(node, visit) {
+    visit(node);
+    for (const child of node.children ?? [])
+        walk(child, visit);
+}
+/**
+ * Whether a fenced block or a `$$` block was closed: its last line, once its container's markers
+ * are off, is a run of the opening character at least as long as the opening one, and nothing else.
+ */
+function closes(source, opening) {
+    const lines = source.split('\n');
+    const run = opening.exec((lines[0] ?? '').replace(CONTAINER_PREFIX, ''))?.[1] ?? '';
+    if (lines.length < 2 || run.length === 0)
+        return false;
+    const last = (lines[lines.length - 1] ?? '').replace(CONTAINER_PREFIX, '').trimEnd();
+    const closing = new RegExp(`^\\${run[0]}{${run.length},}$`);
+    return closing.test(last);
+}
+/**
+ * Whether Mermaid refused a diagram for what it says, rather than for where it runs. Its parsers
+ * answer with a parse error, and an unknown diagram type with its own error; with no DOM, reading a
+ * label of some diagrams fails on the sanitiser instead, and that failure is no notice: a diagram
+ * Mermaid could not finish reading here may well be drawn on the page.
+ */
+function unreadable(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const failure = error;
+    return (typeof failure.hash === 'object' ||
+        failure.name === 'UnknownDiagramError' ||
+        failure.constructor?.name === 'MermaidParseError');
+}
+/** Whether KaTeX typesets a formula, as `rehype-katex` would. */
+function typesets(formula, display) {
+    try {
+        katex.renderToString(formula, { displayMode: display, throwOnError: true, strict: 'ignore' });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The reserved keys of the frontmatter (§6.4, §6.5), and a block that never closes (§6.1). */
+function frontmatter(text, split, report) {
+    const opened = text.startsWith('---');
+    if (opened && text.indexOf('\n---', 3) === -1)
+        report('frontmatter-unclosed', 0, text.indexOf('\n') === -1 ? 3 : text.indexOf('\n'));
+    // Where each key was written, to place a notice on it.
+    const keys = new Map();
+    if (opened && split > 0) {
+        let at = text.indexOf('\n') + 1;
+        for (const line of text.slice(at, split).split('\n')) {
+            const key = KEY.exec(line)?.[1];
+            if (key && !keys.has(key))
+                keys.set(key, at);
+            at += line.length + 1;
+        }
+    }
+    const lineEnd = (at) => {
+        const end = text.indexOf('\n', at);
+        return end === -1 ? text.length : end;
+    };
+    const properties = readProperties(text);
+    const name = keys.get('name');
+    if (name === undefined)
+        report('name-missing', 0);
+    else if (properties.name === null)
+        report('name-unusable', name, lineEnd(name));
+    for (const [key, code] of [
+        ['aliases', 'aliases-missing'],
+        ['tags', 'tags-missing'],
+    ]) {
+        const at = keys.get(key);
+        const entry = properties.entries.find((candidate) => candidate.key === key);
+        if (at === undefined || !entry)
+            report(code, 0);
+        else if (entry.shape === 'empty')
+            report(code, at, lineEnd(at));
+        else if (entry.shape !== 'list')
+            report('reserved-not-a-list', at, lineEnd(at), key);
+    }
+}
+/** The outline of the body (§3.3): the headings at its top level, outside code. */
+function outline(tree, span, report) {
+    let previous = null;
+    for (const node of tree.children ?? []) {
+        if (node.type !== 'heading' || node.depth === undefined)
+            continue;
+        const at = span(node);
+        if (at) {
+            if (previous === null && node.depth > 1)
+                report('heading-first-level', at[0], at[1]);
+            else if (previous !== null && node.depth > previous + 1)
+                report('heading-skipped-level', at[0], at[1]);
+        }
+        previous = node.depth;
+    }
+}
+/**
+ * The wikilinks and embeds no note answers, when the host says which notes exist: a link reaches
+ * a note, and an embed a note or a kept file (§5.2, §5.8). Read on the body outside code, as
+ * `resolveWikilinks` reads it.
+ */
+function pending(hidden, split, options, report) {
+    const body = hidden.text;
+    const { resolve, reaches, keeps = () => false } = options;
+    if (!resolve && !reaches)
+        return;
+    const answered = (name) => reaches ? reaches(name.normalize('NFC')) > 0 : resolve(name.normalize('NFC')) !== null;
+    const code = codeRegions(body);
+    for (const match of body.matchAll(WIKILINK)) {
+        if (insideCode(code, match.index))
+            continue;
+        const name = (match[2] ?? '').split('#')[0]?.trim().replace(/\\$/, '').trim() ?? '';
+        // `[[#Section]]` is a link within the note itself.
+        if (!name)
+            continue;
+        const embed = match[1] !== undefined;
+        if (answered(name) || (embed && keeps(name)))
+            continue;
+        const end = match.index + match[0].length;
+        report(embed ? 'embed-pending' : 'link-pending', split + hidden.original(match.index), split + hidden.original(end, true), name);
+    }
+}

package/dist/host.d.ts

@@ -1,5 +1,6 @@
 import { type ReactNode } from 'react';
 import { type NoteStrings } from './strings.js';
+import { type Scheme, type Theme } from './theme.js';
 /**
  * The host contract: everything the renderer needs from the notebook a note lives in, given by
  * whoever draws it.
@@ -62,8 +63,17 @@ export interface NoteHost {
     readonly renderLink?: (link: LinkRequest) => ReactNode;
     /** The words the page shows, in the reader's language; each one left out is MemorySmith's English. */
     readonly strings?: Partial<NoteStrings>;
-    /** The theme the host draws in, which picks the theme of a Mermaid diagram. Defaults to `light`. */
-    readonly theme?: 'light' | 'dark';
+    /**
+     * How the note looks: a theme (`defineTheme`), or `light` or `dark`, which are the default
+     * theme — MemorySmith's look — in that scheme. Defaults to the default theme.
+     */
+    readonly theme?: Scheme | Theme;
+    /**
+     * The scheme a theme is drawn in, which also picks the theme of a Mermaid diagram. Defaults to
+     * the scheme `theme` names when it is `light` or `dark`, and to `light` otherwise; a theme of one
+     * scheme is drawn in it whatever is asked.
+     */
+    readonly scheme?: Scheme;
     /**
      * Whether a note that fetched images from other sites says so, naming them, under the body
      * (§7.10). Defaults to `true`: the specification forbids only silence. A host that discloses it
@@ -127,7 +137,10 @@ export interface ResolvedHost {
     readonly renderAttachment: ((file: AttachmentRequest) => ReactNode) | null;
     readonly renderLink: (link: LinkRequest) => ReactNode;
     readonly strings: NoteStrings;
-    readonly theme: 'light' | 'dark';
+    /** The theme the note is drawn in. */
+    readonly theme: Theme;
+    /** The scheme it is drawn in. */
+    readonly scheme: Scheme;
 }
 export declare function resolveHost(host: NoteHost): ResolvedHost;
 export declare const HostProvider: import("react").Provider<ResolvedHost>;

package/dist/host.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, useContext } from 'react';
 import { withDefaults } from './strings.js';
+import { DEFAULT_THEME, schemeOf } from './theme.js';
 /**
  * Every member of the contract, by name. The `satisfies` is what makes it complete: a member added
  * to `NoteHost` and not listed here does not compile.
@@ -19,11 +20,18 @@ export const HOST_KEYS = Object.keys({
     renderLink: 1,
     strings: 1,
     theme: 1,
+    scheme: 1,
     remoteNotice: 1,
 });
 const nothing = () => null;
 const never = () => false;
 const plainLink = ({ href, className, children }) => (_jsx("a", { className: className, href: href, children: children }));
+function themeOf(host) {
+    const given = host.theme ?? DEFAULT_THEME;
+    const theme = typeof given === 'string' ? DEFAULT_THEME : given;
+    const asked = host.scheme ?? (typeof given === 'string' ? given : 'light');
+    return { theme, scheme: schemeOf(theme, asked) };
+}
 export function resolveHost(host) {
     const resolve = host.resolve ?? nothing;
     return {
@@ -38,7 +46,7 @@ export function resolveHost(host) {
         renderAttachment: host.renderAttachment ?? null,
         renderLink: host.renderLink ?? plainLink,
         strings: withDefaults(host.strings),
-        theme: host.theme ?? 'light',
+        ...themeOf(host),
     };
 }
 const HostContext = createContext(resolveHost({}));

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 export { NoteBody, type NoteBodyProps } from './NoteBody.js';
 export type { AttachmentRequest, EmbeddedNote, LinkChoiceNote, LinkChoices, LinkRequest, NoteHost } from './host.js';
 export { ENGLISH, type NoteStrings } from './strings.js';
+export { customPropertyOf, DEFAULT_THEME, defineTheme, THEME_PROPERTIES, THEME_SLOTS, type BlockquoteSlotProps, type CalloutSlotProps, type CodeBlockSlotProps, type DiagramSlotProps, type EmbedSlotProps, type FootnotesSlotProps, type HeadingSlotProps, type InlineCodeSlotProps, type PropertiesSlotProps, type Scheme, type TableSlotProps, type TaskBoxSlotProps, type Theme, type ThemeComponents, type ThemeProperties, type WikilinkSlotProps, } from './theme.js';
 export { followable } from './address.js';
 export { readDimensions, readImageAlt, type ImageAlt } from './image-dimensions.js';
 export { codeRegions, fenceRegions, headingKey, remoteImageHosts, resolveWikilinks, splitFrontmatter, tableRegions, toUnixNewlines, type SplitDocument, } from './markdown.js';
 export { ordinalAt, taskBoxes, taskCheckedAt, toggleTaskAt } from './tasklist.js';
+export { readProperties, type NoteProperties, type PropertyEntry, type PropertyShape } from './properties.js';
 export { DELEGATED_TO_THE_BASE_PARSER, unclassified } from './delegated.js';

package/dist/index.js

@@ -1,8 +1,10 @@
 // The entry point of @memorysmithapp/markdown-renderer.
 export { NoteBody } from './NoteBody.js';
 export { ENGLISH } from './strings.js';
+export { customPropertyOf, DEFAULT_THEME, defineTheme, THEME_PROPERTIES, THEME_SLOTS, } from './theme.js';
 export { followable } from './address.js';
 export { readDimensions, readImageAlt } from './image-dimensions.js';
 export { codeRegions, fenceRegions, headingKey, remoteImageHosts, resolveWikilinks, splitFrontmatter, tableRegions, toUnixNewlines, } from './markdown.js';
 export { ordinalAt, taskBoxes, taskCheckedAt, toggleTaskAt } from './tasklist.js';
+export { readProperties } from './properties.js';
 export { DELEGATED_TO_THE_BASE_PARSER, unclassified } from './delegated.js';

package/dist/markdown.d.ts

@@ -20,15 +20,16 @@ export interface SplitDocument {
  */
 export declare function toUnixNewlines(raw: string): string;
 /**
- * Where the body of a note starts: after its frontmatter, which a host shows as properties and
- * not as prose. The cut is the one MemorySmith's reading page makes, so the ordinals of the task
+ * Where the body of a note starts: after its frontmatter, which the theme draws apart from the
+ * body (`readProperties`). The cut is the one MemorySmith's reading page makes, so the ordinals of the task
  * boxes below it are counted over the whole note, as the host stores it.
  */
 export declare function bodyStart(text: string): number;
 /**
  * The frontmatter block, read the way MemorySmith's reading page reads it to show a note's
- * properties. The package does not draw it — `NoteBody` starts after it — and exports this so a
- * host that draws the properties reads the same values MemorySmith does.
+ * properties, its lists joined by commas. The renderer draws the frontmatter from
+ * `readProperties`, which keeps each item and each shape apart; this stays for a host that reads
+ * the values MemorySmith does.
  */
 export declare function splitFrontmatter(input: string): SplitDocument;
 /** The half-open ranges of `body` that are fenced blocks. */
@@ -40,6 +41,26 @@ export declare function insideCode(regions: Array<[number, number]>, at: number)
 export declare function tableRegions(body: string): Array<[number, number]>;
 /** Whether an offset falls inside one of them. */
 export declare function insideTable(regions: Array<[number, number]>, at: number): boolean;
+/**
+ * The comments of a text (§7.6), as half-open ranges: from a `%%` outside code to the next `%%`
+ * outside code, across inline markup and blank lines alike. A `%%` with no partner opens nothing.
+ *
+ * A comment that is all of its lines takes the line break after it too, so a comment written on
+ * lines of its own leaves no empty line behind to loosen a list or split a paragraph.
+ *
+ * MemorySmith's reading page hides a comment inside one run of text only, so one that holds a
+ * link, a tag, emphasis or a blank line reaches the page whole; this is found on the text, before
+ * anything is parsed, so nothing a comment holds is ever read.
+ */
+export declare function commentRegions(text: string): Array<[number, number]>;
+/** A text with its comments taken out, and where an offset into it falls in the text it came from. */
+export interface HiddenComments {
+    readonly text: string;
+    /** The offset in the original text of an offset into `text`; an `end` stays before a comment it meets. */
+    readonly original: (offset: number, end?: boolean) => number;
+}
+/** The text a reader is shown: its comments taken out (§7.6). The note itself is never changed. */
+export declare function hideComments(text: string): HiddenComments;
 /** Runs a rewrite over everything except code, which is copied through. */
 export declare function outsideCode(body: string, rewrite: (text: string) => string): string;
 export declare function resolveWikilinks(body: string, resolve: (name: string) => string | null, 

package/dist/markdown.js

@@ -12,8 +12,8 @@ export function toUnixNewlines(raw) {
     return raw.replace(/\r\n?/g, '\n');
 }
 /**
- * Where the body of a note starts: after its frontmatter, which a host shows as properties and
- * not as prose. The cut is the one MemorySmith's reading page makes, so the ordinals of the task
+ * Where the body of a note starts: after its frontmatter, which the theme draws apart from the
+ * body (`readProperties`). The cut is the one MemorySmith's reading page makes, so the ordinals of the task
  * boxes below it are counted over the whole note, as the host stores it.
  */
 export function bodyStart(text) {
@@ -32,8 +32,9 @@ function unquote(value) {
 }
 /**
  * The frontmatter block, read the way MemorySmith's reading page reads it to show a note's
- * properties. The package does not draw it — `NoteBody` starts after it — and exports this so a
- * host that draws the properties reads the same values MemorySmith does.
+ * properties, its lists joined by commas. The renderer draws the frontmatter from
+ * `readProperties`, which keeps each item and each shape apart; this stays for a host that reads
+ * the values MemorySmith does.
  */
 export function splitFrontmatter(input) {
     const raw = toUnixNewlines(input);
@@ -253,6 +254,54 @@ export function tableRegions(body) {
 export function insideTable(regions, at) {
     return regions.some(([start, end]) => at >= start && at < end);
 }
+/**
+ * The comments of a text (§7.6), as half-open ranges: from a `%%` outside code to the next `%%`
+ * outside code, across inline markup and blank lines alike. A `%%` with no partner opens nothing.
+ *
+ * A comment that is all of its lines takes the line break after it too, so a comment written on
+ * lines of its own leaves no empty line behind to loosen a list or split a paragraph.
+ *
+ * MemorySmith's reading page hides a comment inside one run of text only, so one that holds a
+ * link, a tag, emphasis or a blank line reaches the page whole; this is found on the text, before
+ * anything is parsed, so nothing a comment holds is ever read.
+ */
+export function commentRegions(text) {
+    const code = codeRegions(text);
+    const markers = [...text.matchAll(/%%/g)].map((match) => match.index).filter((at) => !insideCode(code, at));
+    const regions = [];
+    for (let index = 0; index + 1 < markers.length; index += 2) {
+        let start = markers[index];
+        let end = markers[index + 1] + 2;
+        const lineStart = text.lastIndexOf('\n', start - 1) + 1;
+        const lineEnd = text.indexOf('\n', end) === -1 ? text.length : text.indexOf('\n', end);
+        if (/^[ \t]*$/.test(text.slice(lineStart, start)) && /^[ \t]*$/.test(text.slice(end, lineEnd))) {
+            start = lineStart;
+            end = lineEnd === text.length ? lineEnd : lineEnd + 1;
+        }
+        regions.push([start, end]);
+    }
+    return regions;
+}
+/** The text a reader is shown: its comments taken out (§7.6). The note itself is never changed. */
+export function hideComments(text) {
+    const regions = commentRegions(text);
+    if (regions.length === 0)
+        return { text, original: (offset) => offset };
+    let shown = '';
+    let cursor = 0;
+    // Where each comment was, in the shown text, and how much of the original it took.
+    const cuts = [];
+    for (const [start, end] of regions) {
+        shown += text.slice(cursor, start);
+        cuts.push({ at: shown.length, length: end - start });
+        cursor = end;
+    }
+    shown += text.slice(cursor);
+    return {
+        text: shown,
+        original: (offset, end = false) => offset + cuts.filter((cut) => (end ? cut.at < offset : cut.at <= offset)).reduce((total, cut) => total + cut.length, 0),
+    };
+}
 /** Runs a rewrite over everything except code, which is copied through. */
 export function outsideCode(body, rewrite) {
     let out = '';

package/dist/properties.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The frontmatter of a note, read for drawing (§6).
+ *
+ * The frontmatter is content: what the author wrote about the note. The
+ * renderer reads it the way the specification reads it and hands it to the
+ * theme, which decides how — and whether — it is drawn. The default theme
+ * draws `name` as the note's title and every other entry as a property, by
+ * the shape of its value.
+ *
+ * It reads the subset of YAML §6.2 names — scalars, inline lists and dash
+ * lists, with one layer of matching quotes stripped — and nothing else; a line
+ * it does not read is left out, never guessed at. A value written as a
+ * wikilink, `"[[Note]]"`, is kept as written: the theme draws it as a link,
+ * resolved by the host as a link of the body is. That is a decision of the
+ * reading surface; it adds no edge, and what an Indexer reads is unchanged.
+ */
+/** The shape of a value, which decides how it is drawn (§6.3). */
+export type PropertyShape = 'list' | 'date' | 'boolean' | 'text' | 'prose' | 'empty';
+/** One entry of the frontmatter, other than `name`. */
+export interface PropertyEntry {
+    /** The key as the author wrote it, in their language. */
+    readonly key: string;
+    readonly shape: PropertyShape;
+    /**
+     * The value as written, one layer of quotes stripped: one item, or each item of a list. A
+     * theme reads a boolean or a date from it, and shows what was typed where it shows the bytes.
+     */
+    readonly values: readonly string[];
+}
+/** The frontmatter, read. */
+export interface NoteProperties {
+    /** The name of the note: `name:` when it is a single text value (§6.5), else `null`. */
+    readonly name: string | null;
+    /** Every other entry, in the order written. */
+    readonly entries: readonly PropertyEntry[];
+}
+/**
+ * The frontmatter of a note, or no name and no entries when it has none. The block begins on the
+ * first line with `---` and ends at the next line that is `---` (§6.1).
+ */
+export declare function readProperties(markdown: string): NoteProperties;
+/**
+ * What a value may carry that is a link: a wikilink, a Markdown link to the web, or a bare web
+ * address — as MemorySmith's properties read it, and nothing else of Markdown.
+ */
+export declare const VALUE_LINK: RegExp;
+/** Whether a boolean value reads true: `true` or `yes`, in any case. */
+export declare function isTrue(value: string): boolean;
+/** The reserved keys a theme draws as properties (§6.4): `name` is the title, not a property. */
+export declare const DRAWN_RESERVED_KEYS: readonly string[];