@janga/norna 0.7.17 → 0.7.22

package/docs/site-files.md

@@ -1,145 +0,0 @@
-# Site Files
-
-Norna expects a defined set of files and directories. Their names and locations
-are part of the site model: following the structure lets Norna find content,
-presentation, configuration, pages, and assets without path configuration.
-
-The selected site directory is `site/` by default:
-
-```text
-site/
-|-- config.yaml
-|-- theme.yaml
-|-- sitewide-content.yaml
-|-- content.md
-|-- images/
-|   `-- image.jpg
-|-- pages/
-|   `-- <NNN-page-id>/
-|       |-- content.md
-|       |-- theme.yaml
-|       `-- images/
-|           `-- image.jpg
-|-- public/
-`-- .norna/
-    |-- generated-images.json
-    `-- public/
-```
-
-File and directory names shown literally above must use that exact lowercase
-spelling. This keeps sites portable between case-sensitive and
-case-insensitive file systems.
-
-## Root Files
-
-| Path | Required | Responsibility |
-| --- | --- | --- |
-| `config.yaml` | Yes | Public URL, language, and browser scroll behavior. |
-| `theme.yaml` | Yes | Complete visual preset and optional focused overrides. |
-| `sitewide-content.yaml` | No | Shared logo display settings, banners, and footer. |
-| `content.md` | Yes | Homepage title, optional metadata, sections, prose, and Norna blocks. |
-
-These responsibilities are deliberately separate:
-
-- [`config.yaml`](configuration.md) contains the few technical settings that
-  apply to the whole site.
-- [`theme.yaml`](theme.md) controls presentation. A normal file can contain
-  only a preset selection.
-- [`sitewide-content.yaml`](sitewide-content.md) contains editorial material
-  shared by every page.
-- [`content.md`](content.md) is the homepage file and remains ordinary
-  Markdown. YAML frontmatter is optional.
-
-Pages cannot provide `config.yaml` or `sitewide-content.yaml`. Technical
-configuration and shared logo, banner, and footer settings have one site-wide
-source.
-
-## Images
-
-Managed homepage images belong in:
-
-```text
-site/images/
-```
-
-All managed images used by the homepage share this directory. Markdown blocks
-refer to managed images by filename, not by path. See
-[Images and Metadata](images-and-metadata.md) for supported formats, generated
-variants, and syncing.
-
-## Pages
-
-Each first-level page is one directory under `pages/`:
-
-```text
-site/pages/010-guide/
-|-- content.md
-|-- theme.yaml
-`-- images/
-    `-- image.jpg
-```
-
-`content.md` is required for a page. The optional page `theme.yaml` replaces
-the root visual theme for that page. Page images live directly in that page's
-`images/` directory.
-
-The three-digit page prefix controls navigation order and is not part of the
-URL. See [Pages](pages.md) for exact directory-name and page-id rules.
-
-## Public Files
-
-`site/public/` contains static files copied without image processing. Most
-names are site-owned, but Norna recognizes a small set of exact conventional
-filenames for the navigation logo and browser icons.
-
-See [Public Files](public-files.md) for navigation-logo and browser-icon
-filenames, GitHub Pages `CNAME`, arbitrary static files, root-relative links,
-and publishing paths.
-
-## Selecting The Site Directory
-
-Use `NORNA_SITE_DIR` or `norna --site-dir <path>` to select a site directory
-explicitly.
-
-Without an explicit selection, Norna first accepts the current directory when
-it contains both `config.yaml` and `content.md`. Otherwise it walks upward until
-it finds a default `site/` directory containing those two files.
-
-## Versioned Files
-
-Version the source files above together with:
-
-- `site/.norna/generated-images.json`, which records reusable managed-image
-  output;
-- `.github/workflows/deploy.yml`, when using the included GitHub Pages
-  publishing integration;
-- `package.json` and `package-lock.json`, which pin the local Norna engine and
-  project scripts.
-
-Source images and files under `site/public/` are also versioned site input.
-
-## Generated Files
-
-Do not edit these by hand:
-
-- `site/.norna/public/`: build-preparation output copied from `site/public/`,
-  plus generated or copied managed images;
-- `dist/`: final static website output;
-- `.astro/`: Astro cache, generated types, and local dev-server state.
-
-`norna site:public` removes stale copied static files from
-`site/.norna/public/` while preserving managed image output under its `images/`
-directory.
-
-## Engine Repository Layout
-
-These directories belong to the Norna engine repository, not to an ordinary
-site:
-
-- `bin/`: the launcher and public CLI dispatcher;
-- `scripts/`: validation, image, preview, publishing, and test tools;
-- `src/`: the Astro renderer, components, styles, and content schema;
-- `starters/`: source copied by `norna init`;
-- `examples/`: complete sites and focused feature demonstrations;
-- `fixtures/`: engine regression input;
-- root `site/`: the Norna introduction and documentation site.

