@janga/norna 0.7.11 → 0.7.12

package/README.md

@@ -1,126 +1,138 @@
-# norna
-
-`norna` is a reusable command-line toolchain for small static websites.
-It provides the CLI, Astro renderer, validation scripts, image pipeline,
-starter project, fixtures, and deploy helpers used by site repositories such as
-`www.walde.se`.
-
-Use this repository when you are:
-
-- creating a new site repository from the starter,
-- maintaining the reusable `@janga/norna` engine,
-- looking up the generic CLI, content, configuration, image, build, or deploy
-  behavior.
-
-Site-specific content, domain files, source images, and publication decisions
-belong in each site repository. For example, Karin Walde's site lives in
-`www.walde.se` and depends on a pinned version of this package.
-
-## Mental Model
-
-A `norna` site is file-driven:
-
-1. A site repository depends on this package.
-2. The site keeps technical settings, including public URL and optional URL
-   base path, in `site/config.mjs`.
-3. The site selects a complete visual preset, with optional focused overrides
-   for layout, image sizing, font, typography, palettes, and section surfaces,
-   in `site/theme.md`.
-4. The site keeps homepage content, Markdown section order, managed media
-   blocks, alt text, captions, and optional section metadata in
-   `site/content.md`.
-5. Optional route pages live under
-   `site/routes/<NNN-route-id>/route-content.md`.
-6. Source images live under `site/images/<section-id>/` for the homepage, or
-   under `site/routes/<NNN-route-id>/images/<section-id>/` for a route.
-7. Static public files live under `site/public/`.
-8. `norna` validates the files, prepares managed images, builds static Astro
-   pages, and can help publish the committed branch through GitHub Pages.
-
-The default site directory is `site/`. Commands can also use another directory
-with `NORNA_SITE_DIR` or `norna --site-dir <path>`. Without an explicit site
-directory, commands first accept the current directory when it contains
-`config.mjs` and `content.md`; otherwise they walk upward looking for a
-`site/` directory with those files.
+# Norna
 
-## Quick Start
+**Build responsive websites from Markdown, images, and a theme preset.**
 
-For engine development in this repository:
+Norna is an opinionated, open source CLI for building websites from plain
+files. You write the content, keep images beside the content they belong to,
+and choose a visual preset. Norna provides the page structure, navigation,
+responsive image output, validation, and static build.
 
-```sh
-npm install
-npm run dev:local
-npm run test:fixture:build
-npm run package:check
-```
+The result stays readable as source files and works naturally with Git and
+AI-assisted editing. Norna deliberately offers fewer architectural choices
+than a general-purpose site generator: you describe the site instead of
+implementing a new presentation layer for every project.
 
