@janga/norna 0.7.11 → 0.7.13

package/docs/getting-started.md

@@ -1,206 +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.
 
-The starter contains:
+## 2. Replace The Homepage Content
 
-- `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`
+Replace `site/content.md` with:
 
-Commit the generated `package-lock.json` after the first install.
+```md
+---
+title: My first Norna site
+description: A website built from plain files.
+---
 
-### Embedded Site
+## Welcome {#welcome}
 
-Use an embedded setup when a Norna site should live inside an existing Node or
-GitHub project:
+This page is written in Markdown. Norna provides its layout and navigation.
 
-```sh
-cd existing-project
-npx @janga/norna@latest init . --type embedded --site-dir presentation
-npm install
-npm run norna:dev
-```
+## Next {#next}
 
-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. Keep `site/theme.md` and select a complete theme preset. Add focused visual
-   overrides only when the preset needs adjustment.
-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:
-
-```sh
-npm run norna:config:check
-npm run norna:content:check
-npm run norna:sync
-npm run norna:check
-npm run build
+Edit this file while the development server is running and the browser updates.
 ```
 
-`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.
+Each `##` heading is a page section. Its explicit `{#section-id}` gives the
+section a stable identity and is required by Norna.
 
-Relevant documentation: [Content](content.md), [Theme](theme.md),
-[Typography](typography.md), [Routes](routes.md), [Images And Metadata](images-and-metadata.md).
+### Checkpoint: Content And Navigation Update
 
-## Choose A Theme
+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.
 
-The required root `theme.md` can be deliberately short:
+## 3. Set The Shared Brand
+
+Replace `site/sitewide-content.md` with:
 
 ```yaml
 ---
-preset: project
+navigation:
+  brand: My first Norna site
+footer:
+  copyrightMessage: My first Norna site.
 ---
 ```
 
-Available complete presets are `portfolio`, `documentation`, `project`, and
-`statement`. They coordinate layout, image sizing, font, typography, spacing,
-palette, and section surfaces.
+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
 
-Override only what the site needs to change:
+Replace `site/theme.md` with:
 
 ```yaml
 ---
 preset: project
-layout:
-  pageWidth: 1240px
 ---
 ```
 
-Export a commented reference for a preset with:
+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:theme:export -- project
+npm run norna:check
+npm run build
 ```
 
-The generated `site/orig-project-theme.md` is reference material and is not
-loaded by Norna. The command does not overwrite an existing reference file.
+The check should complete without errors. The build should create:
 
-Relevant documentation: [Theme](theme.md), [Typography](typography.md),
-[Commands](commands.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 overall visual expression, select a top-level preset in
-`site/theme.md`. Override individual page-width, gutter, image, typography, or
-palette values only where needed. See [Theme](theme.md) for the accepted shape.
+```sh
+npm run norna:content:check
+```
 
-To give a route a different visual expression, add a route-local `theme.md`
-and normally select another complete top-level preset. 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

@@ -13,7 +13,7 @@ an optional route-local `theme.md`. The route theme replaces the root visual
 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,7 +28,7 @@ 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 required. It can contain only a complete preset selection.
@@ -37,7 +37,7 @@ default `site/` directory containing those files.
 
 Version these files in a site repository:
 
-- `site/config.mjs`: technical site configuration.
+- `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.
@@ -75,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

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
 

package/docs/theme.md

@@ -263,3 +263,21 @@ technical configuration.
 Section surfaces render as full-width horizontal bands while the section
 content keeps the normal page and image widths. Links keep the palette's global
 accent color.
+
+## Common Questions
+
+### Should every route select its own preset?
+
+No. A route without its own `theme.md` inherits the root theme, which is the
+normal choice when the site should keep one visual expression.
+
+Add a route theme only when the route should intentionally look different. If
+the route should keep the same preset but demonstrate a focused change, repeat
+the root preset in the route theme and override only that setting. This is
+necessary because a route theme replaces the root visual theme rather than
+merging with it.
+
+For example, a route demonstrating section surfaces may keep `preset: project`
+and change only `presentation.sectionSurfaces`. A route demonstrating media or
+content blocks should normally inherit the root preset so that the media or
+content remains the only variable being compared.