gutterpress 0.10.7 → 0.10.8

package/dist/package-rm9d2tht.json

@@ -0,0 +1,29 @@
+{
+  "name": "{{SLUG}}",
+  "version": "0.1.0",
+  "description": "{{DESCRIPTION}}",
+  "type": "module",
+  "main": "plugin.js",
+  "files": [
+    "gutterpress.json",
+    "plugin.js",
+    "styles",
+    "snippets",
+    "README.md"
+  ],
+  "keywords": ["gutterpress", "gutterpress-plugin", "markdown-it-plugin"],
+  "author": "{{AUTHOR}}",
+  "license": "MIT",
+  "scripts": {
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "markdown-it": "^14.1.0"
+  },
+  "peerDependencies": {
+    "markdown-it": ">=14"
+  },
+  "peerDependenciesMeta": {
+    "markdown-it": { "optional": true }
+  }
+}

package/dist/page-rules-nsj3aw42.css

@@ -0,0 +1,128 @@
+/* ===========================================================================
+ * {{NAME}} — 5. PAGE RULES
+ *
+ * OWNS
+ *   The CSS `@page` at-rules: the sheet's own geometry (margins), the margin
+ *   boxes that carry running heads and folios, and the named-page wiring that
+ *   connects a markdown `@page .name` to a CSS `@page name`.
+ *
+ *   This is standard CSS Paged Media and GCPM. Everything here is what the
+ *   spec says, not something Gutterpress invented — `string-set`,
+ *   `target-counter()` and the margin boxes all work the way they are
+ *   written down.
+ *
+ * MUST NOT CONTAIN
+ *   - Ordinary element or component rules. `@page` is a separate cascade;
+ *     mixing the two here is how a stylesheet becomes impossible to reason
+ *     about. The two element rules that ARE here — `string-set` on `h1` and
+ *     `page:` on the opener template — are the wiring the margin boxes read,
+ *     not styling; they belong with the boxes that consume them.
+ *   - Component or template styling of any kind.
+ *
+ * ONE THING WORTH KNOWING: `@page` at-rules DO work inside a cascade layer —
+ * verified against the engine, not assumed. Keeping them in `pages` means a
+ * book's own `@page` rule in book.css (a later layer) wins over this one
+ * without a specificity fight, which is the whole point of the arrangement.
+ * ======================================================================== */
+
+@layer pages {
+  /* -------------------------------------------------------------------------
+   * TRIM SIZE. This is the physical size of the printed page, and it has to
+   * be declared in CSS: with no `size:` anywhere, Chromium falls back to US
+   * Letter and prints a book at the wrong trim with no error at all. That is
+   * the single most expensive silent failure in this whole stack, which is
+   * why it is the first thing in the file.
+   *
+   * KEEP IT IN STEP WITH THE MANIFEST. The book's `preset:`/`page:` is what
+   * validation, the publish targets and the PDF/X boxes measure against, and
+   * `gutterpress validate` fails the build when the produced PDF does not
+   * match it. So the manifest is the source of truth and this line is the
+   * instruction that satisfies it — change one and change the other.
+   *
+   * 6in × 9in is the neutral trade-book size the `book` preset declares.
+   * Common alternatives: 5.5in 8.5in (digest), 8.5in 11in (US Letter),
+   * 210mm 297mm (A4).
+   *
+   * Deliberately a literal, not `var(--…)`. A custom property does resolve
+   * here, but an indirection whose failure mode is "silently prints Letter"
+   * is not worth the tidiness.
+   * ---------------------------------------------------------------------- */
+  @page {
+    size: 6in 9in;
+  }
+
+  /* Mirrored margins for a bound book: the inner edge needs the extra room,
+     and which edge is "inner" flips every page. */
+  @page :left {
+    margin: var(--{{PREFIX}}page-margin-top)
+            var(--{{PREFIX}}page-margin-inner)
+            var(--{{PREFIX}}page-margin-bottom)
+            var(--{{PREFIX}}page-margin-outer);
+
+    @bottom-left {
+      content: counter(page);
+      font-family: var(--{{PREFIX}}font-body);
+      font-size: var(--{{PREFIX}}fs-small);
+      color: var(--{{PREFIX}}ink-soft);
+    }
+
+    /* The running head. `string(chaptertitle)` is fed by the `string-set`
+       further down — the standard GCPM mechanism.
+
+       For the book-title-on-verso convention instead, add a second named
+       string (`.title-page h1 { string-set: booktitle content(text); }`) and
+       read `string(booktitle)` here. Do not reference a named string nothing
+       sets: it resolves to empty and the head silently disappears. */
+    @top-left {
+      content: string(chaptertitle);
+      font-family: var(--{{PREFIX}}font-display);
+      font-size: var(--{{PREFIX}}fs-small);
+      color: var(--{{PREFIX}}ink-soft);
+    }
+  }
+
+  @page :right {
+    margin: var(--{{PREFIX}}page-margin-top)
+            var(--{{PREFIX}}page-margin-outer)
+            var(--{{PREFIX}}page-margin-bottom)
+            var(--{{PREFIX}}page-margin-inner);
+
+    @bottom-right {
+      content: counter(page);
+      font-family: var(--{{PREFIX}}font-body);
+      font-size: var(--{{PREFIX}}fs-small);
+      color: var(--{{PREFIX}}ink-soft);
+    }
+
+    /* The recto carries the current chapter — `string(chaptertitle)` picks up
+       the most recent `h1` on or before this page. */
+    @top-right {
+      content: string(chaptertitle);
+      font-family: var(--{{PREFIX}}font-display);
+      font-size: var(--{{PREFIX}}fs-small);
+      color: var(--{{PREFIX}}ink-soft);
+    }
+  }
+
+  /* Feed the running heads. `string-set` is the standard GCPM mechanism:
+     the element's text becomes a named string the margin boxes can read. */
+  h1 { string-set: chaptertitle content(text); }
+
+  /* A chapter opener gets no running head and no folio — the convention in
+     nearly every printed book. `@page .{{PREFIX}}opener` in markdown maps to
+     the named page below via `page:`. */
+  .page.{{PREFIX}}opener { page: {{PREFIX}}opener; }
+
+  @page {{PREFIX}}opener {
+    @top-left { content: none; }
+    @top-right { content: none; }
+    @bottom-left { content: none; }
+    @bottom-right { content: none; }
+  }
+
+  /* First page of the book: no furniture at all. */
+  @page :first {
+    @top-left { content: none; }
+    @top-right { content: none; }
+  }
+}