-For a new site repository:
+[Documentation](https://janga.github.io/norna/) |
+[Five-minute tutorial](docs/getting-started.md) |
+[Live examples](https://janga.github.io/norna/examples/) |
+[npm package](https://www.npmjs.com/package/@janga/norna)
+
+[![A multi-page dog shelter site with a logo, route navigation, text, a card, and a managed image.](docs/assets/norna-dog-shelter.jpg)](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/)
+
+The screenshot shows the built
+[multi-page example source](examples/complete-sites/dog-shelter-multi-page/).
+
+## Quick Start
+
+You need Node.js 22.12 or later.
 
 ```sh
-cd ../
 npx @janga/norna@latest init my-site
 cd my-site
 npm install
 npm run dev
 ```
 
-Run `init` before `npm install`. A new site directory is not a Node project
-until the starter has created its `package.json`; running `npm install` in an
-empty directory can make npm use a parent project instead. Keep real site
-repositories next to this engine repository, not inside it.
-
-The starter pins `@janga/norna` to an exact npm version. Commit the
-generated `package-lock.json` in the site repository so local builds and GitHub
-Actions use the same engine version.
-
-## Common Tasks
-
-- Create a site: [Getting Started](docs/getting-started.md)
-- Understand required site files: [Site Structure](docs/site-structure.md)
-- Edit sections and managed media blocks: [Content](docs/content.md)
-- Configure a site: [Configuration](docs/configuration.md)
-- Publish under a GitHub Pages project path:
-  [`site.basePath`](docs/configuration.md#sitebasepath)
-- Configure site-wide theme: [Theme](docs/theme.md)
-- Export a theme preset for inspection: [`theme:export`](docs/commands.md#command-summary)
-- Add route pages: [Routes](docs/routes.md)
-- Set page width: [`layout.pageWidth`](docs/theme.md#layout)
-- Set side gutters: [`layout.gutter`](docs/theme.md#layout)
-- Set image area width: [`gallery.width`](docs/theme.md#image-sizing)
-- Keep images within viewport height:
-  [`gallery.maxAvailableHeightPercent`](docs/theme.md#image-sizing)
-- Set the site font: [`typography.fontFamily`](docs/theme.md#typography)
-- Choose typography presets and overrides: [Typography](docs/typography.md)
-- Look up CLI and npm scripts: [Commands](docs/commands.md)
-- Understand generated images: [Images And Metadata](docs/images-and-metadata.md)
-- Run local preview: [Local Development](docs/local-development.md)
-- Publish a site: [Publishing](docs/publishing.md)
-- Work on the engine: [Engine Development](docs/engine-development.md)
-
-## Requirements
-
-- Node.js `>=22.12.0`.
-- ImageMagick, either `magick` or the older `identify` and `convert` commands,
-  when generating images locally.
-- GitHub CLI (`gh`) when using deploy checks or deploy monitoring.
-- Playwright Chromium when running navigation diagnostics.
-
-GitHub Pages workflows created from the starter install the image tools during
-deployment.
-
-## License
-
-`norna` is licensed under [GNU GPL v3](LICENSE).
+Open the URL printed by the development server, then edit the files under
+`site/`. The generated project pins its Norna version and includes the npm
+scripts and GitHub Pages workflow needed to check, build, and publish it.
+
+Follow the [five-minute tutorial](docs/getting-started.md) for a first edit and
+verified build.
+
+## The Site Model
+
+```text
+site/
+|-- config.md
+|-- theme.md
+|-- sitewide-content.md
+|-- content.md
+|-- images/
+|-- routes/
+`-- public/
+```
+
+- `content.md` holds the homepage and its sections.
+- `images/` holds managed source images beside the content they belong to.
+- `routes/` adds pages, each with content and optional local images and theme.
+- `theme.md` normally selects one complete visual preset.
+- `sitewide-content.md` holds shared identity, banners, and footer content.
+- `config.md` holds the public URL and optional language and scroll behavior.
+- `public/` holds static files copied without processing.
+
+Norna validates this structure, processes managed images when needed, and
+builds the generated website into `dist/`.
+
+## Why Norna?
+
+- **Useful defaults instead of a new layout project.** Presets coordinate
+  typography, spacing, palettes, image sizing, and section surfaces.
+- **Images without the repetitive work.** Norna creates responsive variants,
+  selects suitable browser sources, and reuses unchanged generated output.
+- **Files that remain manageable.** Content and assets can be inspected,
+  reviewed, versioned, and edited with the tools you already use.
+- **A complete publishing path.** The starter includes validation, static
+  builds, and an integrated GitHub Pages workflow.
+
+## Examples
+
+Every example is built in the repository test suite and published with the
+documentation.
+
+| Example | Live site | Source |
+| --- | --- | --- |
+| Dog shelter, single page | [Open demo](https://janga.github.io/norna/examples/complete-sites/dog-shelter-single-page/) | [View files](examples/complete-sites/dog-shelter-single-page/) |
+| Dog shelter, multi-page | [Open demo](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/) | [View files](examples/complete-sites/dog-shelter-multi-page/) |
+| Theme presets | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-presets/) | [View files](examples/feature-demos/theme-presets/) |
+| Media and surfaces | [Open demo](https://janga.github.io/norna/examples/feature-demos/media-and-surfaces/) | [View files](examples/feature-demos/media-and-surfaces/) |
+| Sitewide content | [Open demo](https://janga.github.io/norna/examples/feature-demos/sitewide-content/) | [View files](examples/feature-demos/sitewide-content/) |
+
+See [examples/README.md](examples/README.md) for what each example is intended
+to demonstrate and how to run it locally.
+
+## Is Norna A Good Fit?
+
+Norna is designed for sites that should be straightforward to edit, review,
+and publish without creating a custom presentation architecture. Typical uses
+include project and product sites, documentation, portfolios, personal sites,
+and organisation or information sites.
+
+Norna is not intended for dynamic applications, database-backed publishing,
+visual CMS workflows, or projects that need complete control over templates,
+components, and rendering logic.
+
+## Requirements And Current Limits
+
+- Node.js `>=22.12.0` is required.
+- ImageMagick is required when Norna generates responsive raster image variants.
+- GitHub Pages is the only publishing provider integrated by Norna today.
+- The build output is static and written to `dist/`; other static hosts can
+  serve that output, but Norna does not currently configure or publish to them.
+- Norna is pre-1.0 software. Its file model and CLI may still change between
+  releases.
+
+GitHub CLI and Playwright are needed only for specific deploy helpers and
+engine diagnostics, not for ordinary editing and local preview. See
+[Requirements and limitations](docs/requirements.md) for the exact boundaries.
 
 ## Documentation
 
-The Norna-built introduction site lives in [`site/`](site/) and is configured
-for GitHub Pages at <https://janga.github.io/norna/>.
+- [Five-minute tutorial](docs/getting-started.md)
+- [Task-oriented documentation map](docs/README.md)
+- [How-to guides](docs/README.md#how-to-guides)
+- [Concepts and explanation](docs/README.md#concepts-and-explanation)
+- [Technical reference](docs/README.md#reference)
+- [Troubleshooting](docs/README.md#troubleshooting)
+- [AI-readable documentation index](https://janga.github.io/norna/llms.txt)
+
+Engine contributors should start with
+[Engine Development](docs/engine-development.md). Planning and future work are
+tracked in [BACKLOG.md](BACKLOG.md).
 
-Start with [docs/README.md](docs/README.md) for the documentation map and
-recommended reading order.
+## Support And License
 
-Planning and future work are tracked in [BACKLOG.md](BACKLOG.md).
+Use the [issue tracker](https://github.com/janga/norna/issues) for reproducible
+bugs, documentation problems, and focused feature proposals.
 
-`AGENTS.md` contains operating rules for coding agents. Human-facing product
-and workflow documentation should live in this README and `docs/`.
+Norna is licensed under [GNU GPL v3](LICENSE).

package/bin/norna-cli.mjs

@@ -14,7 +14,7 @@ Commands:
   dev:status             Show local dev server status
   dev:logs               Show local dev server logs
   dev:stop               Stop local dev server
-  config:check           Validate site/config.mjs
+  config:check           Validate site/config.md
   content:check          Validate site/content.md and image references
   content:sync           Move misplaced Norna-managed images and refresh generated images
   theme:export           Export a commented theme preset reference

package/docs/README.md

@@ -1,75 +1,107 @@
-# norna Documentation
-
-This directory contains the reusable product and engine documentation for
-`norna`. The root README is the entry point; these files hold the details.
-
-## Recommended Reading
-
-For a site maintainer:
-
-1. [Getting Started](getting-started.md)
-2. [Site Structure](site-structure.md)
-3. [Theme](theme.md)
-4. [Sitewide Content](sitewide-content.md)
-5. [Configuration](configuration.md)
-6. [Content](content.md)
-7. [Typography](typography.md)
-8. [Routes](routes.md)
-9. [Images And Metadata](images-and-metadata.md)
-10. [Local Development](local-development.md)
-11. [Publishing](publishing.md)
-
-For a developer integrating or updating the engine:
-
-1. [Commands](commands.md)
-2. [Configuration](configuration.md)
-3. [Content](content.md)
-4. [Theme](theme.md)
-5. [Typography](typography.md)
-6. [Routes](routes.md)
-7. [Engine Development](engine-development.md)
-
-For design and naming principles:
-
-1. [Command Organization](design/command-organization.md)
-2. [Site Examples Structure](design/site-examples-structure.md)
-3. [Norna Diagram Design](design/norna-diagram-design.md)
-
-For a quick reference:
-
-- [Configuration](configuration.md) describes technical `site/config.mjs`
-  fields such as URL, base path, locale labels, GitHub, and deploy
-  settings.
-- [Sitewide Content](sitewide-content.md) describes shared site identity, banners
-  and footer content in `site/sitewide-content.md`.
-- [Content](content.md) describes page frontmatter, Markdown-authored
-  sections, optional section metadata, managed media blocks, temporary sections,
-  and content validation.
-- [Theme](theme.md) describes complete visual presets, focused overrides,
-  preset export, layout, image sizing, typography, palettes, and section
-  surfaces.
-- [Typography](typography.md) describes presets, rhythms, roles, overrides,
-  inheritance, and inspection commands.
-- [Routes](routes.md) describes route files, slugs, route navigation, and
-  route image directories.
-- [Commands](commands.md) lists the public CLI surface and starter npm scripts.
-- [Site Structure](site-structure.md) separates versioned source files from
-  generated build output.
-
-Design documents are intentionally separate from the user reference:
-
-- [Command Organization](design/command-organization.md) defines command
-  namespaces for standalone sites, mixed projects, and engine development.
-- [Site Examples Structure](design/site-examples-structure.md) defines the
-  intended vocabulary for starters, examples, documentation sites, reference
-  docs, and fixtures.
-- [Norna Diagram Design](design/norna-diagram-design.md) defines the first
-  experiment for technical and pedagogical diagrams without adding external
-  diagram tooling to the build pipeline.
-
-Site repositories should document only their site-specific choices and link here
-for generic `norna` behavior.
-
-`norna` is licensed under [GNU GPL v3](../LICENSE).
-
-Planning and future work are tracked in [../BACKLOG.md](../BACKLOG.md).
+# Norna Documentation
+
+Use this page to choose documentation by what you are trying to accomplish.
+The [Norna introduction site](https://janga.github.io/norna/) explains the
+product; these Markdown files provide the tutorial, task guides, explanation,
+and exact 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. [Requirements and limitations](requirements.md) states what must be
+   installed and what Norna does and does not support today.
+3. [Examples](../examples/README.md) pairs complete and focused source projects
+   with their rendered sites.
+
+Do not read the reference from beginning to end before trying Norna. Complete
+the tutorial, then use the task links below when a real site needs them.
+
+## How-To Guides
+
+### 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 And Organise Content
+
+- [Write page sections](content.md#sections)
+- [Use image stacks, carousels, and cards](content.md#managed-media-blocks)
+- [Add notes to prose](content.md#markdown-text)
+- [Add another page](routes.md)
+- [Add shared identity, banners, and a footer](sitewide-content.md)
+
+### Work With Images
+
+- [Add managed source images](images-and-metadata.md#managed-source-images)
+- [Place image blocks in Markdown](content.md#managed-media-blocks)
+- [Check and sync moved image references](content.md#validation-and-sync)
+- [Understand generated variants and SVG handling](images-and-metadata.md#generated-variants-and-static-svg)
+
+### Change The Presentation
+
+- [Choose a complete theme preset](theme.md#theme-presets)
+- [Inspect and override a preset](theme.md#overrides)
+- [Give a route a different theme](theme.md#route-themes)
+- [Adjust typography](typography.md)
+
+### Check, Build, And Publish
+
+- [Run content and configuration checks](commands.md#starter-npm-scripts)
+- [Build and inspect generated output](site-structure.md#generated-files)
+- [Publish through the included GitHub Pages workflow](publishing.md#github-pages-workflow)
+- [Monitor or troubleshoot a deployment](publishing.md)
+
+## Concepts And Explanation
+
+- [Norna's site model](https://janga.github.io/norna/concepts/) explains how
+  files, sections, images, and routes become a website.
+- [Site Structure](site-structure.md) separates source files, generated files,
+  examples, fixtures, and engine code.
+- [Images and Metadata](images-and-metadata.md) explains why Norna manages image
+  variants and published URLs.
+- [Command Organization](design/command-organization.md) explains the command
+  model for standalone sites, embedded sites, and engine development.
+- [Site Examples Structure](design/site-examples-structure.md) explains the
+  difference between starters, examples, documentation sites, and fixtures.
+
+## Reference
+
+- [Configuration](configuration.md): `site/config.md` fields and defaults.
+- [Sitewide Content](sitewide-content.md): shared identity, banners, and footer.
+- [Content](content.md): page frontmatter, sections, blocks, notes, and checks.
+- [Theme](theme.md): presets, overrides, layout, image sizing, and surfaces.
+- [Typography](typography.md): typography roles, rhythms, and inspection.
+- [Routes](routes.md): directory names, route IDs, URLs, and route images.
+- [Images and Metadata](images-and-metadata.md): source formats, variants, and
+  generated manifests.
+- [Commands](commands.md): CLI commands, npm scripts, options, and exit behavior.
+- [Requirements and limitations](requirements.md): runtime dependencies,
+  optional tools, and current product boundaries.
+
+## 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

@@ -101,7 +101,7 @@ should normally mean the repository's complete publishable artifact, while
 - `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.mjs` against the runtime config
+- `config:check`: validates `site/config.md` against the runtime config
   reader.
 - `content:check`: validates section structure, managed media references,
   inline styles, and common content mistakes.
@@ -148,10 +148,11 @@ should normally mean the repository's complete publishable artifact, while
   server tracked under `.astro/`.
 - `preview`: runs Astro preview with the `norna` Astro config.
 - `astro`: runs Astro with the `norna` Astro config.
-- `deploy`: builds and publishes an already committed deploy branch.
+- `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 a GitHub Pages workflow run.
+- `deploy:watch`: follows the included `deploy.yml` GitHub Pages workflow run.
 
 ## Deploy Watch Options
 
@@ -169,4 +170,6 @@ should normally mean the repository's complete publishable artifact, while
 ```
 
 Durations may use `ms`, `s`, or `m`, for example `500ms`, `10s`, or `15m`.
-Without `--sha`, the current `HEAD` is monitored.
+Without repository and branch options, Norna discovers the current GitHub
+repository and its default branch. Without `--sha`, the current `HEAD` is
+monitored.