@janga/norna 0.7.16 → 0.7.17

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/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.

package/docs/theme.md

@@ -4,9 +4,9 @@
 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 route directory replaces the root visual
-theme for that route. Shared identity such as the navigation label and logo
-remains site-wide and belongs in `sitewide-content.yaml`.
+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
 
@@ -80,8 +80,8 @@ typography override.
 Norna never loads `orig-*-theme.yaml`; only `theme.yaml` is active. The export
 command refuses to overwrite an existing reference file.
 
-Site identity is not part of the visual theme. Define the optional navigation
-label and logo display settings in `site/sitewide-content.yaml`; see
+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
@@ -226,26 +226,26 @@ palette: paper  # Alternatives: dark, light
 sectionSurfaces: [base, soft, emphasis]
 ```
 
-## Route Themes
+## Page Themes
 
-Add `theme.yaml` to a route directory when that route should have a different
+Add `theme.yaml` to a page directory when that page should have a different
 visual expression:
 
 ```text
-site/routes/010-guide/theme.yaml
+site/pages/010-guide/theme.yaml
 ```
 
-The route theme uses the same visual schema and complete presets as the root
-theme. A route can therefore select a different expression without repeating a
+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 route. If the route
+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 identity or
+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
@@ -254,18 +254,18 @@ accent color.
 
 ## Common Questions
 
-### Should every route select its own preset?
+### Should every page select its own preset?
 
-No. A route without its own `theme.yaml` inherits the root theme, which is the
+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 route theme only when the route should intentionally look different. If
-the route should keep the same preset but demonstrate a focused change, repeat
-the root preset in the route theme and override only that setting. This is
-necessary because a route theme replaces the root visual theme rather than
+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 route demonstrating section surfaces may keep `preset: project`
-and change only `sectionSurfaces`. A route demonstrating image or content
+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

@@ -12,7 +12,7 @@ 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 route-theme level, not in page or section content.
+or page-theme level, not in page or section content.
 
 ## Typography Profiles
 
@@ -25,7 +25,7 @@ Available profiles:
 - `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 route-level exception.
+  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
@@ -65,7 +65,7 @@ profiles, rhythms, and overrides have been applied:
 norna typography show
 ```
 
-The output includes the site theme, every page route, and every section. Each
+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`.
 
@@ -148,31 +148,31 @@ Supported override fields:
 - `caption.align`, `caption.size`, `caption.lineHeight`,
   `caption.spacingBefore`
 
-## Route Themes
+## Page Themes
 
-The simplest route-specific typography change is to select a complete theme
+The simplest page-specific typography change is to select a complete theme
 preset:
 
 ```yaml
-# site/routes/010-introduction/theme.yaml
+# site/pages/010-introduction/theme.yaml
 preset: statement
 ```
 
