@janga/norna 0.7.17 → 0.7.22

package/docs/design/site-examples-structure.md

@@ -1,115 +0,0 @@
-# Site Examples Structure
-
-This document defines the repository vocabulary for starter files, example
-sites, fixtures, and documentation sites.
-
-## Goal
-
-`norna` should make it easy to find runnable examples and understand which
-files are product documentation, which files are examples, and which files are
-test fixtures.
-
-The repository grew from one local demo, one starter, and a set of tests. The
-current structure keeps those roles distinct while allowing runnable examples
-to serve as documentation and realistic integration tests.
-
-## Terms
-
-### Starter
-
-A starter is a template copied by `norna init`.
-
-It should be small, conservative, and suitable as the first commit in a real
-site repository. It should not be a showcase for every feature.
-
-### Example Site
-
-An example site is a runnable site that demonstrates one or more features.
-
-Examples can be richer than the starter. They may show pages, navigation,
-complete theme presets, image stacks, image carousels, cards, notes, surfaces,
-and site-specific configuration choices.
-
-### Documentation Site
-
-A documentation site is a runnable `norna` site that explains the product
-visually.
-
-It can use images, diagrams, screenshots, and additional pages to explain concepts
-such as file structure, presentation inheritance, site navigation, and image
-handling.
-
-### Reference Documentation
-
-Reference documentation is GitHub-readable Markdown for exact interfaces and
-workflows.
-
-It belongs in `docs/` and should remain useful without building a site. It is
-the right home for command reference, configuration reference, content schema,
-publishing workflows, and engine development notes.
-
-### Fixture
-
-A fixture is test data.
-
-It should be minimal, stable, and optimized for regression tests rather than
-for human reading or visual appeal.
-
-## Repository Structure
-
-Runnable site examples are collected under `examples/`:
-
-```text
-examples/
-  complete-sites/
-    dog-shelter-single-page/
-    dog-shelter-multi-page/
-  feature-demos/
-    theme-presets/
-    media-and-surfaces/
-    sitewide-content/
-```
-
-`complete-sites/` contains coherent sites that show how Norna files work
-together in a realistic project:
-
-- `dog-shelter-single-page/`: sections and managed images without additional pages.
-- `dog-shelter-multi-page/`: ordered pages with page-local content and
-  images.
-
-`feature-demos/` contains focused visual test benches:
-
-- `theme-presets/`: one page per complete built-in theme preset, without
-  overrides.
-- `media-and-surfaces/`: image and card blocks, notes, palettes and section
-  surfaces. This is also the broad demo-build and navigation-test target.
-- `sitewide-content/`: convention-based logo handling, navigation, banner stacks,
-  dismissal and footer content shared across pages.
-
-The repository Pages workflow builds all examples and publishes them
-under `/norna/examples/`. The HTML documentation links to those rendered sites
-from its Examples page.
-
-The repository-local `site/` directory is reserved for the documentation site.
-`docs/` should remain for reference documentation. It should link to the
-documentation site when visual explanation is more useful than reference text.
-
-`starters/basic/` stays separate from examples because it is copied by
-`norna init`. It should stay small and conservative.
-
-Fixtures stay under `fixtures/`. They are intentionally smaller and more stable
-than examples and should not be confused with user-facing sites.
-
-## Constraints
-
-- Do not remove the starter concept; it has a different purpose from examples.
-- Do not make the documentation site the only documentation.
-- Do not let examples become required input for production site repositories.
-- Keep `norna init` deterministic and easy to test.
-- Use examples for build, navigation and visual integration tests where the
-  user-facing site is the behavior being protected.
-- Use fixtures for isolated edge cases, invalid input and narrowly scoped
-  engine regressions.
-
-The repository-local `site/` remains the product documentation site and is not
-an example or fixture.

package/docs/engine-development.md

