@zeropress/build-core 0.2.1 → 0.5.0

package/README.md

@@ -55,7 +55,6 @@ import {
   - `sitemap.xml`
   - `feed.xml`
   - `robots.txt`
-  - `meta.json`
 - writing outputs through a pluggable writer
 
 It does not:
@@ -120,7 +119,7 @@ Notes:
 - `previewData` must already satisfy the canonical preview-data contract
 - `themePackage` must already be a validated in-memory theme package
 - `sitemap.xml` and `feed.xml` are emitted only when `site.url` is a non-empty canonical URL
-- `robots.txt` and `meta.json` are still emitted when `generateSpecialFiles` is enabled
+- `robots.txt` is still emitted when `generateSpecialFiles` is enabled
 
 ### `buildSiteFromThemeDir(input)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeropress/build-core",
-  "version": "0.2.1",
+  "version": "0.5.0",
   "description": "Shared ZeroPress build core",
   "type": "module",
   "license": "MIT",
@@ -34,8 +34,8 @@
   },
   "dependencies": {
     "@zeropress/slug-policy": "^0.1.0",
-    "@zeropress/preview-data-validator": "^0.4.4",
-    "@zeropress/theme-validator": "^0.5.0",
+    "@zeropress/preview-data-validator": "0.5.0",
+    "@zeropress/theme-validator": "0.5.1",
     "highlight.js": "^11.11.1",
     "markdown-it": "^14.1.0",
     "markdown-it-anchor": "^9.2.0"

package/src/api/build-site.js

@@ -3,7 +3,7 @@ import { assertPreviewData } from '@zeropress/preview-data-validator';
 import { isSafeSlugSegment, normalizeStoredSlug } from '@zeropress/slug-policy';
 import { validateThemeFiles } from '@zeropress/theme-validator';
 import { AssetProcessor } from '../assets/asset-processor.js';
-import { renderDocumentContent } from '../render/content-renderer.js';
+import { renderDocument, renderDocumentContent } from '../render/content-renderer.js';
 import { ZeroPressEngine } from '../render/zeropress-engine.js';
 
 const DEFAULT_OPTIONS = {
@@ -17,6 +17,14 @@ const DEFAULT_DATE_FORMAT = 'YYYY-MM-DD';
 const DEFAULT_TIME_FORMAT = 'HH:mm';
 const DEFAULT_TIMEZONE = 'UTC';
 const DEFAULT_LOCALE = 'en-US';
+const DEFAULT_PERMALINKS = Object.freeze({
+  output_style: 'directory',
+  posts: '/posts/:slug/',
+  pages: '/:slug/',
+  categories: '/categories/:slug/',
+  tags: '/tags/:slug/',
+});
+const PERMALINK_OUTPUT_STYLES = new Set(['directory', 'html-extension']);
 const COMMENT_POLICY_OUTPUT_PATH = '_zeropress/comment-policy.json';
 const OUTPUT_PATH_CONTROL_CHAR_PATTERN = /[\u0000-\u001F\u007F]/;
 const SAFE_MEDIA_PROTOCOLS = new Set(['http:', 'https:']);
@@ -75,7 +83,6 @@ export async function buildSite(input) {
       await writeOutput(state.writer, state.summaries, 'feed.xml', buildFeedXml(state.previewData.site, state.emitted, state.generatedAt), 'application/rss+xml');
     }
     await writeOutput(state.writer, state.summaries, 'robots.txt', buildRobotsTxt(state.previewData.site), 'text/plain');
-    await writeOutput(state.writer, state.summaries, 'meta.json', buildMetaJson(state.previewData.site, state.emitted, state.generatedAt), 'application/json');
   }
 
   return finalizeBuildResult(state.writer, state.summaries, options);
@@ -86,7 +93,7 @@ async function createBuildState(input, options) {
     throw new Error('buildSite requires a writer with an async write(file) method');
   }
 
-  assertPreviewData(input.previewData);
+  assertBuildPreviewData(input.previewData);
   const themePackage = await normalizeAndValidateThemePackage(input.themePackage);
 
   const engine = new ZeroPressEngine();
@@ -117,6 +124,7 @@ async function createBuildState(input, options) {
     assetOutputs,
     assetMap,
     customCssHref: customCssAsset ? `/${customCssAsset.path}` : '',
+    customHtml: previewData.custom_html,
     commentPolicyContent: buildCommentPolicyManifest(renderData.posts),
     options,
     generatedAt: new Date(),
@@ -131,6 +139,18 @@ async function createBuildState(input, options) {
   };
 }
 
+function assertBuildPreviewData(previewData) {
+  try {
+    assertPreviewData(previewData);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (message.startsWith('Invalid preview-data')) {
+      throw error;
+    }
+    throw new Error(`Invalid preview-data: ${message}`);
+  }
+}
+
 async function finalizeBuildResult(writer, summaries, options) {
   let manifest;
   if (options.writeManifest) {
@@ -154,12 +174,13 @@ async function finalizeBuildResult(writer, summaries, options) {
 }
 
 async function renderRoute(state, templateName, route) {
-  const currentUrl = normalizeRoutePath(route.path);
+  const currentUrl = routePathToPublicUrl(route.path, state.previewData.site.permalinks.output_style);
   let html = await state.engine.render(
     templateName,
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      taxonomies: state.renderData.taxonomies,
       ...route,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
@@ -171,18 +192,19 @@ async function renderRoute(state, templateName, route) {
     createRenderContext(state.previewData.site, currentUrl),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectCustomCssAssetLink(html, state.customCssHref);
-  await writeOutput(state.writer, state.summaries, routePathToOutputPath(route.path), html, 'text/html');
+  html = injectSiteCustomizations(html, state);
+  await writeOutput(state.writer, state.summaries, routePathToOutputPath(route.path, state.previewData.site.permalinks.output_style), html, 'text/html');
   recordRouteEmission(state, templateName, route, currentUrl);
 }
 
 async function renderPost(state, post) {
-  const currentUrl = `/posts/${encodeSlugSegment(post.slug)}/`;
+  const currentUrl = post.url;
   let html = await state.engine.render(
     'post',
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      taxonomies: state.renderData.taxonomies,
       post,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
@@ -197,8 +219,8 @@ async function renderPost(state, post) {
     createRenderContext(state.previewData.site, currentUrl),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectCustomCssAssetLink(html, state.customCssHref);
-  await writeOutput(state.writer, state.summaries, `posts/${encodeSlugSegment(post.slug)}/index.html`, html, 'text/html');
+  html = injectSiteCustomizations(html, state);
+  await writeOutput(state.writer, state.summaries, routePathToOutputPath(post.url, state.previewData.site.permalinks.output_style), html, 'text/html');
   state.emitted.posts.push({
     url: currentUrl,
     title: post.title,
@@ -210,12 +232,13 @@ async function renderPost(state, post) {
 }
 
 async function renderPage(state, page) {
-  const currentUrl = `/${encodeSlugSegment(page.slug)}/`;
+  const currentUrl = page.url;
   let html = await state.engine.render(
     'page',
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      taxonomies: state.renderData.taxonomies,
       page,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
@@ -228,8 +251,8 @@ async function renderPage(state, page) {
     createRenderContext(state.previewData.site, currentUrl),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectCustomCssAssetLink(html, state.customCssHref);
-  await writeOutput(state.writer, state.summaries, `${encodeSlugSegment(page.slug)}/index.html`, html, 'text/html');
+  html = injectSiteCustomizations(html, state);
+  await writeOutput(state.writer, state.summaries, routePathToOutputPath(page.url, state.previewData.site.permalinks.output_style), html, 'text/html');
   state.emitted.pages.push({
     url: currentUrl,
     title: page.title,
@@ -248,6 +271,7 @@ async function maybeRenderNotFoundPage(state) {
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      taxonomies: state.renderData.taxonomies,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl: '/404.html',
         title: state.previewData.site.title,
@@ -258,7 +282,7 @@ async function maybeRenderNotFoundPage(state) {
     createRenderContext(state.previewData.site, '/404.html'),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectCustomCssAssetLink(html, state.customCssHref);
+  html = injectSiteCustomizations(html, state);
   await writeOutput(state.writer, state.summaries, '404.html', html, 'text/html');
 }
 
@@ -274,6 +298,7 @@ function normalizePreviewData(previewData) {
     timezone: normalizeNonEmptyString(previewData.site.timezone, DEFAULT_TIMEZONE),
     locale: normalizeLocale(previewData.site.locale || DEFAULT_LOCALE),
     disallowComments: previewData.site.disallowComments === true,
+    permalinks: normalizePermalinks(previewData.site.permalinks),
   };
 
   return {
@@ -281,6 +306,7 @@ function normalizePreviewData(previewData) {
     site: normalizedSite,
     widgets: normalizeWidgetAreas(previewData.widgets, normalizedSite.mediaBaseUrl),
     custom_css: normalizeCustomCss(previewData.custom_css),
+    custom_html: normalizeCustomHtml(previewData.custom_html),
     content: {
       ...previewData.content,
       authors: previewData.content.authors.map((author) => ({
@@ -348,6 +374,38 @@ function normalizeCustomCss(customCss) {
   return content ? { content } : undefined;
 }
 
+function normalizeCustomHtml(customHtml) {
+  if (!customHtml || typeof customHtml !== 'object') {
+    return undefined;
+  }
+
+  const headEnd = normalizeOptionalRawString(customHtml.head_end?.content);
+  const bodyEnd = normalizeOptionalRawString(customHtml.body_end?.content);
+  if (!headEnd && !bodyEnd) {
+    return undefined;
+  }
+
+  return {
+    ...(headEnd ? { head_end: { content: headEnd } } : {}),
+    ...(bodyEnd ? { body_end: { content: bodyEnd } } : {}),
+  };
+}
+
+function normalizePermalinks(permalinks) {
+  const source = permalinks && typeof permalinks === 'object' ? permalinks : {};
+  const outputStyle = typeof source.output_style === 'string' && PERMALINK_OUTPUT_STYLES.has(source.output_style)
+    ? source.output_style
+    : DEFAULT_PERMALINKS.output_style;
+
+  return {
+    output_style: outputStyle,
+    posts: normalizeNonEmptyString(source.posts, DEFAULT_PERMALINKS.posts),
+    pages: normalizeNonEmptyString(source.pages, DEFAULT_PERMALINKS.pages),
+    categories: normalizeNonEmptyString(source.categories, DEFAULT_PERMALINKS.categories),
+    tags: normalizeNonEmptyString(source.tags, DEFAULT_PERMALINKS.tags),
+  };
+}
+
 function createRenderData(previewData, themeMetadata = {}) {
   const themeSupportsComments = themeMetadata?.features?.comments === true;
   const authorsById = new Map(previewData.content.authors.map((author) => [author.id, author]));
@@ -376,17 +434,19 @@ function createRenderData(previewData, themeMetadata = {}) {
     prev: index > 0 ? buildAdjacentPostSummary(preparedPosts[index - 1]) : null,
     next: index < preparedPosts.length - 1 ? buildAdjacentPostSummary(preparedPosts[index + 1]) : null,
   }));
-  const pages = previewData.content.pages.map((page) => preparePage(page));
+  const pages = previewData.content.pages.map((page) => preparePage(page, previewData.site));
   const postBySlug = new Map(posts.map((post) => [post.slug, post]));
 
   return {
     posts,
     pages,
     postBySlug,
+    taxonomies: buildGlobalTaxonomies(previewData, categoryCountBySlug, tagCountBySlug),
     indexRoutes: buildPaginatedCollection({
       items: previewData.content.posts,
       postsPerPage: previewData.site.postsPerPage,
       basePath: '/',
+      outputStyle: previewData.site.permalinks.output_style,
     }).map((entry) => ({
       path: entry.path,
       page: entry.page,
@@ -398,6 +458,7 @@ function createRenderData(previewData, themeMetadata = {}) {
       items: previewData.content.posts,
       postsPerPage: previewData.site.postsPerPage,
       basePath: '/archive/',
+      outputStyle: previewData.site.permalinks.output_style,
     }).map((entry) => ({
       path: entry.path,
       page: entry.page,
@@ -412,7 +473,8 @@ function createRenderData(previewData, themeMetadata = {}) {
       postsBySlug: categoryPostsBySlug,
       postBySlug,
       postsPerPage: previewData.site.postsPerPage,
-      buildBasePath: (category) => `/categories/${encodeSlugSegment(category.slug)}/`,
+      outputStyle: previewData.site.permalinks.output_style,
+      buildBasePath: (category) => resolvePermalink(previewData.site, 'categories', category).path,
       renderExtras: (category) => ({
         taxonomy: buildTaxonomyRouteData('category', category, categoryCountBySlug),
       }),
@@ -422,7 +484,8 @@ function createRenderData(previewData, themeMetadata = {}) {
       postsBySlug: tagPostsBySlug,
       postBySlug,
       postsPerPage: previewData.site.postsPerPage,
-      buildBasePath: (tag) => `/tags/${encodeSlugSegment(tag.slug)}/`,
+      outputStyle: previewData.site.permalinks.output_style,
+      buildBasePath: (tag) => resolvePermalink(previewData.site, 'tags', tag).path,
       renderExtras: (tag) => ({
         taxonomy: buildTaxonomyRouteData('tag', tag, tagCountBySlug),
       }),
@@ -430,6 +493,23 @@ function createRenderData(previewData, themeMetadata = {}) {
   };
 }
 
+function buildGlobalTaxonomies(previewData, categoryCountBySlug, tagCountBySlug) {
+  return {
+    categories: buildGlobalTaxonomyItems(previewData.site, 'categories', previewData.content.categories, categoryCountBySlug),
+    tags: buildGlobalTaxonomyItems(previewData.site, 'tags', previewData.content.tags, tagCountBySlug),
+  };
+}
+
+function buildGlobalTaxonomyItems(site, permalinkKind, items, countBySlug) {
+  return items.map((item) => ({
+    name: item.name,
+    slug: item.slug,
+    url: resolvePermalink(site, permalinkKind, item).url,
+    count: countBySlug.get(item.slug) || 0,
+    description: typeof item.description === 'string' ? item.description : '',
+  }));
+}
+
 function resolveWidgetAreas(previewData, renderData) {
   if (!previewData.widgets || typeof previewData.widgets !== 'object') {
     return {};
@@ -521,7 +601,7 @@ function resolveCategoriesWidget(baseWidget, settings, previewData) {
     .map((category) => ({
       name: category.name,
       slug: category.slug,
-      url: `/categories/${encodeSlugSegment(category.slug)}/`,
+      url: resolvePermalink(previewData.site, 'categories', category).url,
       count: countBySlug.get(category.slug) || 0,
       depth: 0,
     }))
@@ -546,7 +626,7 @@ function resolveTagsWidget(baseWidget, settings, previewData) {
     .map((tag) => ({
       name: tag.name,
       slug: tag.slug,
-      url: `/tags/${encodeSlugSegment(tag.slug)}/`,
+      url: resolvePermalink(previewData.site, 'tags', tag).url,
       count: countBySlug.get(tag.slug) || 0,
     }))
     .filter((tag) => tag.count > 0)
@@ -569,7 +649,7 @@ function resolveArchivesWidget(baseWidget, settings, previewData) {
     .slice(0, limit)
     .map((entry) => ({
       label: entry.label,
-      url: '/archive/',
+      url: routePathToPublicUrl('/archive/', previewData.site.permalinks.output_style),
       count: entry.count,
       year: entry.year,
       month: entry.month,
@@ -657,27 +737,32 @@ function resolveProfileWidget(baseWidget, settings) {
   };
 }
 
-function preparePage(page) {
+function preparePage(page, site) {
   const documentType = normalizeDocumentType(page.document_type);
+  const renderedDocument = renderDocument(page.content, documentType);
+  const permalink = resolvePagePermalink(site, page);
 
   return {
     ...page,
+    url: permalink.url,
     document_type: documentType,
-    html: renderDocumentContent(page.content, documentType),
+    html: renderedDocument.html,
+    toc: renderedDocument.toc,
   };
 }
 
 function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug, themeSupportsComments) {
   const documentType = normalizeDocumentType(post.document_type);
-  const html = renderDocumentContent(post.content, documentType);
+  const renderedDocument = renderDocument(post.content, documentType);
   const author = authorsById.get(post.author_id);
+  const permalink = resolvePermalink(site, 'posts', post);
   const categories = post.category_slugs
     .map((slug) => categoriesBySlug.get(slug))
     .filter(Boolean)
     .map((category) => ({
       name: category.name,
       slug: category.slug,
-      url: `/categories/${encodeSlugSegment(category.slug)}/`,
+      url: resolvePermalink(site, 'categories', category).url,
     }));
   const tags = post.tag_slugs
     .map((slug) => tagsBySlug.get(slug))
@@ -685,14 +770,14 @@ function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug, them
     .map((tag) => ({
       name: tag.name,
       slug: tag.slug,
-      url: `/tags/${encodeSlugSegment(tag.slug)}/`,
+      url: resolvePermalink(site, 'tags', tag).url,
     }));
 
   return {
     public_id: post.public_id,
     title: post.title,
     slug: post.slug,
-    url: `/posts/${encodeSlugSegment(post.slug)}/`,
+    url: permalink.url,
     content: post.content,
     document_type: documentType,
     excerpt: post.excerpt,
@@ -700,6 +785,7 @@ function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug, them
     updated_at_iso: post.updated_at_iso,
     author_id: post.author_id,
     featured_image: post.featured_image,
+    meta: post.meta,
     status: post.status,
     allow_comments: post.allow_comments,
     category_slugs: post.category_slugs,
@@ -711,10 +797,11 @@ function preparePost(post, site, authorsById, categoriesBySlug, tagsBySlug, them
     },
     categories,
     tags,
-    html,
+    html: renderedDocument.html,
+    toc: renderedDocument.toc,
     published_at: formatTimestamp(post.published_at_iso, site),
     updated_at: formatTimestamp(post.updated_at_iso, site),
-    reading_time: calculateReadingTime(html),
+    reading_time: calculateReadingTime(renderedDocument.html),
     comments_enabled: themeSupportsComments && site.disallowComments !== true && post.allow_comments === true,
   };
 }
@@ -744,6 +831,7 @@ function buildTaxonomyRoutes(options) {
       items: matchedPosts,
       postsPerPage: options.postsPerPage,
       basePath: options.buildBasePath(item),
+      outputStyle: options.outputStyle,
     });
 
     for (const entry of paginated) {
@@ -764,6 +852,7 @@ function buildTaxonomyRoutes(options) {
 
 function buildPaginatedCollection(options) {
   const basePath = normalizePaginationBasePath(options.basePath);
+  const outputStyle = PERMALINK_OUTPUT_STYLES.has(options.outputStyle) ? options.outputStyle : DEFAULT_PERMALINKS.output_style;
   const postsPerPage = Number.isInteger(options.postsPerPage) && options.postsPerPage > 0 ? options.postsPerPage : DEFAULT_POSTS_PER_PAGE;
   const totalPosts = options.items.length;
   const totalPages = Math.max(1, Math.ceil(totalPosts / postsPerPage));
@@ -778,7 +867,7 @@ function buildPaginatedCollection(options) {
       page,
       totalPages,
       items: options.items.slice(start, end),
-      paginationData: buildPaginationData(page, totalPages, totalPosts, basePath),
+      paginationData: buildPaginationData(page, totalPages, totalPosts, basePath, outputStyle),
     });
   }
 
@@ -811,20 +900,22 @@ function normalizePaginationBasePath(basePath) {
   return `/${normalized}/`;
 }
 
-function buildPaginationData(currentPage, totalPages, totalPosts, basePath) {
+function buildPaginationData(currentPage, totalPages, totalPosts, basePath, outputStyle = DEFAULT_PERMALINKS.output_style) {
+  const buildPageUrl = (page) => routePathToPublicUrl(buildPaginatedPath(basePath, page), outputStyle);
+
   return {
     currentPage,
     totalPages,
     totalPosts,
     hasNext: currentPage < totalPages,
     hasPrev: currentPage > 1,
-    nextUrl: currentPage < totalPages ? buildPaginatedPath(basePath, currentPage + 1) : undefined,
-    prevUrl: currentPage > 1 ? buildPaginatedPath(basePath, currentPage - 1) : undefined,
+    nextUrl: currentPage < totalPages ? buildPageUrl(currentPage + 1) : undefined,
+    prevUrl: currentPage > 1 ? buildPageUrl(currentPage - 1) : undefined,
     pages: Array.from({ length: totalPages }, (_, index) => {
       const page = index + 1;
       return {
         number: page,
-        url: buildPaginatedPath(basePath, page),
+        url: buildPageUrl(page),
         current: page === currentPage,
       };
     }),
@@ -1105,6 +1196,10 @@ function normalizeOptionalString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : '';
 }
 
+function normalizeOptionalRawString(value) {
+  return typeof value === 'string' && value.trim() ? value : '';
+}
+
 function normalizeLocale(value) {
   if (typeof value !== 'string' || !value.trim()) {
     return DEFAULT_LOCALE;
@@ -1433,14 +1528,28 @@ async function writeOutput(writer, summaries, path, content, contentType) {
   });
 }
 
-function routePathToOutputPath(routePath) {
+function routePathToOutputPath(routePath, outputStyle = DEFAULT_PERMALINKS.output_style) {
   const normalizedPath = normalizeRoutePath(routePath);
   if (normalizedPath === '/') {
     return 'index.html';
   }
+  if (outputStyle === 'html-extension') {
+    return `${normalizedPath.replace(/^\/+|\/+$/g, '')}.html`;
+  }
   return `${normalizedPath.replace(/^\//, '')}index.html`;
 }
 
+function routePathToPublicUrl(routePath, outputStyle = DEFAULT_PERMALINKS.output_style) {
+  const normalizedPath = normalizeRoutePath(routePath);
+  if (normalizedPath === '/') {
+    return '/';
+  }
+  if (outputStyle === 'html-extension') {
+    return normalizedPath.replace(/\/$/, '');
+  }
+  return normalizedPath;
+}
+
 function normalizeRoutePath(routePath) {
   if (!routePath || routePath === '/') {
     return '/';
@@ -1449,40 +1558,130 @@ function normalizeRoutePath(routePath) {
   return `/${normalized}/`;
 }
 
+function resolvePagePermalink(site, page) {
+  if (normalizeOptionalString(page.path)) {
+    return buildRouteInfo(page.path, site.permalinks.output_style);
+  }
+  return resolvePermalink(site, 'pages', page);
+}
+
+function resolvePermalink(site, kind, item) {
+  const pattern = normalizeNonEmptyString(site.permalinks?.[kind], DEFAULT_PERMALINKS[kind]);
+  return buildRouteInfo(applyPermalinkPattern(pattern, kind, item, site), site.permalinks.output_style);
+}
+
+function buildRouteInfo(routePath, outputStyle) {
+  const path = normalizeRoutePath(routePath);
+  return {
+    path,
+    url: routePathToPublicUrl(path, outputStyle),
+    outputPath: routePathToOutputPath(path, outputStyle),
+  };
+}
+
+function applyPermalinkPattern(pattern, kind, item, site) {
+  const tokenValues = buildPermalinkTokenValues(kind, item, site);
+  const body = String(pattern || '').replace(/^\/+|\/+$/g, '');
+  const segments = body.split('/').filter(Boolean).map((segment) => {
+    if (segment.startsWith(':')) {
+      return tokenValues[segment.slice(1)] || '';
+    }
+    return segment;
+  });
+  return `/${segments.join('/')}/`;
+}
+
+function buildPermalinkTokenValues(kind, item, site) {
+  const values = {
+    slug: encodeSlugSegment(item.slug),
+  };
+
+  if (kind === 'posts') {
+    const parts = getPermalinkDateParts(item.published_at_iso, site);
+    values.public_id = String(item.public_id);
+    values.year = parts.year;
+    values.month = parts.month;
+    values.day = parts.day;
+  }
+
+  return values;
+}
+
+function getPermalinkDateParts(value, site) {
+  const date = toDate(value);
+  const timeZone = normalizeNonEmptyString(site.timezone, DEFAULT_TIMEZONE);
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).formatToParts(date);
+
+  return {
+    year: parts.find((part) => part.type === 'year')?.value || String(date.getUTCFullYear()),
+    month: parts.find((part) => part.type === 'month')?.value || String(date.getUTCMonth() + 1).padStart(2, '0'),
+    day: parts.find((part) => part.type === 'day')?.value || String(date.getUTCDate()).padStart(2, '0'),
+  };
+}
+
 function normalizeOutputPath(filePath) {
   return String(filePath || '').replace(/^\/+/, '');
 }
 
 function assertPlannedOutputPathsSafe(state) {
+  const outputStyle = state.previewData.site.permalinks.output_style;
   for (const post of state.renderData.posts) {
-    assertSafeSlugDerivedOutputPath(post.slug, `posts/${encodeSlugSegment(post.slug)}/index.html`);
+    assertSafeSlugDerivedOutputPath(post.slug, routePathToOutputPath(post.url, outputStyle));
   }
 
   for (const page of state.renderData.pages) {
-    assertSafeSlugDerivedOutputPath(page.slug, `${encodeSlugSegment(page.slug)}/index.html`);
+    assertSafeSlugDerivedOutputPath(page.slug, routePathToOutputPath(page.url, outputStyle));
   }
 
   for (const category of state.previewData.content.categories) {
-    assertSafeSlugDerivedOutputPath(category.slug, `categories/${encodeSlugSegment(category.slug)}/index.html`);
+    assertSafeSlugDerivedOutputPath(category.slug, resolvePermalink(state.previewData.site, 'categories', category).outputPath);
   }
 
   for (const tag of state.previewData.content.tags) {
-    assertSafeSlugDerivedOutputPath(tag.slug, `tags/${encodeSlugSegment(tag.slug)}/index.html`);
+    assertSafeSlugDerivedOutputPath(tag.slug, resolvePermalink(state.previewData.site, 'tags', tag).outputPath);
   }
 
+  const routeEntries = [
+    ...state.renderData.indexRoutes.map((route) => ({
+      url: routePathToPublicUrl(route.path, outputStyle),
+      outputPath: routePathToOutputPath(route.path, outputStyle),
+    })),
+    ...state.renderData.archiveRoutes.map((route) => ({
+      url: routePathToPublicUrl(route.path, outputStyle),
+      outputPath: routePathToOutputPath(route.path, outputStyle),
+    })),
+    ...state.renderData.categoryRoutes.map((route) => ({
+      url: routePathToPublicUrl(route.path, outputStyle),
+      outputPath: routePathToOutputPath(route.path, outputStyle),
+    })),
+    ...state.renderData.tagRoutes.map((route) => ({
+      url: routePathToPublicUrl(route.path, outputStyle),
+      outputPath: routePathToOutputPath(route.path, outputStyle),
+    })),
+    ...state.renderData.posts.map((post) => ({
+      url: post.url,
+      outputPath: routePathToOutputPath(post.url, outputStyle),
+    })),
+    ...state.renderData.pages.map((page) => ({
+      url: page.url,
+      outputPath: routePathToOutputPath(page.url, outputStyle),
+    })),
+  ];
+  assertUniqueRoutes(routeEntries);
+
   const plannedPaths = [
-    ...state.renderData.indexRoutes.map((route) => routePathToOutputPath(route.path)),
-    ...state.renderData.archiveRoutes.map((route) => routePathToOutputPath(route.path)),
-    ...state.renderData.categoryRoutes.map((route) => routePathToOutputPath(route.path)),
-    ...state.renderData.tagRoutes.map((route) => routePathToOutputPath(route.path)),
-    ...state.renderData.posts.map((post) => `posts/${encodeSlugSegment(post.slug)}/index.html`),
-    ...state.renderData.pages.map((page) => `${encodeSlugSegment(page.slug)}/index.html`),
+    ...routeEntries.map((entry) => entry.outputPath),
     ...state.assetOutputs.map((assetOutput) => assetOutput.path),
     COMMENT_POLICY_OUTPUT_PATH,
   ];
 
   if (state.options.generateSpecialFiles) {
-    plannedPaths.push('404.html', 'robots.txt', 'meta.json');
+    plannedPaths.push('404.html', 'robots.txt');
     if (hasCanonicalSiteUrl(state.previewData.site.url)) {
       plannedPaths.push('sitemap.xml', 'feed.xml');
     }
@@ -1493,6 +1692,34 @@ function assertPlannedOutputPathsSafe(state) {
     const normalizedPath = normalizeOutputPath(rawPath);
     assertSafeRelativeOutputPath(rawPath, normalizedPath);
   }
+
+  assertUniqueOutputPaths(plannedPaths);
+}
+
+function assertUniqueRoutes(routeEntries) {
+  const seenUrls = new Map();
+  for (const entry of routeEntries) {
+    const normalizedUrl = normalizeRouteCollisionKey(entry.url);
+    if (seenUrls.has(normalizedUrl)) {
+      throw new Error(`Duplicate public URL detected: ${entry.url}`);
+    }
+    seenUrls.set(normalizedUrl, entry);
+  }
+}
+
+function assertUniqueOutputPaths(plannedPaths) {
+  const seenPaths = new Set();
+  for (const plannedPath of plannedPaths) {
+    const normalizedPath = normalizeOutputPath(plannedPath);
+    if (seenPaths.has(normalizedPath)) {
+      throw new Error(`Duplicate output path detected: ${plannedPath}`);
+    }
+    seenPaths.add(normalizedPath);
+  }
+}
+
+function normalizeRouteCollisionKey(url) {
+  return String(url || '').replace(/\/+$/, '') || '/';
 }
 
 function assertSafeSlugDerivedOutputPath(rawSlug, outputPath) {
@@ -1553,6 +1780,12 @@ function sha256(content) {
   return hash.digest('hex');
 }
 
+function injectSiteCustomizations(html, state) {
+  let next = injectCustomCssAssetLink(html, state.customCssHref);
+  next = injectCustomHtml(next, state.customHtml);
+  return next;
+}
+
 function injectCustomCssAssetLink(html, href) {
   if (!normalizeOptionalString(href)) {
     return html;
@@ -1561,6 +1794,21 @@ function injectCustomCssAssetLink(html, href) {
   return html.replace('</head>', `  <link rel="stylesheet" href="${escapeHtml(href)}">\n</head>`);
 }
 
+function injectCustomHtml(html, customHtml) {
+  let next = html;
+  const headEnd = normalizeOptionalRawString(customHtml?.head_end?.content);
+  const bodyEnd = normalizeOptionalRawString(customHtml?.body_end?.content);
+
+  if (headEnd) {
+    next = next.replace('</head>', `${headEnd}\n</head>`);
+  }
+  if (bodyEnd) {
+    next = next.replace('</body>', `${bodyEnd}\n</body>`);
+  }
+
+  return next;
+}
+
 function buildSitemapXml(site, emitted, generatedAt) {
   const entries = [
     ...emitted.indexRoutes
@@ -1617,38 +1865,6 @@ function buildRobotsTxt(site) {
   return `${lines.join('\n')}\n`;
 }
 
-function buildMetaJson(site, emitted, generatedAt) {
-  const pages = [
-    ...emitted.posts.map((post) => ({
-      url: post.url,
-      title: post.title,
-      description: post.description,
-      publishedAt: post.publishedAt,
-      updatedAt: post.updatedAt,
-      type: 'post',
-      metadata: { status: post.status },
-    })),
-    ...emitted.pages.map((page) => ({
-      url: page.url,
-      title: page.title,
-      description: page.description,
-      type: 'page',
-      metadata: { status: page.status },
-    })),
-  ];
-
-  return JSON.stringify({
-    generated: formatUtcIsoSeconds(generatedAt),
-    site: {
-      title: site.title,
-      description: site.description,
-      url: site.url,
-      locale: site.locale,
-    },
-    pages,
-  }, null, 2);
-}
-
 function getContentType(assetPath) {
   const ext = assetPath.split('.').pop()?.toLowerCase();
   const contentTypes = {

package/src/render/content-renderer.js

@@ -2,46 +2,84 @@ import MarkdownIt from 'markdown-it';
 import hljs from 'highlight.js';
 import anchor from 'markdown-it-anchor';
 
-const markdown = new MarkdownIt({
-  html: true,
-  linkify: true,
-  typographer: true,
-  breaks: true,
-  highlight(value, language) {
-    if (language && hljs.getLanguage(language)) {
-      try {
-        return hljs.highlight(value, { language }).value;
-      } catch {
-        return value;
-      }
-    }
-
-    try {
-      return hljs.highlightAuto(value).value;
-    } catch {
-      return value;
-    }
-  },
-});
-
-markdown.use(anchor, {
-  permalink: anchor.permalink.headerLink(),
-  slugify: slugify,
-});
+const TOC_LEVELS = new Set([2, 3, 4]);
 
 export function renderDocumentContent(content, documentType = 'markdown') {
+  return renderDocument(content, documentType).html;
+}
+
+export function renderDocument(content, documentType = 'markdown') {
   const normalizedContent = typeof content === 'string' ? content : '';
   const normalizedType = normalizeDocumentType(documentType);
 
   if (normalizedType === 'plaintext') {
-    return transformPlaintext(normalizedContent);
+    return {
+      html: transformPlaintext(normalizedContent),
+      toc: [],
+    };
   }
 
   if (normalizedType === 'html') {
-    return sanitizeHtml(normalizedContent);
+    return {
+      html: sanitizeHtml(normalizedContent),
+      toc: [],
+    };
   }
 
-  return sanitizeHtml(markdown.render(normalizedContent));
+  return renderMarkdownDocument(normalizedContent);
+}
+
+function renderMarkdownDocument(content) {
+  const toc = [];
+  const markdown = createMarkdownRenderer(toc);
+
+  return {
+    html: sanitizeHtml(markdown.render(content)),
+    toc,
+  };
+}
+
+function createMarkdownRenderer(toc) {
+  const markdown = new MarkdownIt({
+    html: true,
+    linkify: true,
+    typographer: true,
+    breaks: true,
+    highlight(value, language) {
+      if (language && hljs.getLanguage(language)) {
+        try {
+          return hljs.highlight(value, { language }).value;
+        } catch {
+          return value;
+        }
+      }
+
+      try {
+        return hljs.highlightAuto(value).value;
+      } catch {
+        return value;
+      }
+    },
+  });
+
+  markdown.use(anchor, {
+    slugify: slugify,
+    callback(token, { slug, title }) {
+      const level = Number(token.tag.slice(1));
+      if (!TOC_LEVELS.has(level)) {
+        return;
+      }
+
+      toc.push({
+        level,
+        id: slug,
+        title,
+        href: `#${slug}`,
+      });
+    },
+  });
+
+  return markdown;
 }
 
 function normalizeDocumentType(value) {

package/src/render/control-flow-renderer.js

@@ -1,8 +1,9 @@
 import { parsePartialToken } from './partial-resolver.js';
 
-const PATH_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*$/;
-const FOR_EXPRESSION_REGEX = /^([a-zA-Z_][a-zA-Z0-9_]*)\s+in\s+([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)$/;
-const IF_EQ_EXPRESSION_REGEX = /^([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)\s+("(?:[^"\\]|\\.)*")$/;
+const PATH_SEGMENT_SOURCE = '[a-zA-Z_][a-zA-Z0-9_]*(?:-[a-zA-Z0-9_]+)*';
+const PATH_REGEX = new RegExp(`^${PATH_SEGMENT_SOURCE}(?:\\.${PATH_SEGMENT_SOURCE})*$`);
+const FOR_EXPRESSION_REGEX = new RegExp(`^([a-zA-Z_][a-zA-Z0-9_]*)\\s+in\\s+(${PATH_SEGMENT_SOURCE}(?:\\.${PATH_SEGMENT_SOURCE})*)$`);
+const IF_EQ_EXPRESSION_REGEX = new RegExp(`^(${PATH_SEGMENT_SOURCE}(?:\\.${PATH_SEGMENT_SOURCE})*)\\s+("(?:[^"\\\\]|\\\\.)*")$`);
 
 export class ControlFlowRenderer {
   constructor(options = {}) {

package/src/render/variable-resolver.js

@@ -1,7 +1,7 @@
 export class VariableResolver {
   static MENU_PATTERN = /\{\{menu:([a-z][a-z0-9_-]{0,63})\}\}/g;
-  static VARIABLE_PATTERN = /\{\{([a-zA-Z_][a-zA-Z0-9_]*(?:\.[a-zA-Z_][a-zA-Z0-9_]*)+)\}\}/g;
-  static STANDALONE_PATTERN = /\{\{([a-zA-Z_][a-zA-Z0-9_]*)\}\}/g;
+  static VARIABLE_PATTERN = /\{\{([a-zA-Z_][a-zA-Z0-9_]*(?:-[a-zA-Z0-9_]+)*(?:\.[a-zA-Z_][a-zA-Z0-9_]*(?:-[a-zA-Z0-9_]+)*)+)\}\}/g;
+  static STANDALONE_PATTERN = /\{\{([a-zA-Z_][a-zA-Z0-9_]*(?:-[a-zA-Z0-9_]+)*)\}\}/g;
 
   resolve(template, data, options = {}) {
     let result = template.replace(VariableResolver.MENU_PATTERN, (_, menuId) => {