@janga/norna 0.7.16 → 0.7.17

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

@@ -26,7 +26,7 @@ site repository. It should not be a showcase for every feature.
 
 An example site is a runnable site that demonstrates one or more features.
 
-Examples can be richer than the starter. They may show routes, navigation,
+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.
 
@@ -35,8 +35,8 @@ and site-specific configuration choices.
 A documentation site is a runnable `norna` site that explains the product
 visually.
 
-It can use images, diagrams, screenshots, and route pages to explain concepts
-such as file structure, presentation inheritance, route navigation, and image
+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
@@ -73,22 +73,22 @@ examples/
 `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 routes.
-- `dog-shelter-multi-page/`: ordered routes with route-local content and
+- `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 route per complete built-in theme preset, without
+- `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 identity, navigation, banner stacks,
-  dismissal and footer content shared across routes.
+- `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 route.
+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

package/docs/engine-development.md

@@ -185,25 +185,25 @@ and commit their updated `package-lock.json`.
 
 ## Rendering Notes
 
-The renderer builds the homepage at `/` and optional first-level routes from
-`site/routes/<NNN-route-id>/content.md`.
+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 pages and routes. It uses normal page URLs and
-  browser history.
-- Page navigation moves between sections on the current page. It uses real
+- 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 route support matures. For now,
-single-page sites should rely on page navigation only; small route-based sites
-may combine site navigation and page navigation; larger information
+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
-page-navigation state. A section-link click pushes one hash entry into browser
+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.

package/docs/getting-started.md

@@ -73,46 +73,51 @@ Replace `site/content.md` with:
 
 ```md
 ---
-title: My first Norna site
-description: A website built from plain files.
+page:
+  description: A website built from plain files.
 ---
 
-## Welcome {#welcome}
+# 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.
 ```
 
-Each `##` heading is a page section. Its explicit `{#section-id}` gives the
-section a stable identity and is required by Norna.
+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 single-page navigation should link to those two sections. You should not
+the section navigation should link to those two sections. You should not
 need to restart the server.
 
-## 3. Set The Shared Identity
+## 3. Set Shared Content
 
 Replace `site/sitewide-content.yaml` with:
 
 ```yaml
-navigation:
-  label: My first Norna site
 footer:
   copyrightMessage: My first Norna site.
 ```
 
-The navigation label and footer are site-wide content rather than page
-sections. If you add routes later, they inherit these values.
+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 Identity Is Shared
+### Checkpoint: The Footer Is Shared
 
-The navigation should now display `My first Norna site`. The footer should show
-the new message.
+The navigation should use `My first Norna site` from `content.md`. The footer
+should show the new message.
 
 ## 4. Choose A Complete Theme
 