@@ -1,218 +0,0 @@
-# Engine Development
-
-This document is for work on the reusable `norna` package itself.
-
-## Main Areas
-
-- `bin/norna.mjs`: public CLI launcher and local-version resolver.
-- `bin/norna-cli.mjs`: public CLI command dispatcher.
-- `scripts/lib/site-paths.mjs`: engine/site path resolution.
-- `scripts/lib/project-config.mjs`: plain YAML `site/config.yaml`
-  validation, defaults and derived URL path.
-- `scripts/sync-content-sections.mjs`: content validation and sync behavior.
-- `scripts/generate-images.mjs`: managed image pipeline and manifest.
-- `scripts/sync-site-public.mjs`: static public file sync.
-- `scripts/deploy-site.mjs`: deploy and deploy:commit behavior.
-- `scripts/watch-pages-deploy.mjs`: GitHub Pages workflow monitor.
-- `src/content.config.ts`: Astro content schema.
-- `src/components/` and `src/layouts/`: rendered page, navigation, image
-  blocks, and layout.
-- `tests/`: Playwright navigation diagnostics.
-- `fixtures/basic/site/`: minimal site used for engine checks.
-- `starters/basic/`: copyable site starter.
-- `examples/feature-demos/media-and-surfaces/site/`: broad visual example used
-  by demo builds and navigation diagnostics.
-
-The repository-local `site/` directory is reserved for a local documentation
-site. It is useful for dogfooding `norna` documentation, but it is not the
-primary visual regression demo.
-
-## Common Checks
-
-Run focused checks while developing:
-
-```sh
-npm run test:content-check
-npm run test:site-public
-npm run test:documentation
-npm run test:fixture:build
-npm run test:examples
-npm run demo:build
-npm run package:check
-```
-
-`npm run test:examples` builds every complete site and feature demo under
-`examples/`. `npm run test` includes those builds in the standard check
-sequence.
-
-`npm run test:documentation` extracts the file examples from the five-minute
-tutorial, applies them to a freshly initialized temporary site, runs the
-configuration and content checks, builds the result, and checks local Markdown
-links plus the `llms.txt` source targets.
-
-`npm run build:pages` is specific to this repository. It builds the
-documentation site and assembles rendered examples under `dist/examples/` for
-the shared GitHub Pages artifact. It is not a generic Norna site command.
-
-The root `site/` directory is the documentation site. Use the ordinary local
-commands for it:
-
-```sh
-npm run dev:local
-npm run build
-```
-
-Inside the engine repository, use npm scripts or explicitly run
-`node bin/norna.mjs ...`. Do not rely on a bare `norna ...` command there: a
-globally installed launcher deliberately does not delegate to another package
-whose own name is `@janga/norna`, so it may continue with the published global
-implementation instead of the working tree.
-
-The media-and-surfaces feature demo is the broad visual and navigation
-diagnostic target:
-
-```sh
-node bin/norna.mjs --site-dir examples/feature-demos/media-and-surfaces/site dev:local
-npm run demo:build
-```
-
-Navigation diagnostics are separate because they use Playwright:
-
-```sh
-npm run test:navigation
-npm run test:navigation:stress
-npm run test:navigation:preview
-```
-
-If Chromium is missing:
-
-```sh
-npx playwright install chromium
-```
-
-## Package Check
-
-`npm run package:check` packs this repository, extracts the package, copies the
-packaged starter into a temporary site project, installs dependencies, runs
-`norna doctor` from a site subdirectory, runs config/content checks,
-builds the installed site, and verifies selected rendered output and validation
-failures.
-
-It needs network access when npm dependencies are not already cached.
-The check uses a reusable npm cache at
-`node_modules/.cache/norna-package-check-npm` and runs npm with
-`--prefer-offline` so repeat runs do not redownload dependencies. Set
-`NORNA_PACKAGE_CHECK_CACHE=/path/to/cache` to use another cache.
-
-## CI Lockfiles
-
-Site repositories are developed on different operating systems but deployed on
-GitHub Actions Linux. `engine:update` therefore normalizes `package-lock.json`
-with npm 11.16.0 for Linux x64 glibc and verifies a clean install before it runs
-the site checks. The starter workflow pins Node 24.18.0, which provides the
-same npm version.
-
-`npm run test:ci-lockfile` recreates and repairs the optional npm peer-dependency
-case that previously caused GitHub Actions `npm ci` failures.
-
-## Test The Package In A Site Repository
-
-> **Warning:** `npm link` is not supported for `norna`. Astro resolves
-> renderer modules and runtime dependencies differently when the package is a
-> symlink, so a linked site can fail to start even though the published package
-> works. Do not use `npm link @janga/norna` to test a site.
-
-Use `npm run package:check` to test the package before release. To test a
-specific published engine version in a real site, update it with:
-
-```sh
-npm run norna:engine:update -- <version>
-```
-
-Commit the resulting `package.json` and `package-lock.json` changes in the
-site repository after the site's normal checks pass.
-
-The installed `norna` command is created from the package `bin` field. The
-launcher first looks for the nearest project `package.json`. If that project
-declares `@janga/norna` and Node can resolve an installed copy from that project
-root, the launcher delegates to that local entrypoint. The engine repository
-itself is excluded from delegation to prevent recursion; its working tree is
-selected explicitly through npm scripts or `node bin/norna.mjs`.
-
-## npm Release
-
-The npm package is published under the `@janga` scope. Choose the release type
-when starting a release; the command requires a clean working tree, verifies npm
-registry authentication for the same registry/cache used by the publish step,
-updates `package.json` and `package-lock.json` without creating a commit, and
-regenerates schemas with documentation links pinned to the new `v<version>` Git
-tag. It then runs `npm test`, verifies that only release files changed, creates
-the release commit and Git tag, publishes to npm, and pushes the commit and tag.
-
-```sh
-npm run release:patch
-```
-
-Use `patch` for backwards-compatible fixes and maintenance changes. Use `minor`
-for backwards-compatible features and `major` for incompatible changes:
-
-```sh
-npm run release:minor
-npm run release:major
-```
-
-The release command deliberately does not run GitHub Pages deployment monitoring.
-If version preparation, schema generation, or testing fails before the release
-commit, the script restores the previous package version and generated schemas.
-
-If npm publication fails, it stops before pushing; the local version commit and
-tag remain available for inspection or recovery. Retry publication with
-`npm run release:publish`, then push the existing commit and tag with
-`git push --follow-tags`. Do not start a new version bump merely to retry these
-steps.
-
-If the npm authentication preflight fails, no version commit or tag has been
-created yet. Run the printed login command:
-
-```sh
-npm login --registry=https://registry.npmjs.org/ --auth-type=web --cache /private/tmp/norna-npm-cache
-```
-
-Then start the release command again.
-
-After publication, update site repositories to the exact published npm version
-and commit their updated `package-lock.json`.
-
-## Rendering Notes
-
-The renderer builds the homepage at `/` and optional first-level pages from
-`site/pages/<NNN-page-id>/content.md`.
-
-Navigation has two separate levels:
-
-- Site navigation moves between the homepage and additional pages. It uses
-  normal page URLs and browser history.
-- Section navigation moves between sections on the current page. It uses real
-  `href="#section-id"` links so anchors work without JavaScript.
-
-The current navigation model is deliberately scoped to single-page and small
-multi-page sites. That scope may change as navigation support matures. For now,
-single-page sites should rely on section navigation only; small multi-page sites
-may combine site navigation and section navigation; larger information
-architectures should not be forced into the sticky-navigation model without a
-separate design decision.
-
-The JavaScript enhancement keeps the URL hash as the source of truth for active
-section-navigation state. A section-link click pushes one hash entry into browser
-history, back/forward moves between hash entries, and returning to the same page
-without a hash restores the first section as active. The enhancement does not
-derive active section state from free manual scrolling.
-
-The sticky navigation updates a root scroll-offset variable so direct hash
-links and clicked links remain visible below the fixed header. The browser owns
-anchor movement; Norna does not run a separate scroll animation or retry anchor
-positions after later layout shifts.
-
-The shared layout selects Norna's built-in UI labels from the optional
-`language` in `site/config.yaml`. Keep editorial content in page Markdown and
-non-editorial engine UI labels in the engine language packs.

