@janga/norna 0.7.18 → 0.7.23

package/docs/commands.md

@@ -1,189 +0,0 @@
-# Commands
-
-The `norna` binary is the stable command surface. Site repositories normally
-use starter npm scripts such as `npm run norna:content:check`; those scripts
-call the local `norna` binary from `node_modules/.bin`.
-
-Npm installation exposes the command as `norna` on macOS, Linux, and Windows
-through the package `bin` field. When a globally installed `norna` is started
-inside a project that declares and has installed its own `@janga/norna`
-dependency, the launcher delegates to that project-local version. If no
-project-local install is found, the version that was started continues running.
-
-The project-owned `norna:*` npm scripts are the portable default for both
-standalone and embedded sites. To use direct commands from an ordinary shell,
-install the launcher once:
-
-```sh
-npm install --global @janga/norna@latest
-```
-
-You can then use commands such as `norna dev`, `norna check`, and
-`norna build`. The launcher still delegates to the current project's locally
-installed and pinned Norna version.
-
-## CLI Commands
-
-```sh
-norna dev:local
-norna dev:lan
-norna dev:restart
-norna dev:status
-norna dev:logs
-norna dev:stop
-norna check
-norna config:check
-norna content:check
-norna content:sync
-norna theme:presets
-norna theme:export <preset>
-norna typography profiles
-norna typography show
-norna site:public
-norna images
-norna engine:update [version|latest]
-norna engine:version [--latest]
-norna init <target-dir> [--type standalone|embedded] [--site-dir <path>]
-norna build
-norna build:local
-norna deploy
-norna deploy:commit
-norna deploy:watch
-norna preview
-norna astro
-norna doctor
-```
-
-Global options:
-
-```sh
-norna --site-dir <path> <command>
-norna --help
-```
-
-`norna dev` is accepted as an alias for `dev:local`. `norna check` runs the
-configuration and content checks in sequence. `help`, `-h`, and `--help` print
-usage.
-
-## Starter npm Scripts
-
-The starter uses `norna:*` for norna-specific work. This avoids collisions
-when a Norna site is embedded inside a larger GitHub project
-whose own `build`, `test`, or deploy scripts mean something different.
-
-The stable project scripts are:
-
-```sh
-npm run norna:dev
-npm run norna:dev:lan
-npm run norna:dev:restart
-npm run norna:dev:status
-npm run norna:dev:logs
-npm run norna:dev:stop
-npm run norna:check
-npm run norna:config:check
-npm run norna:content:check
-npm run norna:sync
-npm run norna:theme:presets
-npm run norna:theme:export -- <preset>
-npm run norna:typography:profiles
-npm run norna:typography:show
-npm run norna:public
-npm run norna:images
-npm run norna:build
-npm run norna:build:local
-npm run norna:deploy
-npm run norna:deploy:commit
-npm run norna:deploy:watch
-npm run norna:doctor
-npm run norna:preview
-npm run norna:engine:update
-npm run norna:engine:version
-```
-
-The standalone starter also provides `npm run dev` and `npm run build` as
-convenience aliases. In mixed repositories, such as
-a GitHub project that embeds a Norna site next to an app, `build`
-should normally mean the repository's complete publishable artifact, while
-`norna:build` builds only the `norna` part.
-
-## Command Summary
-
-- `doctor`: prints resolved engine root, site project root, site directory,
-  content/config/image/public paths, generated manifest, Astro output paths, and
-  cache path.
-- `config:check`: validates `site/config.yaml` against the runtime config
-  reader.
-- `check`: runs `config:check` followed by `content:check`.
-- `content:check`: validates section structure, Norna block references,
-  inline styles, and common content mistakes.
-- `content:sync` / `norna:sync`: moves misplaced referenced image files after
-  confirmation when the intended move is unambiguous. Moving files between the
-  homepage and an additional page, or between additional pages, requires a clean Git working tree.
-- `theme:presets`: lists the available complete theme presets and explains the
-  intended use of each one.
-- `theme:export <preset>`: writes a protected, commented
-  `orig-<preset>-theme.yaml` reference under the selected site directory. The
-  available complete theme presets are `portfolio`, `documentation`,
-  `project`, and `statement`. Norna continues to load only `theme.yaml`.
-- `typography profiles`: prints the exact built-in values for typography
-  profiles and rhythms.
-- `typography show`: prints the selected site's resolved typography for the
-  theme, every page, and every section. Each value includes its source,
-  and inherited page or section values are marked with `inherited: true`.
-- `site:public`: copies `site/public/` into `site/.norna/public/` and
-  removes stale copied static files.
-- `images`: generates WebP variants for raster images, copies managed SVG
-  images, and writes `site/.norna/generated-images.json`.
-- `engine:update [version|latest]`: updates the site repository's
-  `@janga/norna` dependency with `npm install --save-exact`, normalizes
-  `package-lock.json` for the pinned GitHub Actions Linux/npm environment, and
-  verifies it with `npm ci --dry-run` before running config/content/build checks.
-  Use `--skip-checks` to skip only the site checks; lockfile normalization and
-  CI verification still run. Unless npm already has a cache configured, it uses
-  `node_modules/.cache/norna-npm` in the site project.
-- `engine:version [--latest]`: prints the declared site dependency, installed
-  engine version, engine root, Astro dependency, and installed Astro version.
-  With `--latest`, it also asks npm for the latest published engine version.
-- `init <target-dir> [--type standalone|embedded] [--site-dir <path>]`: creates a
-  standalone site project from the packaged starter, or adds a Norna site
-  directory plus `norna:*` scripts to an existing project in embedded mode.
-  Standalone setup pins `@janga/norna` to the version that created it.
-- `build`: runs config check, content check, public sync, image generation, and
-  Astro build.
-- `build:local`: runs `build` and restarts `dev:local`.
-- `dev:local`: starts Astro dev in background mode on `localhost:4321`. Pass
-  `--kill` to stop processes that are blocking the standard port before
-  starting.
-- `dev:lan`: starts the same server on all local network interfaces and prints
-  the IPv4 URL to open from another device on the same network. Stop it after
-  testing because it is accessible to that local network.
-- `dev:restart`, `dev:status`, `dev:logs`, `dev:stop`: manage the local dev
-  server tracked under `.astro/`.
-- `preview`: runs Astro preview with the `norna` Astro config.
-- `astro`: runs Astro with the `norna` Astro config.
-- `deploy`: discovers the GitHub repository and default branch, then builds and
-  publishes the already committed branch.
-- `deploy:commit`: older convenience flow that builds, stages allowed site
-  changes, commits, pushes, and checks Pages.
-- `deploy:watch`: follows the included `deploy.yml` GitHub Pages workflow run.
-
-## Deploy Watch Options
-
-`deploy:watch` accepts:
-
-```sh
---repo <owner/name>
---workflow <name>
---branch <name>
---sha <sha>
---site-url <url>
---interval <duration>
---timeout <duration>
---limit <count>
-```
-
-Durations may use `ms`, `s`, or `m`, for example `500ms`, `10s`, or `15m`.
-Without repository and branch options, Norna discovers the current GitHub
-repository and its default branch. Without `--sha`, the current `HEAD` is
-monitored.