package/docs/sitewide-content.md

@@ -1,73 +0,0 @@
-# `sitewide-content.yaml`
-
-`site/sitewide-content.yaml` is optional. It contains editorial content and
-optional logo display settings shared by every page: banners, footer, and an
-optional navigation-logo height override.
-
-The file contains plain YAML without Markdown frontmatter delimiters. Page
-sections do not belong here; they remain in each page's `content.md`.
-
-## Navigation Logo
-
-A logo file is discovered from `site/public/`; no path or site name is
-configured here. The logo links to the homepage, and its alternative text
-comes from the homepage Markdown H1 in `site/content.md`.
-
-Add `logo` only to override the discovered file's displayed height:
-
-```yaml
-logo:
-  height: 2.6rem
-```
-
-The logo width follows the file's intrinsic aspect ratio. See
-[Public Files: Navigation Logo](public-files.md#navigation-logo) for exact
-filenames, placement, portability, and validation rules.
-
-The logo is a separate home link and does not have a section menu. In a
-multi-page site, the homepage remains the first ordinary navigation item, uses
-its Markdown H1 as its label, and exposes its sections in the same way as
-pages. Page content and page themes cannot replace the shared logo setting.
-
-## Banners
-
-Use `banners` for short notices shown above page content on every page. List
-order controls presentation order. Each banner needs a unique lowercase `id`,
-a title, and text:
-
-```yaml
-banners:
-  - id: project-status
-    tone: warning
-    visible:
-      from: "2026-08-01"
-      until: "2026-09-01"
-    title: Experimental code
-    text: Not for production use.
-```
-
-`tone` currently supports `warning`. `visible` is optional. `from` is inclusive
-and `until` is exclusive; both use `YYYY-MM-DD`, and either may be omitted.
-
-Visitors can dismiss each active banner. Dismissal state is stored locally in
-the browser and tied to the banner content, so an edited banner can appear
-again. Keep banners concise; they are rendered as compact one-line notices and
-may use an ellipsis when space is limited.
-
-## Footer
-
-The footer can contain copyright or ownership text and optional generated build
-information:
-
-```yaml
-footer:
-  copyrightMessage: (c) Example Owner.
-  buildInfo: true
-```
-
-Set `buildInfo` to `true` to show the generated build date and time. Norna uses
-the site's configured language, a compact format, and UTC. If both copyright
-text and build information are absent, no footer is rendered.
-
-See [Site Files](site-files.md) for where this optional file belongs in the
-complete site model.

package/docs/theme.md

@@ -1,271 +0,0 @@
-# Theme
-
-`site/theme.yaml` defines the site-wide visual theme for a Norna site. It is a
-required plain YAML file. The normal setup selects one complete theme preset
-and adds only focused overrides when needed.
-
-An optional `theme.yaml` inside a page directory replaces the root visual
-theme for that page. Navigation-logo display settings remain site-wide and
-belong in `sitewide-content.yaml`.
-
-## Theme Presets
-
-Available complete theme presets are:
-
-- `portfolio`: restrained typography and a broad image area for image-led
-  presentation.
-- `documentation`: reading-focused typography, a paper palette, and compact
-  structural rhythm.
-- `project`: compact layout and a light presentation for project and product
-  sites.
-- `statement`: airy spacing and stronger typography for short editorial
-  content.
-
-A normal `theme.yaml` can be only:
-
-```yaml
-preset: documentation
-```
-
-Each preset supplies coordinated values for:
-
-- layout density, page width, and gutters
-- managed image sizing
-- font family, typography profile, and typography rhythm
-- palette and section-surface behaviour
-
-The nested `typography.profile` setting documented below is a lower-level
-typography choice. A top-level theme `preset` selects the complete visual
-system, including that typography choice.
-
-## Overrides
-
-Values written beside the top-level preset override only that part of the
-preset. Other preset values remain active:
-
-```yaml
-preset: documentation
-layout:
-  pageWidth: 1320px
-palette: dark
-```
-
-Nested objects are merged by key. `sectionSurfaces` replaces the preset array
-when it is specified.
-
-It is still valid to omit the top-level preset and define the visual settings
-explicitly. Omitted explicit settings then use engine defaults. This is useful
-for focused testing, but selecting a complete preset is the simpler normal
-workflow.
-
-## Export A Preset
-
-Export the installed definition of a preset before choosing overrides:
-
-```sh
-norna theme:export documentation
-```
-
-In a generated site, the equivalent npm command is:
-
-```sh
-npm run norna:theme:export -- documentation
-```
-
-The command creates `site/orig-documentation-theme.yaml`, or the corresponding
-path under the selected site directory. The file contains the preset values,
-comments describing accepted alternatives, and an example of a fine-grained
-typography override.
-
-Norna never loads `orig-*-theme.yaml`; only `theme.yaml` is active. The export
-command refuses to overwrite an existing reference file.
-
-Page titles and site navigation are not part of the visual theme. Define
-optional logo display settings in `site/sitewide-content.yaml`; see
-[Sitewide Content](sitewide-content.md).
-
-## Layout
-
-`layout` is optional. It controls the outer page geometry:
-
-- `pageWidth`: maximum width of the main page content area.
-- `gutter`: side margin removed from the viewport before available content
-  width is calculated. Use either one CSS length for all viewports or
-  `desktop` / `mobile` values.
-- `density`: default structural spacing profile. Allowed values are `compact`,
-  `normal`, and `airy`.
-- `spacing`: optional spacing overrides for sections and content blocks. Every
-  spacing value accepts either one CSS length for all viewports or `desktop` /
-  `mobile` values.
-
-Example:
-
-```yaml
-layout:
-  density: normal
-  pageWidth: 1180px
-  gutter:
-    desktop: clamp(1.25rem, 4vw, 3rem)
-    mobile: 1rem
-  spacing:
-    firstSectionTop:
-      desktop: clamp(1.875rem, 3vw, 2.75rem)
-      mobile: 1.375rem
-    sectionGap:
-      desktop: clamp(1.4rem, 3vw, 2.75rem)
-      mobile: 1.5rem
-    headingToBlock:
-      desktop: 0.75em
-      mobile: 0.7em
-    blockGap:
-      desktop: 1.5em
-      mobile: 1.25em
-```
-
-If omitted, Norna uses `1180px` for `pageWidth`, desktop
-`clamp(1.25rem, 4vw, 3rem)` for `gutter`, mobile `1rem`, and `normal` layout
-density.
-
-Spacing keys:
-
-- `firstSectionTop`: space above the first section heading.
-- `sectionGap`: space above each following section.
-- `finalSectionBottom`: space below the final section.
-- `headingToBlock`: space between a section heading and its first visual content
-  block, such as an image stack, carousel, or card list.
-- `blockGap`: space between content blocks in a section. It applies between
-  Markdown, image, carousel, and card-list blocks, but not after the final block.
-- `imageGap`: space between stacked images or carousel blocks.
-
-The default `compact`, `normal`, and `airy` density profiles provide values for
-these spacing keys. The `em` values for `headingToBlock` and `blockGap` are
-relative to the relevant text size, so the rhythm follows typography changes.
-Use `sectionGap` and the other structural keys when the distance should describe
-the page layout rather than the size of nearby text.
-
-Text-near spacing inside Markdown, such as spacing after headings, spacing
-before Markdown subheadings, paragraph spacing, and caption spacing, belongs to
-`typography.rhythm` and typography overrides.
-
-## Image Sizing
-
-`images` is optional. It controls managed image sizing:
-
-- `width`: hard maximum rendered image area width for images, captions, and
-  aligned text.
-- `maxAvailableWidthPercent`: maximum share of available width after gutters.
-- `maxAvailableHeightPercent`: maximum share of viewport height used by
-  images.
-
-Example:
-
-```yaml
-images:
-  width: 900px
-  maxAvailableWidthPercent:
-    desktop: 100
-    mobile: 100
-  maxAvailableHeightPercent:
-    desktop: 74
-    mobile: 68
-```
-
-If omitted, Norna uses `900px`, full available width, and image height limits of
-desktop `74` / mobile `68`.
-
-## Typography
-
-Top-level `typography` is the site-wide typographic base. It supports:
-
-- `fontFamily`: global CSS font-family stack.
-- `profile`: built-in typography profile.
-- `rhythm`: text-near spacing profile. Allowed values are `compact`,
-  `normal`, and `airy`.
-- `overrides`: focused changes to preset values.
-
-Example:
-
-```yaml
-typography:
-  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  profile: reading
-  rhythm: normal
-  overrides:
-    headings:
-      h2:
-        size: medium
-        weight: 600
-        spacingAfter: 0.55em
-      h3:
-        size: medium
-        spacingBefore: 1.5em
-        spacingAfter: 0.5em
-    body:
-      width: narrow
-      lineHeight: 1.55
-```
-
-Use `norna typography profiles` to inspect built-in profile and rhythm values,
-and `norna typography show` to inspect the resolved typography for the
-selected site. See [Typography](typography.md).
-
-## Palette And Section Surfaces
-
-`palette` and `sectionSurfaces` are optional top-level theme settings:
-
-- `palette`: `dark`, `light`, or `paper`. It coordinates page, navigation,
-  footer, and section colors.
-- `sectionSurfaces`: one to three unique values chosen from `base`, `soft`, and
-  `emphasis`. One value gives every section the same surface. Multiple values
-  cycle in the listed order.
-
-Example:
-
-```yaml
-palette: paper  # Alternatives: dark, light
-sectionSurfaces: [base, soft, emphasis]
-```
-
-## Page Themes
-
-Add `theme.yaml` to a page directory when that page should have a different
-visual expression:
-
-```text
-site/pages/010-guide/theme.yaml
-```
-
-The page theme uses the same visual schema and complete presets as the root
-theme. A page can therefore select a different expression without repeating a
-large configuration:
-
-```yaml
-preset: statement
-```
-
-It completely replaces the root visual theme for that page. If the page
-theme selects no top-level preset, omitted values use engine defaults rather
-than values from the root theme. It cannot define navigation-logo settings or
-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 page select its own preset?
-
-No. A page without its own `theme.yaml` inherits the root theme, which is the
-normal choice when the site should keep one visual expression.
-
-Add a page theme only when the page should intentionally look different. If
-the page should keep the same preset but demonstrate a focused change, repeat
-the root preset in the page theme and override only that setting. This is
-necessary because a page theme replaces the root visual theme rather than
-merging with it.
-
-For example, a page demonstrating section surfaces may keep `preset: project`
-and change only `sectionSurfaces`. A page demonstrating image or content
-blocks should normally inherit the root preset so that the blocks remain the
-only variable being compared.

package/docs/typography.md

@@ -1,180 +0,0 @@
-# Typography
-
-Norna typography is configured in `site/theme.yaml` through a site-wide font,
-profile, text rhythm, and optional overrides.
-
-The normal workflow is to select a complete top-level theme preset. It already
-chooses a coordinated font, typography profile, and rhythm:
-
-```yaml
-preset: documentation
-```
-
-Use the nested `typography` block only when those typographic choices need to
-differ from the selected theme preset. Typography is configured at root-theme
-or page-theme level, not in page or section content.
-
-## Typography Profiles
-
-Available profiles:
-
-- `restrained`: the default for image-led sites. Text is restrained and
-  supports the images without dominating the page.
-- `dense`: tighter typography for many sections, many images, or
-  short information blocks.
-- `reading`: more generous body text for pages where longer text carries
-  more of the experience.
-- `statement`: tighter, more declarative line-height for short programmatic
-  statements. Use it sparingly, usually as a page-level exception.
-
-If a complete top-level theme preset is selected, that preset supplies the
-typography choice. If both the top-level preset and nested typography are
-omitted, the engine default is `restrained`.
-
-Profiles define alignment, size, weight, and line height for `headings.h1`
-through `headings.h4`, `body`, and `caption`. They also choose a readable body
-text width. Built-in presets use `medium` as the default size for every text
-role. Visual heading hierarchy comes from the Markdown heading level, so `h1`
-is larger than `h2`, `h2` is larger than `h3`, and so on.
-
-The profiles use these controls deliberately:
-
-- `restrained` uses restrained heading weights and a normal reading width.
-- `dense` uses stronger headings and a wider text column for short,
-  scannable content.
-- `reading` uses a narrower reading width and more generous body line
-  height.
-- `statement` uses the strongest heading weights and a narrow text column for
-  short, declarative content.
-
-`rhythm` defines text-near spacing for headings, paragraphs, and captions.
-Available rhythms are `compact`, `normal`, and `airy`. Built-in rhythm values
-use `em` so spacing follows the rendered text size.
-
-Use this command to inspect the exact profile and rhythm values shipped with
-the installed engine:
-
-```sh
-norna typography profiles
-```
-
-Use this command to inspect the effective values for the selected site after
-profiles, rhythms, and overrides have been applied:
-
-```sh
-norna typography show
-```
-
-The output includes the site theme, every page, and every section. Each
-resolved value shows its `source`; values inherited by a page or section are
-also marked with `inherited: true`.
-
-## Configuration Shape
-
-```yaml
-typography:
-  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  profile: restrained
-  rhythm: normal
-  overrides:
-    headings:
-      h2:
-        size: medium
-        weight: 600
-        spacingAfter: 0.55em
-      h3:
-        size: medium
-        spacingBefore: 1.5em
-        spacingAfter: 0.5em
-    body:
-      width: narrow
-      paragraphSpacing: 0.8em
-    caption:
-      spacingBefore: 0.5em
-```
-
-The typographic roles are:
-
-- `headings.h1`: reserved for page-level Markdown `#` headings if the content
-  model starts supporting them.
-- `headings.h2`: Markdown `##` section headings.
-- `headings.h3`: Markdown `###` subheadings inside section body text.
-- `headings.h4`: Markdown `####` subheadings inside section body text.
-- `body`: Markdown body text inside sections.
-- `caption`: image captions.
-
-Allowed alignment values are `left`, `center`, and `right`. Alignment can be
-responsive:
-
-```yaml
-align:
-  desktop: left
-  mobile: center
-```
-
-Allowed size values are `small`, `medium`, `large`, and `xlarge`. `medium` is
-the normal reading size. Use `small` for quieter supporting text, and use
-`large` or `xlarge` only when a page or section needs stronger emphasis.
-Each heading level uses its own scale but follows the same principle:
-`medium` is the normal size for that level. Norna may render the first section
-heading as an HTML `h1` for document structure, but its visual typography still
-follows the Markdown level the user wrote: `##` uses `headings.h2`.
-
-`lineHeight` is a unitless number from `1` through `3`. `spacingBefore`,
-`spacingAfter`, and `paragraphSpacing` are CSS lengths such as `0`, `0.8em`,
-`1rem`, or `12px`. Use `em` for spacing that should track the text size.
-
-`weight` is a controlled heading weight. Allowed values are `400`, `500`,
-`600`, and `700`. `body.width` is the readable text width and accepts
-`narrow`, `normal`, or `wide`. It controls the prose column, not the page's
-maximum width or the width of image blocks.
-
-Supported override fields:
-
-- `headings.h1.align`, `headings.h1.size`, `headings.h1.weight`,
-  `headings.h1.lineHeight`,
-  `headings.h1.spacingBefore`, `headings.h1.spacingAfter`
-- `headings.h2.align`, `headings.h2.size`, `headings.h2.weight`,
-  `headings.h2.lineHeight`,
-  `headings.h2.spacingBefore`, `headings.h2.spacingAfter`
-- `headings.h3.align`, `headings.h3.size`, `headings.h3.weight`,
-  `headings.h3.lineHeight`,
-  `headings.h3.spacingBefore`, `headings.h3.spacingAfter`
-- `headings.h4.align`, `headings.h4.size`, `headings.h4.weight`,
-  `headings.h4.lineHeight`,
-  `headings.h4.spacingBefore`, `headings.h4.spacingAfter`
-- `body.align`, `body.size`, `body.width`, `body.lineHeight`,
-  `body.paragraphSpacing`
-- `caption.align`, `caption.size`, `caption.lineHeight`,
-  `caption.spacingBefore`
-
-## Page Themes
-
-The simplest page-specific typography change is to select a complete theme
-preset:
-
-```yaml
-# site/pages/010-introduction/theme.yaml
-preset: statement
-```
-
-A page-local `theme.yaml` replaces the root visual theme rather than inheriting
-from it. The complete preset supplies a coherent page theme without repeating
-the root values.
-
-Use a nested typography choice when only the typographic character needs to be
-specified explicitly:
-
-```yaml
-# site/pages/010-introduction/theme.yaml
-typography:
-  profile: statement
-  rhythm: normal
-```
-
-Without a top-level theme preset, other omitted page-theme values use engine
-defaults rather than values from the root theme.
-
-The `body.width` value controls the prose column independently of the page and
-image widths. Captions are normally centered, but `reading` uses
-left-aligned captions to support longer explanatory text.