@janga/norna 0.7.15 → 0.7.17

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/).
@@ -54,15 +54,15 @@ site/
 |-- sitewide-content.yaml
 |-- content.md
 |-- images/
-|-- routes/
+|-- pages/
 `-- 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.
+- `content.md` holds the homepage title, introduction, and sections.
+- `images/` holds the homepage's managed source images.
+- `pages/` adds pages, each with content and optional local images and theme.
 - `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.
 

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/docs/README.md

@@ -29,7 +29,7 @@ site/
 |-- sitewide-content.yaml
 |-- content.md
 |-- images/
-|-- routes/
+|-- pages/
 `-- public/
 ```
 
@@ -37,14 +37,14 @@ 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.
+- [`content.md`](content.md): Markdown page title, optional 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): additional pages, ordering, URLs, page themes, and
+  page-local images.
 - [`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 +67,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 +75,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)
+- [Give a page a different theme](theme.md#page-themes)
 - [Adjust typography](typography.md)
 
 ### Check, Build, And Publish
@@ -95,7 +95,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/content.md

@@ -1,36 +1,64 @@
 # 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/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 pages use the same page model in
+`site/pages/<NNN-page-id>/content.md`. See [Pages](pages.md) for the
+page-specific 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.
 
-Minimal homepage:
+## Work {#work}
+
+Text...
+```
+
+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
@@ -57,39 +85,14 @@ Every section heading must have an explicit id:
 ## 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.
+The id must match `^[a-z0-9-]+$`. It is used for anchors and section
+navigation. 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"
-```
-
-See [Temporary Sections](#temporary-sections) for visibility semantics.
-
-Each `sections.<section-id>` key must match a Markdown heading id in the same
-page file:
-
-```md
-## Work {#work}
-```
-
-Do not list sections in frontmatter just to define order. Section order comes
-from the Markdown heading order.
-
 ## Norna Blocks
 
 Norna-managed local images and cards are written in Markdown fenced blocks at
@@ -97,6 +100,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 +112,8 @@ Use `norna-image-stack` for one or more stacked images:
 ```
 ````
 
+### Image Carousel
+
 Use `norna-image-carousel` for a carousel:
 
 ````md
@@ -120,6 +127,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 +207,13 @@ sizing is less predictable.
 Homepage images live under:
 
 ```text
-site/images/<section-id>/
+site/images/
 ```
 
-Route images live under:
+Page images live under:
 
 ```text
-site/routes/<NNN-route-id>/images/<section-id>/
+site/pages/<NNN-page-id>/images/
 ```
 
 Image references in Norna managed image blocks use only the filename:
@@ -215,13 +224,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/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 +248,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 +258,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 +296,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 +308,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 +321,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.

package/docs/design/navigation-and-theme-plan.md

@@ -0,0 +1,115 @@
+# Navigation And Theme Plan
+
+This document records the intended order of work for page hierarchy,
+navigation, and theme presets. It is an implementation plan, not a description
+of released behavior.
+
+## Goal
+
+Norna should support sites with limited global navigation and a larger local
+page hierarchy without making mobile navigation harder to understand. Theme
+presets should provide a coherent visual system without changing the site's
+information architecture.
+
+## Working Principles
+
+- The file structure defines the page hierarchy and presentation order.
+- Navigation behavior and navigation styling are separate concerns.
+- Global site navigation, local page navigation, and headings on the current
+  page have distinct roles.
+- Changing a theme preset must not change which pages are available or how the
+  page hierarchy is interpreted.
+- Site-wide visual identity should remain coherent while individual pages may
+  vary where that does not disrupt navigation or orientation.
+- Documentation and broad example migration should follow implementation and
+  manual evaluation, not precede them.
+
+## Order Of Work
+
+### 1. Stabilize The Page Tree
+
+Finish and test nested page discovery independently of final navigation
+presentation. Establish deterministic rules for:
+
+- directory parsing, page ids, URL paths, and presentation order;
+- parent and ancestor relationships;
+- collisions and invalid nesting;
+- page-local content, images, and themes;
+- breadcrumbs and current-branch discovery.
+
+Commit this foundation separately before broad theme or preset changes.
+
+### 2. Define The Navigation Contract
+
+The intended information architecture is:
+
+- a small global navigation for the site's top-level areas;
+- a larger local page tree for the selected area;
+- a separate `On this page` list for headings on the current page;
+- breadcrumbs for location and ancestry;
+- one unified mobile navigation containing the whole page hierarchy, with the
+  current branch expanded and current page marked.
+
+The exact contract is potentially difficult to evaluate at an abstract level.
+The maintainer therefore expects this phase to use executable test sites,
+focused automated tests, or clear illustrative examples. These artifacts
+should demonstrate short single-page sites, ordinary two-level sites, and
+deeper documentation-style hierarchies on both desktop and mobile before the
+contract is considered stable.
+
+The contract should also define the fallback and override behavior for the
+supported navigation modes. Structural behavior belongs to site-level engine
+configuration or deterministic automatic selection, not to presentation
+presets.
+
+### 3. Implement Navigation In Layers
+
+Implement and verify the navigation model in this order:
+
+1. page-tree data and validation;
+2. desktop global navigation, local tree, breadcrumbs, and `On this page`;
+3. unified mobile navigation;
+4. keyboard, focus, current-page, and progressive-enhancement behavior;
+5. visual evaluation at representative viewport sizes.
+
+Keep real links as the foundation. Client-side JavaScript should only enhance
+interaction that cannot be expressed adequately with HTML and CSS.
+
+### 4. Refine Theme And Preset Responsibilities
+
+Presets should control visual presentation, including:
+
+- color system;
+- typography;
+- spacing and density;
+- page and content widths;
+- the visual treatment of global navigation, local navigation, breadcrumbs,
+  and `On this page`.
+
+Presets must not determine page hierarchy, link membership, or semantic
+navigation structure. Those must remain stable when a preset changes.
+
+Site-wide color, typography, and navigation treatment should normally remain
+consistent. Page-local theme variation should be limited to properties such as
+content width, density, and media presentation when variation does not weaken
+site identity or navigation clarity.
+
+### 5. Migrate After Evaluation
+
+After the page tree, navigation contract, and preset boundaries have been
+manually evaluated:
+
+- migrate fixtures and examples;
+- update schemas and editor assistance;
+- update Markdown reference documentation;
+- update the rendered documentation site;
+- remove obsolete navigation and preset behavior rather than retaining
+  compatibility layers.
+
+Keep foundation, navigation, preset, migration, and documentation changes in
+separate commits where practical.
+
+## Immediate Checkpoint
+
+The current nested-page implementation should be reviewed, tested, and secured
+before work continues on the final navigation contract or preset model.

package/docs/design/norna-diagram-design.md

@@ -54,9 +54,9 @@ the image, or in `docs/design/` when it is useful for future maintenance.
 - Keep arrows few and directional.
 - Avoid diagrams where every object connects to every other object.
 - Prefer multiple simple diagrams over one dense diagram.
-- Make route order, URL slugs, section ids, image folders, source files, and
+- Make page order, URL slugs, section ids, image folders, source files, and
   generated output visually distinct when those ideas matter.
-- Do not show templates, components, custom rendering logic, route-level
+- Do not show templates, components, custom rendering logic, page-level
   technical configuration, or hosting integrations that Norna does not support.
 - Do not show page layouts that Norna cannot actually render unless the diagram
   is clearly abstract and not a product capability example.
@@ -67,12 +67,12 @@ Diagrams must match the current Norna model:
 
 - A Norna site is described with site files, not arbitrary project structure.
 - `content.md` is the homepage content file.
-- `sitewide-content.yaml` contains shared site identity, banners, and footer
+- `sitewide-content.yaml` contains shared logo settings, banners, and footer
   content.
-- Additional pages are route directories with `content.md`.
-- Route folder prefixes control route presentation order.
-- Route ids become default URL slugs.
-- Images belong under the image root for the page or route, usually grouped by
+- Additional pages are page directories with `content.md`.
+- Page folder prefixes control navigation order.
+- Page ids become URL segments.
+- Images belong under the image root for their page, usually grouped by
   section id.
 - Markdown remains the primary writing format.
 - Norna blocks cover fixed site patterns such as image stacks,
@@ -108,7 +108,7 @@ over relying on horizontal scrolling.
 Store diagram SVG files as normal Norna managed image assets:
 
 ```text
-site/routes/<NNN-route-id>/images/<section-id>/<diagram-name>.svg
+site/pages/<NNN-page-id>/images/<diagram-name>.svg
 ```
 
 Reference them with a Norna image block:
@@ -132,7 +132,7 @@ Before accepting a diagram:
 
 - The main message is obvious without reading the surrounding section.
 - The diagram does not imply unsupported Norna functionality.
-- URL, route, section, image, theme, config, and output terminology is
+- URL, page, section, image, theme, config, and output terminology is
   consistent with documentation.
 - Text fits inside boxes at desktop and mobile widths.
 - Arrows clarify the relationship instead of adding noise.