@janga/norna 0.7.1 → 0.7.3

package/docs/README.md

@@ -9,40 +9,59 @@ For a site maintainer:
 
 1. [Getting Started](getting-started.md)
 2. [Site Structure](site-structure.md)
-3. [Configuration](configuration.md)
-4. [Content](content.md)
-5. [Images And Metadata](images-and-metadata.md)
-6. [Local Development](local-development.md)
-7. [Publishing](publishing.md)
+3. [Theme](theme.md)
+4. [Configuration](configuration.md)
+5. [Content](content.md)
+6. [Typography](typography.md)
+7. [Routes](routes.md)
+8. [Images And Metadata](images-and-metadata.md)
+9. [Local Development](local-development.md)
+10. [Publishing](publishing.md)
 
 For a developer integrating or updating the engine:
 
 1. [Commands](commands.md)
-2. [Command Organization](command-organization.md)
-3. [Site Examples Structure Note](site-examples-structure-note.md)
-4. [Configuration](configuration.md)
-5. [Content](content.md)
-6. [Engine Development](engine-development.md)
+2. [Configuration](configuration.md)
+3. [Content](content.md)
+4. [Theme](theme.md)
+5. [Typography](typography.md)
+6. [Routes](routes.md)
+7. [Engine Development](engine-development.md)
+
+For design and naming principles:
+
+1. [Command Organization](design/command-organization.md)
+2. [Site Examples Structure](design/site-examples-structure.md)
 
 For a quick reference:
 
-- [Configuration](configuration.md) describes every supported
-  `site/config.mjs` field, including `layout.pageWidth`, `layout.gutter`,
-  gallery viewport limits, `typography.fontFamily`, validation rule, and
-  default.
-- [Content](content.md) describes page and route frontmatter, section
-  frontmatter, typography presets, site themes, inline styles, temporary
-  sections, Markdown section matching, and content validation.
+- [Configuration](configuration.md) describes technical `site/config.mjs`
+  fields such as URL, base path, locale labels, footer, GitHub, and deploy
+  settings.
+- [Content](content.md) describes page frontmatter, section frontmatter,
+  image rows, carousels, temporary sections, Markdown section matching, and
+  content validation.
+- [Theme](theme.md) describes site-wide layout, spacing, image sizing, font,
+  typography, presentation colors, frame colors, and inline styles.
+- [Typography](typography.md) describes presets, roles, overrides,
+  inheritance, and inspection commands.
+- [Routes](routes.md) describes route files, slugs, route navigation, and
+  route image directories.
 - [Commands](commands.md) lists the public CLI surface and starter npm scripts.
-- [Command Organization](command-organization.md) defines command namespaces
-  for pure gallery projects, mixed projects, and engine development.
 - [Site Structure](site-structure.md) separates versioned source files from
   generated build output.
-- [Site Examples Structure Note](site-examples-structure-note.md) defines the
-  intended vocabulary for starters, examples, docs sites, reference docs, and
-  fixtures before any repository reorganization.
+
+Design documents are intentionally separate from the user reference:
+
+- [Command Organization](design/command-organization.md) defines command
+  namespaces for standalone sites, mixed projects, and engine development.
+- [Site Examples Structure](design/site-examples-structure.md) defines the
+  intended vocabulary for starters, examples, documentation sites, reference
+  docs, and fixtures.
 
 Site repositories should document only their site-specific choices and link here
 for generic `norna` behavior.
 
+`norna` is licensed under [GNU GPL v3](../LICENSE).
+
 Planning and future work are tracked in [../BACKLOG.md](../BACKLOG.md).

package/docs/commands.md

@@ -1,7 +1,17 @@
 # Commands
 
-The `norna` binary is the stable command surface. The starter's npm
-scripts are thin aliases around these commands.
+The `norna` binary is the stable command surface. Site repositories normally
+use starter npm scripts such as `npm run norna:content:check`; those scripts
+call the local `norna` binary from `node_modules/.bin`.
+
+Npm installation exposes the command as `norna` on macOS, Linux, and Windows
+through the package `bin` field. When a globally installed `norna` is started
+inside a project that declares and has installed its own `@janga/norna`
+dependency, the launcher delegates to that project-local version. If no
+project-local install is found, the version that was started continues running.
+
+Use direct `norna ...` commands only when the binary is on your shell `PATH`,
+inside an npm script, or through `npm exec -- norna ...`.
 
 ## CLI Commands
 
@@ -15,8 +25,8 @@ norna dev:stop
 norna config:check
 norna content:check
 norna content:sync
-norna typography:presets
-norna typography:show
+norna typography presets
+norna typography show
 norna site:public
 norna images
 norna engine:update [version|latest]
@@ -45,7 +55,7 @@ norna --help
 ## Starter npm Scripts
 
 The starter uses `norna:*` for norna-specific work. This avoids collisions
-when a `norna` presentation is embedded inside a larger GitHub project
+when a Norna site is embedded inside a larger GitHub project
 whose own `build`, `test`, or deploy scripts mean something different.
 
 The starter defines:
