@janga/norna 0.7.10 → 0.7.12

package/docs/configuration.md

@@ -1,223 +1,125 @@
 # Configuration
 
-Technical site configuration lives in the selected site's `config.mjs`; by
-default that is `site/config.mjs`. The file must default-export an object.
+Technical site configuration lives in the selected site's `config.md`; by
+default that is `site/config.md`. The file contains YAML frontmatter only.
 
-This document describes the generic configuration interface. It does not list
-the current values for any one site.
+A normal configuration needs only the public URL:
 
-## Site
+```yaml
+---
+url: https://example.com/
+---
+```
+
+Norna deliberately keeps this file small. Visual choices belong in
+`theme.md`; shared identity, banners and footer content belong in
+`sitewide-content.md`.
 
-### `site.url`
+## `url`
 
-- Purpose: canonical public URL used in the page `<link rel="canonical">`,
-  deploy monitoring output, and site-specific documentation.
-- Type: string.
+- Purpose: canonical public URL and the source of the site's deployment path.
+- Type: absolute `http` or `https` URL.
 - Required: yes.
 - Default: none.
-- Validation: non-empty absolute URL accepted by `new URL()`.
-- Consequence: wrong values render a wrong canonical URL and make deploy
-  output point at the wrong site. For GitHub Pages project sites, include the
-  repository path in the URL, for example `https://owner.github.io/repo-name/`.
-
-Example:
+- Restrictions: no query string or fragment.
 
-```js
-site: {
-	url: 'https://example.com/',
-}
-```
-
-### `site.basePath`
+Norna adds a trailing slash when it is omitted. The URL pathname becomes the
+base path for generated links, favicons and managed images, so there is no
+separate `basePath` setting.
 
-- Purpose: URL path prefix used for generated internal page links, favicons,
-  generated image URLs, and root-relative links or images written in Markdown.
-- Type: string URL path.
-- Required: no.
-- Default: `/`.
-- Validation: must start and end with `/` and must not contain whitespace,
-  `?`, `#`, or `//`.
-- Consequence: use `/` for a root site or custom domain. Use
-  `/repository-name/` for a GitHub Pages project site without a custom domain.
-  Source Markdown can still use root-relative paths such as `/favicon.svg` or
-  `/getting-started/`; Norna prefixes them during rendering.
-
-Examples:
-
-```js
-site: {
-	url: 'https://example.com/',
-	basePath: '/',
-}
-```
+Root-hosted site or custom domain:
 
-```js
-site: {
-	url: 'https://janga.github.io/norna/',
-	basePath: '/norna/',
-}
+```yaml
+---
+url: https://example.com/
+---
 ```
 
-## Visual Theme
-
-Visual configuration lives in `site/theme.md`, not `site/config.mjs`.
-
-Use [Theme](theme.md) for:
-
-- `layout.pageWidth`
-- `layout.gutter`
-- `layout.density`
-- `gallery.width`
-- `gallery.maxAvailableWidthPercent`
-- `gallery.maxAvailableHeightPercent`
-- `typography.fontFamily`
-- typography presets, rhythm, and overrides
-- presentation palettes and section surfaces
-
-## Navigation
-
-### `navigation.smoothScroll`
-
-- Purpose: controls enhanced same-page anchor navigation and native
-  `scroll-behavior`.
-- Type: object.
-- Required: no; omitted fields use defaults.
-
-Fields:
-
-- `navigation.smoothScroll.enabled`: boolean, default `true`.
-- `navigation.smoothScroll.minimumDurationMs`: positive integer, default
-  `2000`.
-- `navigation.smoothScroll.maximumDurationMs`: positive integer, default
-  `4000`; must be greater than or equal to `minimumDurationMs`.
-- `navigation.smoothScroll.durationPerPixelMs`: positive number, default
-  `0.22`.
+GitHub Pages project site:
 
-When `enabled` is `false`, section links jump directly to anchors without the
-controlled animation. The no-JavaScript fallback keeps real `href="#section-id"`
-links.
-
-Example:
-
-```js
-navigation: {
-	smoothScroll: {
-		enabled: true,
-		minimumDurationMs: 600,
-		maximumDurationMs: 1_200,
-		durationPerPixelMs: 0.2,
-	},
-}
+```yaml
+---
+url: https://owner.github.io/repository-name/
+---
 ```
 
