@janga/norna 0.7.0 → 0.7.2

package/docs/configuration.md

@@ -16,8 +16,9 @@ the current values for any one site.
 - Required: yes.
 - Default: none.
 - Validation: non-empty absolute URL accepted by `new URL()`.
-- Consequence: wrong values render a wrong canonical URL and make deploy output
-  point at the wrong site.
+- Consequence: wrong values render a wrong canonical URL and make deploy
+  output point at the wrong site. For GitHub Pages project sites, include the
+  repository path in the URL, for example `https://owner.github.io/repo-name/`.
 
 Example:
 
@@ -27,6 +28,36 @@ site: {
 }
 ```
 
+### `site.basePath`
+
+- Purpose: URL path prefix used for generated internal page links, favicons,
+  generated image URLs, and root-relative links or images written in Markdown.
+- Type: string URL path.
+- Required: no.
+- Default: `/`.
+- Validation: must start and end with `/` and must not contain whitespace,
+  `?`, `#`, or `//`.
+- Consequence: use `/` for a root site or custom domain. Use
+  `/repository-name/` for a GitHub Pages project site without a custom domain.
+  Source Markdown can still use root-relative paths such as `/workflow.svg` or
+  `/getting-started/`; Norna prefixes them during rendering.
+
+Examples:
+
+```js
+site: {
+	url: 'https://example.com/',
+	basePath: '/',
+}
+```
+
+```js
+site: {
+	url: 'https://janga.github.io/norna/',
+	basePath: '/norna/',
+}
+```
+
 ## Layout
 
 ### `layout.pageWidth`
@@ -374,3 +405,7 @@ If `NORNA_SITE_DIR` is set to an empty value, commands fail. Relative site
 directories are resolved by walking upward from the invocation root until the
 selected directory contains `config.mjs` and `content.md`. Absolute site
 directories are accepted and make their parent the site project root.
+
+When no site directory is explicitly selected, the current directory itself can
+be the site directory if it contains `config.mjs` and `content.md`. If not,
+Norna walks upward looking for a default `site/` directory with those files.

package/docs/content.md

@@ -1,14 +1,18 @@
 # Content
 
-`site/content.md` is the editable page file for the homepage of a
-`norna` site. Optional route pages use
-`site/routes/<route-folder>/route-content.md` with the same page frontmatter and
-Markdown section model.
+`site/content.md` is the homepage page file for a `norna` site. It defines the
+page metadata, section order, section ids, gallery rows, and Markdown text for
+the homepage.
 
-Site-wide visual defaults may live in `site/theme.md`. Technical site
-configuration lives in `site/config.mjs`.
+Route pages use the same page and section model in
+`site/routes/<route-folder>/route-content.md`. See [Routes](routes.md) for the
+route-specific rules.
 
-## Frontmatter Schema
+Site-wide visual defaults belong in [Theme](theme.md). Typography presets and
+overrides are described in [Typography](typography.md). Technical site settings
+belong in [Configuration](configuration.md).
+
+## Page Frontmatter
 
 The Astro content schema validates these top-level fields in page files:
 
@@ -16,54 +20,19 @@ The Astro content schema validates these top-level fields in page files:
 - `description`: required string. Rendered as the meta description.
 - `slug`: optional route URL slug. It is ignored on the homepage. If omitted on
   a route page, the route folder name is used.
-- `navigation`: optional page navigation metadata.
-- `presentation`: optional page-level presentation overrides.
-- `frame`: optional page-level frame color source.
+- `navigation`: optional page navigation metadata. See [Routes](routes.md).
+- `presentation`: optional page-level presentation overrides. See
+  [Theme](theme.md) and [Typography](typography.md).
+- `frame`: optional page-level frame color source. See [Theme](theme.md).
 - `sections`: required non-empty array. Defines section order, ids,
   presentation overrides, and gallery rows.
 