package/dist/page-templates-7md4ev7d.css

@@ -0,0 +1,60 @@
+/* ===========================================================================
+ * {{NAME}} — 4. PAGE TEMPLATES
+ *
+ * OWNS
+ *   The layout of a `@page .name` wrapper — how content is arranged WITHIN
+ *   one page of the book. Columns, full-bleed art, a centred opener.
+ *
+ *   Authored as:
+ *
+ *       @page .{{PREFIX}}opener
+ *       # Part One
+ *       @end-page
+ *
+ * MUST NOT CONTAIN
+ *   - `@page` at-rules. Confusingly, `@page .name` in MARKDOWN and `@page` in
+ *     CSS are different things: the markdown marker makes a `div.page` you
+ *     style with `.page.name`, while the CSS at-rule sets the sheet's own
+ *     geometry. This file owns the first; page-rules.css owns the second.
+ *   - Component styling. A template says where a component sits, never what
+ *     it looks like.
+ * ======================================================================== */
+
+@layer templates {
+  /* A part/section opener: content parked a third of the way down, centred,
+     with the rest of the sheet left empty on purpose. */
+  .page.{{PREFIX}}opener {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    align-items: center;
+    text-align: center;
+    min-height: 60%;
+  }
+
+  .page.{{PREFIX}}opener h1 {
+    font-size: calc(var(--{{PREFIX}}fs-h1) * 1.35);
+    margin-block-end: var(--{{PREFIX}}space-2);
+  }
+
+  .page.{{PREFIX}}opener p {
+    text-indent: 0;
+    color: var(--{{PREFIX}}ink-soft);
+    max-width: 24em;
+  }
+
+  /* A two-column reference page. Core already ships `.gp-columns-2` as
+     general author vocabulary — reach for that first, and use a named
+     template like this only when the page needs more than the columns. */
+  .page.{{PREFIX}}reference {
+    columns: 2;
+    column-gap: var(--{{PREFIX}}space-4);
+    column-rule: 1px solid var(--{{PREFIX}}rule);
+  }
+
+  .page.{{PREFIX}}reference h2 {
+    column-span: all;
+    border-block-end: 1px solid var(--{{PREFIX}}rule);
+    padding-block-end: var(--{{PREFIX}}space-1);
+  }
+}

package/dist/{plugin-gg5mk26h.js → plugin-b05ck7zd.js}