-## Locale And UI Labels
+In the second example, Norna derives `/repository-name/` as the base path.
+Root-relative links written in Markdown are prefixed when rendered.
 
-### `locale.lang`
+## `language`
 
-- Purpose: language tag rendered on the root `<html lang="...">` element.
-- Type: string language tag such as `en` or `sv`.
+- Purpose: language tag rendered on the root `<html lang="...">` element and
+  selection of Norna's built-in interface text.
+- Type: language tag such as `en`, `en-GB`, `sv` or `sv-SE`.
 - Required: no.
 - Default: `en`.
-- Validation: two or three letters, optionally followed by `-` separated
-  subtags.
-- Consequence: screen readers, browsers, and search engines use this to
-  interpret the page language.
-
-### `locale.labels`
-
-- Purpose: site-wide UI labels rendered by the engine for non-editorial
-  interface text.
-- Type: object.
-- Required: no; omitted labels use English defaults.
-
-Fields:
-
-- `locale.labels.skipToContent`: skip-link text, default `Skip to content`.
-- `locale.labels.siteNavigation`: site-level navigation ARIA label and mobile
-  menu group heading, default `Pages`.
-- `locale.labels.pageNavigation`: current-page section navigation ARIA label and
-  mobile menu group heading, default `On this page`.
-- `locale.labels.sectionNavigation`: legacy section navigation label, default
-  `Sections`.
-- `locale.labels.menu`: mobile menu summary text, default `Menu`.
-- `locale.labels.closeMenu`: reserved close-menu label, default `Close menu`.
-- `locale.labels.dismissBanner`: banner dismissal button label, default
-  `Dismiss notice`.
-- `locale.labels.siteBanners`: ARIA label for the banner stack, default
-  `Site notices`.
-- `locale.labels.gallery`: Norna managed media ARIA label prefix, default
-  `Images`.
-
-Example:
 
-```js
-locale: {
-	lang: 'sv',
-	labels: {
-		skipToContent: 'Hoppa till innehåll',
-		siteNavigation: 'Sidor',
-		pageNavigation: 'På denna sida',
-		sectionNavigation: 'Sektioner',
-		menu: 'Meny',
-		gallery: 'Bilder',
-	},
-}
-```
+Norna currently includes interface text for English and Swedish. Regional tags
+use the language identified by their primary subtag. An unsupported language is
+an error because silently rendering English controls on another-language pages
+would be misleading.
 
-## Sitewide Content
+Interface labels are part of the engine and are not configured individually.
+Editorial text remains in `content.md`, route content files and
+`sitewide-content.md`.
 
-Shared site identity, banners and footer content are defined in
-`site/sitewide-content.md`. See [Sitewide Content](sitewide-content.md) for the
-schema and examples.
+## `smoothScroll`
 
-## GitHub
+- Purpose: enables smooth same-page anchor movement.
+- Type: boolean.
+- Required: no.
+- Default: `false`.
 
-### `github.repo`
+Example:
 
-- Purpose: repository used by deploy checks and deploy monitoring.
-- Type: string in `owner/name` form.
-- Required: yes.
-- Default: none.
-- Validation: non-empty string.
+```yaml
+---
+url: https://example.com/
+smoothScroll: true
+---
+```
 
-### `github.branch`
+Norna uses the browser's native CSS scrolling behavior rather than a scripted
+animation. Visitors whose system requests reduced motion always get immediate
+anchor movement.
 
-- Purpose: deploy branch required by `norna deploy` and monitored by
-  `deploy:watch`.
-- Type: string.
-- Required: yes.
-- Default: none.
-- Validation: non-empty string.
+## Complete Example
 
-### `github.pagesWorkflow`
+```yaml
+---
+url: https://example.com/
+language: en
+smoothScroll: false
+---
+```
 
-- Purpose: GitHub Actions workflow name used by deploy checks and
-  `deploy:watch`.
-- Type: string.
-- Required: yes.
-- Default: none.
-- Validation: non-empty string.
+Do not add Markdown below the closing `---`; `config.md` is frontmatter-only.
+Run `npm run norna:config:check` after changing it.
 
-## Deploy Watch
+## Related Files
 