-`navigation` may contain:
-
-- `include`: optional boolean. Defaults to `true`.
-- `label`: optional string. Defaults to `title`.
-- `order`: optional integer. Defaults to `0` for the homepage and `100` for
-  route pages.
-
-Each `sections[]` item has:
-
-- `id`: required string matching `^[a-z0-9-]+$`. Used for anchors, navigation,
-  image directories, and Markdown heading ids.
-- `visible`: optional date window that controls whether the section is rendered.
-- `presentation`: optional object with `backgroundColor`, `textColor`, and/or
-  `typography` overrides.
-- `gallery`: optional array, defaulting to `[]`.
-
-Each gallery row has:
-
-- `image`: required filename matching `^[a-z0-9][a-z0-9.-]*\.(jpe?g|png)$`.
-  It must be a filename, not a path.
-- `alt`: required string.
-- `caption`: optional string.
-
-## Routes
-
-The homepage is always `site/content.md` and builds to `/`.
-
-Add a first-level route by creating:
-
-```text
-site/routes/about/route-content.md
-```
-
-Minimal route page:
+Minimal homepage:
 
 ```md
 ---
-title: About
-description: About this gallery.
-navigation:
-  label: About
-  order: 20
+title: My Gallery
+description: A small gallery site.
 sections:
   - id: intro
 ---
@@ -73,83 +42,89 @@ sections:
 Text...
 ```
 
-The example above builds to `/about/`. If `slug` is omitted, the route folder
-name is used. If `slug` is set, it must use lowercase letters, numbers, and
-hyphens. Keep the route folder and `slug` aligned unless you intentionally need
-a different URL.
+## Sections
+
+Each `sections[]` item has:
+
+- `id`: required string matching `^[a-z0-9-]+$`. Used for anchors, navigation,
+  image directories, and Markdown heading ids.
+- `visible`: optional date window that controls whether the section is rendered.
+- `presentation`: optional section-level visual overrides.
+- `gallery`: optional array, defaulting to `[]`.
 
-Route images live under the route:
+Example:
 
-```text
-site/routes/about/images/intro/image.jpg
+```yaml
+sections:
+  - id: work
+    gallery:
+      - image: work.jpg
+        alt: "A woven artwork on a white wall."
+        caption: "Work in progress."
 ```
 
-Image references in route frontmatter still use only the filename.
+Every frontmatter section must have a matching level 2 Markdown heading with an
+explicit id:
 
-### Navigation Scope
+```md
+## Work {#work}
 
-Current route navigation is intended for small sites. This guidance may change
-as route support matures, but the present model is:
+Introductory text.
+```
 
-- A single-page site should normally use only page navigation between sections.
-- A small multi-page site may use site navigation between routes plus page
-  navigation between sections on the current page.
-- If a site needs many routes, deeply nested routes, or several navigation
-  levels, it has probably outgrown the current sticky-navigation model and may
-  need a different site structure or navigation system.
+Keep these values aligned:
 
-## Site Theme
+- the frontmatter `sections[].id`
+- the Markdown heading id
+- the source image directory `site/images/<section-id>/`
 
-`site/theme.md` optionally defines site-wide visual defaults. It uses
-frontmatter and does not need a Markdown body. If the file is missing, built-in
-engine defaults are used.
+The visible section navigation label comes from the Markdown heading text, not
+from the frontmatter id.
 
-Starter sites include a marked comment block such as
-`norna:start theme-help` / `norna:end theme-help`. The block is
-only explorable help text; YAML comments do not affect rendering. The active
-configuration is the uncommented YAML below it.
+## Galleries
+
+Each gallery row can contain a single image:
 
 ```yaml
----
-# norna:start theme-help
-# Site-wide visual defaults. Remove a value to use the engine default.
-# norna:end theme-help
-
-presentation:
-  backgroundColor: "#000000"
-  textColor: "#f7f4ee"
-  inlineStyles:
-    highlight:
-      color: "#ffd84d"
-  typography:
-    preset: quiet-gallery
-frame:
-  colors: presentation
----
+gallery:
+  - image: work.jpg
+    alt: "A woven artwork on a white wall."
+    caption: "Work in progress."
 ```
 
-`presentation.backgroundColor` and `presentation.textColor` are optional quoted
-hex colors in `#rgb`, `#rrggbb`, or `#rrggbbaa` form.
+Image rows support:
 
