@heroiclands/package-build 22.12.0 → 22.12.2

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @heroiclands/package-build
 
+## 22.12.2
+
+### Patch Changes
+
+**Content**
+
+- GM passages in notes appear as secret sections in Foundry journals, expandable spoilers on the web, and labelled notes in books.
+
+## 22.12.1
+
+### Patch Changes
+
+**Content authoring**
+
+- Image embeds and Markdown images accept named size hints, so notes can carry the intended size while their displayed appearance stays the same.
+
 ## 22.12.0
 
 ### Minor Changes

package/bin/content-build.mjs

@@ -1627,6 +1627,9 @@ function siteCommand() {
                         message: e.reason,
                     });
                 }
+                for (const e of result.secretErrors) {
+                    emitDiagnostic({ ...e, severity: "error" });
+                }
                 // Reported the way the pack build reports the very same
                 // finding: `file:line:column: error: message`, path first, and
                 // the message from the shared table, not a
@@ -1663,6 +1666,7 @@ function siteCommand() {
                 }
                 if (
                     result.tableErrors.length ||
+                    result.secretErrors.length ||
                     result.wikiErrors.length ||
                     result.imageErrors.length
                 ) {

package/docs/api.md

@@ -935,16 +935,17 @@ Raw HTML in a note's prose, reported. **A note is markdown.** What markdown cann
 
 ### `engine.contentImages`
 
-An image saying how wide it is and where it sits. A markdown image carries no indication of either, so each of the three surfaces decides for itself and the author — who is the one who knows — has no way to say. A directive in the curly-attribute convention Pandoc and Kramdown use closes that, in two closed vocabularies: a width class, and a `float:` position.
+An image saying how wide it is and where it sits. A markdown image carries no indication of either, so each of the three surfaces decides for itself and the author — who is the one who knows — has no way to say. A directive in the curly-attribute convention Pandoc and Kramdown use closes that, in three closed vocabularies: a width class, a named `size:`, and a `float:` position. The named size is accepted without affecting display.
 
 | Export                | Signature                                       | Returns                                                                                                                                        | Use it when                                                                  |
 | --------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
 | `IMAGE_CLASSES`       | `const IMAGE_CLASSES`                           | —                                                                                                                                              | The width classes an image may carry, and what each means to a renderer.     |
+| `IMAGE_SIZES`         | `const IMAGE_SIZES`                             | —                                                                                                                                              | The named sizes an image directive accepts without applying a display size.  |
 | `IMAGE_FLOATS`        | `const IMAGE_FLOATS`                            | —                                                                                                                                              | The `float:` positions an image may take, and where each puts it.            |
 | `IMAGE_FIGURE_CLASS`  | `const IMAGE_FIGURE_CLASS`                      | —                                                                                                                                              | The class every figure carries, whatever its width or position.              |
 | `IMAGE_PATTERN`       | `const IMAGE_PATTERN`                           | —                                                                                                                                              | A markdown image, with the directive it may carry.                           |
 | `imageSourceProblem`  | `function imageSourceProblem(src)`              | {string} The problem, as a finding's sentence, or `""`.                                                                                        | What is wrong with an image's address, or `""` when nothing is.              |
-| `parseImageDirective` | `function parseImageDirective(raw)`             | {{classes: string[], float: string, problems: string[]}} What was written, and what cannot be honoured.                                        | Read the directive on an image.                                              |
+| `parseImageDirective` | `function parseImageDirective(raw)`             | {{classes: string[], size: string, float: string, problems: string[]}} What was written, and what cannot be honoured.                          | Read the directive on an image.                                              |
 | `figureClasses`       | `function figureClasses(directive)`             | {string} A space-separated class list.                                                                                                         | The classes a figure carries, from a parsed directive.                       |
 | `escapeHtml`          | `function escapeHtml(text)`                     | {string} The same value, safe in markup.                                                                                                       | Text going inside an HTML attribute or between tags.                         |
 | `imageFigureHtml`     | `function imageFigureHtml(image)`               | {string} The figure, as one HTML block.                                                                                                        | One image as the `<figure>` both HTML surfaces render.                       |
@@ -1011,6 +1012,7 @@ Shared helpers for the pack compilers in `packages/content-build/`. The HeroicLa
 | Export                    | Signature                                                                                                   | Returns                                                                                                                                                                                                                                 | Use it when                                                                                                                                                                                          |
 | ------------------------- | ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `md`                      | `const md`                                                                                                  | —                                                                                                                                                                                                                                       | The markdown renderer every surface shares.                                                                                                                                                          |
+| `renderFoundryMarkdown`   | `function renderFoundryMarkdown(body)`                                                                      | `string` — HTML with secret sections for GM passages.                                                                                                                                                                                   | Rendering a note body for a Foundry document.                                                                                                                                                        |
 | `parseMarkdownFile`       | `function parseMarkdownFile(filePath)`                                                                      | —                                                                                                                                                                                                                                       | Parses a markdown file with YAML frontmatter.                                                                                                                                                        |
 | `assertStatedScope`       | `function assertStatedScope(skipDirectories, who)`                                                          | {void}                                                                                                                                                                                                                                  | Refuse a corpus read whose scope its caller did not state.                                                                                                                                           |
 | `assertSuppliedCorpus`    | `function assertSuppliedCorpus(records, who)`                                                               | {void}                                                                                                                                                                                                                                  | Refuse a corpus read whose records its caller did not supply.                                                                                                                                        |

package/docs/content-format.md

@@ -1860,15 +1860,16 @@ immediately after the closing `]]`, with no space:
 
 ```markdown
 ![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
+![[branwldrgr|Brànwâal Dôrgaar]]{size: medium, float: top-left}
 ![[thalornamap|Map of Thalorna]]{.full-width}
 ![[thalornamap|Map of Thalorna]]{.full-width, float: top-left}
 ![[thalornamap|Map of Thalorna]]{float: top-left, .full-width}
 ```
 
-**The same parser reads both**, so an embed takes a width class, a `float:`, or
-both together in either order, comma-separated — everything
+**The same parser reads both**, so an embed takes a width class, a `size:`, a
+`float:`, or a combination in any order, comma-separated — everything
 [an image's directive](#width-is-a-class-and-the-ordinary-width-carries-no-marker)
-takes and nothing beyond it. The width and position vocabularies are the ones
+takes and nothing beyond it. The width, size, and position vocabularies are the ones
 above, and they are closed here for the same reason: a directive that is quietly
 ignored looks exactly like one that worked, and a directive holding a problem is
 not honoured in part either.
@@ -2123,6 +2124,7 @@ part of this format follows.
 
 ```markdown
 ![[branwldrgr|Brànwâal Dôrgaar]]{float: top-left}
+![[branwldrgr|Brànwâal Dôrgaar]]{size: medium, float: top-left}
 
 ![Map of Thalorna](images/maps/thalorna.webp){.full-width}
 ```
@@ -2146,13 +2148,30 @@ place for those words and this is it.
 | `.full-width` | the full page | full content width | full page width  |
 
 The simple case needs no spelling, which is why the ordinary width has no name.
-A third width joins this table as a name.
 
 **No pixel values, ever.** A number means something in a browser and nothing
 coherent in print, and a directive carrying a class and a dimension at once
 gives one question two answers with no rule for which wins. `{width=800}` is
 refused.
 
+##### Named size is `size:`
+
+| `size` value | display                  |
+| ------------ | ------------------------ |
+| `auto`       | same as omitting `size:` |
+| `small`      | same as omitting `size:` |
+| `medium`     | same as omitting `size:` |
+| `large`      | same as omitting `size:` |
+| `xlarge`     | same as omitting `size:` |
+| `full-width` | same as omitting `size:` |
+
+The parser accepts and records these names for Markdown images and embedded
+assets. **A `size:` value does not change the displayed dimensions** on the
+website, in Foundry, or in the book. With no `size:`, the parser records `auto`;
+the existing rendering rules apply. In particular, book images occupy a column
+unless they carry `.full-width`. A `size:` may sit before or after `float:` in
+the same directive, and neither changes the other's behavior.
+
 ##### Position is `float:`
 
 | `float` value  | book                 | website and Foundry journal     |
@@ -2182,7 +2201,7 @@ A `.full-width` image that **also states a `float:`** is asking for a float and
 gets one, with no break before it. A float is placed where it fits, which may be
 the next page.
 
-##### Both vocabularies are closed
+##### All three vocabularies are closed
 
 `{.fullwidth}`, `{.full_width}`, `{width=800}` and `{float: middle}` are
 refused, located by file, line and column, and the build fails. An unrecognised
@@ -2194,8 +2213,8 @@ even in the part that parsed: a half-honoured directive is the same silent
 failure in a smaller costume. The image keeps its braces and renders them as
 literal text, so the mistake is visible on the page as well as in the log.
 
-**Nothing else reaches emitted markup.** The two vocabularies and the address
-are all that leave a note; there is no `style`, no `id` and no arbitrary
+**Nothing else reaches emitted markup.** The width and position classes and the
+address are all that leave a note; there is no `style`, no `id` and no arbitrary
 attribute, because data is never compiled into markup here. An address carries
 a scheme of `http:` or `https:`, or none at all.
 
@@ -2399,15 +2418,17 @@ This is secret text
 :::
 ```
 
-A fenced off area of text may be marked as secret, indicating that the text will be treated as secret text. In FoundryVTT, this will be achieved with
+Use a whole-line `:::secret` opener and a whole-line `:::` closer to mark a GM passage. Markdown inside the block, including links and emphasis, renders normally. Keep the fences outside code blocks and close each one before starting another. An unclosed or nested block is a build error at the source line.
+
+In FoundryVTT, the passage is a secret section visible to the GM and owners of the journal:
 
 ```html
-<section class="secret">
+<section class="secret" id="secret-example">
   <p>This is secret text</p>
 </section>
 ```
 
-On webpages, this will be achieved with the use of
+On webpages, the passage appears as a collapsed spoiler that any reader can open:
 
 ```html
 <details>
@@ -2416,6 +2437,8 @@ On webpages, this will be achieved with the use of
 </details>
 ```
 
+In books, the passage is visible under a **GM note** label. A printed page has no reader permissions or interactive disclosure control.
+
 #### Actors
 
 All actor types, including being and vehicle, have their entire markdown section processed as normal.

package/docs/getting-started.md

@@ -332,6 +332,18 @@ an error. A `data:` block and a `sohl:` / `hm3:` block are closed: a misspelled
 key there is a finding that names the key you meant.
 [`content-format.md`](content-format.md) is the specification.
 
+An image stands in its own paragraph. Its directive accepts a named size and a
+position together:
+
+```markdown
+![[icon-anubis|Anubis]]{size: medium, float: top-left}
+```
+
+The accepted sizes are `auto`, `small`, `medium`, `large`, `xlarge`, and
+`full-width`. Omitting `size:` means `auto`. The build checks the name, but
+`size:` does not change the displayed dimensions on the website, in Foundry, or
+in the book. See [Images](content-format.md#images) for the rendering rules.
+
 ## Step 6 — check the tree
 
 Four checks, and they are quick enough to run continuously while authoring.

package/engine/anchored-sections.mjs

@@ -29,7 +29,7 @@
  * @module
  */
 
-import { md } from "./helpers.mjs";
+import { renderFoundryMarkdown } from "./helpers.mjs";
 
 /**
  * Extract the body of an H1 section whose heading carries the explicit
@@ -79,5 +79,5 @@ export function extractAnchorSection(body, anchorId) {
  */
 export function renderSection(body, anchorId) {
     const slice = extractAnchorSection(body, anchorId);
-    return slice ? md.render(slice) : "";
+    return slice ? renderFoundryMarkdown(slice) : "";
 }

package/engine/base-compiler.mjs

@@ -62,6 +62,7 @@
  */
 
 import { authoredFrontmatter } from "./index-records.mjs";
+import { renderSecretBlocks } from "./content-secrets.mjs";
 import { cloneAddressState } from "./address-values.mjs";
 import fs from "fs";
 import path from "path";
@@ -620,6 +621,18 @@ export class BasePackCompiler {
      *   that does not convert.
      */
     convertBody(fm, body) {
+        const secretError = renderSecretBlocks(body, "book").errors[0];
+        if (secretError) {
+            const error = new Error(secretError.message);
+            error.position = {
+                line: (this.currentNote?.bodyLine ?? 1) + secretError.line - 1,
+                column:
+                    secretError.line === 1 ?
+                        (this.currentNote?.bodyColumn ?? 1)
+                    :   secretError.column,
+            };
+            throw error;
+        }
         if (!this.constructor.convertsWikilinks) return body;
         const name = resolveName(fm);
         const { absPath, bodyLine, bodyColumn } = this.currentNote ?? {};

package/engine/bundles.mjs

@@ -72,7 +72,7 @@ import { contentPackage } from "./content-package.mjs";
 import { FOLDER_TYPE } from "./folder-notes.mjs";
 import { HOMEPAGE_TYPE } from "./homepage.mjs";
 import { itemDocEntryId } from "./item-docs.mjs";
-import { folderField, md, resolveName } from "./helpers.mjs";
+import { folderField, renderFoundryMarkdown, resolveName } from "./helpers.mjs";
 import { packForType } from "./ids.mjs";
 import { readQualifier } from "./wikilinks.mjs";
 
@@ -322,7 +322,7 @@ export class Bundles extends BasePackCompiler {
             // Foundry renders on the import card. That is why a bundle earns no
             // separate documentation journal the way an item does: the document
             // it compiles into already has somewhere to put the prose.
-            description: markdown.trim() ? md.render(markdown) : "",
+            description: markdown.trim() ? renderFoundryMarkdown(markdown) : "",
             folder: this.folderResolver(authoredFolder, { isAddress: folderIsAddress }),
             flags: fm.flags,
             stats: this.stats,

package/engine/content-images.mjs

@@ -19,14 +19,15 @@
  *     ![Brànwâal Dôrgaar](images/beings/branwldrgr-portrait.webp){float: top-left}
  *     ![Map of Thalorna](images/map.webp){.full-width}
  *
- * ## Two closed vocabularies, and closed is the point
+ * ## Three closed vocabularies, and closed is the point
  *
  * **Width is a class**, and the ordinary width carries no marker at all — the
  * simple case needs no spelling. {@link IMAGE_CLASSES} holds the one class
  * there is. **Position is `float:`**, and {@link IMAGE_FLOATS} holds the five
- * values it takes.
+ * values it takes. **Named size is `size:`**, and {@link IMAGE_SIZES} holds its
+ * values. Size is parsed but does not change the figure's current presentation.
  *
- * Both are closed, and an unrecognised value is **refused with a located
+ * All three are closed, and an unrecognised value is **refused with a located
  * diagnostic** rather than ignored. Ignoring is the failure worth preventing:
  * `{.fullwidth}` rendering as an ordinary image looks exactly like a directive
  * that worked, so the author publishes a page that is not the one they asked
@@ -36,8 +37,7 @@
  *
  * **No pixel values.** A number means something in a browser and nothing
  * coherent in print, and a directive carrying both a class and a dimension
- * gives one question two answers with no rule for which wins. A third width
- * joins the vocabulary as a name.
+ * gives one question two answers with no rule for which wins.
  *
  * **Not `markdown-it-attrs`.** It is a general attribute injector: it will set
  * `style`, `id` or `onclick`, and those reach emitted markup on the website and
@@ -105,6 +105,16 @@ export const IMAGE_CLASSES = Object.freeze({
     },
 });
 
+/** The named sizes an image directive accepts without applying a display size. */
+export const IMAGE_SIZES = Object.freeze([
+    "auto",
+    "small",
+    "medium",
+    "large",
+    "xlarge",
+    "full-width",
+]);
+
 /**
  * The `float:` positions an image may take, and where each puts it.
  *
@@ -213,16 +223,18 @@ export function imageSourceProblem(src) {
  *
  * Values are validated here rather than at the point of rendering, so a mistake
  * is one finding with a position rather than three surfaces quietly drawing
- * something else. A directive that holds a problem yields **no** class and no
+ * something else. A directive that holds a problem yields **no** class, size or
  * float: a half-honoured directive is the silent failure in a smaller costume.
  *
  * @param {string} [raw] - The text between the braces, braces included or not.
- * @returns {{classes: string[], float: string, problems: string[]}} What was
+ * @returns {{classes: string[], size: string, float: string, problems: string[]}} What was
  *   written, and what cannot be honoured.
  */
 export function parseImageDirective(raw) {
     /** @type {string[]} */
     const classes = [];
+    let size = "auto";
+    let sizeSeen = false;
     let float = "";
     /** @type {string[]} */
     const problems = [];
@@ -230,7 +242,7 @@ export function parseImageDirective(raw) {
     const inner = String(raw ?? "")
         .replace(/^\{/, "")
         .replace(/\}$/, "");
-    if (!inner.trim()) return { classes, float, problems };
+    if (!inner.trim()) return { classes, size, float, problems };
 
     // Split on commas, not whitespace: `float: top-left` is one pair with a
     // space in it, and the space after the colon is the spelling people write.
@@ -259,17 +271,32 @@ export function parseImageDirective(raw) {
         const colon = part.indexOf(":");
         if (colon === -1) {
             problems.push(
-                `\`${part}\` is neither a width class nor \`float: <position>\` — an ` +
-                    "image states its width as a class and its position as `float:`, " +
+                `\`${part}\` is neither a width class nor \`size: <name>\` or ` +
+                    "`float: <position>` — an image states its width as a class and its position as `float:`, " +
                     "and it states no dimensions at all",
             );
             continue;
         }
         const key = part.slice(0, colon).trim();
         const value = part.slice(colon + 1).trim();
