@janga/norna 0.7.9 → 0.7.11

package/docs/sitewide-content.md

@@ -0,0 +1,74 @@
+# Sitewide Content
+
+`site/sitewide-content.md` contains content and settings shared by the whole site. It
+is separate from `content.md`, which defines the homepage, and from
+`config.mjs`, which defines technical behaviour.
+
+## Site identity
+
+Use the optional `navigation` object for identity shared by all pages. `brand`
+is the text shown in the home link when no logo is present. A logo is discovered
+from one convention-based file in `site/public`: `logo.svg`, `logo.png`,
+`logo.jpg`, or `logo.jpeg`.
+
+```yaml
+navigation:
+  brand: Example Site
+  logo:
+    alt: Example Site
+    height: 2.6rem
+```
+
+If `navigation.brand` is omitted, Norna uses the homepage `title` from
+`site/content.md`. The logo's width is derived from its intrinsic aspect ratio.
+If both a logo and a brand are present, the logo is displayed and the brand is
+used as its text fallback and accessible default.
+
+## Banners
+
+Use `banners` for short notices shown above the page content on every route.
+The list order controls the presentation order. Each banner needs a unique
+`id`, a title and text:
+
+```yaml
+---
+banners:
+  - id: project-status
+    tone: warning
+    visible:
+      from: "2026-08-01"
+      until: "2026-09-01"
+    title: Experimental code
+    text: Not for production use.
+---
+```
+
+`visible` uses the same date-window rules as temporary sections. Visitors can
+dismiss individual active banners. The dismissal is stored locally in the
+browser and is tied to the banner content, so an edited banner can appear
+again.
+
+The first version supports the `warning` tone. Keep banner text short; banners
+are presented as compact single-line notices and may use an ellipsis when the
+text does not fit.
+
+## Footer
+
+The footer is also sitewide content. `copyrightMessage` adds a copyright or
+license sentence. `buildInfo` optionally adds a generated build timestamp:
+
+```yaml
+footer:
+  copyrightMessage: (c) Example Artist.
+  buildInfo:
+    enabled: true
+    text: Built
+    dateTimeFormat:
+      locale: en-GB
+      timeZone: UTC
+      dateStyle: short
+      timeStyle: short
+```
+
+If both the copyright message and enabled build information are absent, the
+footer is not rendered.

package/docs/theme.md

@@ -1,69 +1,95 @@
 # Theme
 
-`site/theme.md` defines optional site-wide visual defaults for a `norna` site.
-It uses YAML frontmatter and does not need a Markdown body. If the file is
-missing, built-in engine defaults are used.
+`site/theme.md` defines the site-wide visual theme for a `norna` site. It uses
+YAML frontmatter and does not need a Markdown body. The root theme file is
+required. The normal setup selects one complete theme preset and adds only
+focused overrides when needed.
 
-Page-level presentation in `site/content.md` and route page files is always an
-override on top of `site/theme.md`. Section-level presentation is an override
-on top of the resolved page presentation. Use those overrides for focused
-exceptions; the normal place for shared visual choices is `site/theme.md`.
+An optional `theme.md` inside a route directory replaces the root visual theme
+for that route. Shared identity such as brand and logo remains site-wide and
+belongs in `sitewide-content.md`.
 
-## Minimal Theme
+## Theme Presets
+
+Available complete theme presets are:
+
+- `portfolio`: restrained typography and a broad image area for image-led
+  presentation.
+- `documentation`: reading-focused typography, a paper palette, and compact
+  structural rhythm.
+- `project`: compact layout and a light presentation for project and product
+  sites.
+- `statement`: airy spacing and stronger typography for short editorial
+  content.
+
+A normal `theme.md` can be only:
 
 ```yaml
 ---
-navigation:
-  brand: Example Site
+preset: documentation
+---
+```
+
+Each preset supplies coordinated values for:
+
+- layout density, page width, and gutters
+- managed image sizing
+- font family, typography preset, and typography rhythm
+- palette and section-surface behaviour
+
+The nested `typography.preset` setting documented below is a lower-level
+typography choice. A top-level theme `preset` selects the complete visual
+system, including that typography choice.
+
+## Overrides
+
+Values written beside the top-level preset override only that part of the
+preset. Other preset values remain active:
+
+```yaml
+---
+preset: documentation
 layout:
-  density: normal
-  pageWidth: 1180px
-  gutter:
-    desktop: clamp(1.25rem, 4vw, 3rem)
-    mobile: 1rem
-gallery:
-  width: 900px
-  maxAvailableWidthPercent:
-    desktop: 100
-    mobile: 100
-  maxAvailableHeightPercent:
-    desktop: 74
-    mobile: 68
-typography:
-  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  preset: quiet-gallery
-  rhythm: normal
+  pageWidth: 1320px
 presentation:
-  backgroundColor: "#000000"
-  textColor: "#f7f4ee"
-frame:
-  colors: presentation
+  palette: dark
 ---
 ```
 