-### `deploy.watch`
+- [`theme.md`](theme.md) selects a complete presentation preset and optional
+  focused overrides.
+- [`sitewide-content.md`](sitewide-content.md) contains shared identity,
+  banners and footer content.
+- [`content.md`](content.md) and route content files contain page content.
 
-- Purpose: defaults for `norna deploy:watch`.
-- Type: object.
-- Required: no; omitted fields use defaults.
+## Publishing Discovery
 
-Fields:
+GitHub repository, default branch and deploy workflow are not site
+configuration fields.
 
-- `deploy.watch.intervalMs`: positive integer, default `10000`.
-- `deploy.watch.timeoutMs`: positive integer, default `900000`.
-- `deploy.watch.runLimit`: positive integer, default `10`.
+`norna deploy` discovers the current GitHub repository and its default branch
+through the authenticated GitHub CLI. Norna's included workflow file is
+`.github/workflows/deploy.yml`. `deploy:watch` accepts command-line overrides
+such as `--repo`, `--branch`, `--workflow`, `--interval`, `--timeout` and
+`--limit` when a one-off run needs different values.
 
-Command-line options such as `--interval`, `--timeout`, and `--limit` can
-override these values for one run.
+See [Publishing](publishing.md) for the complete workflow.
 
 ## Site Directory Selection
 
-The site directory is not configured in `config.mjs`.
+The site directory is not configured in `config.md`.
 
 Use one of:
 
@@ -228,9 +130,9 @@ norna --site-dir my-site build
 
 If `NORNA_SITE_DIR` is set to an empty value, commands fail. Relative site
 directories are resolved by walking upward from the invocation root until the
-selected directory contains `config.mjs` and `content.md`. Absolute site
+selected directory contains `config.md` and `content.md`. Absolute site
 directories are accepted and make their parent the site project root.
 
-When no site directory is explicitly selected, the current directory itself can
-be the site directory if it contains `config.mjs` and `content.md`. If not,
+When no site directory is explicitly selected, the current directory itself
+can be the site directory if it contains `config.md` and `content.md`. If not,
 Norna walks upward looking for a default `site/` directory with those files.

package/docs/content.md

@@ -269,14 +269,16 @@ NORNA_TODAY=2026-08-15 npm run norna:build
 
 ## Markdown Text
 
-Inline styles use this Markdown form:
+Use ordinary Markdown for emphasis and structure:
 
 ```md
-This sentence contains [highlighted text]{.highlight}.
+This sentence contains **important text** and *emphasised text*.
 ```
 
