@janga/norna 0.7.10 → 0.7.12

package/docs/getting-started.md

@@ -1,171 +1,188 @@
-# Getting Started
+# Build Your First Norna Site
 
-This guide creates a new site repository from the included starter. It describes
-the generic `norna` setup; site-specific content belongs in the new site
-repository.
+This tutorial takes the shortest path from an empty directory to a running,
+edited, and verified Norna site. Follow the steps in order. Installation time
+depends on your npm connection, but the site work itself should take about five
+minutes.
 
-## Requirements
+At the end you will have:
 
-- Node.js `>=22.12.0`
-- ImageMagick for image generation
-- GitHub CLI (`gh`) for deploy checks and deploy monitoring
+- a standalone site project with a pinned Norna version,
+- a homepage with your own content and navigation,
+- a complete visual preset,
+- validated source files and a static build in `dist/`.
 
-Install Playwright Chromium only when you plan to run navigation diagnostics:
+## Before You Start
 
-```sh
-npx playwright install chromium
-```
+You need:
+
+- Node.js `22.12` or later,
+- npm, which is included with Node.js,
+- a terminal and a text editor.
 
-## Create A Site
+ImageMagick is needed when you add raster images that Norna should process. It
+is not needed to make the text-only first edit in this tutorial. GitHub CLI and
+Playwright are not required.
 
-### Standalone Site
+See [Requirements and limitations](requirements.md) for platform details and
+the current product boundaries.
 
-Use a standalone setup when the website is its own project. Create the site
-from the starter first, then install dependencies inside the new site
-directory:
+## 1. Create And Run The Site
+
+Run these commands from the directory where you keep projects:
 
 ```sh
-cd path/to/your/projects
 npx @janga/norna@latest init my-site
 cd my-site
 npm install
 npm run dev
 ```
 
-After `npm install`, the project's npm scripts use the project-local `norna`
-binary from `node_modules/.bin`. A globally installed `norna` can also be used
-as a convenience launcher; inside a project with an installed `@janga/norna`
-dependency, it delegates to the project's local version.
+`init` creates the project before `npm install` runs. The generated
+`package.json` pins the Norna engine version so this project keeps using the
+same version until you update it deliberately.
 
-A freshly created empty directory is not a `norna` site yet. It becomes a
-site when `init` copies the starter files, including `package.json`. If you run
-`npm install` in an empty directory, npm may walk up to a parent directory and
-install dependencies for another project instead.
+### Checkpoint: The Starter Is Visible
 
-For normal site work, keep site repositories as siblings of the `norna`
-engine repository. For example:
+Open the URL printed by the development server. It is normally
+`http://localhost:4321/`, but Norna uses another available port when necessary.
+You should see the starter homepage and its section navigation.
 
-```text
-Projects/
-  norna/
-  my-site/
+Leave the development server running while you complete the next steps.
+
+## 2. Replace The Homepage Content
+
+Replace `site/content.md` with:
+
+```md
+---
+title: My first Norna site
+description: A website built from plain files.
+---
+
+## Welcome {#welcome}
+
+This page is written in Markdown. Norna provides its layout and navigation.
+
+## Next {#next}
+
+Edit this file while the development server is running and the browser updates.
 ```
 
-The starter contains:
+Each `##` heading is a page section. Its explicit `{#section-id}` gives the
+section a stable identity and is required by Norna.
 
-- `package.json` with npm scripts that call `norna`
-- `.github/workflows/deploy.yml` for GitHub Pages
-- `site/config.mjs`
-- `site/theme.md`
-- `site/sitewide-content.md`
-- `site/content.md`
-- `site/public/robots.txt`
+### Checkpoint: Content And Navigation Update
 
-Commit the generated `package-lock.json` after the first install.
+Return to the browser. The page should now contain `Welcome` and `Next`, and
+the single-page navigation should link to those two sections. You should not
+need to restart the server.
 
-### Embedded Site
+## 3. Set The Shared Brand
 
-Use an embedded setup when a Norna site should live inside an existing Node or
-GitHub project:
+Replace `site/sitewide-content.md` with:
 
