@janga/norna 0.7.18 → 0.7.23

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.

package/docs/images-and-metadata.md

@@ -1,188 +0,0 @@
-# Images And Metadata
-
-This document describes Norna's image pipeline. Site repositories own their
-source images and any copyright or licensing policy for those images.
-
-## Managed Source Images
-
-Norna-managed local images are referenced from Markdown with
-`norna-image-stack`, `norna-image-carousel`, or `norna-card-list` blocks. See
-[Content](content.md#norna-blocks) for the block syntax.
-
-Homepage source images live under:
-
-```text
-site/pages/000-home/images/
-```
-
-Images for any page, including nested pages, live directly under that page:
-
-```text
-site/pages/<NNN-page-id>/pages/<NNN-page-id>/images/
-```
-
-The number of nested `pages/` segments follows the page hierarchy.
-
-Supported source extensions:
-
-- `.jpg`
-- `.jpeg`
-- `.png`
-- `.svg`
-
-Managed image block references use only the filename:
-
-````md
-```norna-image-stack
-- image: portrait.jpg
-  alt: Optional alt text.
-  caption: Optional caption.
-```
-````
-
-`alt` and `caption` are optional. If `alt` is omitted, Norna renders an empty
-alt attribute.
-
-For generated or edited images, keep provenance near the image in a source-only
-comment. Norna removes these comments from rendered HTML:
-
-```md
-<!-- norna-image-provenance:
-image: portrait.jpg
-source: generated
-prompt: Short prompt or editing note.
--->
-```
-
-Each filename identifies one managed source image within its page. The same
-filename may be used by another page. Automatic sync only moves misplaced
-files when the filename identifies exactly one source candidate across all
-page image roots, and when the move will not break another reference. If the
-move crosses page image roots, `content:sync` requires a clean Git working tree
-before writing.
-
-## Markdown Images
-
-Use ordinary Markdown images for external images or static public assets:
-
-```md
-![External image](https://example.com/image.jpg)
-![Public asset](/favicon.svg)
-```
-
-Relative local Markdown images such as `![Portrait](portrait.jpg)` are not
-managed by Norna. `content:check` warns about them because Norna cannot
-validate, process, or sync those files through the image pipeline.
-
-## Generated Variants And Static SVG
-
-For raster images, `npm run norna:images` and `npm run norna:build` generate
-WebP files in:
-
-```text
-site/.norna/public/images/generated/
-```
-
-The normal display widths are:
-
-```text
-480, 768, 1080, 1440, 1920
-```
-
-Widths larger than the source image are skipped. If the source image is wider
-than all normal display widths, the pipeline also creates one variant at the
-source width.
-
-Generated filenames include the first eight characters of the source SHA-256
-hash:
-
-```text
-example-work-1a2b3c4d-1440.webp
-```
-
-When a source image changes, the generated URL changes too. This avoids stale
-browser, CDN, and GitHub Actions cache entries at the old URL.
-
-SVG files are managed by the same Markdown image blocks, validation and sync
-model, but they are not rasterized and do not get WebP variants. Norna copies
-the SVG source to:
-
-```text
-site/.norna/public/images/original/
-```
-
-The copied SVG filename includes the source hash. If the SVG has a `viewBox` or
-numeric `width` and `height`, Norna stores that ratio in the image manifest so
-the existing image layout can size it like other images. If no intrinsic aspect
-ratio can be read, the SVG is still rendered directly.
-
-## Manifest
-
-The generated image manifest is:
-
-```text
-site/.norna/generated-images.json
-```
-
-It is versioned site state. For raster images, it stores source hashes,
-original dimensions, output version, and generated variant paths. For static
-SVG images, it stores the source hash, copied public path, output version, and
-intrinsic dimensions when they can be read. The image pipeline reuses generated
-or copied files only when the manifest entry matches the current source hash
-and output version, and all expected output files exist.
-
-Generated files under `site/.norna/public/` are build-preparation output and
-should not be versioned.
-
-## Metadata Behavior
-
-The current engine does not inspect, require, warn about, or write source image
-copyright metadata.
-
-Generated WebP files are created with ImageMagick using `-strip`, so embedded
-metadata is not a publication mechanism for generated variants. Keep licensing,
-credits, copyright notices, alt text, and captions in site-owned files such as
-`site/pages/000-home/content.md`, page content files, `COPYRIGHT.md`, or other site
-documentation.
-
-If a site wants embedded metadata in original source files, that process is
-outside the current Norna command surface.
-
-## AI-Generated Images
-
-For AI-generated images, keep provenance and the generation prompt in a
-Markdown comment near the image block. This makes the image maintainable as
-content: future editors can understand where it came from and regenerate or
-revise it without reverse-engineering the asset.
-
-````md
-<!--
-AI image prompt for workflow.png:
-A clean editorial illustration of ordinary project files becoming a small
-static website, restrained colors, readable composition, no text in the image.
--->
-
-```norna-image-stack
-- image: workflow.png
-  alt: Abstract illustration of project files becoming a website.
-  caption: Generated illustration.
-```
-````
-
-The same provenance comment style can be used next to a `norna-image-carousel`
-or `norna-card-list` block when generated images are referenced there.
-
-This is a maintenance rule for real editorial images. It is not necessary for
-throwaway test fixtures or examples where the prompt has no practical value.
-
-## GitHub Actions Cache
-
-The starter workflow caches:
-
-```text
-site/.norna/public/images/generated
-```
-
-The cache key should include `site/.norna/generated-images.json` so unchanged
-generated variants can be restored during deploy. With a cache miss or a
-changed source hash, variants are rebuilt from source images.

package/docs/local-development.md

@@ -1,82 +0,0 @@
-# Local Development
-
-Use the local preview commands when editing a site or the engine demo.
-
-## Start Preview
-
-```sh
-npm run norna:dev
-```
-
-The wrapper:
-
-1. syncs `site/public/` into `site/.norna/public/`,
-2. starts Astro in background mode,
-3. waits until the site responds,
-4. opens `http://localhost:4321/` unless `WALDE_NO_OPEN=1` is set.
-
-The host and port are currently fixed in the script:
-
-```text
-localhost:4321
-```
-
-If the port is already in use, the command fails and asks you to stop the
-process using it.
-
-To stop any process that is blocking the standard port before starting, pass
-`--kill`:
-
-```sh
-npm run norna:dev -- --kill
-```
-
-The standalone starter also provides this shorter alias:
-
-```sh
-npm run dev -- --kill
-```
-
-With the optional global launcher installed, the direct form is:
-
-```sh
-norna dev --kill
-```
-
-The launcher selects the current project's locally installed Norna version.
-
-## Test On A Phone
-
-To make the local dev server available to devices on the same Wi-Fi network:
-
-```sh
-npm run norna:dev:lan
-```
-
-The command prints one or more local IPv4 URLs. Open one of them on the phone.
-The phone and computer must use the same network, and macOS may ask to allow
-incoming connections for Node. Stop the server after testing with
-`npm run norna:dev:stop` because it is accessible from the local network.
-
-## Manage Preview
-
-```sh
-npm run norna:dev:status
-npm run norna:dev:logs
-npm run norna:dev:logs -- --follow
-npm run norna:dev:restart
-npm run norna:dev:stop
-```
-
-The local server state and logs live under `.astro/`.
-
-## Rebuild Stale Preview
-
-Use this when generated content or image state looks stale:
-
-```sh
-npm run norna:build:local
-```
-
-It runs the full build and restarts the local dev server without opening a new
-browser window.

package/docs/pages.md

@@ -1,190 +0,0 @@
-# Pages
-
-Every Norna page is a directory under `site/pages/` with its own `content.md`.
-The same model is used for the homepage, top-level areas, and nested pages.
-
-```text
-site/pages/
-|-- 000-home/
-|   `-- content.md
-|-- 010-guides/
-|   |-- content.md
-|   `-- pages/
-|       `-- 010-installation/
-|           `-- content.md
-`-- 020-reference/
-    `-- content.md
-```
-
-Pages use the same Markdown H1, optional metadata, sections, Norna blocks, and
-managed-image model. See [Content](content.md) for what belongs inside
-`content.md`.
-
-## Homepage And Top-Level Pages
-
-The homepage is required at:
-
-```text
-site/pages/000-home/content.md
-```
-
-It builds to `/`. The `000` prefix is reserved for `000-home`, and Home cannot
-contain a nested `pages/` directory. Home is the site's front door, not the
-parent of every page.
-
-Other directories directly under `site/pages/` are top-level navigation roots.
-For example, `site/pages/010-guides/content.md` builds to `/guides/`. Place
-further pages under the nearest meaningful non-home page.
-
-## Nested Pages
-
-A page may contain a `pages/` directory:
-
-```text
-site/pages/010-guides/
-|-- content.md
-`-- pages/
-    `-- 020-workflows/
-        |-- content.md
-        `-- pages/
-            `-- 010-local/
-                `-- content.md
-```
-
-This produces:
-
-```text
-/guides/
-/guides/workflows/
-/guides/workflows/local/
-```
-
-Each directory in the chain is a real page and therefore needs its own
-`content.md`. Empty grouping directories are not part of the page model.
-
-## Directory Names, Order, And URLs
-
-Page directories use:
-
-```text
-NNN-page-id
-```
-
-`NNN` is a three-digit sibling presentation order. `page-id` becomes that
-page's URL segment. Valid ordinary page names include:
-
-```text
-010-getting-started
-020-concepts
-120-api-reference
-```
-
-Invalid names include:
-
-```text
-10-about
-000-about
-010_About
-010-About
-010-about-
-010-about--team
-```
-
-The page id may contain only lowercase `a-z`, numbers, and single hyphens
-between alphanumeric groups. The numeric prefix is not part of the URL.
-Renaming `030-contact/` to `015-contact/` changes its order among siblings but
-keeps the URL segment `contact`.
-
-Sibling page ids and numeric orders must be unique. Reusing the same id below a
-different parent is valid because the complete URL remains different.
-
-## Page Content
-
-A minimal page is ordinary Markdown:
-
-```md
----
-page:
-  description: Installation instructions.
----
-
-# Installation
-
-Introductory text.
-
-## Requirements {#requirements}
-
-Text...
-```
-
-The H1 supplies the visible page title, document title, and navigation label.
-`page.description` is optional metadata and is not rendered. H2 and H3 headings
-provide page-local navigation according to the selected navigation model.
-
-## Navigation
-
-Home and listed top-level pages appear in global navigation. Child pages appear
-in the local hierarchy for their top-level area. Breadcrumbs show actual parent
-pages; Home is not added as an artificial ancestor.
-
-The numeric prefix controls order among siblings. Set `navigation.listed` to
-`false` in a non-home page's frontmatter when the page should remain public but
-not appear in generated navigation:
-
-```yaml
-navigation:
-  listed: false
-```
-
-Home is always listed. By default, Norna chooses navigation from the site
-structure:
-
-- one listed page uses section navigation;
-- a shallow hierarchy uses top navigation;
-- deeper page or heading hierarchies use tree navigation.
-
-The site-wide `navigation.mode` in `config.yaml` can explicitly select
-`automatic`, `sections`, `top`, or `tree`. See
-[Configuration](configuration.md#navigation).
-
-## Page Images
-
-Managed images belong directly to the page that references them:
-
-```text
-site/pages/010-guides/pages/020-workflows/images/diagram.svg
-```
-
-The Markdown block still uses only the filename:
-
-````md
-```norna-image-stack
-- image: diagram.svg
-  alt: The local workflow.
-```
-````
-
-Run `norna content:check` to find missing or misplaced images and
-`norna content:sync` to move unambiguous files into the expected page image
-root. Cross-page writes require a clean Git working tree and never guess when a
-filename has multiple possible sources.
-
-## Page Themes
-
-The root `site/theme.yaml` owns the site's visual identity: preset, palette,
-shape, typography, page frame, and navigation presentation.
-
-An optional page-local `theme.yaml` may adjust only:
-
-- `layout.textWidth`
-- `layout.contentSpacing`
-- managed-image sizing under `images`
-- `sections.backgroundPattern`
-
-These values are inherited by descendant pages and merged with more local page
-settings. Page themes cannot select presets or change site colors, fonts,
-shape, page width, gutters, or navigation. See [Theme](theme.md#page-themes).
-
-Page directories also cannot contain `config.yaml` or
-`sitewide-content.yaml`; technical configuration and shared editorial content
-remain at the selected site's top level.

package/docs/public-files.md

@@ -1,118 +0,0 @@
-# Public Files
-
-`site/public/` contains static files that Norna copies into the published site
-without managed-image processing. Use it for browser icons, verification files,
-`robots.txt`, a custom-domain `CNAME`, downloadable files, and other assets that
-must keep their original format.
-
-Most files and subdirectories under `public/` are site-owned. Logos and browser
-icons are exceptions: Norna discovers a small set of exact filenames by
-convention.
-
-## Navigation Logo
-
-To add a navigation logo, place exactly one supported logo file directly in
-`site/public/`:
-
-- `logo.svg`
-- `logo.png`
-- `logo.jpg`
-- `logo.jpeg`
-
-Norna discovers the logo from its filename, so you do not configure a path or
-enable it separately. Use the exact lowercase filename to keep the site
-portable between case-sensitive and case-insensitive file systems.
-
-The logo links to the homepage. Its alternative text comes from the homepage
-Markdown H1 in `site/pages/000-home/content.md`; no separate site name or logo alt text is
-configured.
-
-Configure top-level `logo` in `site/sitewide-content.yaml` only when you need
-to override the displayed height:
-
-```yaml
-logo:
-  height: 2rem
-```
-
-The width follows the image's intrinsic aspect ratio. `logo` does
-not enable the logo or select a file.
-
-`norna config:check` fails when it finds multiple supported logo files, or when
-`logo` is configured but no logo file exists. A site without a logo uses its
-ordinary page-title navigation; the check reports the missing logo as a
-warning.
-
-## Browser Icons
-
-To add browser icons, place one or more supported files directly in
-`site/public/`:
-
-- `favicon.svg`
-- `favicon.ico`
-- `favicon.png`
-- `apple-touch-icon.png`
-
-Norna discovers these files from their filenames, so you do not configure paths
-or enable them separately. Use the exact lowercase filenames to keep the site
-portable between case-sensitive and case-insensitive file systems.
-
-You may include several supported browser-icon files. Norna links every file it
-finds and lets the browser select the appropriate format.
-
-Browser icons are separate from the navigation logo. The logo appears inside
-the website, while browser icons identify it in tabs, bookmarks, and similar
-browser interfaces.
-
-## GitHub Pages Custom Domain
-
-To use a custom domain with GitHub Pages, place a file named exactly `CNAME`
-directly in `site/public/`. Write the domain name in the file without a protocol
-or path:
-
-```text
-www.example.com
-```
-
-Norna does not discover or interpret `CNAME`; it copies the file to the root of
-the generated website. GitHub Pages gives the filename its meaning. The public
-`url` in `site/config.yaml` should use the same domain.
-
-## Other Static Files
-
-Other names are not restricted. For example:
-
-```text
-site/public/
-|-- robots.txt
-|-- verification.html
-`-- downloads/
-    `-- project-overview.pdf
-```
-
-Except for the navigation logo and browser icons documented above, Norna does
-not attach meaning to filenames or inspect their contents. It copies them
-unchanged. Browsers, crawlers, hosting services, and verification providers may
-still require their own exact filenames and locations.
-
-Norna preserves subdirectories while copying these files. A source file such
-as `site/public/downloads/project-overview.pdf` is published at
-`/downloads/project-overview.pdf`, prefixed with the site's configured base path
-when the site is published below a path such as `/repository-name/`.
-
-Ordinary Markdown image syntax may reference a public asset with a root-relative
-URL:
-
-```md
-![Public diagram](/diagrams/overview.svg)
-```
-
-Use Norna image blocks instead for local editorial images that should be
-validated, synced, processed, and captioned. See
-[Images and Metadata](images-and-metadata.md).
-
-## Generated Copy
-
-`norna site:public` copies source files from `site/public/` to
-`site/.norna/public/`. The latter directory is generated build-preparation
-output and must not be edited or versioned.