@janga/norna 0.7.18 → 0.7.23

package/docs/publishing.md

@@ -1,117 +0,0 @@
-# Publishing
-
-Norna includes a GitHub Pages workflow and deploy helpers. The public URL is
-declared in `site/config.yaml`; repository and default branch are discovered from
-GitHub when a deploy command runs.
-
-Do not run deploy commands from the engine repository unless you deliberately
-want to deploy the documentation site.
-
-## GitHub Pages Workflow
-
-`norna init` creates the GitHub Pages workflow at exactly:
-
-```text
-.github/workflows/deploy.yml
-```
-
-The file belongs to the site repository. GitHub Actions runs its contents, while
-Norna's deploy helpers use the filename to find and monitor the workflow. Keep
-the default filename when using `norna deploy`.
-
-GitHub Actions itself permits other workflow filenames. If the file is renamed,
-`norna deploy:watch` can monitor it with `--workflow <name-or-file>`, but the
-normal `norna deploy` command still expects `deploy.yml`.
-
-The starter workflow:
-
-1. runs for the repository's default branch,
-2. checks out the site repository,
-3. sets up Node and image tools,
-4. restores the generated image cache,
-5. runs `npm ci` and `npm run norna:build`,
-6. uploads `dist/`,
-7. deploys the artifact to GitHub Pages.
-
-In the GitHub repository settings, set Pages to build from GitHub Actions.
-Site-specific public files such as `site/public/CNAME`, `robots.txt`, and
-`sitemap.xml` belong in the site repository. Norna copies them, while GitHub
-Pages, crawlers, and other external consumers give those filenames their
-meaning. See [Public Files](public-files.md).
-
-For a project site without a custom domain, include the repository path in
-`site/config.yaml`:
-
-```yaml
-url: https://owner.github.io/repository-name/
-```
-
-For a custom domain or root-hosted site:
-
-```yaml
-url: https://example.com/
-```
-
-Norna derives the base path from the URL pathname and applies it to generated
-internal links, favicons, managed images and root-relative Markdown links.
-
-## Deploy An Already Committed Branch
-
-Use:
-
-```sh
-npm run norna:deploy
-```
-
-The command requires an authenticated GitHub CLI. It asks GitHub for the
-current repository and its default branch, then:
-
-- requires the current branch to be that default branch,
-- requires a clean worktree before the build,
-- fetches `origin`,
-- refuses to proceed when the branch is behind or diverged,
-- runs the full build,
-- requires the build to leave the worktree clean,
-- pushes only when local `HEAD` is ahead of the remote branch,
-- checks the included `deploy.yml` GitHub Pages workflow.
-
-It does not create commits or push uncommitted changes.
-
-## Deploy With A Generated Commit
-
-The older convenience flow remains available:
-
-```sh
-npm run norna:deploy:commit -- "Commit message"
-```
-
-It discovers the same repository/default branch, builds, stages only allowed
-site changes, commits, pushes and checks Pages. The allowlist is implemented in
-`scripts/deploy-site.mjs` and includes site content and configuration, expected
-managed images and generated image state, public files, package files and
-renderer source changes.
-
-## Watch A Deploy
-
-Use:
-
-```sh
-npm run norna:deploy:watch
-```
-
-By default it monitors `deploy.yml` for the current `HEAD` in the discovered
-repository and default branch. Useful one-run overrides include:
-
-```sh
-npm run norna:deploy:watch -- --timeout 20m --interval 5s
-npm run norna:deploy:watch -- --sha <commit-sha>
-npm run norna:deploy:watch -- --repo owner/name --branch main
-```
-
-The default poll interval is 10 seconds, timeout is 15 minutes and recent-run
-limit is 10. `--workflow`, `--site-url` and `--limit` provide further one-run
-overrides; these operational values do not belong in `config.yaml`.
-
-The monitor prints the run id, run URL, Actions URL, branch, commit SHA, status
-and public site URL. On failures it fetches failed job details and a log
-excerpt.

package/docs/requirements.md