package/docs/configuration.md

@@ -1,142 +0,0 @@
-# `config.yaml`
-
-Technical site configuration lives in the selected site's `config.yaml`; by
-default that is `site/config.yaml`. The file is required and contains plain
-YAML without Markdown frontmatter delimiters.
-
-A normal configuration needs only the public URL:
-
-```yaml
-url: https://example.com/
-```
-
-Norna deliberately keeps this file small. Visual choices belong in
-[`theme.yaml`](theme.md), shared editorial content belongs in
-[`sitewide-content.yaml`](sitewide-content.md), and page content belongs in
-[`pages/*/content.md`](content.md).
-
-## `url`
-
-- Purpose: canonical public URL and source of the site's deployment path.
-- Type: absolute `http` or `https` URL.
-- Required: yes.
-- Default: none.
-- Restrictions: no query string or fragment.
-
-Norna adds a trailing slash when omitted. The URL pathname becomes the base
-path for generated links, browser icons, and managed images, so there is no
-separate `basePath` setting.
-
-Root-hosted site or custom domain:
-
-```yaml
-url: https://example.com/
-```
-
-GitHub Pages project site:
-
-```yaml
-url: https://owner.github.io/repository-name/
-```
-
-In the second example, Norna derives `/repository-name/` as the base path.
-Root-relative Markdown links are prefixed when rendered.
-
-## `language`
-
-- Purpose: language tag on the root `<html lang="...">` element and selection
-  of Norna's built-in interface text.
-- Type: `en`, `sv`, or a regional tag such as `en-GB` or `sv-SE`.
-- Required: no.
-- Default: `en`.
-
-Norna 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 page
-would be misleading.
-
-Interface labels are part of the engine and are not configured individually.
-Editorial text remains in page content and `sitewide-content.yaml`.
-
-## `navigation`
-
-`navigation.mode` selects the site-wide navigation model:
-
-- `automatic`: choose from the discovered page and heading structure. This is
-  the default.
-- `sections`: navigate headings on a single page.
-- `top`: use the sticky top navigation for a shallow multi-page site.
-- `tree`: combine global top-level navigation with a local page hierarchy.
-
-```yaml
-url: https://example.com/
-navigation:
-  mode: automatic
-```
-
-Navigation behavior is technical and site-wide. It cannot be configured in
-`theme.yaml` or in an individual page. See [Pages](pages.md#navigation) for the
-relationship between Home, top-level pages, child pages, and headings.
-
-## `scrollBehavior`
-
-- Purpose: select native same-page anchor movement.
-- Type: `instant` or `smooth`.
-- Required: no.
-- Default: `instant`.
-
-Example using the browser's native smooth scrolling:
-
-```yaml
-url: https://example.com/
-scrollBehavior: smooth
-```
-
-Norna does not add a scripted scrolling implementation. Visitors whose system
-requests reduced motion always get immediate anchor movement.
-
-## Complete Example
-
-```yaml
-url: https://example.com/
-language: en-GB
-navigation:
-  mode: automatic
-scrollBehavior: instant
-```
-
-Run `norna config:check` after changing the file.
-
-## Publishing Discovery
-
-GitHub repository, default branch, and deploy workflow are not fields in
-`config.yaml`.
-
-`norna deploy` discovers the current GitHub repository and default branch
-through the authenticated GitHub CLI. Norna's included workflow file is
-`.github/workflows/deploy.yml`. `deploy:watch` accepts command-line overrides
-when a one-off run needs different operational values.
-
-See [Publishing](publishing.md) for the complete workflow.
-
-## Site Directory Selection
-
-The site directory is not configured in `config.yaml`.
-
-Use one of:
-
-```sh
-NORNA_SITE_DIR=presentation norna build
-norna --site-dir presentation build
-```
-
-If `NORNA_SITE_DIR` is set to an empty value, commands fail. Relative site
-directories are resolved by walking upward from the invocation directory until
-the selected directory contains `config.yaml` and
-`pages/000-home/content.md`.
-
-Without an explicit selection, the current directory itself can be the site
-directory when it contains those two files. Otherwise Norna walks upward for a
-default `site/` directory containing them.
-
-See [Site Files](site-files.md) for the complete source and generated layout.

package/docs/content.md

@@ -1,351 +0,0 @@
-# Content
-
-`site/pages/000-home/content.md` is the homepage file for a Norna site. Its Markdown H1 is
-the page title. Optional page metadata can be added in YAML frontmatter.
-
-Additional and nested pages use the same page model in a page directory under
-`site/pages/`. See [Pages](pages.md) for the directory and nesting rules.
-
-Site-wide visual defaults belong in [Theme](theme.md). Typography profiles and
-overrides are described in [Typography](typography.md). Technical site settings
-belong in [Configuration](configuration.md).
-
-## Page Title And Frontmatter
-
-Every page must contain exactly one Markdown H1. It must be the first heading,
-must not have a section id, and supplies the visible page title, HTML document
-title, and page label in site navigation:
-
-```md
-# My Site
-```
-
-Content between the H1 and the first H2 is the page introduction. It may
-contain prose and Norna blocks.
-
-Frontmatter is optional. When present, the content schema validates these
-top-level fields:
-
-- `page`: optional page metadata.
-- `navigation`: optional page-listing metadata. See [Pages](pages.md).
-
-`page` contains:
-
-- `description`: optional string. Used only as the page's HTML meta description
-  for search engines, link previews, and other metadata consumers. It is not
-  rendered as visible page content.
-
-Minimal homepage without metadata:
-
-```md
-# My Site
-
-Introductory text.
-
-## Work {#work}
-
-Text...
-```
-
-Homepage with a meta description:
-
-```md
----
-page:
-  description: A small Norna site.
----
-
-# My Site
-
-Introductory text.
-```
-
-## Sections
-
-Markdown level 2 headings define the page sections and their order:
-
-```md
-## About {#about}
-
-...
-
-## Work {#work}
-
-...
-
-## Contact {#contact}
-
-...
-```
-
-Norna derives a stable lowercase id from the heading text when no explicit id
-is present:
-
-```md
-## Work
-```
-
-Add an explicit id when a public anchor must remain stable even if the heading
-text changes:
-
-```md
-## Work {#work}
-```
-
-Explicit ids must match `^[a-z0-9-]+$`. Derived and explicit ids are used for
-anchors and section navigation; the visible label still comes from the heading
-text. H3 headings use the same derivation for deeper local navigation. If two
-headings on one page resolve to the same id, `content:check` reports the page
-and both headings instead of guessing.
-
-Markdown section content starts at the level 2 heading and continues until the
-next level 2 heading. `###` and `####` headings are body subheadings within the
-current section, not new sections.
-
-## Norna Blocks
-
-Norna-managed local images and cards are written in Markdown fenced blocks at
-the point where they should appear in the section. Markdown determines
-placement: move the fenced block in the page file to move the rendered image,
-carousel, or card list.
-
-### Image Stack
-
-Use `norna-image-stack` for one or more stacked images:
-
-````md
-```norna-image-stack
-- image: work.jpg
-  alt: A woven artwork on a white wall.
-  caption: Work in progress.
-```
-````
-
-### Image Carousel
-
-Use `norna-image-carousel` for a carousel:
-
-````md
-```norna-image-carousel
-- image: first.jpg
-  alt: First image.
-  caption: First caption.
-- image: second.jpg
-  alt: Second image.
-  caption: Second caption.
-```
-````
-
-### Card List
-
-Use `norna-card-list` for a list of compact cards. Cards can include text,
-managed images, links, and optional badge text:
-
-````md
-```norna-card-list
-layout: image-top
-flow: grid
-size: m
-width: normal
-
-- title: Adopt
-  text: Give a dog a new home.
-  image: adopt.svg
-  link: /adopt/
-  badge-text: Recommended
-- title: Foster
-  text: Help for a shorter period.
-  image: foster.svg
-```
-````
-
-Card-list options:
-
-- `layout`: `image-top`, `image-left`, or `image-right`.
-- `flow`: `grid` or `stack`.
-- `size`: `s`, `m`, `l`, or `xl`.
-- `width`: `text`, `narrow`, `normal`, or `wide`.
-
-Each card starts with `- title: Card title`. Card fields use two spaces of
-indentation. Supported fields are `text`, `image`, `link`, and `badge-text`.
-Each card must include at least one of `text`, `image`, or `link`.
-
-Each image entry supports:
-
-- `image`: required filename matching
-  `^[a-z0-9][a-z0-9.-]*\.(jpe?g|png|svg)$`.
-  It must be a filename, not a path.
-- `alt`: optional alt text. If omitted, Norna renders an empty alt attribute.
-- `caption`: optional caption.
-
-Start every image entry in image stacks and carousels with
-`- image: filename.jpg`. Optional fields use two spaces of indentation:
-
-````md
-```norna-image-stack
-- image: filename.jpg
-  alt: Optional alt text.
-  caption: Optional caption.
-```
-````
-
-Use three or more matching backticks or tildes for fenced blocks. If you need
-to document a Norna image block inside another Markdown code sample, make the
-outer fence longer than the inner fence:
-
-````md
-````
-```norna-image-stack
-- image: filename.jpg
-```
-````
-````
-
-`content:check` warns when carousel images have different aspect ratios. Exact
-matching proportions are recommended because mixed proportions can make the
-layout move while the user changes slides.
-
-SVG files are allowed in image stacks and carousels. When an SVG has a
-`viewBox` or numeric `width` and `height`, Norna uses that ratio in the same
-layout logic as raster images. SVG files without an intrinsic aspect ratio are
-rendered directly, but carousel usage produces a warning because stable slide
-sizing is less predictable.
-
-## Image Files
-
-Homepage images live under:
-
-```text
-site/pages/000-home/images/
-```
-
-Images for any page live directly under that page directory. For example:
-
-```text
-site/pages/010-guide/pages/020-installation/images/
-```
-
-Image references in Norna managed image blocks use only the filename:
-
-````md
-```norna-image-stack
-- image: portrait.jpg
-```
-````
-
-If `portrait.jpg` is referenced anywhere on the homepage, its expected
-location is `site/pages/000-home/images/portrait.jpg`. The same file may be referenced from
-more than one section on that page.
-
-Filenames must be unique within one page's image directory, but do not have to
-be globally unique across the site. Automatic sync only moves files between
-page image roots when the filename identifies exactly one source candidate
-across the site. If more than one candidate exists, Norna reports the
-ambiguity instead of guessing.
-
-## Markdown Images
-
-Markdown image syntax is allowed for external images and public static assets:
-
-```md
-![External image](https://example.com/image.jpg)
-![Public asset](/favicon.svg)
-```
-
-Relative local Markdown images such as `![Portrait](portrait.jpg)` are not
-managed by Norna. Use `norna-image-stack`, `norna-image-carousel`, or
-`norna-card-list` for local site images that should be validated, processed and
-synced.
-
-## Markdown Text
-
-Use ordinary Markdown for emphasis and structure:
-
-```md
-This sentence contains **important text** and *emphasised text*.
-```
-
-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 page visually coherent through its `theme.yaml`
-instead of styling individual phrases.
-
-### Side Notes
-
-Add one numbered side note to a paragraph by placing `{note-ref}` where its
-reference number should appear, then write the matching note on its own line
-immediately after the paragraph:
-
-```md
-Norna keeps the page source readable.{note-ref}
-
-{note: The note appears in the margin when enough horizontal space is available.}
-```
-
-Longer notes may wrap across lines and end with `}` on its own line:
-
-```md
-Norna keeps the page source readable.{note-ref}
-
-{note:
-The note may contain a longer explanation when the extra context is useful.
-}
-```
-
-On wide screens Norna places the note in the reading margin. On narrower
-screens it remains in the normal reading flow. A paragraph may contain one
-note pair; both `{note-ref}` and `{note: ...}` are required. `content:check`
-reports missing, repeated, nested, or unpaired note syntax.
-
-## Validation And Sync
-
-Run:
-
-```sh
-npm run norna:content:check
-```
-
-This checks section heading ids, duplicate image names,
-missing image files, misplaced referenced images, duplicate image references,
-invalid Norna 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 appears at the top level:
-
-```yaml
-navigation:
-  listed: false
-```
-
-Top-level page frontmatter may contain only `page` and `navigation`. Visual
-settings belong in the root or page-local `theme.yaml`.
-
-Run:
-
-```sh
-npm run norna:sync
-```
-
-This moves referenced image files into the image directory for the page that
-references them. Moving a block between sections on the same page does not
-move the file because all sections share the page image directory. The command
-prompts before writing unless `--yes` is passed.
-
-`content:sync` is intentionally conservative. It only moves a file when the
-filename identifies exactly one matching source candidate across all page
-image roots, and when the move will not break another reference.
-If the intended move is ambiguous, rename or move the file manually and run
-`content:check` again.
-
-The same filename may exist in different page image directories. Automatic
-relocation only requires site-wide filename uniqueness for the file being
-moved.
-
-When `content:sync` needs to move an image between the homepage and a page, or
-between two pages, the Git working tree must be clean before the write. This
-keeps cross-page sync easy to roll back. `content:check` only reports issues
-and does not require a clean working tree.