@janga/norna 0.7.16 → 0.7.18

package/starters/basic/README.md

@@ -15,14 +15,12 @@ If the standard local port is blocked, start with:
 npm run norna:dev -- --kill
 ```
 
-Edit the shared navigation label, logo settings, banners, and footer in
+Edit shared logo settings, banners, and footer in
 `site/sitewide-content.yaml`,
 site-wide visual defaults in `site/theme.yaml`, homepage content and section
-metadata in `site/content.md`, and technical settings such as URL and locale
-in `site/config.yaml`. Keep source images under `site/images/<section-id>/`
-and static public files under `site/public/`. The image folder name should
-match the section id in Markdown, for example `## Work {#work}` uses
-`site/images/work/`.
+metadata in `site/pages/000-home/content.md`, and technical settings such as URL
+and locale in `site/config.yaml`. Keep managed homepage source images under
+`site/pages/000-home/images/` and static public files under `site/public/`.
 
 For a GitHub Pages project site without a custom domain, include the repository
 path in the public URL:
@@ -36,10 +34,10 @@ Norna derives `/repository-name/` as the base path. Use a root URL such as
 
 In GitHub repository settings, configure Pages to build from GitHub Actions.
 
-Page width, side gutters, layout density, typography rhythm, image width, image
-height limits, font, palettes, section surfaces, and site-wide typography are
-configured in `site/theme.yaml`. A route may replace that visual theme with its
-own `theme.yaml`.
+Page width, side gutters, content spacing, image sizing, palette, shape, and
+site-wide typography are configured in `site/theme.yaml`. A page may use a
+limited `theme.yaml` for local text width, content spacing, managed-image
+sizing, and section background pattern.
 
 Commit `package-lock.json` after the first install so GitHub Actions can use
 `npm ci`.
@@ -73,7 +71,7 @@ Generic documentation lives in the `norna` repository:
 - `docs/content.md`
 - `docs/theme.md`
 - `docs/typography.md`
-- `docs/routes.md`
+- `docs/pages.md`
 - `docs/configuration.md`
 - `docs/commands.md`
 - `docs/images-and-metadata.md`

package/starters/basic/site/{content.md → pages/000-home/content.md}

@@ -1,16 +1,19 @@
 ---
-title: Example Site
-description: Minimal norna starter site.
+page:
+  description: Minimal norna starter site.
 ---
 
+# Example Site
+
+
 ## Intro {#intro}
 This is a minimal starter site for norna. Since this site doesn't have any
-routes defined, the navigation menu will be a sticky bar with anchor links for
+pages defined, the navigation menu will be a sticky bar with anchor links for
 ease of use on phones etc. **Highlighted inline text** when a short
 phrase needs emphasis
 ## Work {#work}
 Add Norna image blocks in Markdown where the images should appear. Put