@@ -158,7 +163,7 @@ build.
 ## What To Do Next
 
 - [Add and manage images](content.md#norna-blocks)
-- [Add another page](routes.md)
+- [Add another page](pages.md)
 - [Inspect and adjust the theme](theme.md)
 - [Configure the public URL](configuration.md)
 - [Publish with GitHub Pages](publishing.md)

package/docs/images-and-metadata.md

@@ -12,13 +12,13 @@ Norna-managed local images are referenced from Markdown with
 Homepage source images live under:
 
 ```text
-site/images/<section-id>/
+site/images/
 ```
 
-Route source images live under:
+Page source images live under:
 
 ```text
-site/routes/<NNN-route-id>/images/<section-id>/
+site/pages/<NNN-page-id>/images/
 ```
 
 Supported source extensions:
@@ -52,11 +52,12 @@ prompt: Short prompt or editing note.
 -->
 ```
 
-Filenames do not have to be globally unique for the site to be valid.
-Automatic sync only moves misplaced files when the filename identifies exactly
-one source candidate across the site's page and route image roots, and when the
-move will not break another reference. If the move crosses page or route image
-roots, `content:sync` requires a clean Git working tree before writing.
+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
 
@@ -139,7 +140,7 @@ 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/content.md`, route content files, `COPYRIGHT.md`, or other site
+`site/content.md`, page content files, `COPYRIGHT.md`, or other site
 documentation.
 
 If a site wants embedded metadata in original source files, that process is

package/docs/pages.md

@@ -0,0 +1,134 @@
+# Pages
+
+`site/content.md` is the homepage and builds to `/`. Optional additional pages live
+under `site/pages/<NNN-page-id>/content.md` and build to first-level
+URLs.
+
+Pages use the same H1 title, optional frontmatter, Norna-managed blocks, and
+Markdown section model as the homepage. See [Content](content.md) for the page
+and section model.
+
+Page directories can contain page content, page-local images, and
+an optional page-local `theme.yaml`. The page theme replaces the root visual
+theme for that page and can select any complete top-level theme preset. Page
+directories cannot contain `config.yaml` or `sitewide-content.yaml`; technical
+configuration and shared logo, banner, and footer settings remain at the
+selected site's top level.
+
+## Page Directory Format
+
+Page directories must use:
+
+```text
+NNN-page-id
+```
+
+`NNN` is a three-digit presentation order from `001` through `999`.
+`page-id` becomes the page id and URL segment.
+
+Valid examples:
+
+```text
+010-getting-started
+020-concepts
+120-api-reference
+```
+
+Invalid examples:
+
+```text
+10-about
+000-home
+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 page id or
+URL.
+
+Renaming `030-contact/` to `015-contact/` changes navigation order but keeps
+the page id `contact` and URL `/contact/`.
+
+## Page File
+
+Add a first-level page by creating:
+
+```text
+site/pages/010-about/content.md
+```
+
+Minimal additional page:
+
+```md
+---
+page:
+  description: About this site.
+---
+
+# About
+
+Introductory text.
+
+## Team {#team}
+
+Text...
+```
+
+The example above builds to `/about/`.
+
+## Navigation
+
+Site navigation uses each page's Markdown H1 as its visible label and the
+page-directory prefix as its order. In a multi-page site, the homepage is the
+first navigation item and uses its own H1. An optional logo is a separate home
+link; it does not replace the homepage item or own a section menu.
+
+`navigation` has one optional field:
+
+- `listed`: boolean. Defaults to `true`. Set it to `false` to keep the page
+  public while excluding it from site navigation.
+
+```yaml
+navigation:
+  listed: false
+```
+
+Page order comes from the directory prefix.
+The homepage is always listed before additional pages.
+
+Current site navigation is intended for small sites. This guidance may change
+as navigation support matures, but the present model is:
+
+- A single-page site should normally use only section navigation.
+- A small multi-page site may use site navigation between pages plus section
+  navigation on the current page.
+- If a site needs many pages, deeply nested pages, or several navigation
+  levels, it has probably outgrown the current sticky-navigation model and may
+  need a different site structure or navigation system.
+
+## Page Images
+
+Page images live under the physical page directory:
+
+```text
+site/pages/010-about/images/image.jpg
+```
+
+Image references in page content still use only the filename:
+
+````md
+```norna-image-stack
+- image: image.jpg
+  alt: Intro image.
+```
+````
+
+All managed images used by the page share this one `images/` directory. Run
+`norna content:check` to find missing or misplaced images and
+`norna content:sync` to move unambiguous files into the expected page image
+root. `content:sync` can move images between page image roots when the filename
+is unambiguous across the site and the move will not break another reference;
+these cross-page writes require a clean Git working tree.

package/docs/public-files.md

@@ -11,62 +11,72 @@ convention.
 
 ## Navigation Logo
 
-Put exactly one navigation logo directly in `site/public/`. Its filename must
-be exactly one of:
+To add a navigation logo, place exactly one supported logo file directly in
+`site/public/`:
 
 - `logo.svg`
 - `logo.png`
 - `logo.jpg`
 - `logo.jpeg`
 
-Use lowercase letters and match the complete filename exactly. This is required
-for portability between case-sensitive and case-insensitive file systems.
+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.
 
-Norna discovers and displays the file automatically. No configuration path or
-enable switch is needed. Only one supported logo file may exist.
+The logo links to the homepage. Its alternative text comes from the homepage
+Markdown H1 in `site/content.md`; no separate site name or logo alt text is
+configured.
 
-The shared navigation label is configured separately:
+Configure top-level `logo` in `site/sitewide-content.yaml` only when you need
+to override the displayed height:
 
 ```yaml
-navigation:
-  label: Example Site
+logo:
+  height: 2rem
 ```
 
-Without a logo, `label` is shown as navigation text. With a logo, it becomes the
-image alternative text. If `label` is omitted, Norna uses the homepage title.
-
-Add the optional `logo` object only to override the displayed height:
-
-```yaml
-navigation:
-  label: Example Site
-  logo:
-    height: 2rem
-```
-
-The width follows the logo's intrinsic aspect ratio. `navigation.logo` does not
-enable the logo or select a file.
+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
-`navigation.logo` is configured but no logo file exists. A site without a logo
-uses its text label; the check reports this fallback as a warning.
-
-## Logos And Favicons
+`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.
 
-A navigation logo is visible inside the website. A favicon identifies the site
-in browser tabs, bookmarks, and similar browser UI. They are independent and
-may coexist.
+## Browser Icons
 
-Norna recognizes these browser-icon filenames directly under `site/public/`:
+To add browser icons, place one or more supported files directly in
+`site/public/`:
 
 - `favicon.svg`
 - `favicon.ico`
 - `favicon.png`
 - `apple-touch-icon.png`
 
-These filenames must also match exactly and use lowercase letters. More than
-one format may be present. Norna emits links for every supported file and lets
-the browser choose the appropriate one.
+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
 
@@ -75,12 +85,16 @@ Other names are not restricted. For example:
 ```text
 site/public/
 |-- robots.txt
-|-- CNAME
 |-- 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
@@ -102,4 +116,3 @@ validated, synced, processed, and captioned. See
 `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.
-

package/docs/publishing.md

@@ -9,7 +9,21 @@ want to deploy the documentation site.
 
 ## GitHub Pages Workflow
 
-Each site repository owns `.github/workflows/deploy.yml`. The starter workflow:
+`norna init` creates the GitHub Pages workflow at exactly:
+
+```text
+.github/workflows/deploy.yml
+```
+
+The file belongs to the site repository. GitHub Actions runs its contents, while
+Norna's deploy helpers use the filename to find and monitor the workflow. Keep
+the default filename when using `norna deploy`.
+
+GitHub Actions itself permits other workflow filenames. If the file is renamed,
+`norna deploy:watch` can monitor it with `--workflow <name-or-file>`, but the
+normal `norna deploy` command still expects `deploy.yml`.
+
+The starter workflow:
 
 1. runs for the repository's default branch,
 2. checks out the site repository,
@@ -20,8 +34,10 @@ Each site repository owns `.github/workflows/deploy.yml`. The starter workflow:
 7. deploys the artifact to GitHub Pages.
 
 In the GitHub repository settings, set Pages to build from GitHub Actions.
-Site-specific public files such as `site/public/CNAME`, `robots.txt` and
-`sitemap.xml` belong in the site repository.
+Site-specific public files such as `site/public/CNAME`, `robots.txt`, and
+`sitemap.xml` belong in the site repository. Norna copies them, while GitHub
+Pages, crawlers, and other external consumers give those filenames their
+meaning. See [Public Files](public-files.md).
 
 For a project site without a custom domain, include the repository path in
 `site/config.yaml`:

package/docs/site-files.md

@@ -2,7 +2,7 @@
 
 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, routes, and assets without path configuration.
+presentation, configuration, pages, and assets without path configuration.
 
 The selected site directory is `site/` by default:
 
@@ -13,13 +13,13 @@ site/
 |-- sitewide-content.yaml
 |-- content.md
 |-- images/
-|   `-- <section-id>/
-|-- routes/
-|   `-- <NNN-route-id>/
+|   `-- image.jpg
+|-- pages/
+|   `-- <NNN-page-id>/
 |       |-- content.md
 |       |-- theme.yaml
 |       `-- images/
-|           `-- <section-id>/
+|           `-- image.jpg
 |-- public/
 `-- .norna/
     |-- generated-images.json
@@ -36,8 +36,8 @@ case-insensitive file systems.
 | --- | --- | --- |
 | `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 navigation identity, banners, and footer. |
-| `content.md` | Yes | Homepage metadata, sections, prose, and Norna blocks. |
+| `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:
 
@@ -47,43 +47,44 @@ These responsibilities are deliberately separate:
   only a preset selection.
 - [`sitewide-content.yaml`](sitewide-content.md) contains editorial material
   shared by every page.
-- [`content.md`](content.md) is the homepage page file and remains ordinary
-  Markdown with YAML frontmatter.
+- [`content.md`](content.md) is the homepage file and remains ordinary
+  Markdown. YAML frontmatter is optional.
 
-Routes cannot provide `config.yaml` or `sitewide-content.yaml`. Technical
-configuration and shared identity have one site-wide source.
+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/<section-id>/
+site/images/
 ```
 
-The directory name must match an explicit level 2 Markdown section id in
-`content.md`. 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.
+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.
 
-## Routes
+## Pages
 
-Each first-level route is one directory under `routes/`:
+Each first-level page is one directory under `pages/`:
 
 ```text
-site/routes/010-guide/
+site/pages/010-guide/
 |-- content.md
 |-- theme.yaml
 `-- images/
-    `-- intro/
+    `-- image.jpg
 ```
 
-`content.md` is required for a route. The optional route `theme.yaml` replaces
-the root visual theme for that route. Route images follow the same
-`images/<section-id>/` convention as homepage images.
+`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 route prefix controls navigation order and is not part of the
-URL. See [Routes](routes.md) for exact directory-name and route-id rules.
+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
 
@@ -91,8 +92,9 @@ URL. See [Routes](routes.md) for exact directory-name and route-id rules.
 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 logo and favicon filenames, arbitrary
-static files, root-relative links, and publishing paths.
+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
 
@@ -141,4 +143,3 @@ site:
 - `examples/`: complete sites and focused feature demonstrations;
 - `fixtures/`: engine regression input;
 - root `site/`: the Norna introduction and documentation site.
-