-Inline style definitions live in `site/theme.md`. See
-[Theme](theme.md#inline-styles).
+Norna intentionally does not support arbitrary inline color or style classes.
+Deprecated syntax such as `[highlighted text]{.yellow}` is rejected by
+`content:check`. Keep the route visually coherent through its `theme.md`
+instead of styling individual phrases.
 
 ## Validation And Sync
 
@@ -288,27 +290,25 @@ npm run norna:content:check
 
 This checks section heading ids, section metadata, duplicate image names,
 missing image files, misplaced referenced images, duplicate image references,
-invalid managed media blocks, unreferenced images, undefined inline styles,
+invalid managed media blocks, unreferenced images, removed inline style syntax,
 Markdown image references to unmanaged local files, and common frontmatter
 indentation and structure mistakes.
 
 Frontmatter uses YAML indentation. Use ordinary spaces, not tabs or
 non-breaking spaces. `content:check` reports a focused error when indentation is
 invalid, when a key is indented under a line that already has a value, or when a
-known nested key such as section-specific `typography` appears at the top
-level:
+known nested key appears at the top level:
 
 ```yaml
-presentation:
-  typography:
-    preset: quiet-gallery
-    overrides:
-      body:
-        paragraphSpacing: 0.8em
+sections:
+  intro:
+    visible:
+      from: "2026-08-01"
 ```
 
 Top-level page frontmatter may contain only `title`, `description`,
-`navigation`, `presentation`, `frame`, and `sections`.
+`navigation`, and `sections`. Visual settings belong in the root or route-local
+`theme.md`.
 
 Run:
 

package/docs/design/command-organization.md

@@ -295,7 +295,7 @@ Messages emitted by the engine should mention the direct CLI command and the
 starter-style npm wrapper when suggesting a fix.
 
 Configuration edits are normally manual edits to the selected site
-`config.mjs`, followed by:
+`config.md`, followed by:
 
 ```sh
 npm run norna:config:check

package/docs/design/norna-diagram-design.md

@@ -78,7 +78,8 @@ Diagrams must match the current Norna model:
 - Norna managed media blocks cover fixed site patterns such as image stacks,
   carousels, and card lists.
 - `theme.md` controls visual presentation.
-- `config.mjs` controls technical site configuration.
+- `config.md` controls the public URL and optional language and smooth
+  scrolling.
 - `dist/` is generated static output.
 - GitHub Pages is the integrated publishing target today.
 

package/docs/design/site-examples-structure.md

@@ -10,7 +10,8 @@ files are product documentation, which files are examples, and which files are
 test fixtures.
 
 The repository grew from one local demo, one starter, and a set of tests. The
-current structure keeps those roles separate.
+current structure keeps those roles distinct while allowing runnable examples
+to serve as documentation and realistic integration tests.
 
 ## Terms
 
@@ -26,8 +27,8 @@ site repository. It should not be a showcase for every feature.
 An example site is a runnable site that demonstrates one or more features.
 
 Examples can be richer than the starter. They may show routes, navigation,
-typography presets, typography rhythms, image stacks, image carousels, inline
-styles, and site-specific configuration choices.
+complete theme presets, image stacks, image carousels, cards, notes, surfaces,
+and site-specific configuration choices.
 
 ### Documentation Site
 
@@ -54,26 +55,40 @@ A fixture is test data.
 It should be minimal, stable, and optimized for regression tests rather than
 for human reading or visual appeal.
 
-## Intended Direction
+## Repository Structure
 
 Runnable site examples are collected under `examples/`:
 
 ```text
 examples/
-  dog-gallery/
-  routes-demo/
-  typography-demo/
+  complete-sites/
+    dog-shelter-single-page/
+    dog-shelter-multi-page/
+  feature-demos/
+    theme-presets/
+    media-and-surfaces/
+    sitewide-content/
 ```
 
-Only `dog-gallery/` exists today. Additional examples should be added when
-they demonstrate a distinct feature or workflow.
+`complete-sites/` contains coherent sites that show how Norna files work
+together in a realistic project:
 
-- `dog-gallery/`: current local visual demo, manual inspection site, and
-  navigation diagnostic target.
-- `routes-demo/`: focused route/navigation example if the dog example becomes
-  too broad.
-- `typography-demo/`: focused typography preset, rhythm, and override example
-  if needed.
+- `dog-shelter-single-page/`: sections and managed images without routes.
+- `dog-shelter-multi-page/`: ordered routes with route-local content and
+  images.
+
+`feature-demos/` contains focused visual test benches:
+
+- `theme-presets/`: one route per complete built-in theme preset, without
+  overrides.
+- `media-and-surfaces/`: managed media blocks, notes, palettes and section
+  surfaces. This is also the broad demo-build and navigation-test target.
+- `sitewide-content/`: convention-based identity, navigation, banner stacks,
+  dismissal and footer content shared across routes.
+
+The repository Pages workflow builds all examples and publishes them
+under `/norna/examples/`. The HTML documentation links to those rendered sites
+from its Examples route.
 
 The repository-local `site/` directory is reserved for the documentation site.
 `docs/` should remain for reference documentation. It should link to the
@@ -82,8 +97,8 @@ documentation site when visual explanation is more useful than reference text.
 `starters/basic/` stays separate from examples because it is copied by
 `norna init`. It should stay small and conservative.
 
-Fixtures may either stay under `fixtures/` or move under a clearly named test
-area later. They should not be confused with examples.
+Fixtures stay under `fixtures/`. They are intentionally smaller and more stable
+than examples and should not be confused with user-facing sites.
 
 ## Constraints
 
@@ -91,11 +106,10 @@ area later. They should not be confused with examples.
 - Do not make the documentation site the only documentation.
 - Do not let examples become required input for production site repositories.
 - Keep `norna init` deterministic and easy to test.
-- Keep engine tests using stable fixtures, not visually evolving demo content.
-
-## Open Decisions
+- Use examples for build, navigation and visual integration tests where the
+  user-facing site is the behavior being protected.
+- Use fixtures for isolated edge cases, invalid input and narrowly scoped
+  engine regressions.
 
-- Whether the documentation site should be published anywhere, or exist only as
-  a local/example build.
-- How local example selection should work when there are multiple runnable
-  examples.
+The repository-local `site/` remains the product documentation site and is not
+an example or fixture.

package/docs/engine-development.md

@@ -7,7 +7,8 @@ This document is for work on the reusable `norna` package itself.
 - `bin/norna.mjs`: public CLI launcher and local-version resolver.
 - `bin/norna-cli.mjs`: public CLI command dispatcher.
 - `scripts/lib/site-paths.mjs`: engine/site path resolution.
-- `scripts/lib/project-config.mjs`: `site/config.mjs` validation and defaults.
+- `scripts/lib/project-config.mjs`: frontmatter-only `site/config.md`
+  validation, defaults and derived URL path.
 - `scripts/sync-content-sections.mjs`: content validation and sync behavior.
 - `scripts/generate-images.mjs`: managed image pipeline and manifest.
 - `scripts/sync-site-public.mjs`: static public file sync.
@@ -19,8 +20,8 @@ This document is for work on the reusable `norna` package itself.
 - `tests/`: Playwright navigation diagnostics.
 - `fixtures/basic/site/`: minimal site used for engine checks.
 - `starters/basic/`: copyable site starter.
-- `examples/dog-gallery/site/`: visual dog example used by demo builds and
-  navigation diagnostics.
+- `examples/feature-demos/media-and-surfaces/site/`: broad visual example used
+  by demo builds and navigation diagnostics.
 
 The repository-local `site/` directory is reserved for a local documentation
 site. It is useful for dogfooding `norna` documentation, but it is not the
@@ -33,12 +34,25 @@ Run focused checks while developing:
 ```sh
 npm run test:content-check
 npm run test:site-public
+npm run test:documentation
 npm run test:fixture:build
+npm run test:examples
 npm run demo:build
 npm run package:check
 ```
 
-`npm run test` runs the standard non-demo check sequence.
+`npm run test:examples` builds every complete site and feature demo under
+`examples/`. `npm run test` includes those builds in the standard check
+sequence.
+
+`npm run test:documentation` extracts the file examples from the five-minute
+tutorial, applies them to a freshly initialized temporary site, runs the
+configuration and content checks, builds the result, and checks local Markdown
+links plus the `llms.txt` source targets.
+
+`npm run build:pages` is specific to this repository. It builds the
+documentation site and assembles rendered examples under `dist/examples/` for
+the shared GitHub Pages artifact. It is not a generic Norna site command.
 
 The root `site/` directory is the documentation site. Use the ordinary local
 commands for it:
@@ -48,12 +62,11 @@ npm run dev:local
 npm run build
 ```
 
-The dog example remains the visual demo and navigation diagnostic target:
+The media-and-surfaces feature demo is the broad visual and navigation
+diagnostic target:
 
 ```sh
-cd examples/dog-gallery/site
-node ../../../bin/norna.mjs dev:local
-cd ../../..
+node bin/norna.mjs --site-dir examples/feature-demos/media-and-surfaces/site dev:local
 npm run demo:build
 ```
 
@@ -182,11 +195,11 @@ history, back/forward moves between hash entries, and returning to the same page
 without a hash restores the first section as active. The enhancement does not
 derive active section state from free manual scrolling.
 
-The sticky navigation updates root scroll offset variables so direct hash links
-and clicked links land below the fixed header. Hash targets may be corrected
-again after layout shifts such as image loading, but that correction must not
-add history entries or change the active section independently of the URL hash.
+The sticky navigation updates a root scroll-offset variable so direct hash
+links and clicked links remain visible below the fixed header. The browser owns
+anchor movement; Norna does not run a separate scroll animation or retry anchor
+positions after later layout shifts.
 
-The shared layout reads UI language and labels from `site/config.mjs`
-`locale`. Keep editorial content in page Markdown and non-editorial engine UI
-labels in config.
+The shared layout selects Norna's built-in UI labels from the optional
+`language` in `site/config.md`. Keep editorial content in page Markdown and
+non-editorial engine UI labels in the engine language packs.