@@ -80,7 +90,7 @@ npm run build
 
 `npm run dev` calls `npm run norna:dev`. In the pure starter,
 `npm run build` aliases `npm run norna:build`. In mixed repositories, such as
-a GitHub project that embeds a gallery presentation next to an app, `build`
+a GitHub project that embeds a Norna site next to an app, `build`
 should normally mean the repository's complete publishable artifact, while
 `norna:build` builds only the `norna` part.
 
@@ -91,14 +101,15 @@ should normally mean the repository's complete publishable artifact, while
   cache path.
 - `config:check`: validates `site/config.mjs` against the runtime config
   reader.
-- `content:check`: validates section structure and gallery references, then
+- `content:check`: validates section structure and image references, then
   runs `astro sync`.
 - `content:sync` / `norna:sync`: rewrites Markdown section order and moves misplaced referenced
   image files after confirmation.
-- `typography:presets`: prints the exact built-in values for every typography
+- `typography presets`: prints the exact built-in values for every typography
   preset.
-- `typography:show`: prints the selected site's resolved typography after
-  applying theme, page, and section presentation.
+- `typography show`: prints the selected site's resolved typography for the
+  theme, every page route, 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.
 - `images`: generates WebP variants and writes
@@ -114,13 +125,15 @@ should normally mean the repository's complete publishable artifact, while
   engine version, engine root, Astro dependency, and installed Astro version.
   With `--latest`, it also asks npm for the latest published engine version.
 - `init <target-dir> [--type pure|embedded] [--site-dir <path>]`: creates a
-  pure gallery project from the packaged starter, or adds a gallery source
+  standalone site project from the packaged starter, or adds a Norna site
   directory plus `norna:*` scripts to an existing project in embedded mode.
   Pure setup pins `@janga/norna` to the version that created it.
 - `build`: runs config check, content check, public sync, image generation, and
   Astro build.
 - `build:local`: runs `build` and restarts `dev:local`.
-- `dev:local`: starts Astro dev in background mode on `localhost:4321`.
+- `dev:local`: starts Astro dev in background mode on `localhost:4321`. Pass
+  `--kill` to stop processes that are blocking the standard port before
+  starting.
 - `dev:lan`: starts the same server on all local network interfaces and prints
   the IPv4 URL to open from another device on the same network. Stop it after
   testing because it is accessible to that local network.

package/docs/configuration.md

@@ -16,8 +16,9 @@ the current values for any one site.
 - Required: yes.
 - Default: none.
 - Validation: non-empty absolute URL accepted by `new URL()`.
-- Consequence: wrong values render a wrong canonical URL and make deploy output
-  point at the wrong site.
+- Consequence: wrong values render a wrong canonical URL and make deploy
+  output point at the wrong site. For GitHub Pages project sites, include the
+  repository path in the URL, for example `https://owner.github.io/repo-name/`.
 
 Example:
 
@@ -27,152 +28,50 @@ site: {
 }
 ```
 
-## Layout
+### `site.basePath`
 
-### `layout.pageWidth`
-
-- Purpose: maximum width of the main page content area, including section
-  headings, section text, galleries, sticky-navigation alignment, and footer.
-- Type: string containing a simple positive CSS length.
-- Required: no.
-- Default: `1180px`.
-- Validation: if set, it must be a positive number followed by one of `px`,
-  `rem`, `em`, `vw`, `vh`, `vmin`, `vmax`, `ch`, or `%`.
-- Consequence: the value overrides the global `--page-width` CSS variable.
-  It is the outer width limit for content that is centered on the page.
-  `gallery.width` cannot render wider than this page width or the available
-  viewport width after responsive gutters.
-
-Example:
-
-```js
-layout: {
-	pageWidth: '1180px',
-}
-```
-
-### `layout.gutter`
-
-- Purpose: side margin removed from the viewport before the available content
-  width is calculated.
-- Type: either a CSS length string used on all viewports, or an object with
-  `desktop` and `mobile` CSS length strings.
-- Required: no.
-- Default: desktop `clamp(1.25rem, 4vw, 3rem)`, mobile `1rem`.
-- Validation: if set, each value must be a positive CSS length such as `16px`,
-  `3rem`, or `4vw`. `clamp()` with those simple lengths is also accepted.
-- Consequence: wider gutters leave more side margin and reduce the maximum
-  available width for galleries and aligned text.
-
-Example:
-
-```js
-layout: {
-	gutter: {
-		desktop: '48px',
-		mobile: '16px',
-	},
-}
-```
-
-## Gallery
-
-### `gallery.width`
-
-- Purpose: maximum rendered width for gallery images, gallery captions, and
-  left- or right-aligned section text that is intended to line up with gallery
-  edges.
-- Type: string containing a simple positive CSS length.
-- Required: no.
-- Default: `900px`.
-- Validation: if set, it must be a positive number followed by one of `px`,
-  `rem`, `em`, `vw`, `vh`, `vmin`, `vmax`, `ch`, or `%`.
-- Consequence: the value overrides the global `--gallery-width` CSS variable.
-  Images and aligned text cannot render wider than this value, but the
-  effective width is also limited by `layout.pageWidth`, `layout.gutter`, and
-  `gallery.maxAvailableWidthPercent`.
-
-Example:
-
-```js
-gallery: {
-	width: '900px',
-}
-```
-
-### `gallery.maxAvailableWidthPercent`
-
-- Purpose: maximum share of the available width, after gutters, that gallery
-  images, gallery captions, and aligned section text may use.
-- Type: either a number used on all viewports, or an object with `desktop` and
-  `mobile` numbers.
+- Purpose: URL path prefix used for generated internal page links, favicons,
+  generated image URLs, and root-relative links or images written in Markdown.
+- Type: string URL path.
 - Required: no.
-- Default: desktop `100`, mobile `100`.
-- Validation: each value must be greater than `0` and less than or equal to
-  `100`.
-- Consequence: `100` allows the gallery to use the full available width. A
-  smaller value keeps galleries narrower without changing the page width or
-  gutters.
+- Default: `/`.
+- Validation: must start and end with `/` and must not contain whitespace,
+  `?`, `#`, or `//`.
+- Consequence: use `/` for a root site or custom domain. Use
+  `/repository-name/` for a GitHub Pages project site without a custom domain.
+  Source Markdown can still use root-relative paths such as `/workflow.svg` or
+  `/getting-started/`; Norna prefixes them during rendering.
 
