@janga/norna 0.7.1 → 0.7.2

package/docs/engine-development.md

@@ -4,7 +4,8 @@ This document is for work on the reusable `norna` package itself.
 
 ## Main Areas
 
-- `bin/norna.mjs`: public CLI dispatcher.
+- `bin/norna.mjs`: public CLI launcher and local-version resolver.
+- `bin/norna-cli.mjs`: public CLI command dispatcher.
 - `scripts/lib/site-paths.mjs`: engine/site path resolution.
 - `scripts/lib/project-config.mjs`: `site/config.mjs` validation and defaults.
 - `scripts/sync-content-sections.mjs`: content validation and sync behavior.
@@ -18,9 +19,12 @@ This document is for work on the reusable `norna` package itself.
 - `tests/`: Playwright navigation diagnostics.
 - `fixtures/basic/site/`: minimal site used for engine checks.
 - `starters/basic/`: copyable site starter.
+- `examples/dog-gallery/site/`: visual dog-gallery demo used by demo builds
+  and navigation diagnostics.
 
-The repository-local `site/` directory is a dog-gallery demo. It is useful for
-manual engine checks, but it is not a published site.
+The repository-local `site/` directory is reserved for a local documentation
+site. It is useful for dogfooding `norna` documentation, but it is not the
+primary visual regression demo.
 
 ## Common Checks
 
@@ -34,7 +38,24 @@ npm run demo:build
 npm run package:check
 ```
 
-`npm run test` runs the same set in sequence.
+`npm run test` runs the standard non-demo check sequence.
+
+The root `site/` directory is the documentation site. Use the ordinary local
+commands for it:
+
+```sh
+npm run dev:local
+npm run build
+```
+
+The dog gallery remains the visual demo and navigation diagnostic target:
+
+```sh
+cd examples/dog-gallery/site
+node ../../../bin/norna.mjs dev:local
+cd ../../..
+npm run demo:build
+```
 
 Navigation diagnostics are separate because they use Playwright:
 
@@ -92,11 +113,18 @@ npm run norna:engine:update -- <version>
 Commit the resulting `package.json` and `package-lock.json` changes in the
 site repository after the site's normal checks pass.
 
+The installed `norna` command is created from the package `bin` field. The
+launcher first looks for the nearest project `package.json`. If that project
+declares `@janga/norna` and Node can resolve an installed copy from that project
+root, the launcher delegates to that local entrypoint. The engine repository
+itself is excluded from delegation so local engine development keeps using the
+working tree entrypoint.
+
 ## npm Release
 
 The npm package is published under the `@janga` scope. Choose the release type
 when starting a release; the command requires a clean working tree, verifies npm
-registry authentication for the same registry/cache used by `release:publish`,
+registry authentication for the same registry/cache used by the publish step,
 runs `npm test`, requires a clean working tree after the checks, updates
 `package.json` and `package-lock.json`, creates the release commit and Git tag,
 publishes to npm, then pushes the commit and tag.

package/docs/getting-started.md

@@ -29,6 +29,11 @@ npm install
 npm run norna:dev
 ```
 
+After `npm install`, the project's npm scripts use the project-local `norna`
+binary from `node_modules/.bin`. A globally installed `norna` can also be used
+as a convenience launcher; inside a project with an installed `@janga/norna`
+dependency, it delegates to the project's local version.
+
 A freshly created empty directory is not a `norna` site yet. It becomes a
 site when `init` copies the starter files, including `package.json`. If you run
 `npm install` in an empty directory, npm may walk up to a parent directory and
