@janga/norna 0.7.13 → 0.7.15

package/docs/site-files.md

@@ -0,0 +1,144 @@
+# Site Files
+
+Norna expects a defined set of files and directories. Their names and locations
+are part of the site model: following the structure lets Norna find content,
+presentation, configuration, routes, and assets without path configuration.
+
+The selected site directory is `site/` by default:
+
+```text
+site/
+|-- config.yaml
+|-- theme.yaml
+|-- sitewide-content.yaml
+|-- content.md
+|-- images/
+|   `-- <section-id>/
+|-- routes/
+|   `-- <NNN-route-id>/
+|       |-- content.md
+|       |-- theme.yaml
+|       `-- images/
+|           `-- <section-id>/
+|-- public/
+`-- .norna/
+    |-- generated-images.json
+    `-- public/
+```
+
+File and directory names shown literally above must use that exact lowercase
+spelling. This keeps sites portable between case-sensitive and
+case-insensitive file systems.
+
+## Root Files
+
+| Path | Required | Responsibility |
+| --- | --- | --- |
+| `config.yaml` | Yes | Public URL, language, and browser scroll behavior. |
+| `theme.yaml` | Yes | Complete visual preset and optional focused overrides. |
+| `sitewide-content.yaml` | No | Shared navigation identity, banners, and footer. |
+| `content.md` | Yes | Homepage metadata, sections, prose, and Norna blocks. |
+
+These responsibilities are deliberately separate:
+
+- [`config.yaml`](configuration.md) contains the few technical settings that
+  apply to the whole site.
+- [`theme.yaml`](theme.md) controls presentation. A normal file can contain
+  only a preset selection.
+- [`sitewide-content.yaml`](sitewide-content.md) contains editorial material
+  shared by every page.
+- [`content.md`](content.md) is the homepage page file and remains ordinary
+  Markdown with YAML frontmatter.
+
+Routes cannot provide `config.yaml` or `sitewide-content.yaml`. Technical
+configuration and shared identity have one site-wide source.
+
+## Images
+
+Managed homepage images belong in:
+
+```text
+site/images/<section-id>/
+```
+
+The directory name must match an explicit level 2 Markdown section id in
+`content.md`. Markdown blocks refer to managed images by filename, not by path.
+See [Images and Metadata](images-and-metadata.md) for supported formats,
+generated variants, and syncing.
+
+## Routes
+
+Each first-level route is one directory under `routes/`:
+
+```text
+site/routes/010-guide/
+|-- content.md
+|-- theme.yaml
+`-- images/
+    `-- intro/
+```
+
+`content.md` is required for a route. The optional route `theme.yaml` replaces
+the root visual theme for that route. Route images follow the same
+`images/<section-id>/` convention as homepage images.
+
+The three-digit route prefix controls navigation order and is not part of the
+URL. See [Routes](routes.md) for exact directory-name and route-id rules.
+
+## Public Files
+
+`site/public/` contains static files copied without image processing. Most
+names are site-owned, but Norna recognizes a small set of exact conventional
+filenames for the navigation logo and browser icons.
+
+See [Public Files](public-files.md) for logo and favicon filenames, arbitrary
+static files, root-relative links, and publishing paths.
+
+## Selecting The Site Directory
+
+Use `NORNA_SITE_DIR` or `norna --site-dir <path>` to select a site directory
+explicitly.
+
+Without an explicit selection, Norna first accepts the current directory when
+it contains both `config.yaml` and `content.md`. Otherwise it walks upward until
+it finds a default `site/` directory containing those two files.
+
+## Versioned Files
+
+Version the source files above together with:
+
+- `site/.norna/generated-images.json`, which records reusable managed-image
+  output;
+- `.github/workflows/deploy.yml`, when using the included GitHub Pages
+  publishing integration;
+- `package.json` and `package-lock.json`, which pin the local Norna engine and
+  project scripts.
+
+Source images and files under `site/public/` are also versioned site input.
+
+## Generated Files
+
+Do not edit these by hand:
+
+- `site/.norna/public/`: build-preparation output copied from `site/public/`,
+  plus generated or copied managed images;
+- `dist/`: final static website output;
+- `.astro/`: Astro cache, generated types, and local dev-server state.
+
+`norna site:public` removes stale copied static files from
+`site/.norna/public/` while preserving managed image output under its `images/`
+directory.
+
+## Engine Repository Layout
+
+These directories belong to the Norna engine repository, not to an ordinary
+site:
+
+- `bin/`: the launcher and public CLI dispatcher;
+- `scripts/`: validation, image, preview, publishing, and test tools;
+- `src/`: the Astro renderer, components, styles, and content schema;
+- `starters/`: source copied by `norna init`;
+- `examples/`: complete sites and focused feature demonstrations;
+- `fixtures/`: engine regression input;
+- root `site/`: the Norna introduction and documentation site.
+