@@ -1,15 +1,15 @@
 import {
   addNpmPlugin,
   parseNpmPluginSpec
-} from "./cli-kzf64c2g.js";
-import"./cli-pvk2s9d7.js";
+} from "./cli-1hx14cgk.js";
+import"./cli-vxf151ea.js";
 import {
   UsageError,
   exitForUsage,
   rejectExtraPositionals,
   rejectUnknownFlags
-} from "./cli-h8ejbtyr.js";
-import"./cli-s8q42x3r.js";
+} from "./cli-vcv5ewqj.js";
+import"./cli-4vtgt2ng.js";
 import"./cli-c41yr7he.js";
 import {
   EXIT_CODES

package/dist/plugin-m2w7g47v.css

@@ -0,0 +1,114 @@
+/* ===========================================================================
+ * {{NAME}} — component stylesheet
+ *
+ * OWNS
+ *   The look of everything `plugin.js` emits: the `@term-box` container, its
+ *   variants and label, and the `[[key term]]` inline span. Every one of
+ *   those looks is driven by a PUBLIC custom property declared at `:root`
+ *   below, so a book can retune this component without touching this file.
+ *
+ * MUST NOT CONTAIN
+ *   - `@page` rules or page geometry. A plugin styles its own components; the
+ *     book's theme owns the page.
+ *   - Bare element selectors (`p`, `table`, `h2`). They would leak this
+ *     plugin's opinions into every book that installs it. Scope every rule
+ *     under a `{{PREFIX}}` class.
+ *   - Any `gp-` class. That prefix is Gutterpress core's.
+ *   - Per-book values. Ship sane defaults; let the book override the tokens.
+ *
+ * WHY THE @layer
+ *   Gutterpress injects plugin CSS before the book's own stylesheets, and in
+ *   CSS an UNLAYERED rule beats a layered one no matter how specific the
+ *   layered one is. So an unlayered plugin sheet would quietly outrank every
+ *   rule in a book that had adopted the recommended
+ *   `@layer tokens, base, components, templates, pages, book;` convention —
+ *   the author would edit their own CSS and nothing would happen.
+ *
+ *   Declaring our own layer fixes that by construction. This sheet loads
+ *   first, so `{{SLUG}}` becomes the FIRST (weakest) layer; every layer the
+ *   book declares afterwards is appended after it and therefore wins, and the
+ *   book's unlayered rules win too. A plugin should always be the easiest
+ *   thing in the book to override.
+ *
+ *   Adopt it for the WHOLE sheet: a rule left outside the layer here is
+ *   unlayered, and would beat every rule inside it — including our own.
+ * ======================================================================== */
+
+@layer {{SLUG}} {
+  /* -----------------------------------------------------------------------
+   * PUBLIC TOKENS — this component's entire theming surface.
+   *
+   * Declared at `:root` with real defaults so the component looks right in
+   * any book with no setup at all. A book retunes it by resetting these in
+   * its own CSS — either globally, or scoped to one chapter/page/section:
+   *
+   *     #ch-appendix { --{{PREFIX}}term-box-accent: #7a1f1f; }
+   *
+   * Rules below consume them as BARE `var(--x)`, never `var(--x, fallback)`:
+   * the default lives at `:root` exactly once, so there is one place to look
+   * and no second copy to drift.
+   * -------------------------------------------------------------------- */
+  :root {
+    --{{PREFIX}}term-box-accent: #2f5d8a;
+    --{{PREFIX}}term-box-bg: #f2f6fa;
+    --{{PREFIX}}term-box-ink: inherit;
+    --{{PREFIX}}term-box-pad: 0.6em 0.9em;
+    --{{PREFIX}}term-box-rule: 3px;
+    --{{PREFIX}}term-box-label-size: 0.78em;
+    --{{PREFIX}}term-box-label-tracking: 0.08em;
+    --{{PREFIX}}term-ink: #2f5d8a;
+    --{{PREFIX}}term-weight: 600;
+  }
+
+  /* -----------------------------------------------------------------------
+   * The container emitted by `@term-box` (plugin.js's `markers` table).
+   * -------------------------------------------------------------------- */
+  .{{PREFIX}}term-box {
+    background: var(--{{PREFIX}}term-box-bg);
+    border-left: var(--{{PREFIX}}term-box-rule) solid var(--{{PREFIX}}term-box-accent);
+    color: var(--{{PREFIX}}term-box-ink);
+    padding: var(--{{PREFIX}}term-box-pad);
+    /* Print hygiene: a callout that splits across a page break reads badly,
+       and a two-line orphan reads worse. Both are the component's business,
+       not the book's. */
+    break-inside: avoid;
+    margin-block: 1em;
+  }
+
+  .{{PREFIX}}term-box > :first-child { margin-block-start: 0; }
+  .{{PREFIX}}term-box > :last-child { margin-block-end: 0; }
+
+  /* The label element, present only when the author wrote `label="…"`. */
+  .{{PREFIX}}term-box-label {
+    color: var(--{{PREFIX}}term-box-accent);
+    font-size: var(--{{PREFIX}}term-box-label-size);
+    letter-spacing: var(--{{PREFIX}}term-box-label-tracking);
+    text-transform: uppercase;
+    font-weight: 700;
+    margin-block: 0 0.35em;
+  }
+
+  /* -----------------------------------------------------------------------
+   * Variants. Each one only ever RESETS a public token — it never writes a
+   * second copy of the component's rules. That is what keeps a variant three
+   * lines long instead of thirty, and what lets a book add its own variant
+   * without this file changing.
+   * -------------------------------------------------------------------- */
+  .{{PREFIX}}term-box-note {
+    --{{PREFIX}}term-box-accent: #2f5d8a;
+    --{{PREFIX}}term-box-bg: #f2f6fa;
+  }
+
+  .{{PREFIX}}term-box-warning {
+    --{{PREFIX}}term-box-accent: #9a5b12;
+    --{{PREFIX}}term-box-bg: #fdf6ec;
+  }
+
+  /* -----------------------------------------------------------------------
+   * The inline span emitted by `[[key term]]` (plugin.js's bespoke rule).
+   * -------------------------------------------------------------------- */
+  .{{PREFIX}}term {
+    color: var(--{{PREFIX}}term-ink);
+    font-weight: var(--{{PREFIX}}term-weight);
+  }
+}

package/dist/plugin.js-aszz0zgh.tpl

@@ -0,0 +1,172 @@
+/**
+ * {{NAME}} — a Gutterpress plugin.
+ *
+ * A Gutterpress plugin is a PLAIN markdown-it plugin: one function with the
+ * signature `(md, options) => void`. There is no Gutterpress plugin API, no
+ * base class, and no host-injected context object — which is exactly why any
+ * of the hundreds of markdown-it plugins on npm works here unchanged.
+ *
+ * Two ways to add a container, both used below:
+ *
+ *   1. DECLARATIVELY — `export const markers`. A table of marker names, each
+ *      describing the wrapper element Gutterpress should emit. This is DATA
+ *      the loader reads off this module; it is not an API call. Core's own
+ *      marker parser then handles `@term-box` / `@end-term-box` through the
+ *      exact same grammar, class merging and warning channel as `@section`.
+ *      Reach for this whenever "wrap a block in an element with a class" is
+ *      all you need.
+ *
+ *   2. BY HAND — an ordinary markdown-it rule, registered on `md` inside the
+ *      default export. Reach for this when a declarative wrapper cannot
+ *      express it: inline syntax (below), token rewriting, custom renderers.
+ *
+ * WHAT THIS FILE MUST NOT DO
+ *
+ *   - It must not `import` from "gutterpress". Plugin code is resolved against
+ *     the book's folder, and Gutterpress ships as a single compiled binary
+ *     with no `node_modules` for that import to find. If you need a helper
+ *     from core, inline a copy of it here. (Type-only imports are erased
+ *     before runtime and are therefore safe — see README.md.)
+ *   - It must not emit `gp-` classes. That prefix belongs to Gutterpress core.
+ *     Everything this plugin emits carries its own prefix instead — see
+ *     PREFIX below and `test/plugin.test.js`, which fails the build if a
+ *     `gp-` class ever creeps in.
+ */
+
+/**
+ * THE load-bearing convention: every class, custom property and marker name
+ * this package emits starts with this prefix.
+ *
+ * Why it matters. A book loads core, a theme, and any number of plugins into
+ * ONE flat CSS namespace and ONE flat marker namespace. Nothing scopes them
+ * for you. A prefix is what keeps `{{SLUG}}`'s callout from colliding with
+ * some other plugin's callout — and `gp-` is reserved for core, so taking it
+ * would mean silently overriding Gutterpress's own vocabulary.
+ *
+ * Change it if you like — shorter reads better in CSS (`dc-` for Dimm City,
+ * say). It appears in three places, on purpose: here, in `styles/plugin.css`,
+ * and as `PREFIX` in `test/plugin.test.js`. The test file states the
+ * convention INDEPENDENTLY, so changing it in one place fails the suite
+ * instead of silently agreeing with itself.
+ */
+const PREFIX = "{{PREFIX}}";
+
+/**
+ * Declarative containers (the `markers` export).
+ *
+ * Every key becomes an author-facing marker: `@term-box` opens it and
+ * `@end-term-box` closes it — the closer is derived for you, never declared.
+ *
+ *   @term-box warning label="Read this first"
+ *   Ordinary **markdown** goes here.
+ *   @end-term-box
+ *
+ * Fields, all optional:
+ *   tag         wrapper element            (default "div")
+ *   class       base class on the wrapper
+ *   variants    extra classes keyed by the marker's bare word
+ *   label       a label element built from one of the marker's attributes
+ *   autoCloseAt ["eof"] closes an unclosed container at end of file
+ *
+ * Names are validated when the book loads: lower-case letters, digits and
+ * hyphens; they may not start with `end-`, and they may not shadow a core
+ * marker (`@page`, `@section`, `@chapter`, …). A name two loaded plugins both
+ * declare is a hard error naming both sides — which is the other half of why
+ * the prefix convention exists.
+ */
+export const markers = {
+  "term-box": {
+    tag: "aside",
+    class: `${PREFIX}term-box`,
+    variants: {
+      note: `${PREFIX}term-box-note`,
+      warning: `${PREFIX}term-box-warning`,
+    },
+    label: {
+      tag: "p",
+      class: `${PREFIX}term-box-label`,
+      from: "attr:label",
+    },
+    autoCloseAt: ["eof"],
+  },
+};
+
+/** The markdown-it inline rule's name, and the class it emits. */
+const TERM_RULE = `${PREFIX}term`;
+const TERM_TOKEN = `${PREFIX}term`;
+
+/**
+ * The bespoke half: an inline rule turning `[[key term]]` into
+ * `<span class="{{PREFIX}}term">key term</span>`.
+ *
+ * Declarative markers cannot do this — they wrap BLOCKS, and this is inline
+ * syntax in the middle of a sentence. That is the dividing line: reach for
+ * `markers` for block containers, write a rule by hand for anything else.
+ *
+ * Returned from a factory so the emitted class can come from plugin options,
+ * and exported so `test/plugin.test.js` can drive it directly.
+ *
+ * @param {string} className class placed on the emitted span
+ * @returns {(state: object, silent: boolean) => boolean} a markdown-it inline rule
+ */
+export function createTermRule(className) {
+  return function termRule(state, silent) {
+    const start = state.pos;
+    const max = state.posMax;
+
+    // Cheapest possible bail-out first: markdown-it runs this on every `[`.
+    if (start + 2 >= max) return false;
+    if (state.src.charCodeAt(start) !== 0x5b /* [ */) return false;
+    if (state.src.charCodeAt(start + 1) !== 0x5b /* [ */) return false;
+
+    const close = state.src.indexOf("]]", start + 2);
+    // The closing `]]` must exist AND sit inside the current inline span —
+    // `posMax` is not the end of the document, it is the end of what this
+    // inline context is allowed to consume.
+    if (close === -1 || close + 2 > max) return false;
+
+    const raw = state.src.slice(start + 2, close);
+    if (raw.includes("\n") || raw.includes("[") || raw.trim() === "") return false;
+
+    // `silent` means "validate only, emit nothing" — markdown-it uses it to
+    // probe. Honouring it is required of every inline rule.
+    if (!silent) {
+      const open = state.push(`${TERM_TOKEN}_open`, "span", 1);
+      open.attrSet("class", className);
+      const text = state.push("text", "", 0);
+      text.content = raw.trim();
+      state.push(`${TERM_TOKEN}_close`, "span", -1);
+    }
+
+    state.pos = close + 2;
+    return true;
+  };
+}
+
+/**
+ * The plugin function. This is the module's default export and the only thing
+ * Gutterpress requires of it.
+ *
+ * @param {import("markdown-it").default} md the markdown-it instance
+ * @param {{ termClass?: string }} [options] whatever the book's manifest put
+ *   under this plugin's `options:` key
+ */
+export default function {{IDENT}}(md, options = {}) {
+  const termClass =
+    typeof options.termClass === "string" && options.termClass
+      ? options.termClass
+      : `${PREFIX}term`;
+
+  // BEFORE "link", because `[[` would otherwise start being parsed as a link
+  // label and this rule would never see it.
+  md.inline.ruler.before("link", TERM_RULE, createTermRule(termClass));
+}
+
+/**
+ * Optional metadata. Gutterpress shows this in the desktop app's Extensions
+ * panel. Purely descriptive — nothing here changes how the plugin behaves.
+ */
+export const metadata = {
+  name: "{{NAME}}",
+  description: "{{DESCRIPTION}}",
+};