-```sh
-cd existing-project
-npx @janga/norna@latest init . --type embedded --site-dir presentation
-npm install
-npm run norna:dev
+```yaml
+---
+navigation:
+  brand: My first Norna site
+footer:
+  copyrightMessage: My first Norna site.
+---
+```
+
+The brand and footer are site-wide content rather than page sections. If you
+add routes later, they inherit these values.
+
+### Checkpoint: The Brand Is Shared
+
+The navigation should now display `My first Norna site`. The footer should show
+the new message.
+
+## 4. Choose A Complete Theme
+
+Replace `site/theme.md` with:
+
+```yaml
+---
+preset: project
+---
 ```
 
-The command looks different because the target is different. `.` means "add
-Norna to the current project" instead of creating a new directory.
-`--site-dir presentation` tells Norna to manage `presentation/` as the site
-directory instead of the default `site/`.
-
-Embedded setup keeps the surrounding project structure. It adds namespaced
-`norna:*` scripts so Norna does not take over the project's normal `build`,
-`test`, or deploy scripts.
-
-Relevant documentation: [Commands](commands.md), [Site Structure](site-structure.md).
-
-## First Edits
-
-1. Edit `site/config.mjs` for the site's URL, language labels, GitHub
-   repository, and deploy settings.
-2. Edit `site/sitewide-content.md` for the shared brand or logo, banners and
-   footer content.
-3. Edit `site/theme.md` for site-wide layout, layout density, typography
-   rhythm, image sizing, font, typography preset, palettes, and section
-   surfaces, or omit it to use engine defaults.
-4. Edit `site/content.md` for homepage title, description, Markdown sections,
-   text, Norna managed media blocks, alt text, and captions.
-5. Put source images under `site/images/<section-id>/`, where `<section-id>`
-   matches a `## Section {#section-id}` heading in `site/content.md`.
-6. Add optional route pages under
-   `site/routes/<NNN-route-id>/route-content.md`, for example
-   `site/routes/010-about/route-content.md`.
-7. Put static files such as `robots.txt`, `CNAME`, and favicons under
-   `site/public/`.
-8. Run:
+The preset supplies coordinated layout, typography, spacing, image sizing,
+palette, and section surfaces. Add overrides only when a real site needs to
+differ from the preset.
+
+### Checkpoint: The Preset Is Active
+
+The browser should refresh with the `project` presentation. Your content files
+remain unchanged because presentation belongs in `theme.md`.
+
+## 5. Check And Build
+
+Open another terminal in `my-site` and run:
 
 ```sh
-npm run norna:config:check
-npm run norna:content:check
-npm run norna:sync
 npm run norna:check
 npm run build
 ```
 
-`norna:sync` moves misplaced referenced image files when the intended move is
-unambiguous. It can move images between sections and routes, but cross-route
-writes require a clean Git working tree so the operation is easy to roll back.
-Publishing is normally done by committing the site files and pushing them with
-Git; the starter GitHub Pages workflow runs the required checks before
-publishing.
+The check should complete without errors. The build should create:
 
-Relevant documentation: [Content](content.md), [Theme](theme.md),
-[Typography](typography.md), [Routes](routes.md), [Images And Metadata](images-and-metadata.md).
+```text
+dist/
+```
 
-## Configure The Public URL
+`dist/` is generated output. Continue editing the files under `site/`; do not
+edit the built HTML as the source of the website.
 
-For a custom domain or any site published at the web root, use:
+### Checkpoint: The Source Produces A Clean Build
 
-```js
-site: {
-	url: 'https://example.com/',
-	basePath: '/',
-}
-```
+Confirm that both commands exit successfully and that `dist/index.html`
+exists. You now have a complete local Norna workflow: edit, preview, check, and
+build.
+
+## What To Do Next
 