@@ -75,7 +80,37 @@ npm run norna:check
 npm run build
 ```
 
-Read [Site Structure](site-structure.md), [Content](content.md), and
+## Configure The Public URL
+
+For a custom domain or any site published at the web root, use:
+
+```js
+site: {
+	url: 'https://example.com/',
+	basePath: '/',
+}
+```
+
+For a GitHub Pages project site without a custom domain, the site is served
+under the repository name. Configure both values:
+
+```js
+site: {
+	url: 'https://owner.github.io/repository-name/',
+	basePath: '/repository-name/',
+}
+```
+
+After that, content files may still use root-style internal links such as
+`/getting-started/` and `/workflow.svg`. Norna applies `site.basePath` during
+rendering so the built links work under the GitHub Pages project path.
+
+The starter includes a GitHub Pages workflow in `.github/workflows/deploy.yml`.
+In the GitHub repository settings, configure Pages to build from GitHub
+Actions.
+
+Read [Site Structure](site-structure.md), [Content](content.md),
+[Theme](theme.md), [Typography](typography.md), [Routes](routes.md), and
 [Configuration](configuration.md) before publishing a real site.
 
 To change the site's maximum page width, set `layout.pageWidth` in
@@ -91,6 +126,7 @@ accepted format and default value.
 
 To change the site-wide typography preset, edit `site/theme.md`. To change one
 page or section, add a focused `presentation.typography` override in
-`site/content.md`. Use `npm run norna:typography:presets` to inspect the
-installed preset values and `npm run norna:typography:show` to inspect the
-resolved typography for the selected site.
+`site/content.md`. See [Typography](typography.md). Use
+`npm run norna:typography:presets` to inspect the installed preset values and
+`npm run norna:typography:show` to inspect the resolved typography for the
+selected site.

package/docs/local-development.md

@@ -24,6 +24,19 @@ localhost:4321
 If the port is already in use, the command fails and asks you to stop the
 process using it.
 
+To stop any process that is blocking the standard port before starting, pass
+`--kill`:
+
+```sh
+npm run norna:dev -- --kill
+```
+
+For the pure starter's `dev` alias, use:
+
+```sh
+npm run dev -- --kill
+```
+
 ## Test On A Phone
 
 To make the local dev server available to devices on the same Wi-Fi network:

package/docs/publishing.md

@@ -25,6 +25,29 @@ workflow:
 Site-specific static files such as `site/public/CNAME`, `robots.txt`, and
 `sitemap.xml` belong in the site repository.
 
+In the GitHub repository settings, set Pages to build from GitHub Actions. For
+a project site without a custom domain, configure the site URL and base path in
+`site/config.mjs`:
+
+```js
+site: {
+	url: 'https://owner.github.io/repository-name/',
+	basePath: '/repository-name/',
+}
+```
+
+For a custom domain, keep `basePath` as `/`:
+
+```js
+site: {
+	url: 'https://example.com/',
+	basePath: '/',
+}
+```
+
+Norna uses `site.basePath` for generated internal page links, favicons,
+generated images, and root-relative links or images written in Markdown.
+
 ## Deploy An Already Committed Branch
 
 Use:

package/docs/routes.md

@@ -0,0 +1,90 @@
+# Routes
+
+`site/content.md` is the homepage and builds to `/`. Optional route pages live
+under `site/routes/<route-folder>/route-content.md` and build to first-level
+URLs.
+
+Routes use the same page frontmatter, section frontmatter, gallery rows, and
+Markdown section model as the homepage. See [Content](content.md) for the page
+and section model.
+
+## Route File
+
+Add a first-level route by creating:
+
+```text
+site/routes/about/route-content.md
+```
+
+Minimal route page:
+
+```md
+---
+title: About
+description: About this gallery.
+navigation:
+  label: About
+  order: 20
+sections:
+  - id: intro
+---
+
+## Intro {#intro}
+
+Text...
+```
+
+The example above builds to `/about/`.
+
+## Slug
+
+If `slug` is omitted, the route folder name is used. If `slug` is set, it must
+use lowercase letters, numbers, and hyphens.
+
+```yaml
+slug: about-the-work
+```
+
+Keep the route folder and `slug` aligned unless you intentionally need a
+different URL.
+
+The homepage ignores `slug`.
+
+## Navigation
+
+`navigation` may contain:
+
+- `include`: optional boolean. Defaults to `true`.
+- `label`: optional string. Defaults to `title`.
+- `order`: optional integer. Defaults to `0` for the homepage and `100` for
+  route pages.
+
+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 route:
+
+```text
+site/routes/about/images/intro/image.jpg
+```
+
+Image references in route frontmatter still use only the filename:
+
+```yaml
+sections:
+  - id: intro
+    gallery:
+      - image: image.jpg
+        alt: "Intro image."
+```
+
+The image directory segment after `images/` should match the section id.

package/docs/site-structure.md

@@ -26,8 +26,10 @@ site/
 ```
 
 Use `NORNA_SITE_DIR` or `norna --site-dir <path>` to select another
-site directory. Commands started from a subdirectory walk upward until they find
-the selected site directory containing both `config.mjs` and `content.md`.
+site directory. Without an explicit site directory, commands first accept the
+current directory when it contains both `config.mjs` and `content.md`.
+Otherwise, commands started from a subdirectory walk upward until they find the
+default `site/` directory containing those files.
 `theme.md` is optional; omit it to use the engine's built-in presentation
 defaults.
 
@@ -36,12 +38,13 @@ defaults.
 Version these files in a site repository:
 
 - `site/config.mjs`: technical site configuration.
-- `site/theme.md`: optional site-wide visual theme, inline styles, and frame
-  defaults.
+- `site/theme.md`: optional site-wide visual theme, inline styles, typography
+  defaults, and frame colors. See [Theme](theme.md).
 - `site/content.md`: homepage page file with editable content, section
-  definitions, gallery rows, alt text, and captions.
+  definitions, gallery rows, alt text, and captions. See [Content](content.md).
 - `site/images/<section-id>/`: original source images.
 - `site/routes/<route-folder>/route-content.md`: optional route page files.
