@janga/norna 0.7.11 → 0.7.13

package/docs/configuration.md

@@ -1,224 +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:
-
-- complete theme presets and focused overrides
-- `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:
 
@@ -229,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/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

@@ -67,6 +67,7 @@ examples/
   feature-demos/
     theme-presets/
     media-and-surfaces/
+    sitewide-content/
 ```
 
 `complete-sites/` contains coherent sites that show how Norna files work
@@ -82,8 +83,10 @@ together in a realistic project:
   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 four examples and publishes them
+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.
 

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.
@@ -33,6 +34,7 @@ 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
@@ -43,6 +45,11 @@ npm run package:check
 `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.
@@ -188,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.