package/docs/getting-started.md

@@ -1,206 +0,0 @@
-# Build Your First Norna Site
-
-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.
-
-At the end you will have:
-
-- 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/`.
-
-## Before You Start
-
-You need:
-
-- Node.js `22.12` or later,
-- npm, which is included with Node.js,
-- a terminal and a text editor.
-
-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.
-
-See [Requirements and limitations](requirements.md) for platform details and
-the current product boundaries.
-
-## 1. Create And Run The Site
-
-Run these commands from the directory where you keep projects:
-
-```sh
-npx @janga/norna@latest init my-site
-cd my-site
-npm install
-npm run norna:dev
-```
-
-`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.
-
-The tutorial uses the `norna:*` npm scripts because they work in both
-standalone and embedded projects. A standalone project also includes the
-shorter `npm run dev` and `npm run build` aliases.
-
-### Optional: Shorter CLI Commands
-
-Install the Norna launcher globally when you prefer direct commands:
-
-```sh
-npm install --global @janga/norna@latest
-```
-
-You can then run `norna dev`, `norna check`, and `norna build`. Inside a
-project, the launcher automatically delegates to that project's locally
-installed and pinned Norna version. The global installation is only the
-launcher; keep the local dependency and lockfile.
-
-### Checkpoint: The Starter Is Visible
-
-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.
-
-Leave the development server running while you complete the next steps.
-
-## 2. Replace The Homepage Content
-
-Replace `site/content.md` with:
-
-```md
----
-page:
-  description: A website built from plain files.
----
-
-# My first Norna site
-
-This page is written in Markdown. Norna provides its layout and navigation.
-
-## Welcome {#welcome}
-
-This is the first section.
-
-## Next {#next}
-
-Edit this file while the development server is running and the browser updates.
-```
-
-The single `#` heading is the page title. Each `##` heading is a page section.
-Its explicit `{#section-id}` gives the section a stable identity and is
-required by Norna.
-
-### Checkpoint: Content And Navigation Update
-
-Return to the browser. The page should now contain `Welcome` and `Next`, and
-the section navigation should link to those two sections. You should not
-need to restart the server.
-
-## 3. Set Shared Content
-
-Replace `site/sitewide-content.yaml` with:
-
-```yaml
-footer:
-  copyrightMessage: My first Norna site.
-```
-
-The footer is site-wide content rather than a page section. If you add pages
-later, they share it. The homepage H1 you set in the previous step already
-names the homepage in navigation and becomes the alternative text if you add a
-conventional navigation logo.
-
-### Checkpoint: The Footer Is Shared
-
-The navigation should use `My first Norna site` from `content.md`. The footer
-should show the new message.
-
-## 4. Choose A Complete Theme
-
-Replace `site/theme.yaml` with:
-
-```yaml
-preset: project
-```
-
-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.yaml`.
-
-## 5. Check And Build
-
-Open another terminal in `my-site` and run:
-
-```sh
-npm run norna:check
-npm run norna:build
-```
-
-The check should complete without errors. The build should create:
-
-```text
-dist/
-```
-
-`dist/` is generated output. Continue editing the files under `site/`; do not
-edit the built HTML as the source of the website.
-
-### Checkpoint: The Source Produces A Clean Build
-
-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
-
-- [Add and manage images](content.md#norna-blocks)
-- [Add another page](pages.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)
-
-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 norna:dev -- --kill
-```
-
-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
-
-Install ImageMagick and confirm that either `magick` or the older `identify`
-and `convert` commands are available. Then rerun the failed command.
-
-### The Page Reports Invalid Content
-
-Run:
-
-```sh
-npm run norna:content:check
-```
-
-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

@@ -1,35 +0,0 @@
-# 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 Files](../site-files.md) for source and generated files.