@janga/norna 0.7.16 → 0.7.18

package/README.md

@@ -17,7 +17,7 @@ implementing a new presentation layer for every project.
 [Live examples](https://janga.github.io/norna/examples/) |
 [npm package](https://www.npmjs.com/package/@janga/norna)
 
-[![A multi-page dog shelter site with a logo, route navigation, text, a card, and a managed image.](docs/assets/norna-dog-shelter.jpg)](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/)
+[![A multi-page dog shelter site with a logo, navigation between pages, text, a card, and a managed image.](docs/assets/norna-dog-shelter.jpg)](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/)
 
 The screenshot shows the built
 [multi-page example source](examples/complete-sites/dog-shelter-multi-page/).
@@ -52,17 +52,23 @@ site/
 |-- config.yaml
 |-- theme.yaml
 |-- sitewide-content.yaml
-|-- content.md
-|-- images/
-|-- routes/
+|-- pages/
+|   |-- 000-home/
+|   |   |-- content.md
+|   |   `-- images/
+|   `-- 010-guide/
+|       |-- content.md
+|       `-- pages/
+|           `-- 010-installation/
 `-- public/
 ```
 
-- `content.md` holds the homepage and its sections.
-- `images/` holds managed source images beside the content they belong to.
-- `routes/` adds pages, each with content and optional local images and theme.
+- `pages/000-home/content.md` is the required homepage at `/`.
+- Other top-level directories under `pages/` are global navigation roots.
+- A page may contain local images, limited presentation settings, and nested
+  child pages under its own `pages/` directory.
 - `theme.yaml` normally selects one complete visual preset.
-- `sitewide-content.yaml` holds shared identity, banners, and footer content.
+- `sitewide-content.yaml` holds shared logo display settings, banners, and footer content.
 - `config.yaml` holds the public URL and optional language and scroll behavior.
 - `public/` holds static files copied without processing.
 
@@ -89,7 +95,10 @@ documentation.
 | --- | --- | --- |
 | Dog shelter, single page | [Open demo](https://janga.github.io/norna/examples/complete-sites/dog-shelter-single-page/) | [View files](examples/complete-sites/dog-shelter-single-page/) |
 | Dog shelter, multi-page | [Open demo](https://janga.github.io/norna/examples/complete-sites/dog-shelter-multi-page/) | [View files](examples/complete-sites/dog-shelter-multi-page/) |
-| Theme presets | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-presets/) | [View files](examples/feature-demos/theme-presets/) |
+| Portfolio preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-portfolio/) | [View files](examples/feature-demos/theme-preset-portfolio/) |
+| Documentation preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-documentation/) | [View files](examples/feature-demos/theme-preset-documentation/) |
+| Project preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-project/) | [View files](examples/feature-demos/theme-preset-project/) |
+| Statement preset | [Open demo](https://janga.github.io/norna/examples/feature-demos/theme-preset-statement/) | [View files](examples/feature-demos/theme-preset-statement/) |
 | Media and surfaces | [Open demo](https://janga.github.io/norna/examples/feature-demos/media-and-surfaces/) | [View files](examples/feature-demos/media-and-surfaces/) |
 | Sitewide content | [Open demo](https://janga.github.io/norna/examples/feature-demos/sitewide-content/) | [View files](examples/feature-demos/sitewide-content/) |
 

package/astro.config.mjs

@@ -3,6 +3,7 @@ import { execFile } from 'node:child_process';
 import path from 'node:path';
 import { promisify } from 'node:util';
 import { defineConfig } from 'astro/config';
+import { getBasePathRedirectLocation } from './scripts/lib/base-path-redirect.mjs';
 import {
 	astroCacheDir,
 	astroDistDir,
@@ -12,7 +13,7 @@ import {
 	siteContentPath,
 	siteImagesDir,
 	siteProjectRoot,
-	siteRoutesDir,
+	sitePagesDir,
 } from './scripts/lib/site-paths.mjs';
 import projectConfig from './scripts/lib/project-config.mjs';
 
@@ -28,6 +29,37 @@ const runGenerateImages = () => execFileAsync(process.execPath, [path.join(engin
 	maxBuffer: 1024 * 1024 * 10,
 });
 
+const nornaBasePathRedirect = () => {
+	const middleware = (request, response, next) => {
+		if (!request.url) {
+			next();
+			return;
+		}
+
+		const redirectLocation = getBasePathRedirectLocation(projectConfig.site.basePath, request.url);
+		if (!redirectLocation) {
+			next();
+			return;
+		}
+
+		response.statusCode = 308;
+		response.setHeader('Location', redirectLocation);
+		response.end();
+	};
+
+	return {
+		name: 'norna-base-path-redirect',
+		configureServer(server) {
+			return () => {
+				server.middlewares.stack.unshift({ route: '', handle: middleware });
+			};
+		},
+		configurePreviewServer(server) {
+			server.middlewares.use(middleware);
+		},
+	};
+};
+
 const nornaGeneratedImagesWatcher = () => ({
 	name: 'norna-generated-images-watcher',
 	configureServer(server) {
@@ -35,7 +67,7 @@ const nornaGeneratedImagesWatcher = () => ({
 		const watchedSourcePaths = [
 			siteContentPath,
 			siteImagesDir,
-			siteRoutesDir,
+			sitePagesDir,
 		].map((watchedPath) => path.resolve(watchedPath));
 		let refreshTimer;
 		let refreshPromise = Promise.resolve();
@@ -90,6 +122,6 @@ export default defineConfig({
 	publicDir: astroPublicDir,
 	srcDir: path.join(engineRoot, 'src'),
 	vite: {
-		plugins: [nornaGeneratedImagesWatcher()],
+		plugins: [nornaBasePathRedirect(), nornaGeneratedImagesWatcher()],
 	},
 });

package/bin/norna-cli.mjs

@@ -16,7 +16,7 @@ Commands:
   dev:stop               Stop local dev server
   check                  Validate configuration and content
   config:check           Validate site/config.yaml
-  content:check          Validate site/content.md and image references
+  content:check          Validate page content and managed image references
   content:sync           Move misplaced Norna-managed images and refresh generated images
   theme:presets          List available theme presets and their intended uses
   theme:export           Export a commented theme preset reference

package/docs/README.md

@@ -27,9 +27,12 @@ site/
 |-- config.yaml
 |-- theme.yaml
 |-- sitewide-content.yaml
-|-- content.md
-|-- images/
-|-- routes/
+|-- pages/
+|   |-- 000-home/
+|   |   |-- content.md
+|   |   `-- images/
+|   `-- 010-guide/
+|       `-- content.md
 `-- public/
 ```
 
@@ -37,14 +40,13 @@ site/
   scroll behavior.
 - [`theme.yaml`](theme.md): complete visual presets and focused presentation
   overrides.
-- [`sitewide-content.yaml`](sitewide-content.md): shared navigation identity,
+- [`sitewide-content.yaml`](sitewide-content.md): shared logo display settings,
   banners, and footer.
-- [`content.md`](content.md): page metadata, sections, prose, notes, and Norna
-  blocks.
-- [`images/`](images-and-metadata.md): managed source formats, variants, sync,
-  and generated image state.
-- [`routes/`](routes.md): additional pages, ordering, URLs, route themes, and
-  route-local images.
+- [`pages/`](pages.md): Home, top-level areas, nested pages, ordering, and URLs.
+- [`content.md`](content.md): the content file inside every page directory,
+  containing its title, optional metadata, sections, prose, notes, and blocks.
+- [`images/`](images-and-metadata.md): managed images kept inside the page that
+  references them, plus variants, sync, and generated image state.
 - [`public/`](public-files.md): navigation logos, favicons, and other static
   files copied without managed-image processing.
 - [Generated files](site-files.md#generated-files): `site/.norna/public/`,
@@ -67,7 +69,7 @@ required, optional, convention-discovered, versioned, or generated.
 - [Write page sections](content.md#sections)
 - [Use image stacks, carousels, and cards](content.md#norna-blocks)
 - [Add notes to prose](content.md#markdown-text)
-- [Add another page](routes.md)
+- [Add another page](pages.md)
 - [Add shared banners or footer content](sitewide-content.md)
 
 ### Work With Images And Public Assets
@@ -75,14 +77,14 @@ required, optional, convention-discovered, versioned, or generated.
 - [Add managed source images](images-and-metadata.md#managed-source-images)
 - [Check and sync moved image references](content.md#validation-and-sync)
 - [Add a navigation logo](public-files.md#navigation-logo)
-- [Add favicons](public-files.md#logos-and-favicons)
+- [Add browser icons](public-files.md#browser-icons)
 - [Add other static files](public-files.md#other-static-files)
 
 ### Change Presentation
 
 - [Choose a complete theme preset](theme.md#theme-presets)
 - [Inspect and override a preset](theme.md#overrides)
-- [Give a route a different theme](theme.md#route-themes)
+- [Adjust limited presentation for a page subtree](theme.md#page-themes)
 - [Adjust typography](typography.md)
 
 ### Check, Build, And Publish
@@ -95,7 +97,7 @@ required, optional, convention-discovered, versioned, or generated.
 ## Concepts And Explanation
 
 - [Norna's site model](https://janga.github.io/norna/concepts/) explains how
-  files, sections, images, and routes become a website.
+  files, sections, images, and pages become a website.
 - [Images and Metadata](images-and-metadata.md) explains managed variants and
   published URLs.
 - [Command Organization](design/command-organization.md) explains standalone,

package/docs/commands.md

@@ -119,7 +119,7 @@ should normally mean the repository's complete publishable artifact, while
   inline styles, and common content mistakes.
 - `content:sync` / `norna:sync`: moves misplaced referenced image files after
   confirmation when the intended move is unambiguous. Moving files between the
-  homepage and routes, or between routes, requires a clean Git working tree.
+  homepage and an additional page, or between additional pages, requires a clean Git working tree.
 - `theme:presets`: lists the available complete theme presets and explains the
   intended use of each one.
 - `theme:export <preset>`: writes a protected, commented
@@ -129,7 +129,7 @@ should normally mean the repository's complete publishable artifact, while
 - `typography profiles`: prints the exact built-in values for typography
   profiles and rhythms.
 - `typography show`: prints the selected site's resolved typography for the
-  theme, every page route, and every section. Each value includes its source,
+  theme, every page, and every section. Each value includes its source,
   and inherited page or section values are marked with `inherited: true`.
 - `site:public`: copies `site/public/` into `site/.norna/public/` and
   removes stale copied static files.

package/docs/configuration.md

@@ -13,7 +13,7 @@ url: https://example.com/
 Norna deliberately keeps this file small. Visual choices belong in
 [`theme.yaml`](theme.md), shared editorial content belongs in
 [`sitewide-content.yaml`](sitewide-content.md), and page content belongs in
-[`content.md`](content.md).
+[`pages/*/content.md`](content.md).
 
 ## `url`
 
@@ -58,6 +58,26 @@ would be misleading.
 Interface labels are part of the engine and are not configured individually.
 Editorial text remains in page content and `sitewide-content.yaml`.
 
+## `navigation`
+
+`navigation.mode` selects the site-wide navigation model:
+
+- `automatic`: choose from the discovered page and heading structure. This is
+  the default.
+- `sections`: navigate headings on a single page.
+- `top`: use the sticky top navigation for a shallow multi-page site.
+- `tree`: combine global top-level navigation with a local page hierarchy.
+
+```yaml
+url: https://example.com/
+navigation:
+  mode: automatic
+```
+
+Navigation behavior is technical and site-wide. It cannot be configured in
+`theme.yaml` or in an individual page. See [Pages](pages.md#navigation) for the
+relationship between Home, top-level pages, child pages, and headings.
+
 ## `scrollBehavior`
 
 - Purpose: select native same-page anchor movement.
@@ -80,6 +100,8 @@ requests reduced motion always get immediate anchor movement.
 ```yaml
 url: https://example.com/
 language: en-GB
+navigation:
+  mode: automatic
 scrollBehavior: instant
 ```
 
@@ -110,7 +132,8 @@ norna --site-dir presentation build
 
 If `NORNA_SITE_DIR` is set to an empty value, commands fail. Relative site
 directories are resolved by walking upward from the invocation directory until
-the selected directory contains `config.yaml` and `content.md`.
+the selected directory contains `config.yaml` and
+`pages/000-home/content.md`.
 
 Without an explicit selection, the current directory itself can be the site
 directory when it contains those two files. Otherwise Norna walks upward for a

package/docs/content.md

@@ -1,36 +1,63 @@
 # Content
 
-`site/content.md` is the homepage page file for a Norna site. It contains page
-metadata in frontmatter and the homepage content in Markdown.
+`site/pages/000-home/content.md` is the homepage file for a Norna site. Its Markdown H1 is
+the page title. Optional page metadata can be added in YAML frontmatter.
 
-Route pages use the same page model in
-`site/routes/<NNN-route-id>/content.md`. See [Routes](routes.md) for the
-route-specific rules.
+Additional and nested pages use the same page model in a page directory under
+`site/pages/`. See [Pages](pages.md) for the directory and nesting rules.
 
 Site-wide visual defaults belong in [Theme](theme.md). Typography profiles and
 overrides are described in [Typography](typography.md). Technical site settings
 belong in [Configuration](configuration.md).
 
-## Page Frontmatter
+## Page Title And Frontmatter
 
-The Astro content schema validates these top-level fields in page files:
+Every page must contain exactly one Markdown H1. It must be the first heading,
+must not have a section id, and supplies the visible page title, HTML document
+title, and page label in site navigation:
 
-- `title`: required string. Rendered as the document title.
-- `description`: required string. Rendered as the meta description.
-- `navigation`: optional page navigation metadata. See [Routes](routes.md).
-- `sections`: optional section metadata keyed by section id.
+```md
+# My Site
+```
+
+Content between the H1 and the first H2 is the page introduction. It may
+contain prose and Norna blocks.
+
+Frontmatter is optional. When present, the content schema validates these
+top-level fields:
+
+- `page`: optional page metadata.
+- `navigation`: optional page-listing metadata. See [Pages](pages.md).
+
+`page` contains:
+
+- `description`: optional string. Used only as the page's HTML meta description
+  for search engines, link previews, and other metadata consumers. It is not
+  rendered as visible page content.
+
+Minimal homepage without metadata:
+
+```md
+# My Site
+
+Introductory text.
+
+## Work {#work}
+
+Text...
+```
 
-Minimal homepage:
+Homepage with a meta description:
 
 ```md
 ---
-title: My Site
-description: A small Norna site.
+page:
+  description: A small Norna site.
 ---
 
-## Intro {#intro}
+# My Site
 
-Text...
+Introductory text.
 ```
 
 ## Sections
@@ -51,44 +78,29 @@ Markdown level 2 headings define the page sections and their order:
 ...
 ```
 
-Every section heading must have an explicit id:
+Norna derives a stable lowercase id from the heading text when no explicit id
+is present:
 
 ```md
-## Work {#work}
-```
-
-The id must match `^[a-z0-9-]+$`. It is used for anchors, navigation, image
-directories, and optional section metadata. The visible section navigation
-label comes from the Markdown heading text.
-
-Markdown section content starts at the level 2 heading and continues until the
-next level 2 heading. `###` and `####` headings are body subheadings within the
-current section, not new sections.
-
-## Section Metadata
-
-Use `sections` only when a section needs structured metadata that is not
-naturally expressed by Markdown. Currently this is date-based visibility.
-
-```yaml
-sections:
-  work:
-    visible:
-      from: "2026-08-01"
-      until: "2026-09-16"
+## Work
 ```
 
-See [Temporary Sections](#temporary-sections) for visibility semantics.
-
-Each `sections.<section-id>` key must match a Markdown heading id in the same
-page file:
+Add an explicit id when a public anchor must remain stable even if the heading
+text changes:
 
 ```md
 ## Work {#work}
 ```
 
-Do not list sections in frontmatter just to define order. Section order comes
-from the Markdown heading order.
+Explicit ids must match `^[a-z0-9-]+$`. Derived and explicit ids are used for
+anchors and section navigation; the visible label still comes from the heading
+text. H3 headings use the same derivation for deeper local navigation. If two
+headings on one page resolve to the same id, `content:check` reports the page
+and both headings instead of guessing.
+
+Markdown section content starts at the level 2 heading and continues until the
+next level 2 heading. `###` and `####` headings are body subheadings within the
+current section, not new sections.
 
 ## Norna Blocks
 
@@ -97,6 +109,8 @@ the point where they should appear in the section. Markdown determines
 placement: move the fenced block in the page file to move the rendered image,
 carousel, or card list.
 
+### Image Stack
+
 Use `norna-image-stack` for one or more stacked images:
 
 ````md
@@ -107,6 +121,8 @@ Use `norna-image-stack` for one or more stacked images:
 ```
 ````
 
+### Image Carousel
+
 Use `norna-image-carousel` for a carousel:
 
 ````md
@@ -120,6 +136,8 @@ Use `norna-image-carousel` for a carousel:
 ```
 ````
 
+### Card List
+
 Use `norna-card-list` for a list of compact cards. Cards can include text,
 managed images, links, and optional badge text:
 
@@ -198,13 +216,13 @@ sizing is less predictable.
 Homepage images live under:
 
 ```text
-site/images/<section-id>/
+site/pages/000-home/images/
 ```
 
-Route images live under:
+Images for any page live directly under that page directory. For example:
 
 ```text
-site/routes/<NNN-route-id>/images/<section-id>/
+site/pages/010-guide/pages/020-installation/images/
 ```
 
 Image references in Norna managed image blocks use only the filename:
@@ -215,13 +233,15 @@ Image references in Norna managed image blocks use only the filename:
 ```
 ````
 
-If `portrait.jpg` is referenced from `## Team {#team}`, the expected homepage
-location is `site/images/team/portrait.jpg`.
+If `portrait.jpg` is referenced anywhere on the homepage, its expected
+location is `site/pages/000-home/images/portrait.jpg`. The same file may be referenced from
+more than one section on that page.
 
-Filenames do not have to be globally unique for the site to be valid. Automatic
-sync only moves files when the filename identifies exactly one source candidate
-across the site's page and route image roots. If more than one candidate
-exists, Norna reports the ambiguity instead of guessing.
+Filenames must be unique within one page's image directory, but do not have to
+be globally unique across the site. Automatic sync only moves files between
+page image roots when the filename identifies exactly one source candidate
+across the site. If more than one candidate exists, Norna reports the
+ambiguity instead of guessing.
 
 ## Markdown Images
 
@@ -237,36 +257,6 @@ managed by Norna. Use `norna-image-stack`, `norna-image-carousel`, or
 `norna-card-list` for local site images that should be validated, processed and
 synced.
 
-## Temporary Sections
-
-Use `sections.<section-id>.visible` for sections that should be rendered only
-during a date window:
-
-```yaml
-sections:
-  exhibition:
-    visible:
-      from: "2026-08-01"
-      until: "2026-09-16"
-```
-
-`from` is inclusive. `until` is exclusive. With the example above, the section
-is visible from 2026-08-01 through 2026-09-15 and hidden again on 2026-09-16.
-
-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 the page file, and `content:check` still validates their matching
-Markdown headings and image references.
-
-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
-```
-
 ## Markdown Text
 
 Use ordinary Markdown for emphasis and structure:
@@ -277,7 +267,7 @@ This sentence contains **important text** and *emphasised text*.
 
 Norna intentionally does not support arbitrary inline color or style classes.
 Deprecated syntax such as `[highlighted text]{.yellow}` is rejected by
-`content:check`. Keep the route visually coherent through its `theme.yaml`
+`content:check`. Keep the page visually coherent through its `theme.yaml`
 instead of styling individual phrases.
 
 ### Side Notes
@@ -315,7 +305,7 @@ Run:
 npm run norna:content:check
 ```
 
-This checks section heading ids, section metadata, duplicate image names,
+This checks section heading ids, duplicate image names,
 missing image files, misplaced referenced images, duplicate image references,
 invalid Norna blocks, unreferenced images, removed inline style syntax,
 Markdown image references to unmanaged local files, and common frontmatter
@@ -327,15 +317,12 @@ invalid, when a key is indented under a line that already has a value, or when a
 known nested key appears at the top level:
 
 ```yaml
-sections:
-  intro:
-    visible:
-      from: "2026-08-01"
+navigation:
+  listed: false
 ```
 
-Top-level page frontmatter may contain only `title`, `description`,
-`navigation`, and `sections`. Visual settings belong in the root or route-local
-`theme.yaml`.
+Top-level page frontmatter may contain only `page` and `navigation`. Visual
+settings belong in the root or page-local `theme.yaml`.
 
 Run:
 
@@ -343,20 +330,22 @@ Run:
 npm run norna:sync
 ```
 
-This moves referenced image files into the section directory shown by the
-Markdown placement. It prompts before writing unless `--yes` is passed.
+This moves referenced image files into the image directory for the page that
+references them. Moving a block between sections on the same page does not
+move the file because all sections share the page image directory. The command
+prompts before writing unless `--yes` is passed.
 
 `content:sync` is intentionally conservative. It only moves a file when the
-filename identifies exactly one matching source candidate across the site's
-page and route image roots, and when the move will not break another reference.
+filename identifies exactly one matching source candidate across all page
+image roots, and when the move will not break another reference.
 If the intended move is ambiguous, rename or move the file manually and run
 `content:check` again.
 
-Duplicate filenames are allowed when files already live where their Markdown
-references expect them. Automatic relocation only requires site-wide filename
-uniqueness for the file being moved.
+The same filename may exist in different page image directories. Automatic
+relocation only requires site-wide filename uniqueness for the file being
+moved.
 
-When `content:sync` needs to move an image between the homepage and a route, or
-between two routes, the Git working tree must be clean before the write. This
-keeps cross-route sync easy to roll back. `content:check` only reports issues
+When `content:sync` needs to move an image between the homepage and a page, or
+between two pages, the Git working tree must be clean before the write. This
+keeps cross-page sync easy to roll back. `content:check` only reports issues
 and does not require a clean working tree.