@iterant/site-runtime 3.9.0 → 3.10.0

package/docs/runtime-contract.md

@@ -50,7 +50,7 @@ runtime and says so.
 
 <!-- generated: available libraries -->
 
-_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.9.0._
+_Generated from package.json by scripts/generate-kit-table.mjs. Runtime 3.10.0._
 
 **Toolchain** (this package owns the version; do NOT declare these):
 
@@ -157,7 +157,7 @@ CommonMark, stored as written.
 
   const body = readMarkdown(data.body); // raw CommonMark | null
   <div
-    class="prose"
+    class="markdown-body"
     data-editable="body"
     data-path="props.body"
     data-edit-type="markdown"
@@ -165,6 +165,22 @@ CommonMark, stored as written.
   />;
   ```
 
+- **`markdown-body` is the wrapper class, and the stylesheet is opt-in
+  (3.10.0).** The compiler emits bare `<h2>`, `<ul>` and `<blockquote>`, and
+  Preflight flattens all three to paragraph size, so an unstyled body renders as
+  a run of identical lines. Add the import to `src/styles/globals.css` once,
+  below `@import "tailwindcss"`:
+
+  ```css
+  @import "@iterant/site-runtime/styles/markdown.css";
+  ```
+
+  It styles measure, rhythm and hierarchy from the repo's own `--it-*` and
+  `--font-*` tokens, and reads two knobs of its own:
+  `--it-markdown-measure` (the reading width, `68ch`, `none` to fill) and
+  `--it-markdown-flow` (the space between blocks, `1.25em`). Every rule sits in
+  the `base` layer, so a utility class on the wrapper still wins.
+
 - **Headings start at `##`.** The body renders below the page's own h1; the
   compiler does not demote levels for you.
 - Hrefs inside the value follow the same rules as link wrappers: root-relative

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iterant/site-runtime",
-  "version": "3.9.0",
+  "version": "3.10.0",
   "type": "module",
   "description": "The platform layer every Iterant brand site runs on: content grammar, collection schemas, SEO head and JSON-LD, layout core, Astro config preset, dev integrations and the verify gates.",
   "scripts": {
@@ -27,6 +27,7 @@
     "docs",
     "scripts",
     "src",
+    "styles",
     "!**/*.test.ts",
     "!scripts/check-fixture.mjs",
     "!scripts/check-packed.mjs",
@@ -59,6 +60,7 @@
     "./routes": "./src/routes/index.ts",
     "./config": "./src/config/preset.ts",
     "./integrations/*": "./src/integrations/*.mjs",
+    "./styles/markdown.css": "./styles/markdown.css",
     "./package.json": "./package.json"
   },
   "iterant": {

package/styles/markdown.css

@@ -0,0 +1,221 @@
+/*
+ * The article-body stylesheet: `class="markdown-body"` around compiled
+ * `renderMarkdown` output.
+ *
+ * It exists because `renderMarkdown` is bare micromark: it emits `<h2>`, `<ul>`
+ * and `<blockquote>` with no classes, and Tailwind's Preflight flattens every
+ * one of them to the paragraph's size, weight and margin. A body compiled
+ * without this file renders as a run of identical lines, which is what a blog
+ * post looked like through 3.9.0.
+ *
+ * OPT-IN, and imported once. The package ships no stylesheet of its own and
+ * LayoutCore imports none, so nothing here reaches a brand until that brand's
+ * `globals.css` names it:
+ *
+ *   @import "@iterant/site-runtime/styles/markdown.css";
+ *
+ * Put the line AFTER `@import "tailwindcss"`. Everything below lives in the
+ * `base` layer, so it wins over Preflight by order and loses to every utility
+ * class: `class="markdown-body text-lg"` still reads as the site author wrote
+ * it, and a brand rule outside a layer overrides anything here.
+ *
+ * Colors, fonts, radius and border come from the `--it-*` and `--font-*` tokens
+ * a brand's `globals.css` defines, each with a fallback so the file also works
+ * in a repo that defines none. Two knobs are its own, settable on any ancestor:
+ *
+ *   --it-markdown-measure   the reading width (default 68ch; `none` to fill)
+ *   --it-markdown-flow      the space between blocks (default 1.25em)
+ */
+
+@layer base {
+  .markdown-body {
+    color: var(--it-text-primary, currentColor);
+    font-family: var(--font-body, inherit);
+    font-size: var(--font-size-base, 1rem);
+    font-weight: var(--font-body-weight, 400);
+    line-height: var(--font-body-line-height, 1.7);
+    max-width: var(--it-markdown-measure, 68ch);
+  }
+
+  /* The wrapper's own spacing belongs to the page around it. */
+  .markdown-body > :first-child {
+    margin-top: 0;
+  }
+
+  .markdown-body > :last-child {
+    margin-bottom: 0;
+  }
+
+  .markdown-body p {
+    margin: 0 0 var(--it-markdown-flow, 1.25em);
+  }
+
+  /* A body opens at `##` under the page's own h1, so h2 carries the section
+     weight here. h1 is styled anyway: a pasted body that starts at `#` should
+     read as a heading rather than as an outsized paragraph. */
+  .markdown-body h1,
+  .markdown-body h2,
+  .markdown-body h3,
+  .markdown-body h4 {
+    color: var(--it-text-primary, currentColor);
+    font-family: var(--font-heading, inherit);
+    font-weight: var(--font-heading-weight, 700);
+    letter-spacing: var(--font-heading-letter-spacing, normal);
+    line-height: var(--font-heading-line-height, 1.2);
+    margin: 2em 0 0.6em;
+    text-wrap: balance;
+  }
+
+  .markdown-body h1 {
+    font-size: var(--font-size-3xl, 1.875rem);
+  }
+
+  .markdown-body h2 {
+    font-size: var(--font-size-2xl, 1.5rem);
+  }
+
+  .markdown-body h3 {
+    font-size: var(--font-size-xl, 1.25rem);
+  }
+
+  .markdown-body h4 {
+    font-size: var(--font-size-lg, 1.125rem);
+  }
+
+  .markdown-body ul,
+  .markdown-body ol {
+    margin: 0 0 var(--it-markdown-flow, 1.25em);
+    padding-left: 1.5em;
+  }
+
+  .markdown-body ul {
+    list-style: disc;
+  }
+
+  .markdown-body ol {
+    list-style: decimal;
+  }
+
+  .markdown-body ul ul {
+    list-style: circle;
+  }
+
+  .markdown-body li {
+    margin-block: 0.35em;
+  }
+
+  .markdown-body li::marker {
+    color: var(--it-text-secondary, currentColor);
+  }
+
+  /* A nested list is part of its parent item, not a new block. */
+  .markdown-body li > ul,
+  .markdown-body li > ol {
+    margin-block: 0.35em;
+  }
+
+  .markdown-body li > p {
+    margin-bottom: 0.35em;
+  }
+
+  .markdown-body blockquote {
+    border-left: var(--border-width, 1px) var(--border-style, solid)
+      var(--it-border-primary, currentColor);
+    color: var(--it-text-secondary, currentColor);
+    margin: var(--it-markdown-flow, 1.25em) 0;
+    padding-left: 1.25em;
+  }
+
+  .markdown-body blockquote > :last-child {
+    margin-bottom: 0;
+  }
+
+  .markdown-body code {
+    font-family: var(--font-mono, ui-monospace, monospace);
+    font-size: 0.9em;
+  }
+
+  /* A code span is a chip; a fence is a surface. */
+  .markdown-body :not(pre) > code {
+    background-color: var(--it-background-secondary, transparent);
+    border-radius: calc(var(--radius, 0.5rem) / 2);
+    padding: 0.15em 0.4em;
+  }
+
+  .markdown-body pre {
+    background-color: var(--it-background-secondary, transparent);
+    border-radius: var(--radius, 0.5rem);
+    line-height: 1.55;
+    margin: var(--it-markdown-flow, 1.25em) 0;
+    overflow-x: auto;
+    padding: 1em 1.15em;
+  }
+
+  .markdown-body pre code {
+    background-color: transparent;
+    font-size: inherit;
+    padding: 0;
+  }
+
+  /* The link keeps the body's color: an accent token is a background color in
+     some brand palettes, and a link mid-sentence has to stay readable in all of
+     them. The underline is what marks it. */
+  .markdown-body a {
+    color: inherit;
+    text-decoration: underline;
+    text-decoration-thickness: from-font;
+    text-underline-offset: 0.2em;
+  }
+
+  .markdown-body a:hover {
+    text-decoration-thickness: 2px;
+  }
+
+  .markdown-body strong {
+    color: var(--it-text-primary, currentColor);
+    font-weight: var(--font-body-bold-weight, 600);
+  }
+
+  .markdown-body hr {
+    border: 0;
+    border-top: var(--border-width, 1px) var(--border-style, solid)
+      var(--it-border-primary, currentColor);
+    margin: 2.5em 0;
+  }
+
+  .markdown-body img {
+    display: block;
+    height: auto;
+    margin: var(--it-markdown-flow, 1.25em) 0;
+    max-width: 100%;
+  }
+
+  /* GFM tables. The table itself scrolls, so a wide one never widens the page. */
+  .markdown-body table {
+    border-collapse: collapse;
+    display: block;
+    font-size: 0.95em;
+    margin: var(--it-markdown-flow, 1.25em) 0;
+    max-width: 100%;
+    overflow-x: auto;
+    width: max-content;
+  }
+
+  .markdown-body th,
+  .markdown-body td {
+    border: var(--border-width, 1px) var(--border-style, solid)
+      var(--it-border-primary, currentColor);
+    padding: 0.5em 0.75em;
+  }
+
+  /* gfm writes `align` on a column the author aligned; only the rest defaults. */
+  .markdown-body th:not([align]),
+  .markdown-body td:not([align]) {
+    text-align: left;
+  }
+
+  .markdown-body th {
+    background-color: var(--it-background-secondary, transparent);
+    font-weight: var(--font-body-bold-weight, 600);
+  }
+}