@janga/norna 0.7.1 → 0.7.3

package/src/content.config.ts

@@ -25,6 +25,12 @@ const cssLength = z.string().regex(
 	/^(?:0|(?:\d+(?:\.\d+)?|\.\d+)(?:px|rem|em|ch|lh))$/,
 	'Use a CSS length such as "0", "0.8em", "1rem", or "12px".',
 );
+const visualCssLengthUnit = String.raw`(?:px|rem|em|vw|vh|vmin|vmax|ch|%)`;
+const visualCssLengthValue = String.raw`(?:\d+(?:\.\d+)?|\.\d+)${visualCssLengthUnit}`;
+const visualCssLength = z.string().regex(
+	new RegExp(`^(?:0|${visualCssLengthValue}|clamp\\(\\s*${visualCssLengthValue}\\s*,\\s*${visualCssLengthValue}\\s*,\\s*${visualCssLengthValue}\\s*\\))$`),
+	'Use a CSS length such as "0", "900px", "56rem", "90%", or "clamp(1rem, 4vw, 3rem)".',
+);
 const inlineStyleName = z.string().regex(/^[a-z][a-z0-9-]*$/);
 const dateOnly = z.string()
 	.regex(/^\d{4}-\d{2}-\d{2}$/, 'Use YYYY-MM-DD format.')
@@ -55,6 +61,12 @@ const headingPresentationOverride = z.object({
 	...commonTextPresentationOverride,
 	spacing: cssLength.optional(),
 }).strict();