-`presentation.inlineStyles` defines named inline text styles that can be used
-from Markdown. Inline style names must match `^[a-z][a-z0-9-]*$`. Each style
-currently supports a required `color` field using the same quoted hex color
-format as `textColor`.
+- `image`: required filename matching `^[a-z0-9][a-z0-9.-]*\.(jpe?g|png)$`.
+  It must be a filename, not a path.
+- `alt`: required string.
+- `caption`: optional string.
 
-`frame.colors` controls the sticky navigation and footer colors:
+Source image filenames must be unique across the selected page's image tree.
+The homepage reads images from `site/images/<section-id>/`. Route pages read
+images from `site/routes/<route-folder>/images/<section-id>/`.
 
-- `presentation`: use the resolved presentation colors for this level.
-- `theme`: use the site theme frame colors. This is useful in page-level
-  frontmatter.
-- explicit colors:
+## Carousels
+
+A gallery row can contain a carousel instead of a single image:
 
 ```yaml
-frame:
-  colors:
-    backgroundColor: "#111111"
-    textColor: "#eeeeee"
+gallery:
+  - carousel:
+      - image: first.jpg
+        alt: "First image."
+        caption: "First caption."
+      - image: second.jpg
+        alt: "Second image."
+        caption: "Second caption."
 ```
 
+Each carousel item has the same `image`, `alt`, and `caption` fields as a
+single image row.
+
+`content:check` warns when carousel images have different aspect ratios. Exact
+matching proportions are recommended because mixed proportions can make the
+layout move while the user changes slides.
+
 ## Temporary Sections
 
 Use `sections[].visible` for sections that should be rendered only during a
@@ -171,171 +146,37 @@ Both `from` and `until` use `YYYY-MM-DD`. Either value may be omitted, but a
 `visible` object must contain at least one of them.
 
 Hidden sections are omitted from the rendered HTML and sticky navigation. They
-remain in `content.md`, and `content:check` still validates their matching
+remain in the page file, and `content:check` still validates their matching
 Markdown headings and gallery image references.
 
-The current date is evaluated at dev/build time. Set `NORNA_TODAY` to
-preview or test a specific date:
+The current date is evaluated at dev/build time. Set `NORNA_TODAY` to preview
+or test a specific date:
 
 ```sh
 NORNA_TODAY=2026-08-15 npm run norna:build
 ```
 
-## Presentation
+## Markdown Text
 
-Site-wide presentation belongs in `site/theme.md`. Page-level presentation in
-`site/content.md` is always an override on top of the theme. Section-specific
-presentation belongs under `sections[].presentation`.
-
-If a page omits `presentation`, it uses the theme presentation unchanged. If a
-section omits `presentation`, it uses the resolved page presentation.
-
-```yaml
-presentation:
-  typography:
-    overrides:
-      body:
-        paragraphSpacing: 1em
-```
-
-### Typography Presets
-
-Typographic presentation is configured through presets with optional overrides:
-
-```yaml
-presentation:
-  typography:
-    preset: quiet-gallery
-    overrides:
-      body:
-        paragraphSpacing: 0.8em
-```
-
-Available presets:
-
-- `quiet-gallery`: the default for image-led art and portfolio sites. Text is
-  restrained and supports the images without dominating the page.
-- `compact-gallery`: tighter typography for many sections, many images, or
-  short information blocks.
-- `text-forward`: more generous body text for pages where longer text carries
-  more of the experience.
-- `statement`: stronger type for introductions, first sections, and short
-  programmatic statements. Use it sparingly, usually as a section override.
-
-The normal place to choose a site-wide preset is `site/theme.md`. If theme
-typography is omitted, `quiet-gallery` is used. A page-level
-`presentation.typography.preset` changes the typographic base for the page. A
-section-level `sections[].presentation.typography.preset` changes the
-typographic base for that section.
-
-Use this command to inspect the exact preset values shipped with the installed
-engine:
-
-```sh
-norna typography:presets
-```
-
-Use this command to inspect the effective values for the selected site after
-presets and overrides have been applied:
-
-```sh
-norna typography:show
-```
-
-The typographic roles are:
-
-- `heading`: section headings.
-- `body`: Markdown body text inside sections.
-- `caption`: gallery 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`.
-`lineHeight` is a unitless number from `1` through `3`. `spacing` and
-`paragraphSpacing` are CSS lengths such as `0`, `0.8em`, `1rem`, or `12px`.
-
-Supported override fields:
-
-- `heading.align`, `heading.size`, `heading.lineHeight`, `heading.spacing`
-- `body.align`, `body.size`, `body.lineHeight`, `body.paragraphSpacing`
-- `caption.align`, `caption.size`, `caption.lineHeight`, `caption.spacing`
-
-Use `site/theme.md` `presentation.inlineStyles` for named inline text styles
-that can be applied inside Markdown:
-
-```yaml
-presentation:
-  inlineStyles:
-    highlight:
-      color: "#ffd84d"
-```
-
-Apply an inline style in Markdown with `[text]{.style-name}`:
+Section Markdown starts at the matching level 2 heading and continues until the
+next level 2 heading.
 
 ```md