package/docs/sitewide-content.md

@@ -1,38 +1,49 @@
-# Sitewide Content
+# `sitewide-content.yaml`
 
-`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.md`, which defines the public URL and optional language and scroll
-behaviour.
+`site/sitewide-content.yaml` is optional. It contains editorial content and
+identity shared by every page: the navigation label, banners, and footer.
 
-## Site identity
+The file contains plain YAML without Markdown frontmatter delimiters. Page
+sections do not belong here; they remain in each page's `content.md`.
 
-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`.
+## Navigation Identity
+
+Use the optional `navigation` object for identity shared by the homepage and
+all routes:
 
 ```yaml
 navigation:
-  brand: Example Site
+  label: Example Site
+```
+
+Without a navigation logo, `label` is shown in the home link. With a logo,
+`label` becomes the image alternative text. If omitted, Norna uses the homepage
+title from `site/content.md`.
+
+A logo file is discovered from `site/public/`; no path is configured here. Add
+`logo` only to override its displayed height:
+
+```yaml
+navigation:
+  label: 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.
+The logo width follows the file's intrinsic aspect ratio. See
+[Public Files: Navigation Logo](public-files.md#navigation-logo) for exact
+filenames, placement, portability, and validation rules.
+
+Routes inherit this identity and cannot replace it in route content or a route
+theme.
 
 ## 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:
+Use `banners` for short notices shown above page content on every route. List
+order controls presentation order. Each banner needs a unique lowercase `id`,
+a title, and text:
 
 ```yaml
----
 banners:
   - id: project-status
     tone: warning
@@ -41,26 +52,25 @@ banners:
       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.
+`tone` currently supports `warning`. `visible` is optional and uses the same
+date-window rules as temporary sections: `from` is inclusive and `until` is
+exclusive.
 
-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.
+Visitors can dismiss each active banner. Dismissal state is stored locally in
+the browser and tied to the banner content, so an edited banner can appear
+again. Keep banners concise; they are rendered as compact one-line notices and
+may use an ellipsis when space is limited.
 
 ## Footer
 
-The footer is also sitewide content. `copyrightMessage` adds a copyright or
-license sentence. `buildInfo` optionally adds a generated build timestamp:
+The footer can contain copyright or ownership text and optional generated build
+information:
 
 ```yaml
 footer:
-  copyrightMessage: (c) Example Artist.
+  copyrightMessage: (c) Example Owner.
   buildInfo:
     enabled: true
     text: Built
@@ -71,5 +81,9 @@ footer:
       timeStyle: short
 ```
 
-If both the copyright message and enabled build information are absent, the
-footer is not rendered.
+`dateTimeFormat` uses `Intl.DateTimeFormat` values. `timeZone` must be a valid
+IANA time-zone name. If both copyright text and enabled build information are
+absent, no footer is rendered.
+
+See [Site Files](site-files.md) for where this optional file belongs in the
+complete site model.

package/docs/theme.md

@@ -1,13 +1,12 @@
 # Theme
 
-`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.
+`site/theme.yaml` defines the site-wide visual theme for a Norna site. It is a
+required plain YAML file. The normal setup selects one complete theme preset
+and adds only focused overrides when needed.
 
-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`.
+An optional `theme.yaml` inside a route directory replaces the root visual
+theme for that route. Shared identity such as the navigation label and logo
+remains site-wide and belongs in `sitewide-content.yaml`.
 
 ## Theme Presets
 
@@ -22,22 +21,20 @@ Available complete theme presets are:
 - `statement`: airy spacing and stronger typography for short editorial
   content.
 
-A normal `theme.md` can be only:
+A normal `theme.yaml` can be only:
 
 ```yaml
----
 preset: documentation
----
 ```
 
 Each preset supplies coordinated values for:
 
 - layout density, page width, and gutters
 - managed image sizing
-- font family, typography preset, and typography rhythm
+- font family, typography profile, and typography rhythm
 - palette and section-surface behaviour
 
-The nested `typography.preset` setting documented below is a lower-level
+The nested `typography.profile` setting documented below is a lower-level
 typography choice. A top-level theme `preset` selects the complete visual
 system, including that typography choice.
 
@@ -47,18 +44,14 @@ Values written beside the top-level preset override only that part of the
 preset. Other preset values remain active:
 
 ```yaml
----
 preset: documentation
 layout:
   pageWidth: 1320px
-presentation:
-  palette: dark
----
+palette: dark
 ```
 
-Nested objects are merged by key. Arrays such as
-`presentation.sectionSurfaces.sequence` replace the preset array when they are
-specified.
+Nested objects are merged by key. `sectionSurfaces` replaces the preset array
+when it is specified.
 
 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
@@ -79,16 +72,17 @@ In a generated site, the equivalent npm command is:
 npm run norna:theme:export -- documentation
 ```
 
-The command creates `site/orig-documentation-theme.md`, or the corresponding
+The command creates `site/orig-documentation-theme.yaml`, 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
+Norna never loads `orig-*-theme.yaml`; only `theme.yaml` 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).
+label and logo display settings in `site/sitewide-content.yaml`; see
+[Sitewide Content](sitewide-content.md).
 
 ## Layout
 