+const headingLevelsPresentationOverride = z.object({
+	h1: headingPresentationOverride.optional(),
+	h2: headingPresentationOverride.optional(),
+	h3: headingPresentationOverride.optional(),
+	h4: headingPresentationOverride.optional(),
+}).strict();
 const bodyPresentationOverride = z.object({
 	...commonTextPresentationOverride,
 	paragraphSpacing: cssLength.optional(),
@@ -64,7 +76,7 @@ const captionPresentationOverride = z.object({
 	spacing: cssLength.optional(),
 }).strict();
 const typographyOverrides = z.object({
-	heading: headingPresentationOverride.optional(),
+	headings: headingLevelsPresentationOverride.optional(),
 	body: bodyPresentationOverride.optional(),
 	caption: captionPresentationOverride.optional(),
 }).strict();
@@ -75,6 +87,50 @@ const typography = z.object({
 	(value) => value.preset !== undefined || value.overrides !== undefined,
 	'Specify preset, overrides, or both.',
 );
+const themeTypography = z.object({
+	fontFamily: z.string()
+		.min(1)
+		.refine((value) => !/[\n\r;{}]/.test(value), 'Do not use semicolons, braces, or line breaks.').optional(),
+	preset: typographyPreset.optional(),
+	overrides: typographyOverrides.optional(),
+}).strict().refine(
+	(value) => value.fontFamily !== undefined || value.preset !== undefined || value.overrides !== undefined,
+	'Specify fontFamily, preset, overrides, or both.',
+);
+const responsiveCssLength = z.union([
+	visualCssLength,
+	z.object({
+		desktop: visualCssLength,
+		mobile: visualCssLength,
+	}).strict(),
+]);
+const responsivePercent = z.union([
+	z.number().positive().max(100),
+	z.object({
+		desktop: z.number().positive().max(100),
+		mobile: z.number().positive().max(100),
+	}).strict(),
+]);
+const themeLayoutSpacing = z.object({
+	bodyToImages: responsiveCssLength.optional(),
+	finalSectionBottom: responsiveCssLength.optional(),
+	firstSectionTop: responsiveCssLength.optional(),
+	imageGap: responsiveCssLength.optional(),
+	sectionGap: responsiveCssLength.optional(),
+	sectionHeadingToBody: responsiveCssLength.optional(),
+	subheadingRuleTop: responsiveCssLength.optional(),
+	subheadingTop: responsiveCssLength.optional(),
+}).strict();
+const themeLayout = z.object({
+	pageWidth: visualCssLength.optional(),
+	gutter: responsiveCssLength.optional(),
+	spacing: themeLayoutSpacing.optional(),
+}).strict();
+const themeGallery = z.object({
+	width: visualCssLength.optional(),
+	maxAvailableWidthPercent: responsivePercent.optional(),
+	maxAvailableHeightPercent: responsivePercent.optional(),
+}).strict();
 const sectionPresentationOverride = z.object({
 	backgroundColor: colorValue.optional(),
 	textColor: colorValue.optional(),
@@ -86,7 +142,6 @@ const themePresentation = z.object({
 	inlineStyles: z.record(inlineStyleName, z.object({
 		color: colorValue,
 	}).strict()).optional(),
-	typography: typography.optional(),
 }).strict();
 const pagePresentation = z.object({
 	backgroundColor: colorValue.optional(),
@@ -108,6 +163,9 @@ const pageNavigation = z.object({
 	label: z.string().optional(),
 	order: z.number().int().optional(),
 }).strict();
+const themeNavigation = z.object({
+	brand: z.string().min(1).optional(),
+}).strict();
 
 const galleryImage = z.object({
 	image: contentImageName,
@@ -137,6 +195,10 @@ const siteSchema = z.object({
 });
 
 const themeSchema = z.object({
+	navigation: themeNavigation.optional(),
+	layout: themeLayout.optional(),
+	gallery: themeGallery.optional(),
+	typography: themeTypography.optional(),
 	presentation: themePresentation.optional(),
 	frame: frame.optional(),
 }).strict();

package/src/layouts/BaseLayout.astro

@@ -1,6 +1,7 @@
 ---
 import projectConfig from '../../scripts/lib/project-config.mjs';
 import { getIconLinks } from '../lib/sitePublicAssets';
+import { withBasePath } from '../lib/basePath';
 import '../styles/global.css';
 
 type FrameColors = {
@@ -23,17 +24,34 @@ const {
 } = Astro.props;
 
 const documentTitle = title;
-const canonicalUrl = new URL(pathname, projectConfig.site.url).href;
+const canonicalUrl = new URL(withBasePath(projectConfig.site.basePath, pathname), projectConfig.site.url).href;
 const iconLinks = getIconLinks();
 const scrollBehavior = projectConfig.navigation.smoothScroll.enabled ? 'smooth' : 'auto';
 const formatPercent = (value: number) => `${value}%`;
 const formatViewportHeightPercent = (value: number) => `${value}svh`;
+const layoutSpacing = projectConfig.layout.spacing;
 const documentStyle = [
 	`scroll-behavior: ${scrollBehavior}`,
 	`--font-sans: ${projectConfig.typography.fontFamily}`,
 	`--page-width: ${projectConfig.layout.pageWidth}`,
 	`--content-gutter-desktop: ${projectConfig.layout.gutter.desktop}`,
 	`--content-gutter-mobile: ${projectConfig.layout.gutter.mobile}`,
+	`--space-nav-to-first-section-desktop: ${layoutSpacing.firstSectionTop.desktop}`,
+	`--space-nav-to-first-section-mobile: ${layoutSpacing.firstSectionTop.mobile}`,
+	`--space-section-title-to-body-desktop: ${layoutSpacing.sectionHeadingToBody.desktop}`,
+	`--space-section-title-to-body-mobile: ${layoutSpacing.sectionHeadingToBody.mobile}`,
+	`--space-section-body-to-gallery-desktop: ${layoutSpacing.bodyToImages.desktop}`,
+	`--space-section-body-to-gallery-mobile: ${layoutSpacing.bodyToImages.mobile}`,
+	`--space-gallery-item-desktop: ${layoutSpacing.imageGap.desktop}`,
+	`--space-gallery-item-mobile: ${layoutSpacing.imageGap.mobile}`,
+	`--space-section-to-section-desktop: ${layoutSpacing.sectionGap.desktop}`,
+	`--space-section-to-section-mobile: ${layoutSpacing.sectionGap.mobile}`,
+	`--space-final-section-bottom-desktop: ${layoutSpacing.finalSectionBottom.desktop}`,
+	`--space-final-section-bottom-mobile: ${layoutSpacing.finalSectionBottom.mobile}`,
+	`--space-subheading-top-desktop: ${layoutSpacing.subheadingTop.desktop}`,
+	`--space-subheading-top-mobile: ${layoutSpacing.subheadingTop.mobile}`,
+	`--space-subheading-rule-top-desktop: ${layoutSpacing.subheadingRuleTop.desktop}`,
+	`--space-subheading-rule-top-mobile: ${layoutSpacing.subheadingRuleTop.mobile}`,
 	`--gallery-width: ${projectConfig.gallery.width}`,
 	`--gallery-max-available-width-desktop: ${formatPercent(projectConfig.gallery.maxAvailableWidthPercent.desktop)}`,
 	`--gallery-max-available-width-mobile: ${formatPercent(projectConfig.gallery.maxAvailableWidthPercent.mobile)}`,

package/src/lib/basePath.ts

@@ -0,0 +1,21 @@
+export const withBasePath = (basePath: string, value: string) => {
+	if (
+		basePath === '/'
+		|| value.startsWith('#')
+		|| value.startsWith('//')
+		|| /^[a-z][a-z0-9+.-]*:/i.test(value)
+	) {
+		return value;
+	}
+
+	if (!value.startsWith('/')) {
+		return value;
+	}
+
+	return `${basePath.replace(/\/$/, '')}${value}`;
+};
+
+export const applyBasePathToHtml = (basePath: string, html: string) =>
+	html.replace(/\b(href|src)=(["'])\/(?!\/)([^"']*)\2/g, (_match, attribute: string, quote: string, path: string) => (
+		`${attribute}=${quote}${withBasePath(basePath, `/${path}`)}${quote}`
+	));

package/src/lib/generatedImages.ts

@@ -1,5 +1,7 @@
 import { readFileSync } from 'node:fs';
+import projectConfig from '../../scripts/lib/project-config.mjs';
 import { generatedImagesManifestPath } from '../../scripts/lib/site-paths.mjs';
+import { withBasePath } from './basePath';
 
 type GeneratedImage = {
 	outputVersion?: number;
@@ -26,7 +28,9 @@ const fallbackDisplayImageWidth = 1440;
 
 export const getGeneratedImage = (src: string) => images[src];
 
-export const getLinkedImageSrc = (src: string) => getGeneratedImage(src)?.variants.at(-1)?.src ?? src;
+const displaySrc = (src: string) => withBasePath(projectConfig.site.basePath, src);
+
+export const getLinkedImageSrc = (src: string) => displaySrc(getGeneratedImage(src)?.variants.at(-1)?.src ?? src);
 
 const getDisplayVariants = (variants: GeneratedImage['variants']) => {
 	const sortedVariants = [...variants].sort((a, b) => a.width - b.width);
@@ -44,7 +48,7 @@ export const getImageAttributes = (src: string, sizes: string) => {
 
 	if (!image) {
 		return {
-			src,
+			src: displaySrc(src),
 			sizes,
 		};
 	}
@@ -53,8 +57,8 @@ export const getImageAttributes = (src: string, sizes: string) => {
 	const fallbackVariant = getFallbackVariant(displayVariants);
 
 	return {
-		src: fallbackVariant?.src ?? src,
-		srcset: displayVariants.map((variant) => `${variant.src} ${variant.width}w`).join(', '),
+		src: displaySrc(fallbackVariant?.src ?? src),
+		srcset: displayVariants.map((variant) => `${displaySrc(variant.src)} ${variant.width}w`).join(', '),
 		sizes,
 		style: `aspect-ratio: ${image.width} / ${image.height};`,
 		width: image.width,

package/src/lib/sectionContent.ts

@@ -1,4 +1,6 @@
 import type { CollectionEntry } from 'astro:content';
+import projectConfig from '../../scripts/lib/project-config.mjs';
+import { applyBasePathToHtml } from './basePath';
 
 type SiteSection = CollectionEntry<'site'>['data']['sections'][number];
 type ThemePresentation = CollectionEntry<'theme'>['data']['presentation'];
@@ -56,6 +58,9 @@ const applyInlineStyles = (html: string, inlineStyles: InlineStyles | undefined)
 		return `<span class="inline-style inline-style-${styleName}" style="--inline-style-color: ${style.color}">${text}</span>`;
 	});
 
+const prepareContentHtml = (html: string, inlineStyles: InlineStyles | undefined) =>
+	applyBasePathToHtml(projectConfig.site.basePath, applyInlineStyles(html, inlineStyles));
+
 export const getSectionsContent = (
 	html: string,
 	sections: SiteSection[],
@@ -88,7 +93,7 @@ export const getSectionsContent = (
 
 		contentById.set(id, {
 			title,
-			contentHtml: applyInlineStyles(content, inlineStyles),
+			contentHtml: prepareContentHtml(content, inlineStyles),
 		});
 		markdownSectionIds.push(id);
 	}

package/src/lib/sitePublicAssets.ts

@@ -1,6 +1,8 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { sitePublicDir } from '../../scripts/lib/site-paths.mjs';
+import projectConfig from '../../scripts/lib/project-config.mjs';
+import { withBasePath } from './basePath';
 
 type IconLink = {
 	rel: 'icon' | 'apple-touch-icon';
@@ -36,4 +38,9 @@ const publicAssetExists = (href: string) => {
 	return existsSync(path.join(sitePublicDir, relativePath));
 };
 
-export const getIconLinks = () => faviconCandidates.filter((candidate) => publicAssetExists(candidate.href));
+export const getIconLinks = () => faviconCandidates
+	.filter((candidate) => publicAssetExists(candidate.href))
+	.map((candidate) => ({
+		...candidate,
+		href: withBasePath(projectConfig.site.basePath, candidate.href),
+	}));

package/src/styles/global.css

@@ -28,20 +28,30 @@
 	--gallery-max-image-height: var(--gallery-max-image-height-desktop);
 	--nav-top-safety-inset: 0px;
 
-	/* Avstand fran sticky navigationsrad till forsta sektionsrubriken. */
-	--space-nav-to-first-section: clamp(1.875rem, 3vw, 2.75rem);
-
-	/* Avstand fran sektionsrubrik till sektionens forsta textstycke. */
-	--space-section-title-to-body: clamp(0.5625rem, 1.25vw, 0.75rem);
-
-	/* Avstand fran sektionens lopande text till efterfoljande galleri. */
-	--space-section-body-to-gallery: clamp(1.25rem, 2.5vw, 2rem);
-
-	/* Avstand mellan enskilda bilder/verk inom samma galleri. */
-	--space-gallery-item: clamp(1.5rem, 3.5vw, 2.75rem);
-
-	/* Avstand fran sista galleriobjektet eller textblocket till nasta sektion. */
-	--space-section-to-section: clamp(2.55rem, 4.2vw, 3.9rem);
+	--space-nav-to-first-section-desktop: clamp(1.875rem, 3vw, 2.75rem);
+	--space-nav-to-first-section-mobile: 1.375rem;
+	--space-nav-to-first-section: var(--space-nav-to-first-section-desktop);
+	--space-section-title-to-body-desktop: clamp(0.5625rem, 1.25vw, 0.75rem);
+	--space-section-title-to-body-mobile: 0.4375rem;
+	--space-section-title-to-body: var(--space-section-title-to-body-desktop);
+	--space-section-body-to-gallery-desktop: clamp(1.25rem, 2.5vw, 2rem);
+	--space-section-body-to-gallery-mobile: 1.25rem;
+	--space-section-body-to-gallery: var(--space-section-body-to-gallery-desktop);
+	--space-gallery-item-desktop: clamp(1.5rem, 3.5vw, 2.75rem);
+	--space-gallery-item-mobile: 2.75rem;
+	--space-gallery-item: var(--space-gallery-item-desktop);
+	--space-section-to-section-desktop: clamp(2.55rem, 4.2vw, 3.9rem);
+	--space-section-to-section-mobile: 2.25rem;
+	--space-section-to-section: var(--space-section-to-section-desktop);
+	--space-final-section-bottom-desktop: var(--space-section-to-section-desktop);
+	--space-final-section-bottom-mobile: var(--space-section-to-section-mobile);
+	--space-final-section-bottom: var(--space-final-section-bottom-desktop);
+	--space-subheading-top-desktop: 2rem;
+	--space-subheading-top-mobile: 1.6rem;
+	--space-subheading-top: var(--space-subheading-top-desktop);
+	--space-subheading-rule-top-desktop: 1rem;
+	--space-subheading-rule-top-mobile: 0.8rem;
+	--space-subheading-rule-top: var(--space-subheading-rule-top-desktop);
 
 	--content-gutter-desktop: clamp(1.25rem, 4vw, 3rem);
 	--content-gutter-mobile: 1rem;
@@ -316,7 +326,7 @@ a {
 }
 
 .site-section:last-child {
-	padding-bottom: var(--space-section-to-section);
+	padding-bottom: var(--space-final-section-bottom);
 }
 
 .section-card {
@@ -331,18 +341,18 @@ a {
 	text-align: var(--section-heading-align-desktop, center);
 }
 
-h1,
-h2,
+.section-header h1,
+.section-header h2,
 p,
 ul {
 	margin-top: 0;
 }
 
-h1,
-h2 {
+.section-header h1,
+.section-header h2 {
 	margin-bottom: 0;
 	color: inherit;
-	font-size: var(--section-heading-font-size-desktop, clamp(1.4rem, 3.1vw, 3.2rem));
+	font-size: var(--section-heading-font-size-desktop, clamp(1.35rem, 1.1rem + 0.9vw, 2rem));
 	font-weight: 400;
 	letter-spacing: 0;
 	line-height: var(--section-heading-line-height, 1.04);
@@ -350,23 +360,18 @@ h2 {
 	overflow-wrap: anywhere;
 }
 
-.site-section-primary h1 {
-	font-size: var(--section-heading-font-size-desktop, clamp(1.65rem, 4.6vw, 5.65rem));
-	font-weight: 700;
-}
-
 .section-body {
 	width: 100%;
 	margin: 0 auto;
 	color: inherit;
 	font-family: var(--font-sans);
-	font-size: clamp(1rem, 0.96rem + 0.18vw, 1.125rem);
+	font-size: clamp(0.96rem, 0.94rem + 0.08vw, 1rem);
 }
 
 .section-markdown {
 	width: min(100%, var(--section-body-width-desktop, var(--text-width)));
 	margin: 0 auto var(--space-section-body-to-gallery);
-	font-size: var(--section-body-font-size-desktop, clamp(1rem, 0.96rem + 0.18vw, 1.125rem));
+	font-size: var(--section-body-font-size-desktop, clamp(0.96rem, 0.94rem + 0.08vw, 1rem));
 	line-height: var(--section-body-line-height, 1.78);
 	text-align: var(--section-body-align-desktop, center);
 }
@@ -389,23 +394,25 @@ h2 {
 }
 
 .section-markdown h3 {
-	margin: 2.75rem 0 0.9rem;
+	margin: var(--space-subheading-top) 0 var(--section-markdown-h3-spacing, 0.9rem);
 	border-top: 1px solid var(--color-soft);
-	padding-top: 1.75rem;
+	padding-top: var(--space-subheading-rule-top);
 	font-family: var(--font-sans);
-	font-size: 0.82rem;
-	letter-spacing: 0.14em;
-	line-height: 1.35;
+	font-size: var(--section-markdown-h3-font-size-desktop, 0.82rem);
+	letter-spacing: 0;
+	line-height: var(--section-markdown-h3-line-height, 1.35);
+	text-align: var(--section-markdown-h3-align-desktop, left);
 	text-transform: uppercase;
 }
 
 .section-markdown h4 {
-	margin: 0 0 0.85rem;
+	margin: 0 0 var(--section-markdown-h4-spacing, 0.85rem);
 	color: inherit;
-	font-size: clamp(0.95rem, 0.9rem + 0.2vw, 1.08rem);
+	font-size: var(--section-markdown-h4-font-size-desktop, clamp(0.96rem, 0.94rem + 0.08vw, 1rem));
 	font-weight: 400;
-	letter-spacing: 0.02em;
-	line-height: 1.5;
+	letter-spacing: 0;
+	line-height: var(--section-markdown-h4-line-height, 1.5);
+	text-align: var(--section-markdown-h4-align-desktop, left);
 }
 
 .section-markdown ul,
@@ -639,11 +646,14 @@ h2 {
 
 @media (max-width: 700px) {
 	:root {
-		--space-nav-to-first-section: 1.375rem;
-		--space-section-title-to-body: 0.4375rem;
-		--space-section-body-to-gallery: 1.25rem;
-		--space-gallery-item: 2.75rem;
-		--space-section-to-section: 2.25rem;
+		--space-nav-to-first-section: var(--space-nav-to-first-section-mobile);
+		--space-section-title-to-body: var(--space-section-title-to-body-mobile);
+		--space-section-body-to-gallery: var(--space-section-body-to-gallery-mobile);
+		--space-gallery-item: var(--space-gallery-item-mobile);
+		--space-section-to-section: var(--space-section-to-section-mobile);
+		--space-final-section-bottom: var(--space-final-section-bottom-mobile);
+		--space-subheading-top: var(--space-subheading-top-mobile);
+		--space-subheading-rule-top: var(--space-subheading-rule-top-mobile);
 		--content-gutter: var(--content-gutter-mobile);
 		--gallery-max-available-width: var(--gallery-max-available-width-mobile);
 		--gallery-max-image-height: var(--gallery-max-image-height-mobile);
@@ -780,18 +790,11 @@ h2 {
 		line-height: 1.72;
 	}
 
-	h1,
-	h2 {
-		font-size: var(
-			--section-heading-font-size-mobile,
-			var(--section-heading-font-size-desktop, clamp(1.4rem, 3.1vw, 3.2rem))
-		);
-	}
-
-	.site-section-primary h1 {
+	.section-header h1,
+	.section-header h2 {
 		font-size: var(
 			--section-heading-font-size-mobile,
-			var(--section-heading-font-size-desktop, clamp(1.9rem, 8vw, 3.2rem))
+			var(--section-heading-font-size-desktop, clamp(1.3rem, 1.05rem + 1.35vw, 1.75rem))
 		);
 	}
 
@@ -804,7 +807,7 @@ h2 {
 		width: min(100%, var(--section-body-width-mobile, var(--section-body-width-desktop, var(--text-width))));
 		font-size: var(
 			--section-body-font-size-mobile,
-			var(--section-body-font-size-desktop, clamp(1rem, 0.96rem + 0.18vw, 1.125rem))
+			var(--section-body-font-size-desktop, clamp(0.96rem, 0.94rem + 0.08vw, 1rem))
 		);
 		text-align: var(--section-body-align-mobile, var(--section-body-align-desktop, left));
 	}
@@ -819,12 +822,13 @@ h2 {
 	}
 
 	.section-markdown h3 {
-		margin-top: 2.25rem;
-		padding-top: 1.35rem;
+		font-size: var(--section-markdown-h3-font-size-mobile, var(--section-markdown-h3-font-size-desktop, 0.82rem));
+		text-align: var(--section-markdown-h3-align-mobile, var(--section-markdown-h3-align-desktop, left));
 	}
 
 	.section-markdown h4 {
-		text-align: center;
+		font-size: var(--section-markdown-h4-font-size-mobile, var(--section-markdown-h4-font-size-desktop, clamp(0.96rem, 0.94rem + 0.08vw, 1rem)));
+		text-align: var(--section-markdown-h4-align-mobile, var(--section-markdown-h4-align-desktop, left));
 	}
 
 	.section-markdown ul,

package/starters/basic/.github/workflows/deploy.yml

@@ -34,10 +34,10 @@ jobs:
       - name: Restore generated images
         uses: actions/cache@v4
         with:
-          path: site/.cli-gallery/public/images/generated
-          key: cli-gallery-images-${{ hashFiles('site/.cli-gallery/generated-images.json') }}
+          path: site/.norna/public/images/generated
+          key: norna-images-${{ hashFiles('site/.norna/generated-images.json') }}
           restore-keys: |
-            cli-gallery-images-
+            norna-images-
 
       - name: Install dependencies
         run: npm ci

package/starters/basic/README.md

@@ -6,22 +6,35 @@ This is a minimal site repository starter for `@janga/norna`.
 
 ```sh
 npm install
-npm run norna:dev
+npm run dev
 ```
 
-Edit site-wide theme defaults in `site/theme.md`, homepage content and section
-overrides in `site/content.md`, technical settings such as URL, layout, font,
-and locale labels in `site/config.mjs`, source images under
+If the standard local port is blocked, start with:
+
+```sh
+npm run dev -- --kill
+```
+
+Edit site-wide visual defaults in `site/theme.md`, homepage content and section
+overrides in `site/content.md`, technical settings such as URL and locale
+labels in `site/config.mjs`, source images under
 `site/images/<section-id>/`, and static public files under `site/public/`.
 
-The page width is configured with `layout.pageWidth`; gallery width is
-configured with `gallery.width`. Side margins are configured with
-`layout.gutter`; image height is limited with
-`gallery.maxAvailableHeightPercent`.
+Use `site.basePath: '/'` for a custom domain or root-hosted site. For a GitHub
+Pages project site without a custom domain, set both values:
+
+```js
+site: {
+	url: 'https://owner.github.io/repository-name/',
+	basePath: '/repository-name/',
+}
+```
+
+In GitHub repository settings, configure Pages to build from GitHub Actions.
 
-The site font is configured with `typography.fontFamily` in `site/config.mjs`.
-Site-wide text presentation is configured with typography presets and overrides
-in `site/theme.md`; page and section overrides live in `site/content.md`.
+Page width, side gutters, vertical spacing, image width, image height limits,
+font, colors, and site-wide typography are configured in `site/theme.md`. Page
+and section presentation overrides live in `site/content.md`.
 
 Commit `package-lock.json` after the first install so GitHub Actions can use
 `npm ci`.
@@ -36,9 +49,9 @@ npm run norna:typography:show
 npm run norna:build
 ```
 
-This keeps gallery commands separate from repository-specific build or
-publishing commands in projects that embed a gallery inside a larger GitHub
-project. This pure starter also keeps `npm run build` as an alias for
+This keeps Norna commands separate from repository-specific build or publishing
+commands in projects that embed a Norna site inside a larger GitHub project.
+This pure starter also keeps `npm run build` as an alias for
 `npm run norna:build`.
 
 Use `npm run norna:engine:version` to inspect the installed engine and
@@ -49,6 +62,9 @@ Generic documentation lives in the `norna` repository:
 - `docs/getting-started.md`
 - `docs/site-structure.md`
 - `docs/content.md`
+- `docs/theme.md`
+- `docs/typography.md`
+- `docs/routes.md`
 - `docs/configuration.md`
 - `docs/commands.md`
 - `docs/images-and-metadata.md`

package/starters/basic/package.json

@@ -3,7 +3,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "npm run norna:dev",
+    "dev": "npm run norna:dev --",
     "norna:dev": "norna dev:local",
     "norna:dev:lan": "norna dev:lan",
     "norna:dev:restart": "norna dev:restart",
@@ -14,8 +14,8 @@
     "norna:config:check": "norna config:check",
     "norna:content:check": "norna content:check",
     "norna:sync": "norna content:sync",
-    "norna:typography:presets": "norna typography:presets",
-    "norna:typography:show": "norna typography:show",
+    "norna:typography:presets": "norna typography presets",
+    "norna:typography:show": "norna typography show",
     "norna:public": "norna site:public",
     "norna:images": "norna images",
     "norna:build": "norna build",

package/starters/basic/site/config.mjs

@@ -1,27 +1,7 @@
 export default {
 	site: {
 		url: 'https://example.com/',
-	},
-	layout: {
-		pageWidth: '1180px',
-		gutter: {
-			desktop: 'clamp(1.25rem, 4vw, 3rem)',
-			mobile: '1rem',
-		},
-	},
-	gallery: {
-		width: '900px',
-		maxAvailableWidthPercent: {
-			desktop: 100,
-			mobile: 100,
-		},
-		maxAvailableHeightPercent: {
-			desktop: 74,
-			mobile: 68,
-		},
-	},
-	typography: {
-		fontFamily: "Arial, 'Helvetica Neue', Helvetica, sans-serif",
+		basePath: '/',
 	},
 	navigation: {
 		smoothScroll: {
@@ -36,11 +16,11 @@ export default {
 		labels: {
 			skipToContent: 'Skip to content',
 			sectionNavigation: 'Sections',
-			gallery: 'Gallery',
+			gallery: 'Images',
 		},
 	},
 	footer: {
-		copyrightMessage: '(c) Example Artist.',
+		copyrightMessage: '(c) Example Owner.',
 		buildInfo: {
 			enabled: true,
 			text: 'Built',
@@ -53,7 +33,7 @@ export default {
 		},
 	},
 	github: {
-		repo: 'owner/example-gallery',
+		repo: 'owner/example-site',
 		branch: 'main',
 		pagesWorkflow: 'Deploy to GitHub Pages',
 	},