-matching source images under `images/work/`.
+matching source images directly under `images/`.
 
 ````
 ```norna-image-stack

package/starters/basic/site/sitewide-content.yaml

@@ -1,12 +1,3 @@
-navigation:
-  label: Example Site
 footer:
   copyrightMessage: (c) Example Owner.
-  buildInfo:
-    enabled: true
-    text: Built
-    dateTimeFormat:
-      locale: en-GB
-      timeZone: UTC
-      dateStyle: short
-      timeStyle: short
+  buildInfo: true

package/starters/basic/site/theme.yaml

@@ -1,105 +1 @@
-# norna:start theme-help
-# Site-wide visual defaults. Remove a value to use the engine default.
-# Active values below are ordinary YAML; this marked comment block is only help text.
-#
-# Available structure:
-# layout:
-#   density: compact | normal | airy
-#   pageWidth: CSS length, e.g. 1180px
-#   gutter:
-#     desktop: CSS length or clamp(), e.g. clamp(1.25rem, 4vw, 3rem)
-#     mobile: CSS length, e.g. 1rem
-#   spacing:
-#     firstSectionTop:
-#       desktop: CSS length or clamp(), e.g. clamp(1.875rem, 3vw, 2.75rem)
-#       mobile: CSS length, e.g. 1.375rem
-#     sectionGap:
-#       desktop: CSS length or clamp(), e.g. clamp(1.4rem, 3vw, 2.75rem)
-#       mobile: CSS length, e.g. 1.5rem
-#     finalSectionBottom:
-#       desktop: CSS length or clamp(), e.g. clamp(1.4rem, 3vw, 2.75rem)
-#       mobile: CSS length, e.g. 1.5rem
-#     headingToBlock:
-#       desktop: CSS length, e.g. 0.75em
-#       mobile: CSS length, e.g. 0.7em
-#     blockGap:
-#       desktop: CSS length, e.g. 1.5em
-#       mobile: CSS length, e.g. 1.25em
-#     imageGap:
-#       desktop: CSS length or clamp(), e.g. clamp(1.25rem, 2.8vw, 2rem)
-#       mobile: CSS length, e.g. 1.5rem
-# images:
-#   width: CSS length, e.g. 900px
-#   maxAvailableWidthPercent:
-#     desktop: number from 1 through 100
-#     mobile: number from 1 through 100
-#   maxAvailableHeightPercent:
-#     desktop: number from 1 through 100
-#     mobile: number from 1 through 100
-# typography:
-#   fontFamily: CSS font-family stack
-#   profile: restrained | dense | reading | statement
-#   rhythm: compact | normal | airy
-#   overrides:
-#     headings:
-#       h2:
-#         align:
-#           desktop: left | center | right
-#           mobile: left | center | right
-#         size: small | medium | large | xlarge
-#         lineHeight: number from 1 through 3
-#         spacingBefore: CSS length, e.g. 0
-#         spacingAfter: CSS length, e.g. 0.55em
-#       h3:
-#         align:
-#           desktop: left | center | right
-#           mobile: left | center | right
-#         size: small | medium | large | xlarge
-#         lineHeight: number from 1 through 3
-#         spacingBefore: CSS length, e.g. 1.5em
-#         spacingAfter: CSS length, e.g. 0.5em
-#       h4:
-#         align:
-#           desktop: left | center | right
-#           mobile: left | center | right
-#         size: small | medium | large | xlarge
-#         lineHeight: number from 1 through 3
-#         spacingBefore: CSS length, e.g. 1.1em
-#         spacingAfter: CSS length, e.g. 0.4em
-#     body:
-#       align:
-#         desktop: left | center | right
-#         mobile: left | center | right
-#       size: small | medium | large | xlarge
-#       lineHeight: number from 1 through 3
-#       paragraphSpacing: CSS length, e.g. 0.85em
-#     caption:
-#       align:
-#         desktop: left | center | right
-#         mobile: left | center | right
-#       size: small | medium | large | xlarge
-#       lineHeight: number from 1 through 3
-#       spacingBefore: CSS length, e.g. 0.5em
-# palette: dark  # Alternatives: light, paper
-# sectionSurfaces: [base, soft, emphasis]
-# norna:end theme-help
-layout:
-  density: normal
-  pageWidth: 1180px
-  gutter:
-    desktop: clamp(1.25rem, 4vw, 3rem)
-    mobile: 1rem
-images:
-  width: 900px
-  maxAvailableWidthPercent:
-    desktop: 100
-    mobile: 100
-  maxAvailableHeightPercent:
-    desktop: 74
-    mobile: 68
-typography:
-  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
-  profile: restrained
-  rhythm: normal
-palette: dark  # Alternatives: light, paper
-sectionSurfaces: [base, soft, emphasis]
+preset: project

package/starters/project/README.md

@@ -19,13 +19,13 @@ npm run norna:dev -- --kill
 ## Files
 
 - `site/config.yaml`: public URL and optional language and smooth scrolling.
-- `site/sitewide-content.yaml`: shared navigation identity, banners, and footer.
-- `site/theme.yaml`: site-wide visual settings such as layout density, typography
-  rhythm, palettes, section surfaces, and typography.
-- `site/content.md`: homepage title, sections, placeholders, project summary,
+- `site/sitewide-content.yaml`: shared logo display settings, banners, and footer.
+- `site/theme.yaml`: the site-wide visual preset and any focused overrides.
+- `site/pages/000-home/content.md`: homepage title, sections, placeholders,
+  project summary,
   links, install command, example usage, benefits, next steps, Norna blocks,
   and license.
-- `site/routes/010-guide/content.md`: short secondary page with realistic
+- `site/pages/010-guide/content.md`: short secondary page with realistic
   project guide content.
 - `site/public/robots.txt`: static public file copied into the built site.
 
@@ -36,15 +36,15 @@ GitHub Pages workflow uses `npm ci`.
 ## Adapt The Starter
 
 1. Replace the project name, tagline, links, install command, example usage,
-   benefits, use cases, and license in `site/content.md`.
-2. Replace the guide examples in `site/routes/010-guide/content.md`, or
-   delete the route if the homepage is enough.
-3. Edit `site/sitewide-content.yaml` for the navigation label, logo display,
+   benefits, use cases, and license in `site/pages/000-home/content.md`.
+2. Replace the guide examples in `site/pages/010-guide/content.md`, or
+   delete the page if the homepage is enough.
+3. Edit `site/sitewide-content.yaml` for logo display settings,
    banners, and footer.
-4. Edit `site/theme.yaml` for layout density, typography rhythm, palette, section
-   surfaces, and typography.
-5. Put any local source images in the image folder for the Markdown section
-   that references them, for example `site/images/intro/`.
+4. Select a preset in `site/theme.yaml`. Add focused overrides only when the
+   project needs them.
+5. Put managed homepage source images in `site/pages/000-home/images/`. Images
+   for another page belong directly in that page's `images/` directory.
 6. Edit `site/config.yaml` for the public URL and, when needed, language or smooth
    scrolling. Deploy commands discover the GitHub repository and default branch.
 7. Update `package.json` with the site's package name and keep
@@ -79,6 +79,6 @@ Generic Norna documentation lives in the Norna repository:
 - `docs/content.md`
 - `docs/theme.md`
 - `docs/typography.md`
-- `docs/routes.md`
+- `docs/pages.md`
 - `docs/configuration.md`
 - `docs/commands.md`

package/starters/project/site/{content.md → pages/000-home/content.md}

@@ -1,10 +1,11 @@
 ---
-title: Your project
-description: A compact project site starter for an open source developer tool.
-navigation:
-  label: Home
+page:
+  description: A compact project site starter for an open source developer tool.
 ---
 
+# Your project
+
+
 ## `<Your project> - <short value proposition>` {#intro}
 
 Describe the project in one short, concrete phrase. Focus on what it helps the

package/starters/project/site/{routes → pages}/010-guide/content.md

@@ -1,10 +1,11 @@
 ---
-title: Guide
-description: Adapt this compact guide for normal project use.
-navigation:
-  label: Guide
+page:
+  description: Adapt this compact guide for normal project use.
 ---
 
+# Guide
+
+
 ## Quickstart {#quickstart}
 
 Show the shortest path from installation to a useful result.

package/starters/project/site/sitewide-content.yaml

@@ -1,12 +1,3 @@
-navigation:
-  label: Project Name
 footer:
   copyrightMessage: (c) Project contributors.
-  buildInfo:
-    enabled: true
-    text: Built
-    dateTimeFormat:
-      locale: en-GB
-      timeZone: UTC
-      dateStyle: short
-      timeStyle: short
+  buildInfo: true

package/starters/project/site/theme.yaml

@@ -1,31 +1 @@
-# Site-wide visual defaults. Remove a value to use the engine default.
-layout:
-  density: compact
-  pageWidth: 1120px
-  gutter:
-    desktop: clamp(1.25rem, 4vw, 3rem)
-    mobile: 1rem
-  spacing:
-    firstSectionTop:
-      desktop: clamp(0.9rem, 1.6vw, 1.5rem)
-      mobile: 0.9rem
-    sectionGap:
-      desktop: clamp(0.8rem, 1.6vw, 1.5rem)
-      mobile: 1rem
-    finalSectionBottom:
-      desktop: clamp(1rem, 2vw, 1.75rem)
-      mobile: 1rem
-images:
-  width: 840px
-  maxAvailableWidthPercent:
-    desktop: 100
-    mobile: 100
-  maxAvailableHeightPercent:
-    desktop: 70
-    mobile: 62
-typography:
-  fontFamily: "Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif"
-  profile: reading
-  rhythm: compact
-palette: dark  # Alternatives: light, paper
-sectionSurfaces: [base, soft]
+preset: project

package/docs/routes.md

@@ -1,121 +0,0 @@
-# Routes
-
-`site/content.md` is the homepage and builds to `/`. Optional route pages live
-under `site/routes/<NNN-route-id>/content.md` and build to first-level
-URLs.
-
-Routes use the same page frontmatter, optional section metadata, Norna-managed
-Norna blocks, and Markdown section model as the homepage. See [Content](content.md)
-for the page and section model.
-
-Route directories can contain route content, route-local images, and
-an optional route-local `theme.yaml`. The route theme replaces the root visual
-theme for that route and can select any complete top-level theme preset. Route
-directories cannot contain `config.yaml` or `sitewide-content.yaml`; technical
-configuration and shared identity remain at the selected site's top level.
-
-## Route Directory Format
-
-Route directories must use:
-
-```text
-NNN-route-id
-```
-
-`NNN` is a three-digit presentation order from `001` through `999`.
-`route-id` becomes the route identity 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 route id may contain only lowercase `a-z`, numbers, and single hyphens
-between alphanumeric groups. The numeric prefix is not part of the route id or
-URL.
-
-Renaming `030-contact/` to `015-contact/` changes navigation order but keeps
-the route id `contact` and URL `/contact/`.
-
-## Route File
-
-Add a first-level route by creating:
-
-```text
-site/routes/010-about/content.md
-```
-
-Minimal route page:
-
-```md
----
-title: About
-description: About this site.
-navigation:
-  label: About
----
-
-## Intro {#intro}
-
-Text...
-```
-
-The example above builds to `/about/`.
-
-## Navigation
-
-`navigation` may contain:
-
-- `include`: optional boolean. Defaults to `true`.
-- `label`: optional string. Defaults to `title`.
-
-Route order comes from the directory prefix. The homepage is always first.
-
-Current route navigation is intended for small sites. This guidance may change
-as route support matures, but the present model is:
-
-- 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.
-
-## Route Images
-
-Route images live under the physical route directory:
-
-```text
-site/routes/010-about/images/intro/image.jpg
-```
-
-Image references in route content still use only the filename:
-
-````md
-```norna-image-stack
-- image: image.jpg
-  alt: Intro image.
-```
-````
-
-The image directory segment after `images/` should match the section id.
-If the section id or route folder changes, run `norna content:check` to find
-misplaced images and `norna content:sync` to move unambiguous files into the
-expected section folder. `content:sync` can move images between route image
-roots when the filename is unambiguous across the site and the move will not
-break another reference; these cross-route writes require a clean Git working
-tree.

package/examples/feature-demos/media-and-surfaces/site/routes/020-surfaces/theme.yaml

@@ -1,3 +0,0 @@
-preset: project
-palette: light
-sectionSurfaces: [base, soft, emphasis]

package/examples/feature-demos/sitewide-content/site/content.md

@@ -1,16 +0,0 @@
----
-title: Sitewide Content
-description: See how Norna keeps shared identity, notices and footer content consistent across routes.
-navigation:
-  label: Home
----
-
-## Shared across the site {#intro}
-
-This demo separates page content from elements that belong to the site as a
-whole. The logo, navigation identity, banners and footer come from shared files
-and remain consistent as you move between routes.
-
-Visit [Identity](/identity/) to inspect the logo and navigation model,
-[Notices](/notices/) to inspect the banner stack and dismissal behaviour, and
-[Footer](/footer/) to inspect persistent footer content and build information.

package/examples/feature-demos/sitewide-content/site/routes/010-identity/content.md

@@ -1,20 +0,0 @@
----
-title: Identity
-description: See how a convention-based logo and shared identity work across a Norna site.
-navigation:
-  label: Identity
----
-
-## One identity across routes {#identity}
-
-The logo in the navigation is discovered from `public/logo.svg`. Its alt text
-and display height belong to `sitewide-content.yaml`, because the identity is
-shared by every route.
-
-If a site has no logo file, Norna shows the navigation label as text instead. A
-route cannot replace the shared navigation identity.
-
-## Navigation context {#navigation}
-
-The route links come from the site's page structure. The shared logo returns to
-Home, while the active route is indicated in the same navigation row.

package/examples/feature-demos/theme-presets/README.md

@@ -1,18 +0,0 @@
-# Themes
-
-This feature demo compares Norna's complete built-in theme presets. Every route
-uses one preset without overrides, so differences in layout, typography,
-palette, surfaces and image presentation come from the preset itself.
-
-[Live demo](https://janga.github.io/norna/examples/feature-demos/theme-presets/)
-|
-[View source](https://github.com/janga/norna/tree/main/examples/feature-demos/theme-presets)
-
-Run it from the repository root:
-
-```sh
-node bin/norna.mjs --site-dir examples/feature-demos/theme-presets/site dev:local
-```
-
-The dog photos are CC0 images by Bicanski, sourced from Pixnio. Attribution is
-included in the image captions even though the licence does not require it.