+        if (key === "size") {
+            if (!IMAGE_SIZES.includes(value)) {
+                problems.push(
+                    `\`size: ${value}\` is not a size — the ones there are: ${IMAGE_SIZES.join(", ")}`,
+                );
+                continue;
+            }
+            if (sizeSeen) {
+                problems.push("`size:` is written twice, and an image has one named size");
+                continue;
+            }
+            size = value;
+            sizeSeen = true;
+            continue;
+        }
         if (key !== "float") {
             problems.push(
-                `\`${key}\` is not an image attribute — \`float\` is the only one, ` +
+                `\`${key}\` is not an image attribute — use \`size\` or \`float\`, ` +
                     "and width is a class rather than an attribute",
             );
             continue;
@@ -292,8 +319,8 @@ export function parseImageDirective(raw) {
         problems.push("an image states one width, and this states more than one");
     }
     // Nothing partial: a directive with a problem in it is not honoured at all.
-    if (problems.length) return { classes: [], float: "", problems };
-    return { classes, float, problems };
+    if (problems.length) return { classes: [], size: "auto", float: "", problems };
+    return { classes, size, float, problems };
 }
 
 /**
@@ -594,7 +621,7 @@ export function lintContentImages(contentBase, { skipDirectories = [], config }
  * **Hugo is handed markdown, not a rendered page.** The site emitter writes a
  * note's body through verbatim, so a `{…}` directive left in it reaches the
  * page as its own literal braces: Goldmark's block-attribute parser is off, and
- * turning it on would accept `style` and `id` alongside the two vocabularies,
+ * turning it on would accept `style` and `id` alongside the closed vocabularies,
  * which is the injection surface this rule exists to avoid. So the directive is
  * resolved here, into markup Goldmark passes through.
  *

package/engine/content-secrets.mjs

@@ -0,0 +1,110 @@
+/*
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import crypto from "node:crypto";
+import markdownit from "markdown-it";
+
+const webMarkdown = markdownit({ html: true });
+
+/**
+ * Render whole-line `:::secret` blocks for one publishing surface.
+ * The source line of each syntax error is relative to the supplied body.
+ *
+ * @param {string} source - Markdown containing secret blocks.
+ * @param {"foundry"|"web"|"book"} target - Publishing surface.
+ * @param {(markdown: string) => string} [renderMarkdown] - Foundry's configured renderer.
+ * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function renderSecretBlocks(
+    source,
+    target,
+    renderMarkdown = webMarkdown.render.bind(webMarkdown),
+) {
+    const lines = String(source ?? "").split("\n");
+    const result = [];
+    const errors = [];
+    let opening = -1;
+    let body = [];
+    let codeFence = null;
+
+    for (let index = 0; index < lines.length; index++) {
+        const line = lines[index];
+        const fence = line.match(/^ {0,3}(`{3,}|~{3,})/);
+        if (codeFence) {
+            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length) {
+                codeFence = null;
+            }
+            if (opening >= 0) body.push(line);
+            else result.push(line);
+            continue;
+        }
+        if (fence) {
+            codeFence = fence[1];
+            if (opening >= 0) body.push(line);
+            else result.push(line);
+            continue;
+        }
+        if (/^:::secret[ \t]*$/.test(line)) {
+            if (opening >= 0) {
+                errors.push({
+                    line: index + 1,
+                    column: 1,
+                    message: "nested secret blocks are not supported",
+                });
+                body.push(line);
+            } else {
+                opening = index;
+                body = [];
+            }
+            continue;
+        }
+        if (/^:::[ \t]*$/.test(line)) {
+            if (opening < 0) {
+                errors.push({
+                    line: index + 1,
+                    column: 1,
+                    message: "secret block has no opening :::secret line",
+                });
+                result.push(line);
+                continue;
+            }
+            const inner = body.join("\n").trim();
+            if (target === "book") {
+                result.push("", "**GM note**", "", inner, "");
+            } else {
+                const html = renderMarkdown(inner).trim();
+                if (target === "foundry") {
+                    const id = crypto
+                        .createHash("sha256")
+                        .update(`${opening}:${inner}`)
+                        .digest("hex")
+                        .slice(0, 12);
+                    result.push(
+                        "",
+                        `<section class="secret" id="secret-${id}">`,
+                        html,
+                        "</section>",
+                        "",
+                    );
+                } else {
+                    result.push("", "<details><summary>Spoiler</summary>", html, "</details>", "");
+                }
+            }
+            opening = -1;
+            body = [];
+            continue;
+        }
+        if (opening >= 0) body.push(line);
+        else result.push(line);
+    }
+    if (opening >= 0) {
+        errors.push({
+            line: opening + 1,
+            column: 1,
+            message: "secret block needs a closing ::: line",
+        });
+        result.push(":::secret", ...body);
+    }
+    return { markdown: result.join("\n"), errors };
+}

package/engine/helpers.mjs

@@ -62,6 +62,7 @@ import { linkFindingMessage } from "./wikilink-syntax.mjs";
 // from there rather than respelt, so the tag and its one reader cannot drift.
 import { isDraftNote } from "./note-vocabulary.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { renderSecretBlocks } from "./content-secrets.mjs";
 import { positionInBody } from "./diagnostics.mjs";
 // The pure `sohl:` frontmatter readers live in a leaf module so the item-type
 // registry can import them without reaching back through this one.
@@ -125,6 +126,12 @@ export const md = markdownit({ html: true })
         }),
     );
 
+/** Render a note body with Foundry's secret section markup. */
+export function renderFoundryMarkdown(body) {
+    const { markdown } = renderSecretBlocks(body, "foundry", (inner) => md.render(inner));
+    return md.render(markdown);
+}
+
 /**
  * Parses a markdown file with YAML frontmatter.
  *
@@ -165,7 +172,7 @@ export function parseMarkdownFile(filePath, { addressContext } = {}) {
     }
     const raw = fmMatch[2];
     const body = raw.trim();
-    const description = body ? md.render(body) : "";
+    const description = body ? renderFoundryMarkdown(body) : "";
     // Where the trimmed body starts in the *file*, so an offset within it can
     // be reported as a file position. The frontmatter's lines and the
     // blank lines `trim()` removes both sit in between, and the trim can take

package/engine/journals.mjs

@@ -51,7 +51,14 @@
 
 import log from "loglevel";
 
-import { sohlField, makeId, resolveName, defaultStats, md, folderField } from "./helpers.mjs";
+import {
+    sohlField,
+    makeId,
+    resolveName,
+    defaultStats,
+    renderFoundryMarkdown,
+    folderField,
+} from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
 import { anchorPageId, resolveReference } from "./wikilinks.mjs";
 import { infoboxesToHtml, linkToUuid } from "./infobox-render.mjs";
@@ -83,6 +90,7 @@ export function splitPages(body, leadName = "Introduction") {
     const beforeFirstH1 = [];
     let current = null;
     let inCodeBlock = false;
+    let inSecret = false;
 
     const closeCurrent = () => {
         if (!current) return;
@@ -99,11 +107,14 @@ export function splitPages(body, leadName = "Introduction") {
         if (line.trim().startsWith("```")) {
             inCodeBlock = !inCodeBlock;
         }
+        if (!inCodeBlock && /^:::secret[ \t]*$/.test(line)) inSecret = true;
+        else if (!inCodeBlock && /^:::[ \t]*$/.test(line)) inSecret = false;
 
         // An H1 starts a page, as does any heading carrying an `{#slug}`
         // anchor: a Foundry UUID can only address a page, so a linkable
         // section has to be one.
-        const headingMatch = !inCodeBlock ? line.match(/^\s*(#{1,6})\s+(.+?)\s*#*\s*$/) : null;
+        const headingMatch =
+            !inCodeBlock && !inSecret ? line.match(/^\s*(#{1,6})\s+(.+?)\s*#*\s*$/) : null;
         const rawHeading = headingMatch?.[2]?.trim();
         const anchorMatch = rawHeading?.match(/^(.*?)\s*\{#([^}]+)\}\s*$/);
         const startsPage = headingMatch && (headingMatch[1].length === 1 || anchorMatch);
@@ -255,7 +266,7 @@ export function buildPages(rawPages, entryId, noteName) {
             title: { show: true, level: page.level ?? 1 },
             text: {
                 format: 1,
-                content: page.markdown ? md.render(page.markdown) : "",
+                content: page.markdown ? renderFoundryMarkdown(page.markdown) : "",
             },
             _key: `!journal.pages!${entryId}.${pageId}`,
         };

package/engine/pdf-build.mjs

@@ -102,6 +102,7 @@ import { resolveWebWikilinks } from "./web-wikilinks.mjs";
 import { linkFindingMessage } from "./wikilink-syntax.mjs";
 import { assetAddressIndex } from "./art-fields.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { renderSecretBlocks } from "./content-secrets.mjs";
 import { protectCode } from "./code-fences.mjs";
 import { imageSourcesIn } from "./content-images.mjs";
 import { pathnameProblem, resolvePathname } from "./pathnames.mjs";
@@ -523,8 +524,18 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
                 message: err.message ?? (err.reason ? linkFindingMessage(err) : String(err)),
             });
         }
-        stageImages(resolvedBody, page.file);
-        const prose = markdownToTypst(resolvedBody, {
+        const secrets = renderSecretBlocks(resolvedBody, "book");
+        for (const error of renderSecretBlocks(page.body, "book").errors) {
+            findings.push({
+                file: page.file,
+                line: (page.bodyLine ?? 1) + error.line - 1,
+                column: error.column,
+                severity: "error",
+                message: error.message,
+            });
+        }
+        stageImages(secrets.markdown, page.file);
+        const prose = markdownToTypst(secrets.markdown, {
             md,
             links: plan.links,
             glyphs,

package/engine/site-build.mjs

@@ -61,6 +61,7 @@ import matter from "gray-matter";
 import { addressSlug } from "./content-address.mjs";
 import { protectCode } from "./code-fences.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { renderSecretBlocks } from "./content-secrets.mjs";
 import { renderImageFigures } from "./content-images.mjs";
 import { pathnameProblem, resolvePathname } from "./pathnames.mjs";
 import { buildSiteIndex, resolveInfoboxRef, wikiContext } from "./site-index.mjs";
@@ -140,8 +141,10 @@ function siteCorpusFiles(contentBase, ctx) {
  */
 function readNote(file, ctx) {
     let parsed;
+    let source;
     try {
-        parsed = matter(fs.readFileSync(file, "utf8"));
+        source = fs.readFileSync(file, "utf8");
+        parsed = matter(source);
     } catch {
         return null;
     }
@@ -150,7 +153,11 @@ function readNote(file, ctx) {
         package: ctx.contentPackage ?? ctx.config?.contentPackage,
     };
     try {
-        return { fm: decodeNoteAddresses(parsed.data, context), body: parsed.content };
+        return {
+            fm: decodeNoteAddresses(parsed.data, context),
+            body: parsed.content,
+            bodyLine: source.slice(0, source.length - parsed.content.length).split("\n").length,
+        };
     } catch (error) {
         const position = positionOfYamlPath(parsed.matter, error.keyPath ?? [], {
             key: error.addressKey,
@@ -202,7 +209,7 @@ export function collectContentPages(contentBase, ctx) {
         const note = readNote(file, ctx);
         if (!note) continue;
         applyComputedBeingAge(note.fm, present);
-        const { fm, body } = note;
+        const { fm, body, bodyLine } = note;
         // The configuration's, never a note's: `package:` is retired, so every
         // note in the tree belongs to the package this repository compiles.
         const pkg = ctx.contentPackage;
@@ -249,6 +256,7 @@ export function collectContentPages(contentBase, ctx) {
             // — reads one configured value and never frontmatter.
             pkg,
             body,
+            bodyLine,
             name,
             slug,
             base,
@@ -734,6 +742,7 @@ export function renderPages(pages, options) {
     });
 
     const tableErrors = [];
+    const secretErrors = [];
     const wikiErrors = [];
     const imageErrors = [];
     const byKind = {};
@@ -847,7 +856,17 @@ export function renderPages(pages, options) {
         tableErrors.push(...errors);
 
         const data = pageFrontmatter(page, { decorate, webSrc, artSrc });
-        rendered.push({ page, body: protectCode(body, resolve), data });
+        const resolvedBody = protectCode(body, resolve);
+        const secrets = renderSecretBlocks(resolvedBody, "web");
+        for (const error of renderSecretBlocks(page.body, "book").errors) {
+            secretErrors.push({
+                file: page.file,
+                line: (page.bodyLine ?? 1) + error.line - 1,
+                column: error.column,
+                message: error.message,
+            });
+        }
+        rendered.push({ page, body: secrets.markdown, data });
         // A resolved target with no URL is a pack-only package's address:
         // real, and nowhere on the web, so not an edge.
         for (const hit of resolved) {
@@ -885,6 +904,7 @@ export function renderPages(pages, options) {
         written: pages.length,
         byKind,
         tableErrors,
+        secretErrors,
         wikiErrors,
         imageErrors,
         related,
@@ -1044,6 +1064,7 @@ export function buildSite({ config, sqlTables, locate } = {}) {
             gates: { ...emptyGates(), homepages: homepageFindings },
             manifests: null,
             tableErrors: [],
+            secretErrors: [],
             wikiErrors: [],
             imageErrors: [],
             mapFindings: [],
@@ -1063,6 +1084,7 @@ export function buildSite({ config, sqlTables, locate } = {}) {
             gates: emptyGates(),
             manifests: null,
             tableErrors: [],
+            secretErrors: [],
             wikiErrors: [],
             imageErrors: [],
             mapFindings: [],
@@ -1108,6 +1130,7 @@ export function buildSite({ config, sqlTables, locate } = {}) {
             gates,
             stats: null,
             tableErrors: [],
+            secretErrors: [],
             wikiErrors: [],
             imageErrors: [],
             mapFindings: [],
@@ -1175,6 +1198,7 @@ export function buildSite({ config, sqlTables, locate } = {}) {
     return {
         gates,
         tableErrors: rendered.tableErrors,
+        secretErrors: rendered.secretErrors,
         wikiErrors: rendered.wikiErrors,
         imageErrors: rendered.imageErrors,
         mapFindings: drawn.findings,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.12.0",
+    "version": "22.12.2",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/content-images.d.mts

@@ -16,15 +16,16 @@ export function imageSourceProblem(src: string): string;
  *
  * Values are validated here rather than at the point of rendering, so a mistake
  * is one finding with a position rather than three surfaces quietly drawing
- * something else. A directive that holds a problem yields **no** class and no
+ * something else. A directive that holds a problem yields **no** class, size or
  * float: a half-honoured directive is the silent failure in a smaller costume.
  *
  * @param {string} [raw] - The text between the braces, braces included or not.
- * @returns {{classes: string[], float: string, problems: string[]}} What was
+ * @returns {{classes: string[], size: string, float: string, problems: string[]}} What was
  *   written, and what cannot be honoured.
  */
 export function parseImageDirective(raw?: string): {
     classes: string[];
+    size: string;
     float: string;
     problems: string[];
 };
@@ -182,7 +183,7 @@ export function lintContentImages(contentBase: string, { skipDirectories, config
  * **Hugo is handed markdown, not a rendered page.** The site emitter writes a
  * note's body through verbatim, so a `{…}` directive left in it reaches the
  * page as its own literal braces: Goldmark's block-attribute parser is off, and
- * turning it on would accept `style` and `id` alongside the two vocabularies,
+ * turning it on would accept `style` and `id` alongside the closed vocabularies,
  * which is the injection surface this rule exists to avoid. So the directive is
  * resolved here, into markup Goldmark passes through.
  *
@@ -248,6 +249,8 @@ export const IMAGE_CLASSES: Readonly<Record<string, {
     scope: string;
     describe: string;
 }>>;
+/** The named sizes an image directive accepts without applying a display size. */
+export const IMAGE_SIZES: readonly string[];
 /**
  * The `float:` positions an image may take, and where each puts it.
  *

package/types/engine/content-secrets.d.mts

@@ -0,0 +1,17 @@
+/**
+ * Render whole-line `:::secret` blocks for one publishing surface.
+ * The source line of each syntax error is relative to the supplied body.
+ *
+ * @param {string} source - Markdown containing secret blocks.
+ * @param {"foundry"|"web"|"book"} target - Publishing surface.
+ * @param {(markdown: string) => string} [renderMarkdown] - Foundry's configured renderer.
+ * @returns {{markdown: string, errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function renderSecretBlocks(source: string, target: "foundry" | "web" | "book", renderMarkdown?: (markdown: string) => string): {
+    markdown: string;
+    errors: Array<{
+        line: number;
+        column: number;
+        message: string;
+    }>;
+};

package/types/engine/helpers.d.mts

@@ -1,3 +1,5 @@
+/** Render a note body with Foundry's secret section markup. */
+export function renderFoundryMarkdown(body: any): string;
 /**
  * Parses a markdown file with YAML frontmatter.
  *