+  See [Routes](routes.md).
 - `site/routes/<route-folder>/images/<section-id>/`: original source images
   for that route page.
 - `site/public/`: site-specific static public files.
@@ -66,16 +69,20 @@ Do not edit these by hand:
 
 Favicons are convention-based. Put files such as `favicon.svg`, `favicon.ico`,
 `favicon.png`, or `apple-touch-icon.png` in `site/public/`. The renderer emits
-icon links only for files that exist.
+icon links only for files that exist and prefixes them with `site.basePath`
+when the site is published below a path such as `/repository-name/`.
 
 ## Engine Repository Layout
 
 In this repository:
 
-- `bin/norna.mjs` dispatches public CLI commands.
+- `bin/norna.mjs` launches the appropriate installed Norna version.
+- `bin/norna-cli.mjs` dispatches public CLI commands.
 - `scripts/` contains validation, image, local preview, deploy, and test tools.
 - `src/` contains the Astro renderer, components, styles, and content schema.
 - `starters/basic/` is copied by `norna init <target-dir>` to create a
   site repository.
 - `fixtures/basic/site/` is used by engine regression tests.
-- `site/` is the local dog-gallery demo used by default in this repository.
+- `examples/dog-gallery/site/` is the local visual dog-gallery demo used by
+  demo builds and navigation diagnostics.
+- `site/` is reserved for the local documentation site.

package/docs/theme.md

@@ -0,0 +1,150 @@
+# Theme
+
+`site/theme.md` defines optional site-wide visual defaults for a `norna` site.
+It uses YAML frontmatter and does not need a Markdown body. If the file is
+missing, built-in engine defaults are used.
+
+Page-level presentation in `site/content.md` and route page files is always an
+override on top of `site/theme.md`. Section-level presentation is an override
+on top of the resolved page presentation.
+
+## Minimal Theme
+
+```yaml
+---
+navigation:
+  brand: Example Gallery
+presentation:
+  backgroundColor: "#000000"
+  textColor: "#f7f4ee"
+  typography:
+    preset: quiet-gallery
+frame:
+  colors: presentation
+---
+```
+
+Starter sites include a marked comment block such as
+`norna:start theme-help` / `norna:end theme-help`. The block is only
+explorable help text; YAML comments do not affect rendering. The active
+configuration is the uncommented YAML below it.
+
+## Navigation
+
+`navigation` is optional. It currently supports:
+
+- `brand`: optional site-wide brand or home-link text shown in the site
+  navigation.
+
+If `navigation.brand` is omitted, Norna uses the homepage `title` from
+`site/content.md`. Use `navigation.brand` when the homepage title is editorial
+or route-specific, but the navigation should keep a stable site name.
+
+Example:
+
+```yaml
+navigation:
+  brand: Norna
+```
+
+## Presentation
+
+`presentation` is optional. It can contain:
+
+- `backgroundColor`: optional quoted hex color in `#rgb`, `#rrggbb`, or
+  `#rrggbbaa` form.
+- `textColor`: optional quoted hex color in `#rgb`, `#rrggbb`, or
+  `#rrggbbaa` form.
+- `inlineStyles`: optional named inline text styles.
+- `typography`: optional typography preset and overrides. See
+  [Typography](typography.md).
+
+Example:
+
+```yaml
+presentation:
+  backgroundColor: "#101418"
+  textColor: "#f4f1ea"
+```
+
+## Page And Section Overrides
+
+Site-wide presentation belongs in `site/theme.md`. Page-level presentation in a
+page file is always an override on top of the theme:
+
+```yaml
+presentation:
+  typography:
+    overrides:
+      body:
+        paragraphSpacing: 1em
+```
+
+Section-specific presentation belongs under `sections[].presentation`:
+
+```yaml
+sections:
+  - id: intro
+    presentation:
+      backgroundColor: "#161616"
+      textColor: "#ffffff"
+      typography:
+        preset: statement
+```
+
+If a page omits `presentation`, it uses the theme presentation unchanged. If a
+section omits `presentation`, it uses the resolved page presentation.
+
+Configured section backgrounds render as full-width horizontal bands while the
+section content keeps the normal page and gallery widths. The top spacing
+before the first heading, the spacing between sections, and the spacing after
+the final section are part of the section background.
+
+Configured section text colors apply to section headings, Markdown text,
+Markdown subheadings, and gallery captions. Links keep the global accent color.
+
+## Frame Colors
+
+`frame.colors` controls the sticky navigation and footer colors.
+
+Allowed values:
+
+- `presentation`: use the resolved presentation colors for this level.
+- `theme`: use the site theme frame colors. This is useful in page-level
+  frontmatter.
+- explicit colors:
+
+```yaml
+frame:
+  colors:
+    backgroundColor: "#111111"
+    textColor: "#eeeeee"
+```
+
+The sticky section navigation row and footer use the resolved frame colors, not
+section-specific presentation.
+
+## Inline Styles
+
+`presentation.inlineStyles` defines named inline text styles that can be used
+from Markdown:
+
+```yaml
+presentation:
+  inlineStyles:
+    highlight:
+      color: "#ffd84d"
+```
+
+Inline style names must match `^[a-z][a-z0-9-]*$`. Each style currently
+supports a required `color` field using the same quoted hex color format as
+`textColor`.
+
+Apply an inline style in Markdown with `[text]{.style-name}`:
+
+```md
+This sentence contains [highlighted text]{.highlight}.
+```
+
+`content:check` fails if Markdown uses an inline style that is not defined in
+`site/theme.md` `presentation.inlineStyles`.