@@ -155,7 +149,7 @@ before Markdown subheadings, paragraph spacing, and caption spacing, belongs to
 
 ## Image Sizing
 
-`gallery` is optional. It controls image sizing:
+`images` is optional. It controls managed image sizing:
 
 - `width`: hard maximum rendered image area width for images, captions, and
   aligned text.
@@ -166,7 +160,7 @@ before Markdown subheadings, paragraph spacing, and caption spacing, belongs to
 Example:
 
 ```yaml
-gallery:
+images:
   width: 900px
   maxAvailableWidthPercent:
     desktop: 100
@@ -184,7 +178,7 @@ desktop `74` / mobile `68`.
 Top-level `typography` is the site-wide typographic base. It supports:
 
 - `fontFamily`: global CSS font-family stack.
-- `preset`: built-in typography preset.
+- `profile`: built-in typography profile.
 - `rhythm`: text-near spacing profile. Allowed values are `compact`,
   `normal`, and `airy`.
 - `overrides`: focused changes to preset values.
@@ -194,7 +188,7 @@ Example:
 ```yaml
 typography:
   fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  preset: text-forward
+  profile: reading
   rhythm: normal
   overrides:
     headings:
@@ -211,38 +205,34 @@ typography:
       lineHeight: 1.55
 ```
 
-Use `norna typography presets` to inspect built-in preset and rhythm values,
+Use `norna typography profiles` to inspect built-in profile and rhythm values,
 and `norna typography show` to inspect the resolved typography for the
 selected site. See [Typography](typography.md).
 
-## Presentation
+## Palette And Section Surfaces
 
-`presentation` is optional. It selects a small built-in visual palette for the
-page frame and defines how section surfaces are assigned:
+`palette` and `sectionSurfaces` are optional top-level theme settings:
 
-- `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.
+- `palette`: `dark`, `light`, or `paper`. It coordinates page, navigation,
+  footer, and section colors.
+- `sectionSurfaces`: one to three unique values chosen from `base`, `soft`, and
+  `emphasis`. One value gives every section the same surface. Multiple values
+  cycle in the listed order.
 
 Example:
 
 ```yaml
-presentation:
-  palette: paper  # Alternatives: dark, light
-  sectionSurfaces:
-    mode: cycle
-    sequence: [base, soft, emphasis]
+palette: paper  # Alternatives: dark, light
+sectionSurfaces: [base, soft, emphasis]
 ```
 
 ## Route Themes
 