-Starter sites include a marked comment block such as
-`norna:start theme-help` / `norna:end theme-help`. The block is only
-explorable help text; YAML comments do not affect rendering. The active
-configuration is the uncommented YAML below it.
+Nested objects are merged by key. Arrays such as
+`presentation.sectionSurfaces.sequence` replace the preset array when they are
+specified.
 
-## Navigation
+It is still valid to omit the top-level preset and define the visual settings
+explicitly. Omitted explicit settings then use engine defaults. This is useful
+for focused testing, but selecting a complete preset is the simpler normal
+workflow.
 
-`navigation` is optional. It currently supports:
+## Export A Preset
 
-- `brand`: optional site-wide brand or home-link text shown in the site
-  navigation.
+Export the installed definition of a preset before choosing overrides:
 
-If `navigation.brand` is omitted, Norna uses the homepage `title` from
-`site/content.md`. Use `navigation.brand` when the homepage title is editorial
-or route-specific, but the navigation should keep a stable site name.
+```sh
+norna theme:export documentation
+```
 
-Example:
+In a generated site, the equivalent npm command is:
 
-```yaml
-navigation:
-  brand: Norna
+```sh
+npm run norna:theme:export -- documentation
 ```
 
+The command creates `site/orig-documentation-theme.md`, or the corresponding
+path under the selected site directory. The file contains the preset values,
+comments describing accepted alternatives, and an example of a fine-grained
+typography override.
+
+Norna never loads `orig-*-theme.md`; only `theme.md` is active. The export
+command refuses to overwrite an existing reference file.
+
+Site identity is not part of the visual theme. Define the optional navigation
+brand and logo settings in `site/sitewide-content.md`; see [Sitewide Content](sitewide-content.md).
+
 ## Layout
 
 `layout` is optional. It controls the outer page geometry:
@@ -74,9 +100,9 @@ navigation:
   `desktop` / `mobile` values.
 - `density`: default structural spacing profile. Allowed values are `compact`,
   `normal`, and `airy`.
-- `spacing`: optional structural spacing overrides for sections and Norna
-  managed media blocks. Every spacing value accepts either one CSS length for all
-  viewports or `desktop` / `mobile` values.
+- `spacing`: optional spacing overrides for sections and content blocks. Every
+  spacing value accepts either one CSS length for all viewports or `desktop` /
+  `mobile` values.
 
 Example:
 
@@ -94,6 +120,12 @@ layout:
     sectionGap:
       desktop: clamp(1.4rem, 3vw, 2.75rem)
       mobile: 1.5rem
+    headingToBlock:
+      desktop: 0.75em
+      mobile: 0.7em
+    blockGap:
+      desktop: 1.5em
+      mobile: 1.25em
 ```
 
 If omitted, Norna uses `1180px` for `pageWidth`, desktop
@@ -105,11 +137,20 @@ Spacing keys:
 - `firstSectionTop`: space above the first section heading.
 - `sectionGap`: space above each following section.
 - `finalSectionBottom`: space below the final section.
-- `bodyToImages`: space from section body text to Norna managed media blocks.
+- `headingToBlock`: space between a section heading and its first visual content
+  block, such as an image stack, carousel, or card list.
+- `blockGap`: space between content blocks in a section. It applies between
+  Markdown, image, carousel, and card-list blocks, but not after the final block.
 - `imageGap`: space between stacked images or carousel blocks.
 
-Text-near spacing, such as spacing after headings, spacing before Markdown
-subheadings, paragraph spacing, and caption spacing, belongs to
+The default `compact`, `normal`, and `airy` density profiles provide values for
+these spacing keys. The `em` values for `headingToBlock` and `blockGap` are
+relative to the relevant text size, so the rhythm follows typography changes.
+Use `sectionGap` and the other structural keys when the distance should describe
+the page layout rather than the size of nearby text.
+
+Text-near spacing inside Markdown, such as spacing after headings, spacing
+before Markdown subheadings, paragraph spacing, and caption spacing, belongs to
 `typography.rhythm` and typography overrides.
 
 ## Image Sizing