package/docs/typography.md

@@ -0,0 +1,125 @@
+# Typography
+
+`norna` typography is configured through presets with optional overrides. The
+site font family itself is a technical setting in
+[`typography.fontFamily`](configuration.md#typographyfontfamily).
+
+The normal place to choose a site-wide typography preset is `site/theme.md`.
+Page and section files may override the theme when a page or section needs a
+different presentation.
+
+## Presets
+
+Available presets:
+
+- `quiet-gallery`: the default for image-led art and portfolio sites. Text is
+  restrained and supports the images without dominating the page.
+- `compact-gallery`: tighter typography for many sections, many images, or
+  short information blocks.
+- `text-forward`: more generous body text for pages where longer text carries
+  more of the experience.
+- `statement`: stronger type for introductions, first sections, and short
+  programmatic statements. Use it sparingly, usually as a section override.
+
+If theme typography is omitted, `quiet-gallery` is used.
+
+Presets normally keep `heading.size` and `body.size` at `medium`. They differ
+primarily through alignment, line height, paragraph spacing, caption treatment,
+and intended use. Choose larger or smaller type with focused overrides when a
+specific page or section needs it.
+
+Use this command to inspect the exact preset values shipped with the installed
+engine:
+
+```sh
+npm run norna:typography:presets
+```
+
+Use this command to inspect the effective values for the selected site after
+presets and overrides have been applied:
+
+```sh
+npm run norna:typography:show
+```
+
+The output includes the site theme, every page route, and every section. Each
+resolved value shows its `source`; values inherited by a page or section are
+also marked with `inherited: true`.
+
+## Configuration Shape
+
+```yaml
+presentation:
+  typography:
+    preset: quiet-gallery
+    overrides:
+      body:
+        paragraphSpacing: 0.8em
+```
+
+The typographic roles are:
+
+- `heading`: section headings.
+- `body`: Markdown body text inside sections.
+- `caption`: gallery captions.
+
+Allowed alignment values are `left`, `center`, and `right`. Alignment can be
+responsive:
+
+```yaml
+align:
+  desktop: left
+  mobile: center
+```
+
+Allowed size values are `small`, `medium`, `large`, and `xlarge`. `medium` is
+the normal reading size. Use `small` for quieter supporting text, and use
+`large` or `xlarge` only when a page or section needs stronger emphasis.
+Headings use their own scale, but follow the same principle: `medium` is the
+normal section heading size, not a hero size.
+
+`lineHeight` is a unitless number from `1` through `3`. `spacing` and
+`paragraphSpacing` are CSS lengths such as `0`, `0.8em`, `1rem`, or `12px`.
+
+Supported override fields:
+
+- `heading.align`, `heading.size`, `heading.lineHeight`, `heading.spacing`
+- `body.align`, `body.size`, `body.lineHeight`, `body.paragraphSpacing`
+- `caption.align`, `caption.size`, `caption.lineHeight`, `caption.spacing`
+
+## Inheritance
+
+Theme typography is the site-wide base:
+
+```yaml
+# site/theme.md
+presentation:
+  typography:
+    preset: quiet-gallery
+```
+
+A page-level `presentation.typography.preset` changes the typographic base for
+that page. A section-level `sections[].presentation.typography.preset` changes
+the typographic base for that section.
+
+If a section sets `typography.preset`, that section starts from that preset. If
+a section only sets `typography.overrides`, it keeps the resolved page preset
+and changes only the specified values.
+
+Example section override:
+
+```yaml
+sections:
+  - id: intro
+    presentation:
+      typography:
+        preset: statement
+        overrides:
+          body:
+            paragraphSpacing: 0.7em
+```
+
+Centered text uses narrower text widths. Left- or right-aligned heading and body
+text use the calculated gallery layout width so text edges line up with gallery
+images after layout gutters and gallery limits are applied. Gallery captions
+are normally centered.