@janga/norna 0.7.16 → 0.7.18

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/pages/000-home/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:
 
@@ -11,15 +11,19 @@ site/
 |-- config.yaml
 |-- theme.yaml
 |-- sitewide-content.yaml
-|-- content.md
-|-- images/
-|   `-- <section-id>/
-|-- routes/
-|   `-- <NNN-route-id>/
+|-- pages/
+|   |-- 000-home/
+|   |   |-- content.md
+|   |   `-- images/
+|   |       `-- image.jpg
+|   `-- 010-guide/
 |       |-- content.md
 |       |-- theme.yaml
-|       `-- images/
-|           `-- <section-id>/
+|       |-- images/
+|       |   `-- image.jpg
+|       `-- pages/
+|           `-- 010-installation/
+|               `-- content.md
 |-- public/
 `-- .norna/
     |-- generated-images.json
@@ -36,8 +40,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. |
+| `pages/` | Yes | Homepage, top-level pages, and nested page hierarchies. |
 
 These responsibilities are deliberately separate:
 
@@ -47,43 +51,47 @@ 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.
+- [`pages/000-home/content.md`](content.md) is the required homepage 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
+## Pages
 
-Managed homepage images belong in:
+Every page is represented by a directory containing `content.md`. The homepage
+is the one reserved page:
 
 ```text
-site/images/<section-id>/
+site/pages/000-home/content.md
 ```
 
-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.
-
-## Routes
-
-Each first-level route is one directory under `routes/`:
+It maps to `/`, cannot contain child pages, and appears first in global
+navigation. Other directories directly under `site/pages/` are top-level page
+roots:
 
 ```text
-site/routes/010-guide/
+site/pages/010-guide/
 |-- content.md
 |-- theme.yaml
-`-- images/
-    `-- intro/
+|-- images/
+|   `-- image.jpg
+`-- pages/
+    `-- 010-installation/
+        |-- content.md
+        `-- images/
+            `-- diagram.svg
 ```
 
-`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.
+Nested `pages/` directories create child pages and may continue to further
+depths. Each page owns its optional `images/` directory. A page-local
+`theme.yaml` may adjust a limited set of presentation properties and is inherited
+by descendants; site colors, typography, shape, and navigation remain global.
 
-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 sibling navigation order and is not part
+of the URL. See [Pages](pages.md) for hierarchy, URL, navigation, and page-theme
+rules. See [Images and Metadata](images-and-metadata.md) for managed files.
 
 ## Public Files
 
@@ -91,8 +99,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
 
@@ -100,8 +109,8 @@ 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.
+it contains `config.yaml` and `pages/000-home/content.md`. Otherwise it walks
+upward until it finds a default `site/` directory containing those markers.
 
 ## Versioned Files
 
@@ -141,4 +150,3 @@ site:
 - `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,45 +1,37 @@
 # `sitewide-content.yaml`
 
 `site/sitewide-content.yaml` is optional. It contains editorial content and
-identity shared by every page: the navigation label, banners, and footer.
+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 Identity
+## Navigation Logo
 
-Use the optional `navigation` object for identity shared by the homepage and
-all routes:
+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/pages/000-home/content.md`.
 
-```yaml
-navigation:
-  label: Example Site
-```
-
-Without a navigation logo, `label` is shown in the home link. With a logo,
-`label` becomes the image alternative text. If omitted, Norna uses the homepage
-title from `site/content.md`.
-
-A logo file is discovered from `site/public/`; no path is configured here. Add
-`logo` only to override its displayed height:
+Add `logo` only to override the discovered file's displayed height:
 
 ```yaml
-navigation:
-  label: Example Site
-  logo:
-    height: 2.6rem
+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.
 
-Routes inherit this identity and cannot replace it in route content or a route
-theme.
+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 route. List
+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:
 
@@ -54,9 +46,8 @@ banners:
     text: Not for production use.
 ```
 
-`tone` currently supports `warning`. `visible` is optional and uses the same
-date-window rules as temporary sections: `from` is inclusive and `until` is
-exclusive.
+`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
@@ -71,19 +62,12 @@ information:
 ```yaml
 footer:
   copyrightMessage: (c) Example Owner.
-  buildInfo:
-    enabled: true
-    text: Built
-    dateTimeFormat:
-      locale: en-GB
-      timeZone: UTC
-      dateStyle: short
-      timeStyle: short
+  buildInfo: true
 ```
 
-`dateTimeFormat` uses `Intl.DateTimeFormat` values. `timeZone` must be a valid
-IANA time-zone name. If both copyright text and enabled build information are
-absent, no footer is rendered.
+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.