@@ -153,18 +194,20 @@ Example:
 ```yaml
 typography:
   fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  preset: quiet-gallery
+  preset: text-forward
   rhythm: normal
   overrides:
     headings:
       h2:
         size: medium
+        weight: 600
         spacingAfter: 0.55em
       h3:
         size: medium
         spacingBefore: 1.5em
         spacingAfter: 0.5em
     body:
+      width: narrow
       lineHeight: 1.55
 ```
 
@@ -174,107 +217,49 @@ selected site. See [Typography](typography.md).
 
 ## Presentation
 
-`presentation` is optional. It can contain:
+`presentation` is optional. It selects a small built-in visual palette for the
+page frame and defines how section surfaces are assigned:
 
-- `backgroundColor`: optional quoted hex color in `#rgb`, `#rrggbb`, or
-  `#rrggbbaa` form.
-- `textColor`: optional quoted hex color in `#rgb`, `#rrggbb`, or
-  `#rrggbbaa` form.
-- `inlineStyles`: optional named inline text styles.
+- `palette`: `dark`, `light`, or `paper`. The palette controls the page,
+  navigation, footer, and section colors.
+- `sectionSurfaces.mode`: `none` or `cycle`.
+- `sectionSurfaces.sequence`: optional sequence of `base`, `soft`, and
+  `emphasis`. Each surface may occur at most once.
 
 Example:
 
 ```yaml
 presentation:
-  backgroundColor: "#101418"
-  textColor: "#f4f1ea"
-```
-
-## Page And Section Overrides
-
-Site-wide presentation belongs in `site/theme.md`. Page-level presentation in a
-page file is always an override on top of the theme:
-
-```yaml
-presentation:
-  typography:
-    overrides:
-      headings:
-        h2:
-          size: large
-          spacingAfter: 0.6em
-      body:
-        paragraphSpacing: 1em
-```
-
-Section-specific presentation belongs under
-`sections.<section-id>.presentation`. Use it when one section genuinely needs
-different presentation; do not use `sections` to define section order or normal
-Markdown structure.
-
-```yaml
-sections:
-  intro:
-    presentation:
-      backgroundColor: "#161616"
-      textColor: "#ffffff"
-      typography:
-        preset: statement
+  palette: paper  # Alternatives: dark, light
+  sectionSurfaces:
+    mode: cycle
+    sequence: [base, soft, emphasis]
 ```
 
-If a page omits `presentation`, it uses the theme presentation unchanged. If a
-section omits `presentation`, it uses the resolved page presentation.
-
-Configured section backgrounds render as full-width horizontal bands while the
-section content keeps the normal page and image widths. The top spacing
-before the first heading, the spacing between sections, and the spacing after
-the final section are part of the section background.
-
-Configured section text colors apply to section headings, Markdown text,
-Markdown subheadings, and image captions. Links keep the global accent color.
-
-## Frame Colors
+## Route Themes
 
-`frame.colors` controls the sticky navigation and footer colors.
+Add `theme.md` to a route directory when that route should have a different
+visual expression:
 
-Allowed values:
-
-- `presentation`: use the resolved presentation colors for this level.
-- `theme`: use the site theme frame colors. This is useful in page-level
-  frontmatter.
-- explicit colors:
-
-```yaml
-frame:
-  colors:
-    backgroundColor: "#111111"
-    textColor: "#eeeeee"
+```text
+site/routes/010-guide/theme.md
 ```
 
-The sticky section navigation row and footer use the resolved frame colors, not
-section-specific presentation.
-
-## Inline Styles
-
-`presentation.inlineStyles` defines named inline text styles that can be used
-from Markdown:
+The route theme uses the same visual schema and complete presets as the root
+theme. A route can therefore select a different expression without repeating a
+large configuration:
 
 ```yaml
