@janga/norna 0.7.18 → 0.7.22

package/starters/basic/README.md

@@ -34,7 +34,7 @@ Norna derives `/repository-name/` as the base path. Use a root URL such as
 
 In GitHub repository settings, configure Pages to build from GitHub Actions.
 
-Page width, side gutters, content spacing, image sizing, palette, shape, and
+Page width, side gutters, content spacing, image sizing, palette, corners, and
 site-wide typography are configured in `site/theme.yaml`. A page may use a
 limited `theme.yaml` for local text width, content spacing, managed-image
 sizing, and section background pattern.
@@ -65,7 +65,7 @@ Use `npm run norna:engine:version` to inspect the installed engine and
 
 Generic documentation lives in the `norna` repository:
 
-- `docs/getting-started.md`
+- `docs/README.md`
 - `docs/site-files.md`
 - `docs/public-files.md`
 - `docs/content.md`

package/docs/README.md

@@ -1,137 +0,0 @@
-# Norna Documentation
-
-The [Norna introduction site](https://janga.github.io/norna/) explains what the
-tool is for. These Markdown files are the authoritative tutorial, workflow
-guides, and reference.
-
-## Start Here
-
-1. [Build your first Norna site](getting-started.md) follows one short path from
-   an empty directory to a checked build.
-2. [Site Files](site-files.md) is the canonical map of every source file,
-   convention-based directory, and generated location.
-3. [Requirements and limitations](requirements.md) lists required software and
-   current product boundaries.
-4. [Examples](../examples/README.md) pairs complete and focused source projects
-   with rendered sites.
-
-Do not read the reference from beginning to end before trying Norna. Complete
-the tutorial, then open the reference for the file or workflow you are changing.
-
-## Site File Reference
-
-Norna expects this top-level source model:
-
-```text
-site/
-|-- config.yaml
-|-- theme.yaml
-|-- sitewide-content.yaml
-|-- pages/
-|   |-- 000-home/
-|   |   |-- content.md
-|   |   `-- images/
-|   `-- 010-guide/
-|       `-- content.md
-`-- public/
-```
-
-- [`config.yaml`](configuration.md): public URL, language, and native browser
-  scroll behavior.
-- [`theme.yaml`](theme.md): complete visual presets and focused presentation
-  overrides.
-- [`sitewide-content.yaml`](sitewide-content.md): shared logo display settings,
-  banners, and footer.
-- [`pages/`](pages.md): Home, top-level areas, nested pages, ordering, and URLs.
-- [`content.md`](content.md): the content file inside every page directory,
-  containing its title, optional metadata, sections, prose, notes, and blocks.
-- [`images/`](images-and-metadata.md): managed images kept inside the page that
-  references them, plus variants, sync, and generated image state.
-- [`public/`](public-files.md): navigation logos, favicons, and other static
-  files copied without managed-image processing.
-- [Generated files](site-files.md#generated-files): `site/.norna/public/`,
-  `dist/`, and `.astro/`.
-
-The [complete Site Files reference](site-files.md) explains which paths are
-required, optional, convention-discovered, versioned, or generated.
-
-## Common Workflows
-
-### Create And Run A Site
-
-- [Create a standalone site](getting-started.md#1-create-and-run-the-site)
-- [Add Norna to an existing Node project](how-to/embedded-site.md)
-- [Start and manage local preview](local-development.md)
-- [Inspect or update the installed engine](commands.md#command-summary)
-
-### Write Content
-
-- [Write page sections](content.md#sections)
-- [Use image stacks, carousels, and cards](content.md#norna-blocks)
-- [Add notes to prose](content.md#markdown-text)
-- [Add another page](pages.md)
-- [Add shared banners or footer content](sitewide-content.md)
-
-### Work With Images And Public Assets
-
-- [Add managed source images](images-and-metadata.md#managed-source-images)
-- [Check and sync moved image references](content.md#validation-and-sync)
-- [Add a navigation logo](public-files.md#navigation-logo)
-- [Add browser icons](public-files.md#browser-icons)
-- [Add other static files](public-files.md#other-static-files)
-
-### Change Presentation
-
-- [Choose a complete theme preset](theme.md#theme-presets)
-- [Inspect and override a preset](theme.md#overrides)
-- [Adjust limited presentation for a page subtree](theme.md#page-themes)
-- [Adjust typography](typography.md)
-
-### Check, Build, And Publish
-
-- [Run configuration and content checks](commands.md#starter-npm-scripts)
-- [Build and inspect generated output](site-files.md#generated-files)
-- [Publish through GitHub Pages](publishing.md#github-pages-workflow)
-- [Monitor or troubleshoot deployment](publishing.md)
-
-## Concepts And Explanation
-
-- [Norna's site model](https://janga.github.io/norna/concepts/) explains how
-  files, sections, images, and pages become a website.
-- [Images and Metadata](images-and-metadata.md) explains managed variants and
-  published URLs.
-- [Command Organization](design/command-organization.md) explains standalone,
-  embedded, and engine-development command models.
-- [Site Examples Structure](design/site-examples-structure.md) distinguishes
-  starters, examples, documentation sites, and fixtures.
-
-## Command And Platform Reference
-
-- [Commands](commands.md): CLI commands, npm scripts, and options.
-- [Requirements and limitations](requirements.md): runtime dependencies,
-  optional tools, and current boundaries.
-- [Publishing](publishing.md): GitHub Pages workflow and deploy helpers.
-
-## Troubleshooting
-
-- [Common first problems](getting-started.md#common-first-problems)
-- [Manage and restart local preview](local-development.md#manage-preview)
-- [Rebuild a stale preview](local-development.md#rebuild-stale-preview)
-- [Validate and sync content](content.md#validation-and-sync)
-- [Inspect publishing failures](publishing.md)
-- [Report a reproducible problem](https://github.com/janga/norna/issues)
-
-## Engine Contributors
-
-Start with [Engine Development](engine-development.md). Design documents live
-under [`docs/design/`](design/), and planned work is tracked in
-[BACKLOG.md](../BACKLOG.md).
-
-## AI-Readable Access
-
-The documentation source is Markdown and can be read directly from this
-repository. The published site also exposes
-[`llms.txt`](https://janga.github.io/norna/llms.txt), which links AI tools to
-the authoritative Markdown entry points rather than duplicating them.
-
-Norna is licensed under [GNU GPL v3](../LICENSE).

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.