@janga/norna 0.7.1 → 0.7.3

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:
@@ -56,7 +79,7 @@ npm run norna:deploy:commit -- "Commit message"
 
 It builds, stages only allowed site changes, commits, pushes, and checks Pages.
 The allowlist is implemented in `scripts/deploy-site.mjs` and includes the
-site content file, selected config/static files, expected gallery images,
+site content file, selected config/static files, expected generated images,
 generated image manifest, package files, `tsconfig.json`, `astro.config.mjs`,
 and `src/` changes.
 

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, image 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 site.
+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,22 +26,26 @@ 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`.
-`theme.md` is optional; omit it to use the engine's built-in presentation
-defaults.
+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 visual defaults.
 
 ## Versioned Source Files
 
 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, including layout, spacing,
+  image sizing, font, typography defaults, colors, inline styles, 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, image 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 +70,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 example used by demo
+  builds and navigation diagnostics.
+- `site/` is reserved for the local documentation site.

package/docs/theme.md

@@ -0,0 +1,292 @@
+# 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 Site
+layout:
+  pageWidth: 1180px
+  gutter:
+    desktop: clamp(1.25rem, 4vw, 3rem)
+    mobile: 1rem
+  spacing:
+    firstSectionTop:
+      desktop: clamp(1.875rem, 3vw, 2.75rem)
+      mobile: 1.375rem
+    sectionGap:
+      desktop: clamp(2.55rem, 4.2vw, 3.9rem)
+      mobile: 2.25rem
+    finalSectionBottom:
+      desktop: clamp(2.55rem, 4.2vw, 3.9rem)
+      mobile: 2.25rem
+    sectionHeadingToBody:
+      desktop: clamp(0.5625rem, 1.25vw, 0.75rem)
+      mobile: 0.4375rem
+    bodyToImages:
+      desktop: clamp(1.25rem, 2.5vw, 2rem)
+      mobile: 1.25rem
+    imageGap:
+      desktop: clamp(1.5rem, 3.5vw, 2.75rem)
+      mobile: 2.75rem
+    subheadingTop:
+      desktop: 2rem
+      mobile: 1.6rem
+    subheadingRuleTop:
+      desktop: 1rem
+      mobile: 0.8rem
+gallery:
+  width: 900px
+  maxAvailableWidthPercent:
+    desktop: 100
+    mobile: 100
+  maxAvailableHeightPercent:
+    desktop: 74
+    mobile: 68
+typography:
+  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
+  preset: quiet-gallery
+presentation:
+  backgroundColor: "#000000"
+  textColor: "#f7f4ee"
+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
+```
+
+## Layout
+
+`layout` is optional. It controls the outer page geometry:
+
+- `pageWidth`: maximum width of the main page content area.
+- `gutter`: side margin removed from the viewport before available content
+  width is calculated. Use either one CSS length for all viewports or
+  `desktop` / `mobile` values.
+- `spacing`: vertical rhythm for sections, text, image rows, and Markdown
+  subheadings. Every spacing value accepts either one CSS length for all
+  viewports or `desktop` / `mobile` values.
+
+Example:
+
+```yaml
+layout:
+  pageWidth: 1180px
+  gutter:
+    desktop: clamp(1.25rem, 4vw, 3rem)
+    mobile: 1rem
+  spacing:
+    firstSectionTop:
+      desktop: clamp(1.875rem, 3vw, 2.75rem)
+      mobile: 1.375rem
+    sectionGap:
+      desktop: clamp(2.55rem, 4.2vw, 3.9rem)
+      mobile: 2.25rem
+    subheadingTop:
+      desktop: 2rem
+      mobile: 1.6rem
+```
+
+If omitted, Norna uses `1180px` for `pageWidth`, desktop
+`clamp(1.25rem, 4vw, 3rem)` for `gutter`, mobile `1rem`, and the spacing
+defaults shown in the minimal theme example.
+
+Spacing keys:
+
+- `firstSectionTop`: space above the first section heading.
+- `sectionGap`: space above each following section.
+- `finalSectionBottom`: space below the final section.
+- `sectionHeadingToBody`: space from a section heading to its body text.
+- `bodyToImages`: space from section body text to image rows.
+- `imageGap`: space between image rows.
+- `subheadingTop`: space above Markdown `###` subheadings inside body text.
+- `subheadingRuleTop`: space between the rule above a Markdown `###`
+  subheading and the subheading text.
+
+## Image Sizing
+
+`gallery` is optional. It controls image sizing:
+
+- `width`: hard maximum rendered image area width for images, captions, and
+  aligned text.
+- `maxAvailableWidthPercent`: maximum share of available width after gutters.
+- `maxAvailableHeightPercent`: maximum share of viewport height used by
+  images.
+
+Example:
+
+```yaml
+gallery:
+  width: 900px
+  maxAvailableWidthPercent:
+    desktop: 100
+    mobile: 100
+  maxAvailableHeightPercent:
+    desktop: 74
+    mobile: 68
+```
+
+If omitted, Norna uses `900px`, full available width, and image height limits of
+desktop `74` / mobile `68`.
+
+## Typography
+
+Top-level `typography` is the site-wide typographic base. It supports:
+
+- `fontFamily`: global CSS font-family stack.
+- `preset`: built-in typography preset.
+- `overrides`: focused changes to preset values.
+
+Example:
+
+```yaml
+typography:
+  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
+  preset: quiet-gallery
+  overrides:
+    headings:
+      h2:
+        size: medium
+      h3:
+        size: small
+    body:
+      lineHeight: 1.55
+```
+
+Use `norna typography presets` to inspect built-in preset values and
+`norna typography show` to inspect the resolved typography for the selected
+site. See [Typography](typography.md).
+
+## 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.
+
+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:
+      headings:
+        h2:
+          size: large
+      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 image 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 image 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,144 @@
+# Typography
+
+`norna` typography is configured in `site/theme.md` through a site-wide font,
+presets, and optional overrides.
+
+The normal place to choose a site-wide typography preset is the top-level
+`typography` block in `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 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 define `headings.h1` through `headings.h4`, `body`, and `caption`.
+They differ primarily through heading scale, 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
+norna typography presets
+```
+
+Use this command to inspect the effective values for the selected site after
+presets and overrides have been applied:
+
+```sh
+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
+typography:
+  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
+  preset: quiet-gallery
+  overrides:
+    headings:
+      h2:
+        size: medium
+      h3:
+        size: small
+    body:
+      paragraphSpacing: 0.8em
+```
+
+The typographic roles are:
+
+- `headings.h1`: reserved for page-level Markdown `#` headings if the content
+  model starts supporting them.
+- `headings.h2`: Markdown `##` section headings.
+- `headings.h3`: Markdown `###` subheadings inside section body text.
+- `headings.h4`: Markdown `####` subheadings inside section body text.
+- `body`: Markdown body text inside sections.
+- `caption`: image 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. Norna may render the first
+section heading as an HTML `h1` for document structure, but its visual
+typography still follows the Markdown level the user wrote: `##` uses
+`headings.h2`.
+
+`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:
+
+- `headings.h1.align`, `headings.h1.size`, `headings.h1.lineHeight`,
+  `headings.h1.spacing`
+- `headings.h2.align`, `headings.h2.size`, `headings.h2.lineHeight`,
+  `headings.h2.spacing`
+- `headings.h3.align`, `headings.h3.size`, `headings.h3.lineHeight`,
+  `headings.h3.spacing`
+- `headings.h4.align`, `headings.h4.size`, `headings.h4.lineHeight`,
+  `headings.h4.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
+typography:
+  fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif"
+  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 image layout width so text edges line up with images
+after layout gutters and image limits are applied. Captions are normally
+centered.