-presentation:
-  inlineStyles:
-    highlight:
-      color: "#ffd84d"
+---
+preset: statement
+---
 ```
 
-Inline style names must match `^[a-z][a-z0-9-]*$`. Each style currently
-supports a required `color` field using the same quoted hex color format as
-`textColor`.
-
-Apply an inline style in Markdown with `[text]{.style-name}`:
-
-```md
-This sentence contains [highlighted text]{.highlight}.
-```
+It completely replaces the root visual theme for that route. If the route
+theme selects no top-level preset, omitted values use engine defaults rather
+than values from the root theme. It cannot define navigation, brand, logo, or
+technical configuration.
 
-`content:check` fails if Markdown uses an inline style that is not defined in
-`site/theme.md` `presentation.inlineStyles`.
+Section surfaces render as full-width horizontal bands while the section
+content keeps the normal page and image widths. Links keep the palette's global
+accent color.

package/docs/typography.md

@@ -3,12 +3,20 @@
 `norna` typography is configured in `site/theme.md` through a site-wide font,
 presets, text rhythm, and optional overrides.
 
-The normal place to choose a site-wide typography preset and rhythm is the
-top-level `typography` block in `site/theme.md`.
-Page and section files may override the theme when a focused exception is
-needed, but the normal workflow is to keep typography in `theme.md`.
+The normal workflow is to select a complete top-level theme preset. It already
+chooses a coordinated font, typography preset, and rhythm:
 
-## Presets
+```yaml
+---
+preset: documentation
+---
+```
+
+Use the nested `typography` block only when those typographic choices need to
+differ from the selected theme preset. Typography is configured at root-theme
+or route-theme level, not in page or section content.
+
+## Typography Presets
 
 Available presets:
 
@@ -21,13 +29,25 @@ Available presets:
 - `statement`: tighter, more declarative line-height for short programmatic
   statements. Use it sparingly, usually as a page or section exception.
 
-If theme typography is omitted, `quiet-gallery` is used.
+If a complete top-level theme preset is selected, that preset supplies the
+typography choice. If both the top-level preset and nested typography are
+omitted, the engine default is `quiet-gallery`.
 
-Presets define alignment, size, and line height for `headings.h1` through
-`headings.h4`, `body`, and `caption`. Built-in presets use `medium` as the
-default size for every text role. Visual heading hierarchy comes from the
-Markdown heading level, so `h1` is larger than `h2`, `h2` is larger than `h3`,
-and so on.
+Presets define alignment, size, weight, and line height for `headings.h1`
+through `headings.h4`, `body`, and `caption`. They also choose a readable body
+text width. Built-in presets use `medium` as the default size for every text
+role. Visual heading hierarchy comes from the Markdown heading level, so `h1`
+is larger than `h2`, `h2` is larger than `h3`, and so on.
+
+The presets use these controls deliberately:
+
+- `quiet-gallery` uses restrained heading weights and a normal reading width.
+- `compact-gallery` uses stronger headings and a wider text column for short,
+  scannable content.
+- `text-forward` uses a narrower reading width and more generous body line
+  height.
+- `statement` uses the strongest heading weights and a narrow text column for
+  short, declarative content.
 
 `rhythm` defines text-near spacing for headings, paragraphs, and captions.
 Available rhythms are `compact`, `normal`, and `airy`. Built-in rhythm values
@@ -62,12 +82,14 @@ typography:
     headings:
       h2:
         size: medium
+        weight: 600
         spacingAfter: 0.55em
       h3:
         size: medium
         spacingBefore: 1.5em
         spacingAfter: 0.5em
     body:
+      width: narrow
       paragraphSpacing: 0.8em
     caption:
       spacingBefore: 0.5em
@@ -104,56 +126,61 @@ follows the Markdown level the user wrote: `##` uses `headings.h2`.
 `spacingAfter`, and `paragraphSpacing` are CSS lengths such as `0`, `0.8em`,
 `1rem`, or `12px`. Use `em` for spacing that should track the text size.
 
+`weight` is a controlled heading weight. Allowed values are `400`, `500`,
+`600`, and `700`. `body.width` is the readable text width and accepts
+`narrow`, `normal`, or `wide`. It controls the prose column, not the page's
+maximum width or the width of image blocks.
+
 Supported override fields:
 
-- `headings.h1.align`, `headings.h1.size`, `headings.h1.lineHeight`,
+- `headings.h1.align`, `headings.h1.size`, `headings.h1.weight`,
+  `headings.h1.lineHeight`,
   `headings.h1.spacingBefore`, `headings.h1.spacingAfter`