-For a GitHub Pages project site without a custom domain, the site is served
-under the repository name. Configure both values:
+- [Add and manage images](content.md#managed-media-blocks)
+- [Add another page](routes.md)
+- [Inspect and adjust the theme](theme.md)
+- [Configure the public URL](configuration.md)
+- [Publish with GitHub Pages](publishing.md)
+- [Browse complete and focused examples](../examples/README.md)
 
-```js
-site: {
-	url: 'https://owner.github.io/repository-name/',
-	basePath: '/repository-name/',
-}
+To add Norna inside an existing Node project instead of creating a standalone
+site, see [Add an embedded site](how-to/embedded-site.md).
+
+The [documentation map](README.md) separates task guides, explanation, and
+reference so you can continue from the kind of question you have.
+
+## Common First Problems
+
+### The Default Port Is Occupied
+
+Start the development server with:
+
+```sh
+npm run dev -- --kill
 ```
 
-After that, content files may still use root-style internal links such as
-`/getting-started/` and `/favicon.svg`. Norna applies `site.basePath` during
-rendering so the built links work under the GitHub Pages project path.
+This tells Norna to stop the process occupying its standard port before
+starting. The separator `--` is required so npm forwards `--kill` to Norna.
+
+### Images Fail During Checking Or Building
 
-The starter includes a GitHub Pages workflow in `.github/workflows/deploy.yml`.
-In the GitHub repository settings, configure Pages to build from GitHub
-Actions.
+Install ImageMagick and confirm that either `magick` or the older `identify`
+and `convert` commands are available. Then rerun the failed command.
 
-Relevant documentation: [Configuration](configuration.md), [Publishing](publishing.md).
+### The Page Reports Invalid Content
 
-Read [Site Structure](site-structure.md), [Content](content.md),
-[Theme](theme.md), [Typography](typography.md), [Routes](routes.md), and
-[Configuration](configuration.md) before publishing a real site.
+Run:
 
-To change the site's maximum page width, side gutters, layout density,
-typography rhythm, image width, image height limits, font, palettes, or
-site-wide typography preset, edit `site/theme.md`. See [Theme](theme.md) for
-the accepted shape.
+```sh
+npm run norna:content:check
+```
 
-To give a route a different visual expression, add a complete route-local
-`theme.md`. See [Theme](theme.md#route-themes) and [Typography](typography.md).
-Use `norna typography presets` to inspect the installed preset and rhythm values
-and `norna typography show` to inspect the resolved typography for the selected
-site.
+Read all reported issues before editing. Norna reports file and line context
+for invalid sections and managed content blocks. See [Content](content.md) for
+the accepted Markdown forms.

package/docs/how-to/embedded-site.md

@@ -0,0 +1,35 @@
+# Add Norna To An Existing Project
+
+Use embedded setup when the website should live inside an existing Node
+project rather than in its own repository.
+
+From the existing project root, run:
+
+```sh
+npx @janga/norna@latest init . --type embedded --site-dir presentation
+npm install
+npm run norna:dev
+```
+
+The arguments are intentionally different from standalone setup:
+
+- `.` means that Norna should update the current project instead of creating a
+  new project directory.
+- `--type embedded` preserves the surrounding project's role and scripts.
+- `--site-dir presentation` puts the site source in `presentation/` instead of
+  the default `site/` directory.
+
+Embedded setup adds `@janga/norna` as a project dependency and adds namespaced
+`norna:*` npm scripts. It refuses to overwrite conflicting scripts or a
+non-empty target site directory.
+
+The surrounding project keeps its normal `build`, `test`, and deploy commands.
+Use the added commands for the embedded site:
+
+```sh
+npm run norna:check
+npm run norna:build
+```
+
+See [Commands](../commands.md) for the complete script list and
+[Site Structure](../site-structure.md) for source and generated files.

package/docs/publishing.md

@@ -1,52 +1,47 @@
 # Publishing
 
-Publishing is site-specific. The generic deploy commands read repository,
-branch, workflow, watch, and public URL settings from the selected site's
-`site/config.mjs`.
+Norna includes a GitHub Pages workflow and deploy helpers. The public URL is
+declared in `site/config.md`; 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 test the demo configuration.
+want to deploy the documentation site.
 
 ## GitHub Pages Workflow
 
-Each site repository should own its `.github/workflows/deploy.yml`. The starter
-workflow:
+Each site repository owns `.github/workflows/deploy.yml`. The starter workflow:
 
-1. checks out the site repository,
-2. sets up Node,
-3. installs image tools,
+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`,
-6. runs `npm run build` in the starter, which aliases
-   `npm run norna:build`,
-7. uploads `dist/`,
-8. deploys to GitHub Pages.
+5. runs `npm ci` and `npm run build`,
+6. uploads `dist/`,
+7. deploys the artifact to GitHub Pages.
 
-Site-specific static files such as `site/public/CNAME`, `robots.txt`, and
+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.
 
-In the GitHub repository settings, set Pages to build from GitHub Actions. For
-a project site without a custom domain, configure the site URL and base path in
-`site/config.mjs`:
+For a project site without a custom domain, include the repository path in
+`site/config.md`:
 
-```js
-site: {
-	url: 'https://owner.github.io/repository-name/',
-	basePath: '/repository-name/',
-}
+```yaml
+---
+url: https://owner.github.io/repository-name/
+---
 ```
 
-For a custom domain, keep `basePath` as `/`:
+For a custom domain or root-hosted site:
 
-```js
-site: {
-	url: 'https://example.com/',
-	basePath: '/',
-}
+```yaml
+---
+url: https://example.com/
+---
 ```
 
-Norna uses `site.basePath` for generated internal page links, favicons,
-generated images, and root-relative links or images written in Markdown.
+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
 
@@ -56,16 +51,17 @@ Use:
 npm run norna:deploy
 ```
 
-The deploy command:
+The command requires an authenticated GitHub CLI. It asks GitHub for the
+current repository and its default branch, then:
 
-- requires the current branch to equal `github.branch`,
-- requires a clean worktree before build,
+- 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 the local branch is ahead of `origin/<branch>`,
-- checks the configured GitHub Pages workflow.
+- 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.
 
@@ -77,11 +73,11 @@ The older convenience flow remains available:
 npm run norna:deploy:commit -- "Commit message"
 ```
 
-It builds, stages only allowed site changes, commits, pushes, and checks Pages.
-The allowlist is implemented in `scripts/deploy-site.mjs` and includes the
-site content file, selected config/static files, expected generated images,
-generated image manifest, package files, `tsconfig.json`, `astro.config.mjs`,
-and `src/` changes.
+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
 
@@ -91,14 +87,19 @@ Use:
 npm run norna:deploy:watch
 ```
 
-By default it monitors the workflow run for the current `HEAD` on the configured
-branch and repository. Useful one-run overrides include:
+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 monitor prints the run id, run URL, Actions URL, branch, commit SHA, status,
-and configured public site URL. On failures it fetches failed job details and a
-log excerpt.
+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.md`.
+
+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

@@ -0,0 +1,54 @@
+# 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/routes.md

@@ -10,9 +10,10 @@ for the page and section model.
 
 Route directories can contain route content, route-local images, and
 an optional route-local `theme.md`. The route theme replaces the root visual
-theme for that route. Route directories cannot contain technical site
+theme for that route and can select any complete top-level theme preset. Route
+directories cannot contain technical site
 configuration; technical configuration stays in the selected site directory's
-top-level `config.mjs`.
+top-level `config.md`.
 
 ## Route Directory Format
 

package/docs/site-structure.md

@@ -9,7 +9,7 @@ The selected site directory defaults to `site/`:
 
 ```text
 site/
-|-- config.mjs
+|-- config.md
 |-- theme.md
 |-- sitewide-content.md
 |-- content.md
@@ -28,18 +28,19 @@ site/
 
 Use `NORNA_SITE_DIR` or `norna --site-dir <path>` to select another
 site directory. Without an explicit site directory, commands first accept the
-current directory when it contains both `config.mjs` and `content.md`.
+current directory when it contains both `config.md` and `content.md`.
 Otherwise, commands started from a subdirectory walk upward until they find the
 default `site/` directory containing those files.
-`theme.md` is optional; omit it to use the engine's built-in visual defaults.
+`theme.md` is required. It can contain only a complete preset selection.
 
 ## Versioned Source Files
 
 Version these files in a site repository:
 
-- `site/config.mjs`: technical site configuration.
-- `site/theme.md`: optional site-wide visual theme, including layout, spacing,
-  image sizing, font, typography defaults, palettes, and section surfaces.
+- `site/config.md`: public URL and optional language and smooth scrolling.
+- `site/theme.md`: required site-wide visual theme. It normally selects a
+  complete preset and may add focused layout, image, typography, palette, or
+  section-surface overrides.
   See [Theme](theme.md).
 - `site/sitewide-content.md`: shared site identity, banners and footer content.
   See [Sitewide Content](sitewide-content.md).
@@ -74,7 +75,7 @@ Do not edit these by hand:
 
 Favicons are convention-based. Put files such as `favicon.svg`, `favicon.ico`,
 `favicon.png`, or `apple-touch-icon.png` in `site/public/`. The renderer emits
-icon links only for files that exist and prefixes them with `site.basePath`
+icon links only for files that exist and prefixes them with the base path
 when the site is published below a path such as `/repository-name/`.
 
 ## Engine Repository Layout
@@ -90,6 +91,8 @@ In this repository:
 - `starters/project/` is a project-site starter used as a maintained example
   for small project and developer-tool sites.
 - `fixtures/basic/site/` is used by engine regression tests.
-- `examples/dog-gallery/site/` is the local visual dog example used by demo
-  builds and navigation diagnostics.
+- `examples/feature-demos/media-and-surfaces/site/` is the broad visual example
+  used by demo builds and navigation diagnostics.
+- `examples/complete-sites/` contains coherent sites, while
+  `examples/feature-demos/` contains focused visual test benches.
 - `site/` is reserved for the local documentation site.

package/docs/sitewide-content.md

@@ -2,7 +2,8 @@
 
 `site/sitewide-content.md` contains content and settings shared by the whole site. It
 is separate from `content.md`, which defines the homepage, and from
-`config.mjs`, which defines technical behaviour.
+`config.md`, which defines the public URL and optional language and scroll
+behaviour.
 
 ## Site identity