-Add `theme.md` to a route directory when that route should have a different
+Add `theme.yaml` to a route directory when that route should have a different
 visual expression:
 
 ```text
-site/routes/010-guide/theme.md
+site/routes/010-guide/theme.yaml
 ```
 
 The route theme uses the same visual schema and complete presets as the root
@@ -250,14 +240,12 @@ theme. A route can therefore select a different expression without repeating a
 large configuration:
 
 ```yaml
----
 preset: statement
----
 ```
 
 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
+than values from the root theme. It cannot define navigation identity or
 technical configuration.
 
 Section surfaces render as full-width horizontal bands while the section
@@ -268,7 +256,7 @@ accent color.
 
 ### Should every route select its own preset?
 
-No. A route without its own `theme.md` inherits the root theme, which is the
+No. A route without its own `theme.yaml` inherits the root theme, which is the
 normal choice when the site should keep one visual expression.
 
 Add a route theme only when the route should intentionally look different. If
@@ -278,6 +266,6 @@ necessary because a route theme replaces the root visual theme rather than
 merging with it.
 
 For example, a route demonstrating section surfaces may keep `preset: project`
-and change only `presentation.sectionSurfaces`. A route demonstrating media or
-content blocks should normally inherit the root preset so that the media or
-content remains the only variable being compared.
+and change only `sectionSurfaces`. A route demonstrating image or content
+blocks should normally inherit the root preset so that the blocks remain the
+only variable being compared.

package/docs/typography.md

@@ -1,50 +1,48 @@
 # Typography
 
-`norna` typography is configured in `site/theme.md` through a site-wide font,
-presets, text rhythm, and optional overrides.
+Norna typography is configured in `site/theme.yaml` through a site-wide font,
+profile, text rhythm, and optional overrides.
 
 The normal workflow is to select a complete top-level theme preset. It already
-chooses a coordinated font, typography preset, and rhythm:
+chooses a coordinated font, typography profile, and rhythm:
 
 ```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
+## Typography Profiles
 
-Available presets:
+Available profiles:
 
-- `quiet-gallery`: the default for image-led sites. Text is restrained and
+- `restrained`: the default for image-led sites. Text is restrained and
   supports the images without dominating the page.
-- `compact-gallery`: tighter typography for many sections, many images, or
+- `dense`: tighter typography for many sections, many images, or
   short information blocks.
-- `text-forward`: more generous body text for pages where longer text carries
+- `reading`: more generous body text for pages where longer text carries
   more of the experience.
 - `statement`: tighter, more declarative line-height for short programmatic
-  statements. Use it sparingly, usually as a page or section exception.
+  statements. Use it sparingly, usually as a route-level exception.
 
 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`.
+omitted, the engine default is `restrained`.
 
-Presets define alignment, size, weight, and line height for `headings.h1`
+Profiles 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:
+The profiles 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,
+- `restrained` uses restrained heading weights and a normal reading width.
+- `dense` uses stronger headings and a wider text column for short,
   scannable content.
-- `text-forward` uses a narrower reading width and more generous body line
+- `reading` 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.
@@ -53,15 +51,15 @@ The presets use these controls deliberately:
 Available rhythms are `compact`, `normal`, and `airy`. Built-in rhythm values
 use `em` so spacing follows the rendered text size.
 
-Use this command to inspect the exact preset and rhythm values shipped with
+Use this command to inspect the exact profile and rhythm values shipped with
 the installed engine:
 
 ```sh
-norna typography presets
+norna typography profiles
 ```
 
 Use this command to inspect the effective values for the selected site after
-presets, rhythms, and overrides have been applied:
+profiles, rhythms, and overrides have been applied:
 
 ```sh
 norna typography show
@@ -76,7 +74,7 @@ also marked with `inherited: true`.
 ```yaml
 typography:
   fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  preset: quiet-gallery
+  profile: restrained
   rhythm: normal
   overrides:
     headings:
@@ -117,7 +115,7 @@ align:
 Allowed size values are `small`, `medium`, `large`, and `xlarge`. `medium` is
 the normal reading size. Use `small` for quieter supporting text, and use
 `large` or `xlarge` only when a page or section needs stronger emphasis.
-Each heading level uses its own scale, but follows the same principle:
+Each heading level uses its own scale but follows the same principle:
 `medium` is the normal size for that level. Norna may render the first section
 heading as an HTML `h1` for document structure, but its visual typography still
 follows the Markdown level the user wrote: `##` uses `headings.h2`.
@@ -156,13 +154,11 @@ The simplest route-specific typography change is to select a complete theme
 preset:
 
 ```yaml
-# site/routes/010-introduction/theme.md
----
+# site/routes/010-introduction/theme.yaml
 preset: statement
----
 ```
 
-A route-local `theme.md` replaces the root visual theme rather than inheriting
+A route-local `theme.yaml` replaces the root visual theme rather than inheriting
 from it. The complete preset supplies a coherent route theme without repeating
 the root values.
 
@@ -170,17 +166,15 @@ Use a nested typography choice when only the typographic character needs to be
 specified explicitly:
 
 ```yaml
-# site/routes/010-introduction/theme.md
----
+# site/routes/010-introduction/theme.yaml
 typography:
-  preset: statement
+  profile: statement
   rhythm: normal
----
 ```
 
 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
+image widths. Captions are normally centered, but `reading` uses
 left-aligned captions to support longer explanatory text.

package/examples/complete-sites/dog-shelter-multi-page/README.md

@@ -9,6 +9,14 @@ A small Norna site with a homepage and ordered routes for dogs and adoption.
 The dog photos are CC0 images by Bicanski, sourced from Pixnio. Attribution is
 included in the site footer even though the licence does not require it.
 
+<!-- norna-image-provenance:
+image: site/public/logo.svg
+source: AI-assisted, hand-authored SVG
+prompt: Create a compact horizontal dog shelter logo with a simple dog face in
+a house-shaped mark and the words Dog Shelter. Use flat vector shapes, a warm
+red accent, dark text, transparent background and no external assets.
+-->
+
 Run it from the Norna repository root:
 
 ```sh

package/examples/complete-sites/{dog-shelter-single-page/site/config.md → dog-shelter-multi-page/site/config.yaml}

@@ -1,3 +1 @@
----
 url: http://localhost:4321/
----

package/examples/complete-sites/dog-shelter-multi-page/site/sitewide-content.yaml

@@ -0,0 +1,6 @@
+navigation:
+  label: Dog Shelter
+  logo:
+    height: 3rem
+footer:
+  copyrightMessage: Dog Shelter example site. Dog photos by Bicanski, CC0, via Pixnio.

package/examples/complete-sites/dog-shelter-multi-page/site/{theme.md → theme.yaml}

@@ -1,3 +1 @@
----
 preset: project
----

package/examples/complete-sites/dog-shelter-single-page/README.md

@@ -9,6 +9,14 @@ A small Norna site with two homepage sections and no routes.
 The dog photos are CC0 images by Bicanski, sourced from Pixnio. Attribution is
 included in the site footer even though the licence does not require it.
 
+<!-- norna-image-provenance:
+image: site/public/logo.svg
+source: AI-assisted, hand-authored SVG
+prompt: Create a compact horizontal dog shelter logo with a simple dog face in
+a house-shaped mark and the words Dog Shelter. Use flat vector shapes, a warm
+red accent, dark text, transparent background and no external assets.
+-->
+
 Run it from the Norna repository root:
 
 ```sh

package/examples/complete-sites/{dog-shelter-multi-page/site/config.md → dog-shelter-single-page/site/config.yaml}

@@ -1,3 +1 @@
----
 url: http://localhost:4321/
----

package/examples/complete-sites/dog-shelter-single-page/site/sitewide-content.yaml

@@ -0,0 +1,6 @@
+navigation:
+  label: Dog Shelter
+  logo:
+    height: 3rem
+footer:
+  copyrightMessage: Dog Shelter example site. Dog photos by Bicanski, CC0, via Pixnio.