-This sentence contains [highlighted text]{.highlight}.
-```
-
-`content:check` fails if Markdown uses an inline style that is not defined in
-`site/theme.md` `presentation.inlineStyles`.
+## Intro {#intro}
 
-`sections[].presentation` contains only section-specific differences:
+Paragraph text.
 
-```yaml
-sections:
-  - id: intro
-    presentation:
-      backgroundColor: "#161616"
-      textColor: "#ffffff"
-      typography:
-        preset: statement
-        overrides:
-          body:
-            paragraphSpacing: 0.7em
+Another paragraph.
 ```
 
-If a section sets `typography.preset`, that section starts from that preset. If
-a section only sets `typography.overrides`, it keeps the resolved page preset
-and changes only the specified values.
-
-Centered text uses narrower text widths. Left- or right-aligned heading and body
-text use the calculated gallery layout width so text edges line up with gallery
-images after layout gutters and gallery limits are applied.
-Configured section backgrounds render as full-width horizontal bands while the
-section content keeps the normal page and gallery widths. The top spacing
-before the first heading, the spacing between sections, and the spacing after
-the final section are part of the section background. The sticky section
-navigation row and footer use the resolved frame colors, not section-specific
-presentation.
-Configured section text colors apply to section headings, Markdown text,
-Markdown subheadings, and gallery captions. Links keep the global accent color.
-
-## Markdown Sections
-
-Every frontmatter section must have a matching level 2 Markdown heading with an
-explicit id:
+Inline styles use this Markdown form:
 
 ```md
-## Work {#work}
-
-Introductory text.
+This sentence contains [highlighted text]{.highlight}.
 ```
 
-Keep these values aligned:
-
-- the frontmatter `sections[].id`
-- the Markdown heading id
-- the source image directory `site/images/<section-id>/`
-
-The visible navigation label comes from the Markdown heading text, not from the
-frontmatter id.
+Inline style definitions live in `site/theme.md`. See
+[Theme](theme.md#inline-styles).
 
 ## Validation And Sync
 
@@ -352,8 +193,8 @@ frontmatter indentation and structure mistakes.
 
 Frontmatter uses YAML indentation. Use ordinary spaces, not tabs or
 non-breaking spaces. `content:check` reports a focused error when indentation is
-invalid, when a key is indented under a line that already has a value, or when
-a known nested key such as `gallery` appears at the top level:
+invalid, when a key is indented under a line that already has a value, or when a
+known nested key such as `gallery` appears at the top level:
 
 ```yaml
 typography:
@@ -363,9 +204,9 @@ typography:
       paragraphSpacing: 0.8em
 ```
 
-Top-level page frontmatter may contain only `title`, `description`,
-`presentation`, `frame`, and `sections`. A `gallery` key belongs under one
-`sections[]` item:
+Top-level page frontmatter may contain only `title`, `description`, `slug`,
+`navigation`, `presentation`, `frame`, and `sections`. A `gallery` key belongs
+under one `sections[]` item:
 
 ```yaml
 sections:

package/docs/{command-organization.md → design/command-organization.md}

@@ -86,12 +86,15 @@ Examples:
 npm run release:patch
 npm run release:minor
 npm run release:major
-npm run release:publish
 ```
 
-These commands change or publish the reusable `@janga/norna` package.
+These commands change and publish the reusable `@janga/norna` package.
 They must not be part of ordinary site repositories.
 
+`npm run release:publish` is a low-level script used by the release command
+after the version has already been bumped. It is not the normal release entry
+point.
+
 ### Direct CLI Commands
 
 The `norna` binary is the stable low-level command surface.
@@ -157,7 +160,6 @@ In the engine repository, version changes belong to `release:*`:
 
 ```sh
 npm run release:minor
-npm run release:publish
 ```
 
 ### Initialize A Gallery Project Directory
@@ -231,7 +233,7 @@ npm run norna:dev:stop
 The shorter `norna:dev` starts the normal local server. Subcommands manage
 the same server.
 
-In the engine repository, engine/demo development may use the engine's own
+In the engine repository, engine and example development may use the engine's own
 unprefixed commands:
 
 ```sh
@@ -360,7 +362,9 @@ gallery, they should call `norna:*` scripts internally.
 Engine publishing uses `release:*`, not `norna:*`:
 
 ```sh
-npm run release:publish
+npm run release:patch
+npm run release:minor
+npm run release:major
 ```
 
 ### Monitor Publishing

package/docs/{site-examples-structure-note.md → design/site-examples-structure.md}

@@ -1,8 +1,7 @@
-# Site Examples Structure Note
+# Site Examples Structure
 
-This note defines the intended repository vocabulary before reorganizing
-starter files, demo sites, fixtures, and documentation sites. It is a design
-note, not an implementation record.
+This document defines the repository vocabulary for starter files, example
+sites, fixtures, and documentation sites.
 
 ## Goal
 
@@ -10,8 +9,8 @@ note, not an implementation record.
 files are product documentation, which files are examples, and which files are
 test fixtures.
 
-The current repository grew from one local demo, one starter, and a set of
-tests. A future structure should keep those roles separate.
+The repository grew from one local demo, one starter, and a set of tests. The
+current structure keeps those roles separate.
 
 ## Terms
 
@@ -57,30 +56,31 @@ for human reading or visual appeal.
 
 ## Intended Direction
 
-A future structure should collect runnable site examples in one place, for
-example:
+Runnable site examples are collected under `examples/`:
 
 ```text
-sites/
-  starter-basic/
+examples/
   dog-gallery/
   routes-demo/
   typography-demo/
-  docs-site/
 ```
 
-The exact names can change, but the roles should remain clear:
+Only `dog-gallery/` exists today. Additional examples should be added when
+they demonstrate a distinct feature or workflow.
 
-- `starter-basic/`: copied by `norna init`.
-- `dog-gallery/`: local visual demo and manual inspection site.
+- `dog-gallery/`: current local visual demo, manual inspection site, and
+  navigation diagnostic target.
 - `routes-demo/`: focused route/navigation example if dog-gallery becomes too
   broad.
 - `typography-demo/`: focused typography preset and override example if needed.
-- `docs-site/`: visual documentation built with `norna`.
 
+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 may either stay under `fixtures/` or move under a clearly named test
 area later. They should not be confused with examples.
 
@@ -94,12 +94,7 @@ area later. They should not be confused with examples.
 
 ## Open Decisions
 
-- Exact top-level directory name: `sites/`, `examples/`, or another name.
-- Whether `starter-basic/` belongs beside examples or in a separate template
-  area.
-- Whether the current dog-gallery remains the primary manual test site or
-  becomes one example among several.
 - Whether the documentation site should be published anywhere, or exist only as
   a local/example build.
-- How demo selection should work in npm scripts, for example
-  `npm run demo:dev -- dog-gallery`.
+- How local example selection should work when there are multiple runnable
+  examples.