@@ -1,54 +0,0 @@
-# Requirements And Limitations
-
-This page separates requirements for ordinary site work from optional tooling
-and current product boundaries.
-
-## Required For Every Site
-
-- Node.js `22.12.0` or later.
-- npm or another package manager capable of installing the project-local
-  `@janga/norna` dependency. Generated standalone sites use npm scripts and a
-  committed `package-lock.json` by default.
-- A terminal and a text editor.
-
-## Required For Managed Raster Images
-
-ImageMagick is required when Norna reads raster image dimensions or generates
-responsive raster variants. Norna accepts either the current `magick` command
-or the older `identify` and `convert` commands.
-
-Static SVG images with an intrinsic aspect ratio are rendered directly and do
-not need raster variants. See [Images and Metadata](images-and-metadata.md) for
-the supported managed-image behavior.
-
-## Optional Tools
-
-- Git is strongly recommended for reviewing and restoring site changes. It is
-  used by the normal commit-and-push publishing workflow.
-- GitHub CLI (`gh`) is needed only for Norna's deploy status and monitoring
-  helpers.
-- Playwright Chromium is needed only for navigation diagnostics used while
-  developing the Norna engine.
-
-Neither GitHub CLI nor Playwright is required to edit, preview, check, or build
-an ordinary Norna site.
-
-## Current Product Boundaries
-
-- Norna builds generated static output into `dist/`.
-- GitHub Pages is the only publishing provider with an included integration.
-  Other static hosts can serve the generated files, but Norna does not
-  currently configure or publish to them.
-- Norna provides its own site model and presentation layer. A project does not
-  supply custom page templates, component trees, or rendering logic through
-  the normal site interface.
-- Norna is intended for content-driven websites. Dynamic applications,
-  database-backed publishing, and visual CMS editing are outside its current
-  scope.
-- Norna is pre-1.0. Breaking changes to files, configuration, and commands may
-  occur between releases and should be reviewed before updating a project.
-
-These constraints are part of the product's current scope, not hidden setup
-steps. Start with [the tutorial](getting-started.md), and use
-[`norna engine:version`](commands.md#command-summary) to inspect the version
-installed by an existing project.

package/docs/site-files.md

@@ -1,152 +0,0 @@
-# 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, pages, and assets without path configuration.
-
-The selected site directory is `site/` by default:
-
-```text
-site/
-|-- config.yaml
-|-- theme.yaml
-|-- sitewide-content.yaml
-|-- pages/
-|   |-- 000-home/
-|   |   |-- content.md
-|   |   `-- images/
-|   |       `-- image.jpg
-|   `-- 010-guide/
-|       |-- content.md
-|       |-- theme.yaml
-|       |-- images/
-|       |   `-- image.jpg
-|       `-- pages/
-|           `-- 010-installation/
-|               `-- content.md
-|-- 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 logo display settings, banners, and footer. |
-| `pages/` | Yes | Homepage, top-level pages, and nested page hierarchies. |
-
-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.
-- [`pages/000-home/content.md`](content.md) is the required homepage and remains
-  ordinary Markdown. YAML frontmatter is optional.
-
-Pages cannot provide `config.yaml` or `sitewide-content.yaml`. Technical
-configuration and shared logo, banner, and footer settings have one site-wide
-source.
-
-## Pages
-
-Every page is represented by a directory containing `content.md`. The homepage
-is the one reserved page:
-
-```text
-site/pages/000-home/content.md
-```
-
-It maps to `/`, cannot contain child pages, and appears first in global
-navigation. Other directories directly under `site/pages/` are top-level page
-roots:
-
-```text
-site/pages/010-guide/
-|-- content.md
-|-- theme.yaml
-|-- images/
-|   `-- image.jpg
-`-- pages/
-    `-- 010-installation/
-        |-- content.md
-        `-- images/
-            `-- diagram.svg
-```
-
-Nested `pages/` directories create child pages and may continue to further
-depths. Each page owns its optional `images/` directory. A page-local
-`theme.yaml` may adjust a limited set of presentation properties and is inherited
-by descendants; site colors, typography, shape, and navigation remain global.
-
-The three-digit page prefix controls sibling navigation order and is not part
-of the URL. See [Pages](pages.md) for hierarchy, URL, navigation, and page-theme
-rules. See [Images and Metadata](images-and-metadata.md) for managed files.
-
-## 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 navigation-logo and browser-icon
-filenames, GitHub Pages `CNAME`, 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 `config.yaml` and `pages/000-home/content.md`. Otherwise it walks
-upward until it finds a default `site/` directory containing those markers.
-
-## 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,73 +0,0 @@
-# `sitewide-content.yaml`
-
-`site/sitewide-content.yaml` is optional. It contains editorial content and
-optional logo display settings shared by every page: banners, footer, and an
-optional navigation-logo height override.
-
-The file contains plain YAML without Markdown frontmatter delimiters. Page
-sections do not belong here; they remain in each page's `content.md`.
-
-## Navigation Logo
-
-A logo file is discovered from `site/public/`; no path or site name is
-configured here. The logo links to the homepage, and its alternative text
-comes from the homepage Markdown H1 in `site/pages/000-home/content.md`.
-
-Add `logo` only to override the discovered file's displayed height:
-
-```yaml
-logo:
-  height: 2.6rem
-```
-
-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.
-
-The logo is a separate home link and does not have a section menu. In a
-multi-page site, the homepage remains the first ordinary navigation item, uses
-its Markdown H1 as its label, and exposes its sections in the same way as
-pages. Page content and page themes cannot replace the shared logo setting.
-
-## Banners
-
-Use `banners` for short notices shown above page content on every page. List
-order controls presentation order. Each banner needs a unique lowercase `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.
-```
-
-`tone` currently supports `warning`. `visible` is optional. `from` is inclusive
-and `until` is exclusive; both use `YYYY-MM-DD`, and either may be omitted.
-
-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 can contain copyright or ownership text and optional generated build
-information:
-
-```yaml
-footer:
-  copyrightMessage: (c) Example Owner.
-  buildInfo: true
-```
-
-Set `buildInfo` to `true` to show the generated build date and time. Norna uses
-the site's configured language, a compact format, and UTC. If both copyright
-text and 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,237 +0,0 @@
-# Theme
-
-`site/theme.yaml` defines the visual identity and default presentation for the
-whole Norna site. It is a required plain YAML file. The normal setup selects one
-complete preset and adds only focused overrides when they are needed:
-
-```yaml
-preset: documentation
-```
-
-The root theme owns site-wide colors, shapes, typography, page frame, and
-navigation presentation. An optional page-local `theme.yaml` has a deliberately
-smaller role described under [Page Themes](#page-themes).
-
-## Theme Presets
-
-Available complete 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.
-
-Each preset coordinates:
-
-- colors, shape, and typography
-- page width, gutters, text width, and content spacing
-- navigation spacing and visual treatment
-- managed-image sizing
-- section background sequence
-
-These coordinated values keep the site's identity consistent. Page themes
-cannot select another preset.
-
-## Overrides
-
-Values beside the root preset override only that part of the preset. Other
-preset values remain active:
-
-```yaml
-preset: documentation
-layout:
-  pageWidth: 1320px
-palette: dark
-```
-
-Nested objects are merged by key. It is valid to omit `preset` and define root
-settings explicitly, but a complete preset is the simpler normal workflow.
-
-## Export A Preset
-
-Export the installed definition before choosing overrides:
-
-```sh
-norna theme:export documentation
-```
-
-In a generated site, use:
-
-```sh
-npm run norna:theme:export -- documentation
-```
-
-The command creates `site/orig-documentation-theme.yaml`. The file contains the
-preset values, accepted alternatives, and example overrides. Norna never loads
-`orig-*-theme.yaml`; only `theme.yaml` is active. The command refuses to
-overwrite an existing reference file.
-
-Page titles and site-wide editorial content are not part of the visual theme.
-Optional logo display settings, banners, and the footer belong in
-[`sitewide-content.yaml`](sitewide-content.md).
-
-## Layout
-
-Root `layout` settings control the site frame and default content geometry:
-
-- `pageWidth`: maximum width of the full site layout, including local tree
-  navigation where present.
-- `gutter`: horizontal viewport gutter, either one CSS length or separate
-  `desktop` and `mobile` values.
-- `textWidth`: body-text line length: `narrow`, `normal`, or `wide`.
-- `contentSpacing`: vertical spacing between sections and structured blocks:
-  `compact`, `normal`, or `spacious`.
-- `spacing`: fine-grained structural spacing overrides.
-
-Example:
-
-```yaml
-preset: documentation
-layout:
-  pageWidth: 1320px
-  gutter:
-    desktop: clamp(1.25rem, 4vw, 3rem)
-    mobile: 1rem
-  textWidth: narrow
-  contentSpacing: compact
-  spacing:
-    firstSectionTop: 1.5rem
-    sectionGap:
-      desktop: 2.5rem
-      mobile: 1.5rem
-    headingToBlock: 0.75em
-    blockGap: 1.5em
-```
-
-Spacing keys are:
-
-- `firstSectionTop`: space above the first section heading.
-- `sectionGap`: space above each following section.
-- `finalSectionBottom`: space below the final section.
-- `headingToBlock`: space between a section heading and its first structured
-  block, such as an image stack, carousel, or card list.
-- `blockGap`: space between structured content blocks.
-- `imageGap`: space between images in an image stack.
-
-The `contentSpacing` profiles supply coordinated defaults for these values.
-Text-near spacing inside Markdown, including paragraph and subheading spacing,
-belongs to typography rhythm.
-
-The horizontal gap between tree navigation and page content is coordinated by
-the selected preset. It is intentionally not a separate public override.
-
-## Image Sizing
-
-`images` controls managed image sizing:
-
-- `width`: maximum rendered image-area width.
-- `maxAvailableWidthPercent`: maximum share of available horizontal space.
-- `maxAvailableHeightPercent`: maximum share of viewport height.
-
-Example:
-
-```yaml
-images:
-  width: 900px
-  maxAvailableWidthPercent:
-    desktop: 100
-    mobile: 100
-  maxAvailableHeightPercent:
-    desktop: 74
-    mobile: 68
-```
-
-Each responsive percentage may also be a single number.
-
-## Typography
-
-Root `typography` is site-wide. It supports:
-
-- `fontFamily`: global CSS font-family stack.
-- `profile`: `restrained`, `dense`, `reading`, or `statement`.
-- `rhythm`: `compact`, `normal`, or `airy`.
-- `overrides`: focused changes to headings, body text, and captions.
-
-Example:
-
-```yaml
-typography:
-  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  profile: reading
-  rhythm: normal
-  overrides:
-    headings:
-      h2:
-        size: medium
-        weight: 600
-        spacingAfter: 0.55em
-    body:
-      size: medium
-      lineHeight: 1.55
-```
-
-Use `norna typography profiles` to inspect built-in values and
-`norna typography show` to inspect the resolved site typography. See
-[Typography](typography.md) for every override field.
-
-## Palette And Section Surfaces
-
-These root settings are site-wide:
-
-- `palette`: `dark`, `light`, or `paper`.
-- `shape`: `square` or `soft`.
-- `sections.backgroundPattern`: `uniform`, `alternating`, or `cycling`.
-
-Example:
-
-```yaml
-preset: project
-palette: paper
-shape: soft
-sections:
-  backgroundPattern: cycling
-```
-
-The background pattern uses coordinated surfaces from the active palette. It
-does not let individual sections select arbitrary colors.
-
-## Page Themes
-
-Add `theme.yaml` to a non-home page directory only when that page or one of its
-descendants needs a narrower presentation adjustment:
-
-```text
-site/pages/010-guide/theme.yaml
-```
-
-A page theme may set only:
-
-- `layout.textWidth`
-- `layout.contentSpacing`
-- managed-image sizing under `images`
-- `sections.backgroundPattern`
-
-For example:
-
-```yaml
-layout:
-  textWidth: narrow
-  contentSpacing: compact
-images:
-  width: 760px
-sections:
-  backgroundPattern: uniform
-```
-
-Page settings are merged with the root theme and inherited by descendant pages.
-A more local page theme may override the same limited fields. Site colors,
-shape, typography, page width, gutters, and navigation remain constant.
-
-Page themes cannot define `preset`, `palette`, `shape`, `typography`,
-`navigation`, `config.yaml`, or site-wide content. This boundary keeps one
-recognisable site while still allowing a guide, gallery, or reference area to
-use an appropriate reading width and media presentation.