-A route-local `theme.yaml` replaces the root visual theme rather than inheriting
-from it. The complete preset supplies a coherent route theme without repeating
+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/routes/010-introduction/theme.yaml
+# site/pages/010-introduction/theme.yaml
 typography:
   profile: statement
   rhythm: normal
 ```
 
-Without a top-level theme preset, other omitted route-theme values use engine
+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

package/examples/README.md

@@ -7,10 +7,10 @@ documentation workflow.
 | Example | Purpose | Live demo | Source |
 | --- | --- | --- | --- |
 | Dog shelter, single page | A coherent homepage made from sections | [Open site](https://janga.github.io/norna/examples/complete-sites/dog-shelter-single-page/) | [View files](complete-sites/dog-shelter-single-page/) |
-| Dog shelter, multi-page | A coherent site with ordered routes and route-local images | [Open site](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/) | [View files](complete-sites/dog-shelter-multi-page/) |
+| Dog shelter, multi-page | A coherent site with ordered pages and page-local images | [Open site](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/) | [View files](complete-sites/dog-shelter-multi-page/) |
 | Theme presets | All complete presets without overrides | [Open site](https://janga.github.io/norna/examples/feature-demos/theme-presets/) | [View files](feature-demos/theme-presets/) |
 | Media and surfaces | Image blocks, cards, notes, palettes, and section surfaces | [Open site](https://janga.github.io/norna/examples/feature-demos/media-and-surfaces/) | [View files](feature-demos/media-and-surfaces/) |
-| Sitewide content | Shared identity, navigation, banners, and footer content | [Open site](https://janga.github.io/norna/examples/feature-demos/sitewide-content/) | [View files](feature-demos/sitewide-content/) |
+| Sitewide content | Shared logo settings, banners, and footer content | [Open site](https://janga.github.io/norna/examples/feature-demos/sitewide-content/) | [View files](feature-demos/sitewide-content/) |
 
 ## Directory Structure
 

package/examples/complete-sites/dog-shelter-multi-page/.astro/collections/site.schema.json

@@ -2,58 +2,34 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
-    "title": {
-      "type": "string"
-    },
-    "description": {
-      "type": "string"
+    "page": {
+      "type": "object",
+      "properties": {
+        "description": {
+          "description": "Optional page-specific meta description.",
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false,
+      "description": "Optional metadata for this homepage or additional page. The Markdown H1 supplies the page title."
     },
     "navigation": {
+      "description": "Optional navigation metadata for this page.",
       "type": "object",
       "properties": {
-        "include": {
+        "listed": {
+          "default": true,
+          "description": "List this page in site navigation. The page remains public when false.",
           "type": "boolean"
-        },
-        "label": {
-          "type": "string"
         }
       },
       "additionalProperties": false
     },
-    "sections": {
-      "default": {},
-      "type": "object",
-      "propertyNames": {
-        "type": "string",
-        "pattern": "^[a-z0-9-]+$"
-      },
-      "additionalProperties": {
-        "type": "object",
-        "properties": {
-          "visible": {
-            "type": "object",
-            "properties": {
-              "from": {
-                "type": "string",
-                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
-              },
-              "until": {
-                "type": "string",
-                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
-              }
-            },
-            "additionalProperties": false
-          }
-        },
-        "additionalProperties": false
-      }
-    },
     "$schema": {
       "type": "string"
     }
   },
-  "required": [
-    "title",
-    "description"
-  ]
+  "additionalProperties": false,
+  "description": "Frontmatter for a homepage or additional page content.md file."
 }

package/examples/complete-sites/dog-shelter-multi-page/.astro/collections/sitewide.schema.json

@@ -2,55 +2,49 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "type": "object",
   "properties": {
-    "navigation": {
+    "logo": {
       "type": "object",
       "properties": {
-        "brand": {
+        "height": {
+          "description": "Displayed logo height. Width follows the intrinsic aspect ratio.",
           "type": "string",
-          "minLength": 1
-        },
-        "logo": {
-          "type": "object",
-          "properties": {
-            "alt": {
-              "type": "string",
-              "minLength": 1
-            },
-            "height": {
-              "type": "string",
-              "pattern": "^(?:0|(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)|clamp\\(\\s*(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)\\s*,\\s*(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)\\s*,\\s*(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)\\s*\\))$"
-            }
-          },
-          "additionalProperties": false
+          "pattern": "^(?:0|(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)|clamp\\(\\s*(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)\\s*,\\s*(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)\\s*,\\s*(?:\\d+(?:\\.\\d+)?|\\.\\d+)(?:px|rem|em|vw|vh|vmin|vmax|ch|%)\\s*\\))$"
         }
       },
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "Optional display settings for a convention-based navigation logo."
     },
     "banners": {
       "default": [],
+      "description": "Site-wide dismissible notices.",
       "type": "array",
       "items": {
         "type": "object",
         "properties": {
           "id": {
             "type": "string",
-            "pattern": "^[a-z0-9-]+$"
+            "pattern": "^[a-z0-9-]+$",
+            "description": "Stable banner identifier used for dismissal state."
           },
           "tone": {
             "default": "warning",
+            "description": "Semantic banner tone.",
             "type": "string",
             "enum": [
               "warning"
             ]
           },
           "visible": {
+            "description": "Optional date window for the banner.",
             "type": "object",
             "properties": {
               "from": {
+                "description": "First date on which the content is visible.",
                 "type": "string",
                 "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
               },
               "until": {
+                "description": "First date on which the content is no longer visible.",
                 "type": "string",
                 "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
               }
@@ -59,11 +53,13 @@
           },
           "title": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "description": "Short banner heading."
           },
           "text": {
             "type": "string",
-            "minLength": 1
+            "minLength": 1,
+            "description": "Concise banner message."
           }
         },
         "required": [
@@ -71,61 +67,23 @@
           "title",
           "text"
         ],
-        "additionalProperties": false
+        "additionalProperties": false,
+        "description": "Dismissible site-wide warning shown above page content for important temporary information."
       }
     },
     "footer": {
+      "description": "Site-wide footer content.",
       "type": "object",
       "properties": {
         "copyrightMessage": {
+          "description": "Copyright or ownership text shown in the site footer.",
           "type": "string",
           "minLength": 1
         },
         "buildInfo": {
-          "type": "object",
-          "properties": {
-            "enabled": {
-              "default": true,
-              "type": "boolean"
-            },
-            "text": {
-              "type": "string",
-              "minLength": 1
-            },
-            "dateTimeFormat": {
-              "type": "object",
-              "properties": {
-                "locale": {
-                  "type": "string",
-                  "minLength": 1
-                },
-                "timeZone": {
-                  "type": "string",
-                  "minLength": 1
-                },
-                "dateStyle": {
-                  "type": "string",
-                  "minLength": 1
-                },
-                "timeStyle": {
-                  "type": "string",
-                  "minLength": 1
-                }
-              },
-              "required": [
-                "locale",
-                "timeZone",
-                "dateStyle",
-                "timeStyle"
-              ],
-              "additionalProperties": false
-            }
-          },
-          "required": [
-            "text",
-            "dateTimeFormat"
-          ],
-          "additionalProperties": false
+          "default": false,
+          "description": "Show a localized generated build timestamp in the footer.",
+          "type": "boolean"
         }
       },
       "additionalProperties": false
@@ -134,5 +92,6 @@
       "type": "string"
     }
   },
-  "additionalProperties": false
+  "additionalProperties": false,
+  "description": "Editorial content and optional navigation logo display settings shared by every page."
 }