-- `headings.h2.align`, `headings.h2.size`, `headings.h2.lineHeight`,
+- `headings.h2.align`, `headings.h2.size`, `headings.h2.weight`,
+  `headings.h2.lineHeight`,
   `headings.h2.spacingBefore`, `headings.h2.spacingAfter`
-- `headings.h3.align`, `headings.h3.size`, `headings.h3.lineHeight`,
+- `headings.h3.align`, `headings.h3.size`, `headings.h3.weight`,
+  `headings.h3.lineHeight`,
   `headings.h3.spacingBefore`, `headings.h3.spacingAfter`
-- `headings.h4.align`, `headings.h4.size`, `headings.h4.lineHeight`,
+- `headings.h4.align`, `headings.h4.size`, `headings.h4.weight`,
+  `headings.h4.lineHeight`,
   `headings.h4.spacingBefore`, `headings.h4.spacingAfter`
-- `body.align`, `body.size`, `body.lineHeight`, `body.paragraphSpacing`
+- `body.align`, `body.size`, `body.width`, `body.lineHeight`,
+  `body.paragraphSpacing`
 - `caption.align`, `caption.size`, `caption.lineHeight`,
   `caption.spacingBefore`
 
-## Inheritance
+## Route Themes
 
-Theme typography is the site-wide base:
+The simplest route-specific typography change is to select a complete theme
+preset:
 
 ```yaml
-# site/theme.md
-typography:
-  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  preset: quiet-gallery
-  rhythm: normal
+# site/routes/010-introduction/theme.md
+---
+preset: statement
+---
 ```
 
-A page-level `presentation.typography.preset` changes the typographic character
-for that page. A section-level
-`sections.<section-id>.presentation.typography.preset` changes the typographic
-character for that section. `rhythm` is inherited separately, so changing
-preset does not change spacing unless `rhythm` is also set.
-
-If a section sets `typography.rhythm`, that section changes text-near spacing.
-If a section only sets `typography.overrides`, it keeps the resolved page
-preset and rhythm and changes only the specified values.
+A route-local `theme.md` replaces the root visual theme rather than inheriting
+from it. The complete preset supplies a coherent route theme without repeating
+the root values.
 
-Example section override:
+Use a nested typography choice when only the typographic character needs to be
+specified explicitly:
 
 ```yaml
-sections:
-  intro:
-    presentation:
-      typography:
-        preset: statement
-        overrides:
-          body:
-            paragraphSpacing: 0.7em
+# site/routes/010-introduction/theme.md
+---
+typography:
+  preset: statement
+  rhythm: normal
+---
 ```
 
-Centered text uses narrower text widths. Left- or right-aligned heading and body
-text use the calculated image layout width so text edges line up with images
-after layout gutters and image limits are applied. Captions are normally
-centered.
+Without a top-level theme preset, other omitted route-theme values use engine
+defaults rather than values from the root theme.
+
+The `body.width` value controls the prose column independently of the page and
+image widths. Captions are normally centered, but `text-forward` uses
+left-aligned captions to support longer explanatory text.

package/examples/README.md

@@ -0,0 +1,41 @@
+# Norna examples
+
+Runnable examples are grouped by purpose.
+
+```text
+examples/
+|-- complete-sites/
+|   |-- dog-shelter-single-page/
+|   `-- dog-shelter-multi-page/
+`-- feature-demos/
+    |-- theme-presets/
+    `-- media-and-surfaces/
+```
+
+## Complete sites
+
+`complete-sites/` contains small sites that can be read as coherent examples
+of a Norna project.
+
+- `dog-shelter-single-page/` demonstrates a homepage made from sections.
+- `dog-shelter-multi-page/` adds ordered routes and route-local content.
+
+## Feature demos
+
+`feature-demos/` contains focused visual test benches. They are useful for
+documentation, manual inspection and integration checks, but are not intended
+as starter templates.
+
+- `theme-presets/` compares Norna's complete built-in theme presets.
+- `media-and-surfaces/` demonstrates managed media blocks, notes, palettes and
+  section surfaces.
+
+The repository's GitHub Pages workflow publishes rendered copies under
+`https://janga.github.io/norna/examples/` so the HTML documentation can link to
+working sites rather than only their source files.
+
+Run an example from the repository root by passing its `site/` directory:
+
+```sh
+node bin/norna.mjs --site-dir examples/feature-demos/media-and-surfaces/site dev:local
+```