forgebook 0.1.8 → 0.3.0

package/dist/src/vite/docPageLinks.js

@@ -0,0 +1,135 @@
+/**
+ * A docs page's links and images: a link to another page written to its file (`./colours.md#brand`), so it also works
+ * in the repository, and an image of the page's own package, both checked and written for the shell to fill.
+ *
+ * @module
+ */
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { ASSET_SCHEME, PAGE_LINK_SCHEME } from "../docPages.js";
+import { pageSlug } from "../pageAddress.js";
+import { frontMatterOf, titleOf } from "./docMarkdown.js";
+/**
+ * A linked page's text from the disk.
+ *
+ * @param file - the file.
+ */
+export const readLinkedFile = (file) => {
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Whether an address is outside the page's folder: it has a scheme, or starts at the root or the page's own address.
+ *
+ * @param href - the address.
+ */
+export const isOutside = (href) => /^([a-z][a-z0-9+.-]*:|\/|#|\?)/i.test(href);
+/** A path as a link writes it, its escapes read: a `%` that escapes nothing is a file's own character. */
+const decodedPath = (path) => {
+    try {
+        return decodeURI(path);
+    }
+    catch {
+        return path;
+    }
+};
+/**
+ * The file an address relative to a page names, and its fragment.
+ *
+ * @param file - the page's file.
+ * @param href - the address.
+ */
+export const relativeTarget = (file, href) => {
+    const [path = "", fragment] = href.split("#");
+    return { file: resolve(dirname(file), decodedPath(path)), fragment };
+};
+/**
+ * The folder of the package a file belongs to: the nearest with a `package.json`, or the file's own without one.
+ *
+ * @param file - the file.
+ */
+export const packageFolderOf = (file) => {
+    let folder = dirname(file);
+    while (!existsSync(join(folder, "package.json"))) {
+        const parent = dirname(folder);
+        if (parent === folder)
+            return dirname(file);
+        folder = parent;
+    }
+    return folder;
+};
+/**
+ * Whether a page may show a file as an image: a file of its own package. A build copies an image into the catalogue
+ * whatever it is, so a path that climbs out of the package would publish a file a reviewer took for a picture's name.
+ *
+ * @param file - the page's file.
+ * @param image - the image's file.
+ */
+export const isOwnImage = (file, image) => {
+    const fromPackage = relative(packageFolderOf(file), image);
+    return !fromPackage.startsWith("..") && existsSync(image) && statSync(image).isFile();
+};
+/**
+ * Whether a link names another page by its file.
+ *
+ * @param href - the link's address.
+ */
+export const isPageLink = (href) => !isOutside(href) && /\.md(#|$)/i.test(href);
+/**
+ * The slug of the page a link names; none when its file is not there.
+ *
+ * @param file - the linking page's file.
+ * @param href - the link's address.
+ * @param read - reads a linked page's text.
+ */
+export const linkedSlug = (file, href, read) => {
+    const target = relativeTarget(file, href);
+    const text = read(target.file);
+    return text === undefined ? undefined : pageSlug(titleOf(target.file, frontMatterOf(text)));
+};
+/**
+ * The address the shell fills for a link to another page, by its slug; none when the file is not there.
+ *
+ * @param file - the linking page's file.
+ * @param href - the link's address.
+ * @param read - reads a linked page's text.
+ */
+export const pageAddress = (file, href, read) => {
+    const slug = linkedSlug(file, href, read);
+    if (slug === undefined)
+        return undefined;
+    const { fragment } = relativeTarget(file, href);
+    return `${PAGE_LINK_SCHEME}${slug}${fragment === undefined ? "" : `#${fragment}`}`;
+};
+/**
+ * The address an image's file is written as, by its place in the page's images.
+ *
+ * @param place - its place.
+ */
+export const assetAddress = (place) => `${ASSET_SCHEME}${place}`;
+/**
+ * The version of the package a file belongs to, from its `package.json`; none without one.
+ *
+ * @param file - the file.
+ */
+export const packageVersionOf = (file) => {
+    const text = readLinkedFile(join(packageFolderOf(file), "package.json"));
+    if (text === undefined)
+        return undefined;
+    try {
+        const manifest = JSON.parse(text);
+        return typeof manifest === "object" &&
+            manifest !== null &&
+            "version" in manifest &&
+            typeof manifest.version === "string"
+            ? manifest.version
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};

package/dist/src/vite/docPageMarkdown.d.ts

@@ -0,0 +1,86 @@
+/**
+ * A docs page, or the catalogue's written home, read from its Markdown: what the index lists without rendering it,
+ * and, when it opens, its blocks.
+ *
+ * @remarks
+ * Markdown with directives instead of MDX: a page is read here at build time, with no compiler in the page. Its body
+ * is split into blocks by line (`docDirectives.ts`), each given its meaning and checked (`docPageBlocks.ts`), and turned
+ * into HTML (`docPageRender.ts`). A page's files are the package's, read at build time, and Markdown lets them hold raw
+ * HTML, so a page is trusted as a story's code is: whoever can write one can run script in the catalogue.
+ *
+ * Reading the index never renders, so a catalogue with many pages pays for highlighting only on the pages opened.
+ *
+ * @module
+ */
+import type { DocPageIndex } from "@forgebook/story-format/source";
+import type { DocPage } from "../docPages.ts";
+import { type ReadPage } from "./docPageLinks.ts";
+/**
+ * What the index lists of a page, read from its text without rendering it.
+ *
+ * @param file - the page's file, absolute.
+ * @param text - its text.
+ * @param read - reads a linked page's text; from the disk by default.
+ * @param fences - the fences the catalogue's plugins draw; none by default.
+ */
+export declare const docPageIndex: (file: string, text: string, read?: ReadPage, fences?: readonly string[]) => DocPageIndex;
+/** A docs page as its module gives it: what the shell draws, with its images as files, and its Markdown. */
+export type CompiledDocPage = Omit<DocPage, "assets"> & {
+    /** The image files, absolute: the module imports each, and its address takes the file's place. */
+    readonly images: readonly string[];
+    /** The page's Markdown, without its front matter, for tools. */
+    readonly text: string;
+};
+/**
+ * A page, rendered: its blocks, its headings and its images.
+ *
+ * @param file - the page's file, absolute.
+ * @param text - its text.
+ * @param read - reads a linked page's text; from the disk by default.
+ * @param fences - the fences the catalogue's plugins draw; none by default.
+ */
+export declare const compiledDocPage: (file: string, text: string, read?: ReadPage, fences?: readonly string[]) => CompiledDocPage;
+/** What the catalogue's written home lists without rendering it. */
+export type HomeIndex = {
+    /** Its title: its front matter's or its opening heading's; none to show the catalogue's. */
+    readonly title: string | undefined;
+    /** Its lead, the front matter's `description`; none when it has none. */
+    readonly description: string | undefined;
+    /** The stories it shows. */
+    readonly stories: readonly string[];
+    /** The components whose tables it shows. */
+    readonly components: readonly string[];
+    /** The sources its pieces name, to check against the catalogue's. */
+    readonly sources: readonly string[];
+    /** What it gets wrong, each with its line and column. */
+    readonly notes: readonly string[];
+};
+/**
+ * What the catalogue's written home lists, read without rendering it.
+ *
+ * @param file - the home's file, absolute.
+ * @param text - its text.
+ * @param read - reads a linked page's text; from the disk by default.
+ * @param fences - the fences the catalogue's plugins draw; none by default.
+ */
+export declare const homeIndex: (file: string, text: string, read?: ReadPage, fences?: readonly string[]) => HomeIndex;
+/** The written home as its module gives it. */
+export type CompiledHome = Omit<CompiledDocPage, "headings"> & {
+    /** Its title; none for the catalogue's. */
+    readonly title: string | undefined;
+    /** Its lead; none when it has none. */
+    readonly description: string | undefined;
+    /** The stories it shows, for their frames. */
+    readonly stories: readonly string[];
+    /** What it gets wrong, each with its line and column. */
+    readonly notes: readonly string[];
+};
+/**
+ * The catalogue's written home, rendered.
+ *
+ * @param file - the home's file, absolute.
+ * @param text - its text.
+ * @param read - reads a linked page's text; from the disk by default.
+ * @param fences - the fences the catalogue's plugins draw; none by default.
+ */
+export declare const compiledHome: (file: string, text: string, read?: ReadPage, fences?: readonly string[]) => CompiledHome;

package/dist/src/vite/docPageMarkdown.js

@@ -0,0 +1,133 @@
+import { bodySegments, noteText, sourceLines } from "./docDirectives.js";
+import { frontMatterOf, LEXER, openingHeading, titleOf } from "./docMarkdown.js";
+import { pageNodes } from "./docPageBlocks.js";
+import { packageVersionOf, readLinkedFile } from "./docPageLinks.js";
+import { renderedPage } from "./docPageRender.js";
+/** Notes in the order of the file, those about the whole page first. */
+const inFileOrder = (notes) => [...notes].sort((left, right) => (left.position?.line ?? 0) - (right.position?.line ?? 0) ||
+    (left.position?.column ?? 0) - (right.position?.column ?? 0));
+/** The nodes without the page's opening `#` title, which the page's header shows. */
+const withoutTitle = (nodes) => {
+    const first = nodes[0];
+    if (first?.type !== "tokens" || openingHeading(first.tokens) === undefined)
+        return nodes;
+    const heading = first.tokens.find((token) => token.type !== "space");
+    return [{ type: "tokens", tokens: first.tokens.filter((token) => token !== heading) }, ...nodes.slice(1)];
+};
+/**
+ * A page read, every block checked.
+ *
+ * @param file - the page's file, absolute.
+ * @param text - its text.
+ * @param read - reads a linked page's text.
+ * @param isHome - whether it is the catalogue's written home.
+ * @param pluginFences - the fences the catalogue's plugins draw.
+ */
+const readDocPage = (file, text, read, isHome, pluginFences) => {
+    const frontMatter = frontMatterOf(text);
+    let version;
+    const reading = {
+        file,
+        read,
+        isHome,
+        pluginFences,
+        version: () => {
+            version ??= { value: packageVersionOf(file) };
+            return version.value;
+        },
+        notes: frontMatter.notes.map((note) => ({
+            position: { line: note.line, column: 1 },
+            message: note.message
+        })),
+        fences: new Map(),
+        stories: [],
+        components: [],
+        links: [],
+        sources: [],
+        images: []
+    };
+    const segments = bodySegments(sourceLines(frontMatter.body, frontMatter.bodyLine), reading.notes);
+    const nodes = withoutTitle(pageNodes(segments, reading));
+    return { frontMatter, nodes, reading };
+};
+/** A page's notes as the index lists them, in the order of the file. */
+const notesOf = (reading) => inFileOrder(reading.notes).map(noteText);
+/**
+ * What the index lists of a page, read from its text without rendering it.
+ *
+ * @param file - the page's file, absolute.
+ * @param text - its text.
+ * @param read - reads a linked page's text; from the disk by default.
+ * @param fences - the fences the catalogue's plugins draw; none by default.
+ */
+export const docPageIndex = (file, text, read = readLinkedFile, fences = []) => {
+    const { frontMatter, reading } = readDocPage(file, text, read, false, fences);
+    const { order, description } = frontMatter;
+    const notes = notesOf(reading);
+    return {
+        title: titleOf(file, frontMatter),
+        ...(order === undefined ? {} : { order }),
+        ...(description === undefined ? {} : { description }),
+        stories: reading.stories,
+        components: reading.components,
+        links: reading.links,
+        ...(notes.length === 0 ? {} : { notes })
+    };
+};
+/**
+ * A page, rendered: its blocks, its headings and its images.
+ *
+ * @param file - the page's file, absolute.
+ * @param text - its text.
+ * @param read - reads a linked page's text; from the disk by default.
+ * @param fences - the fences the catalogue's plugins draw; none by default.
+ */
+export const compiledDocPage = (file, text, read = readLinkedFile, fences = []) => {
+    const { frontMatter, nodes, reading } = readDocPage(file, text, read, false, fences);
+    const { blocks, headings } = renderedPage(nodes, reading.fences);
+    return { blocks, headings, images: reading.images, text: frontMatter.body.trim() };
+};
+/** A front matter's text with `{{version}}` written in: the shell fills the other values, as in the text. */
+const withVersion = (text, reading) => text?.replace(/\{\{\s*version\s*\}\}/g, () => reading.version() ?? "");
+/** The home's title: its front matter's, else its opening heading; none for the catalogue's own. */
+const homeTitle = (frontMatter, reading) => withVersion(frontMatter.title ?? openingHeading(LEXER.lexer(frontMatter.body)), reading);
+/**
+ * What the catalogue's written home lists, read without rendering it.
+ *
+ * @param file - the home's file, absolute.
+ * @param text - its text.
+ * @param read - reads a linked page's text; from the disk by default.
+ * @param fences - the fences the catalogue's plugins draw; none by default.
+ */
+export const homeIndex = (file, text, read = readLinkedFile, fences = []) => {
+    const { frontMatter, reading } = readDocPage(file, text, read, true, fences);
+    return {
+        title: homeTitle(frontMatter, reading),
+        description: withVersion(frontMatter.description, reading),
+        stories: reading.stories,
+        components: reading.components,
+        sources: reading.sources,
+        notes: notesOf(reading)
+    };
+};
+/**
+ * The catalogue's written home, rendered.
+ *
+ * @param file - the home's file, absolute.
+ * @param text - its text.
+ * @param read - reads a linked page's text; from the disk by default.
+ * @param fences - the fences the catalogue's plugins draw; none by default.
+ */
+export const compiledHome = (file, text, read = readLinkedFile, fences = []) => {
+    const { frontMatter, nodes, reading } = readDocPage(file, text, read, true, fences);
+    const { blocks } = renderedPage(nodes, reading.fences);
+    return {
+        title: homeTitle(frontMatter, reading),
+        description: withVersion(frontMatter.description, reading),
+        blocks,
+        images: reading.images,
+        stories: reading.stories,
+        notes: notesOf(reading),
+        text: frontMatter.body.trim()
+    };
+};

package/dist/src/vite/docPageRender.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A docs page's nodes as the blocks the shell draws: text as HTML, code coloured with its lines marked, and each
+ * container with its own blocks inside.
+ *
+ * @remarks
+ * One renderer per page, made here, collects the page's headings in the order of the file, through every container,
+ * so the contents list and the anchors agree with what is drawn. A heading links to itself rather than holding a
+ * separate "link to this section" control: the heading's own words name the link for a screen reader, so the HTML, made
+ * at build time, holds no text of the shell's. Anchors are made as GitHub makes them (`tokens`, `tokens-1`), so a link
+ * written for a repository's reader keeps working here.
+ *
+ * @module
+ */
+import { type Token } from "marked";
+import { type DocBlock, type DocHeading } from "../docPages.ts";
+import type { PageNode } from "./docPageBlocks.ts";
+import { type FenceRead } from "./docPageTokens.ts";
+/**
+ * A page's nodes as the blocks the shell draws, and its headings.
+ *
+ * @param nodes - the page's nodes.
+ * @param fences - what each of its fences is.
+ */
+export declare const renderedPage: (nodes: readonly PageNode[], fences: ReadonlyMap<Token, FenceRead>) => {
+    readonly blocks: DocBlock[];
+    readonly headings: DocHeading[];
+};

package/dist/src/vite/docPageRender.js

@@ -0,0 +1,199 @@
+/**
+ * A docs page's nodes as the blocks the shell draws: text as HTML, code coloured with its lines marked, and each
+ * container with its own blocks inside.
+ *
+ * @remarks
+ * One renderer per page, made here, collects the page's headings in the order of the file, through every container,
+ * so the contents list and the anchors agree with what is drawn. A heading links to itself rather than holding a
+ * separate "link to this section" control: the heading's own words name the link for a screen reader, so the HTML, made
+ * at build time, holds no text of the shell's. Anchors are made as GitHub makes them (`tokens`, `tokens-1`), so a link
+ * written for a repository's reader keeps working here.
+ *
+ * @module
+ */
+import { Marked } from "marked";
+import { PAGE_LINK_SCHEME } from "../docPages.js";
+import { fencedCode } from "./codeFence.js";
+import { codeHtml, headingAnchors } from "./componentPage.js";
+import { isValueToken, VALUES_EXTENSION } from "./docMarkdown.js";
+import { isCode } from "./docPageTokens.js";
+import { escapeHtml } from "./highlightCode.js";
+/**
+ * What inline tokens say, without marks or raw HTML; a value as written, for the shell to fill.
+ *
+ * @param tokens - the tokens.
+ */
+const plainText = (tokens) => tokens
+    .map((token) => {
+    if (token.type === "html")
+        return "";
+    if (isValueToken(token))
+        return token.name === "version" ? token.text : token.raw;
+    const nested = "tokens" in token ? token.tokens : undefined;
+    if (Array.isArray(nested) && nested.length > 0)
+        return plainText(nested);
+    return "text" in token && typeof token.text === "string" ? token.text : "";
+})
+    .join("");
+/**
+ * The addresses a page's link may hold: another site, mail, another page of the catalogue as the reader wrote it
+ * (`PAGE_LINK_SCHEME`), or an address with no scheme of its own (an anchor, a file); never one whose scheme runs code.
+ */
+const SAFE_LINK = new RegExp(`^(https?:|mailto:|${PAGE_LINK_SCHEME}|[^:]*$|[^:]*[/?#])`, "i");
+/**
+ * The Markdown renderer of one page: it keeps the page's headings, so it is made for each page.
+ *
+ * @param headings - receives the page's second- and third-level headings.
+ */
+const pageRenderer = (headings) => {
+    const anchorOf = headingAnchors();
+    return new Marked(VALUES_EXTENSION, {
+        async: false,
+        gfm: true,
+        renderer: {
+            code: codeHtml,
+            heading({ tokens, depth }) {
+                const text = plainText(tokens);
+                const anchor = anchorOf(text);
+                if (depth === 2 || depth === 3)
+                    headings.push({ depth, anchor, text });
+                // a link cannot hold a link, so a heading with one in it keeps its words and loses their marks
+                const hasLink = tokens.some((token) => token.type === "link");
+                const words = hasLink ? escapeHtml(text) : this.parser.parseInline(tokens);
+                return `<h${depth} id="doc-${escapeHtml(anchor)}"><a class="forgebook-anchor" href="#${escapeHtml(anchor)}">${words}</a></h${depth}>\n`;
+            },
+            link({ href, title, tokens }) {
+                // a link that would run code (`javascript:`, `data:`) keeps its words and loses its address
+                if (!SAFE_LINK.test(href))
+                    return this.parser.parseInline(tokens);
+                const titled = title === null || title === undefined ? "" : ` title="${escapeHtml(title)}"`;
+                // a page of the catalogue opens in place; another site must not replace the catalogue being read
+                const opens = /^https?:/i.test(href) ? ' target="_blank" rel="noreferrer"' : "";
+                return `<a href="${escapeHtml(href)}"${titled}${opens}>${this.parser.parseInline(tokens)}</a>`;
+            }
+        }
+    });
+};
+/** A code block as the page draws it. */
+const codeBlock = (token, fence) => {
+    const code = token.text;
+    if (fence === undefined)
+        return { kind: "code", text: code, html: escapeHtml(code) };
+    if (fence.kind === "plugin")
+        return { kind: "plugin", fence: fence.fence, argument: fence.argument, body: code };
+    if (fence.kind !== "code")
+        return { kind: fence.kind, id: fence.id };
+    const drawn = fencedCode(code, fence.info);
+    return {
+        kind: "code",
+        text: drawn.text,
+        html: drawn.html,
+        ...(drawn.language === undefined ? {} : { language: drawn.language }),
+        ...(drawn.title === undefined ? {} : { title: drawn.title }),
+        ...(drawn.isWrapped ? { isWrapped: true } : {})
+    };
+};
+/**
+ * Tokens in a page's own flow as blocks: each fence on its own, the text between them as HTML.
+ *
+ * @param tokens - the tokens.
+ * @param renderer - the page's renderer.
+ * @param fences - what each fence is.
+ */
+const tokenBlocks = (tokens, renderer, fences) => {
+    const blocks = [];
+    let text = [];
+    const flushText = () => {
+        if (text.length === 0)
+            return;
+        blocks.push({ kind: "text", html: renderer.parser(text) });
+        text = [];
+    };
+    for (const token of tokens) {
+        if (token.type === "space")
+            continue;
+        if (!isCode(token)) {
+            text.push(token);
+            continue;
+        }
+        flushText();
+        blocks.push(codeBlock(token, fences.get(token)));
+    }
+    flushText();
+    return blocks;
+};
+/**
+ * A container's node as its block, what it holds drawn by `inner`.
+ *
+ * @param node - the node.
+ * @param inner - draws what it holds.
+ */
+const containerBlock = (node, inner) => {
+    switch (node.type) {
+        case "aside":
+            return {
+                kind: "aside",
+                tone: node.tone,
+                ...(node.title === undefined ? {} : { title: node.title }),
+                children: inner(node.children)
+            };
+        case "tabs":
+            return {
+                kind: "tabs",
+                ...(node.sync === undefined ? {} : { sync: node.sync }),
+                tabs: node.tabs.map((tab) => ({ label: tab.label, children: inner(tab.children) }))
+            };
+        case "cards":
+            return { kind: "cards", children: inner(node.children) };
+        default:
+            return { kind: "card", title: node.title, children: inner(node.children) };
+    }
+};
+/**
+ * A page's nodes as blocks.
+ *
+ * @param nodes - the nodes.
+ * @param renderer - the page's renderer.
+ * @param fences - what each fence is.
+ */
+const nodeBlocks = (nodes, renderer, fences) => nodes.flatMap((node) => {
+    switch (node.type) {
+        case "tokens":
+            return tokenBlocks(node.tokens, renderer, fences);
+        case "steps":
+            return [{ kind: "steps", steps: node.steps.map((step) => tokenBlocks(step, renderer, fences)) }];
+        case "link-card":
+            return [
+                {
+                    kind: "link-card",
+                    title: node.title,
+                    href: node.href,
+                    ...(node.description === undefined ? {} : { description: node.description })
+                }
+            ];
+        case "home":
+            return [
+                {
+                    kind: "home",
+                    piece: node.piece,
+                    ...(node.label === undefined ? {} : { label: node.label }),
+                    ...(node.source === undefined ? {} : { source: node.source })
+                }
+            ];
+        case "problem":
+            return [{ kind: "problem", message: node.message }];
+        default:
+            return [containerBlock(node, (children) => nodeBlocks(children, renderer, fences))];
+    }
+});
+/**
+ * A page's nodes as the blocks the shell draws, and its headings.
+ *
+ * @param nodes - the page's nodes.
+ * @param fences - what each of its fences is.
+ */
+export const renderedPage = (nodes, fences) => {
+    const headings = [];
+    const blocks = nodeBlocks(nodes, pageRenderer(headings), fences);
+    return { blocks, headings };
+};

package/dist/src/vite/docPageTokens.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The tokens of a docs page read: each top-level fence given its kind, every link and image checked and addressed,
+ * every value checked, each mistake noted where it is in the file.
+ *
+ * @remarks
+ * Markdown tokens carry no position, so a token's place is found from its text inside the text it was read from: its
+ * whole text, or its first line where a list item's lines lost their indent. Used by `docPageBlocks.ts` for every run of
+ * Markdown, a step's included.
+ *
+ * @module
+ */
+import type { Token, Tokens } from "marked";
+import { type FenceInfo } from "./codeFence.ts";
+import type { PageNote, SourceLine, SourcePosition } from "./docDirectives.ts";
+import { type ReadPage } from "./docPageLinks.ts";
+/** What a top-level code fence is. */
+export type FenceRead = {
+    readonly kind: "story" | "props";
+    readonly id: string;
+} | {
+    readonly kind: "plugin";
+    readonly fence: string;
+    readonly argument: string;
+} | {
+    readonly kind: "code";
+    readonly info: FenceInfo;
+};
+/** What reading a page gathers as it goes. */
+export type PageReading = {
+    /** The page's file, absolute. */
+    readonly file: string;
+    /** Reads a linked page's text. */
+    readonly read: ReadPage;
+    /** Whether the page is the catalogue's written home, where the home's pieces may be placed. */
+    readonly isHome: boolean;
+    /** The fences the catalogue's plugins draw: such a fence is the plugin's block, not code. */
+    readonly pluginFences: readonly string[];
+    /** The version `{{version}}` shows: the page's package's; none without one. */
+    readonly version: () => string | undefined;
+    /** What it gets wrong. */
+    readonly notes: PageNote[];
+    /** What each top-level fence is. */
+    readonly fences: Map<Token, FenceRead>;
+    /** The stories it shows, in its order. */
+    readonly stories: string[];
+    /** The components whose tables it shows. */
+    readonly components: string[];
+    /** The slugs of the pages it links to. */
+    readonly links: string[];
+    /** The sources its home pieces name. */
+    readonly sources: string[];
+    /** Its images' files, in the order their addresses name them. */
+    readonly images: string[];
+};
+/**
+ * Where each character of a text made of lines sits in the file.
+ *
+ * @param lines - the lines the text joins.
+ */
+export declare const positionsOf: (lines: readonly SourceLine[]) => ((offset: number) => SourcePosition);
+/**
+ * Whether a token is a code block.
+ *
+ * @param token - the token.
+ */
+export declare const isCode: (token: Token) => token is Tokens.Code;
+/**
+ * Whether a token is an ordered list.
+ *
+ * @param token - the token.
+ */
+export declare const isOrderedList: (token: Token | undefined) => token is Tokens.List;
+/**
+ * Reads tokens that sit in a page's own flow: each fence a block, every link, image and value checked inside them.
+ *
+ * @param tokens - the tokens.
+ * @param container - the text they were read from.
+ * @param base - where that text starts in the text the positions are counted in.
+ * @param at - the position of a character of that text.
+ * @param reading - the reading.
+ */
+export declare const readTokens: (tokens: readonly Token[], container: string, base: number, at: (offset: number) => SourcePosition, reading: PageReading) => void;
+/**
+ * A run of Markdown lines' text and its tokens.
+ *
+ * @param lines - the lines.
+ */
+export declare const lexed: (lines: readonly SourceLine[]) => {
+    readonly text: string;
+    readonly tokens: Token[];
+};