-Example:
+Examples:
 
 ```js
-gallery: {
-	maxAvailableWidthPercent: {
-		desktop: 100,
-		mobile: 100,
-	},
+site: {
+	url: 'https://example.com/',
+	basePath: '/',
 }
 ```
 
-### `gallery.maxAvailableHeightPercent`
-
-- Purpose: maximum share of viewport height that gallery images may use.
-- Type: either a number used on all viewports, or an object with `desktop` and
-  `mobile` numbers.
-- Required: no.
-- Default: desktop `74`, mobile `68`.
-- Validation: each value must be greater than `0` and less than or equal to
-  `100`.
-- Consequence: images keep their proportions and are scaled down when filling
-  the available width would make them taller than this limit. This applies to
-  both landscape and portrait images.
-
-Example:
-
 ```js
-gallery: {
-	maxAvailableHeightPercent: {
-		desktop: 74,
-		mobile: 68,
-	},
+site: {
+	url: 'https://janga.github.io/norna/',
+	basePath: '/norna/',
 }
 ```
 
-## Typography
-
-### `typography.fontFamily`
+## Visual Theme
 
-- Purpose: global CSS `font-family` stack used by site text and sticky
-  navigation.
-- Type: string containing a CSS font-family value.
-- Required: no.
-- Default: `Arial, 'Helvetica Neue', Helvetica, sans-serif`, matching the
-  engine's existing sticky-navigation font stack.
-- Validation: if set, it must be a non-empty string and must not contain
-  semicolons, braces, or line breaks.
-- Consequence: the value overrides the global `--font-sans` CSS variable for
-  the whole page. Section headings, body text, gallery captions, footer text,
-  and sticky navigation all inherit from that variable unless engine CSS gives a
-  more specific rule.
+Visual configuration lives in `site/theme.md`, not `site/config.mjs`.
 
-Example:
+Use [Theme](theme.md) for:
 
-```js
-typography: {
-	fontFamily: "system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif",
-}
-```
+- `layout.pageWidth`
+- `layout.gutter`
+- `gallery.width`
+- `gallery.maxAvailableWidthPercent`
+- `gallery.maxAvailableHeightPercent`
+- `typography.fontFamily`
+- typography presets and overrides
+- presentation colors, inline styles, and frame colors
 
 ## Navigation
 
@@ -241,7 +140,7 @@ Fields:
   `Sections`.
 - `locale.labels.menu`: mobile menu summary text, default `Menu`.
 - `locale.labels.closeMenu`: reserved close-menu label, default `Close menu`.
-- `locale.labels.gallery`: gallery ARIA label prefix, default `Gallery`.
+- `locale.labels.gallery`: image row ARIA label prefix, default `Images`.
 
 Example:
 
@@ -254,7 +153,7 @@ locale: {
 		pageNavigation: 'På denna sida',
 		sectionNavigation: 'Sektioner',
 		menu: 'Meny',
-		gallery: 'Galleri',
+		gallery: 'Bilder',
 	},
 }
 ```
@@ -374,3 +273,7 @@ If `NORNA_SITE_DIR` is set to an empty value, commands fail. Relative site
 directories are resolved by walking upward from the invocation root until the
 selected directory contains `config.mjs` and `content.md`. Absolute site
 directories are accepted and make their parent the site project root.
+
+When no site directory is explicitly selected, the current directory itself can
+be the site directory if it contains `config.mjs` and `content.md`. If not,
+Norna walks upward looking for a default `site/` directory with those files.