@zeropress/build-core 0.2.2 → 0.5.1

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.2",
+  "version": "0.5.1",
   "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.5",
-    "@zeropress/theme-validator": "^0.5.0",
+    "@zeropress/preview-data-validator": "0.5.1",
+    "@zeropress/theme-validator": "0.5.2",
     "highlight.js": "^11.11.1",
     "markdown-it": "^14.1.0",
     "markdown-it-anchor": "^9.2.0"

package/src/api/build-site.js

@@ -24,6 +24,14 @@ const DEFAULT_PERMALINKS = Object.freeze({
   categories: '/categories/:slug/',
   tags: '/tags/:slug/',
 });
+const DEFAULT_FRONT_PAGE = Object.freeze({
+  type: 'theme_index',
+});
+const DEFAULT_POST_INDEX = Object.freeze({
+  enabled: true,
+  path: '/',
+  paginate: true,
+});
 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]/;
@@ -34,6 +42,10 @@ export async function buildSite(input) {
   const state = await createBuildState(input, options);
   assertPlannedOutputPathsSafe(state);
 
+  if (state.renderData.frontPageRoute) {
+    await renderFrontPage(state, state.renderData.frontPageRoute);
+  }
+
   for (const route of state.renderData.indexRoutes) {
     await renderRoute(state, 'index', route);
   }
@@ -83,7 +95,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);
@@ -94,7 +105,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();
@@ -125,10 +136,12 @@ async function createBuildState(input, options) {
     assetOutputs,
     assetMap,
     customCssHref: customCssAsset ? `/${customCssAsset.path}` : '',
+    customHtml: previewData.custom_html,
     commentPolicyContent: buildCommentPolicyManifest(renderData.posts),
     options,
     generatedAt: new Date(),
     emitted: {
+      frontPage: null,
       indexRoutes: [],
       archiveRoutes: [],
       categoryRoutes: [],
@@ -139,6 +152,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) {
@@ -163,12 +188,18 @@ async function finalizeBuildResult(writer, summaries, options) {
 
 async function renderRoute(state, templateName, route) {
   const currentUrl = routePathToPublicUrl(route.path, state.previewData.site.permalinks.output_style);
+  const routeContext = buildRouteContext(route.route_type || templateName, currentUrl, {
+    isFrontPage: route.is_front_page === true,
+    isPostIndex: route.is_post_index === true,
+  });
   let html = await state.engine.render(
     templateName,
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      taxonomies: state.renderData.taxonomies,
       ...route,
+      route: routeContext,
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
         title: state.previewData.site.title,
@@ -179,11 +210,92 @@ async function renderRoute(state, templateName, route) {
     createRenderContext(state.previewData.site, currentUrl),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectCustomCssAssetLink(html, state.customCssHref);
+  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 renderFrontPage(state, route) {
+  const currentUrl = '/';
+  const routeContext = buildRouteContext('front_page', currentUrl, {
+    isFrontPage: true,
+    isPostIndex: false,
+  });
+
+  if (route.front_page_type === 'standalone_html') {
+    await writeOutput(state.writer, state.summaries, 'index.html', route.html, 'text/html');
+    state.emitted.frontPage = {
+      url: currentUrl,
+      title: state.previewData.site.title,
+      description: state.previewData.site.description,
+      includeInFeed: false,
+    };
+    return;
+  }
+
+  if (route.front_page_type === 'page') {
+    const page = {
+      ...route.page,
+      url: currentUrl,
+    };
+    let html = await state.engine.render(
+      'page',
+      {
+        menus: state.previewData.menus,
+        widgets: state.widgets,
+        taxonomies: state.renderData.taxonomies,
+        page,
+        route: routeContext,
+        meta: buildPageMeta(state.previewData.site, {
+          currentUrl,
+          title: buildDocumentTitle(page.title, state.previewData.site.title),
+          description: page.excerpt,
+          ogType: 'website',
+          image: page.featured_image,
+        }),
+      },
+      createRenderContext(state.previewData.site, currentUrl),
+    );
+    html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
+    html = injectSiteCustomizations(html, state);
+    await writeOutput(state.writer, state.summaries, 'index.html', html, 'text/html');
+    state.emitted.frontPage = {
+      url: currentUrl,
+      title: page.title,
+      description: page.excerpt,
+      includeInFeed: false,
+    };
+    return;
+  }
+
+  let html = await state.engine.render(
+    'index',
+    {
+      menus: state.previewData.menus,
+      widgets: state.widgets,
+      taxonomies: state.renderData.taxonomies,
+      ...route,
+      route: routeContext,
+      meta: buildPageMeta(state.previewData.site, {
+        currentUrl,
+        title: state.previewData.site.title,
+        description: state.previewData.site.description,
+        ogType: 'website',
+      }),
+    },
+    createRenderContext(state.previewData.site, currentUrl),
+  );
+  html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
+  html = injectSiteCustomizations(html, state);
+  await writeOutput(state.writer, state.summaries, 'index.html', html, 'text/html');
+  state.emitted.frontPage = {
+    url: currentUrl,
+    title: state.previewData.site.title,
+    description: state.previewData.site.description,
+    includeInFeed: false,
+  };
+}
+
 async function renderPost(state, post) {
   const currentUrl = post.url;
   let html = await state.engine.render(
@@ -191,7 +303,9 @@ async function renderPost(state, post) {
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      taxonomies: state.renderData.taxonomies,
       post,
+      route: buildRouteContext('post', currentUrl),
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
         title: buildDocumentTitle(post.title, state.previewData.site.title),
@@ -205,7 +319,7 @@ async function renderPost(state, post) {
     createRenderContext(state.previewData.site, currentUrl),
   );
   html = state.assetProcessor.updateAssetReferences(html, state.assetMap);
-  html = injectCustomCssAssetLink(html, state.customCssHref);
+  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,
@@ -219,14 +333,19 @@ async function renderPost(state, post) {
 
 async function renderPage(state, page) {
   const currentUrl = page.url;
+  const outputPath = pageToOutputPath(page, state.previewData.site.permalinks.output_style);
+  const canonicalUrl = normalizeOptionalString(page.canonical_url) || currentUrl;
   let html = await state.engine.render(
     'page',
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      taxonomies: state.renderData.taxonomies,
       page,
+      route: buildRouteContext('page', currentUrl),
       meta: buildPageMeta(state.previewData.site, {
         currentUrl,
+        canonicalUrl,
         title: buildDocumentTitle(page.title, state.previewData.site.title),
         description: page.excerpt,
         ogType: 'website',
@@ -236,13 +355,14 @@ 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, routePathToOutputPath(page.url, state.previewData.site.permalinks.output_style), html, 'text/html');
+  html = injectSiteCustomizations(html, state);
+  await writeOutput(state.writer, state.summaries, outputPath, html, 'text/html');
   state.emitted.pages.push({
     url: currentUrl,
     title: page.title,
     description: page.excerpt,
     status: page.status,
+    includeInSitemap: page.omit_from_sitemap !== true,
   });
 }
 
@@ -256,6 +376,8 @@ async function maybeRenderNotFoundPage(state) {
     {
       menus: state.previewData.menus,
       widgets: state.widgets,
+      taxonomies: state.renderData.taxonomies,
+      route: buildRouteContext('not_found', '/404.html'),
       meta: buildPageMeta(state.previewData.site, {
         currentUrl: '/404.html',
         title: state.previewData.site.title,
@@ -266,7 +388,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');
 }
 
@@ -283,6 +405,9 @@ function normalizePreviewData(previewData) {
     locale: normalizeLocale(previewData.site.locale || DEFAULT_LOCALE),
     disallowComments: previewData.site.disallowComments === true,
     permalinks: normalizePermalinks(previewData.site.permalinks),
+    front_page: normalizeFrontPage(previewData.site.front_page),
+    post_index: normalizePostIndex(previewData.site.post_index),
+    footer: normalizeSiteFooter(previewData.site.footer),
   };
 
   return {
@@ -290,6 +415,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) => ({
@@ -333,6 +459,22 @@ function normalizeWidgetAreas(widgetAreas, mediaBaseUrl) {
   );
 }
 
+function normalizeSiteFooter(footer) {
+  const source = footer && typeof footer === 'object' && !Array.isArray(footer) ? footer : {};
+  const attribution = source.attribution && typeof source.attribution === 'object' && !Array.isArray(source.attribution)
+    ? source.attribution
+    : {};
+
+  return {
+    ...source,
+    copyright_text: normalizeOptionalString(source.copyright_text),
+    attribution: {
+      ...attribution,
+      enabled: attribution.enabled !== false,
+    },
+  };
+}
+
 function normalizeWidgetItem(item, mediaBaseUrl) {
   const normalizedItem = {
     ...item,
@@ -357,6 +499,23 @@ 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)
@@ -372,8 +531,37 @@ function normalizePermalinks(permalinks) {
   };
 }
 
+function normalizeFrontPage(frontPage) {
+  if (!frontPage || typeof frontPage !== 'object') {
+    return { ...DEFAULT_FRONT_PAGE };
+  }
+
+  const type = ['theme_index', 'page', 'standalone_html'].includes(frontPage.type)
+    ? frontPage.type
+    : DEFAULT_FRONT_PAGE.type;
+
+  return {
+    type,
+    ...(type === 'page' ? { page_slug: normalizeOptionalString(frontPage.page_slug) } : {}),
+    ...(type === 'standalone_html' ? { html: normalizeOptionalRawString(frontPage.html) } : {}),
+  };
+}
+
+function normalizePostIndex(postIndex) {
+  if (!postIndex || typeof postIndex !== 'object') {
+    return { ...DEFAULT_POST_INDEX };
+  }
+
+  return {
+    enabled: postIndex.enabled !== false,
+    path: normalizeNonEmptyString(postIndex.path, DEFAULT_POST_INDEX.path),
+    paginate: postIndex.paginate !== false,
+  };
+}
+
 function createRenderData(previewData, themeMetadata = {}) {
   const themeSupportsComments = themeMetadata?.features?.comments === true;
+  const themeSupportsPostIndex = themeMetadata?.features?.postIndex !== false;
   const authorsById = new Map(previewData.content.authors.map((author) => [author.id, author]));
   const categoriesBySlug = new Map(previewData.content.categories.map((category) => [category.slug, category]));
   const tagsBySlug = new Map(previewData.content.tags.map((tag) => [tag.slug, tag]));
@@ -402,23 +590,38 @@ function createRenderData(previewData, themeMetadata = {}) {
   }));
   const pages = previewData.content.pages.map((page) => preparePage(page, previewData.site));
   const postBySlug = new Map(posts.map((post) => [post.slug, post]));
+  const frontPage = previewData.site.front_page;
+  const postIndex = previewData.site.post_index;
+  const effectivePostIndexEnabled = postIndex.enabled !== false && themeSupportsPostIndex;
+  const effectivePostIndexPaginate = effectivePostIndexEnabled && postIndex.paginate !== false;
+  const postIndexBasePath = normalizeRoutePath(postIndex.path || DEFAULT_POST_INDEX.path);
+
+  if (frontPage.type !== 'theme_index' && effectivePostIndexEnabled && postIndexBasePath === '/') {
+    throw new Error('Invalid front page configuration: site.front_page occupies "/" so site.post_index.path must not be "/". Set site.post_index.path to a non-root path or disable site.post_index.');
+  }
+
+  const frontPageRoute = buildFrontPageRoute(frontPage, pages, effectivePostIndexEnabled, postIndexBasePath);
+  const pageFrontPageSlug = frontPage.type === 'page' ? frontPage.page_slug : '';
+  const preparedPages = pageFrontPageSlug
+    ? pages.filter((page) => page.slug !== pageFrontPageSlug)
+    : pages;
 
   return {
     posts,
-    pages,
+    pages: preparedPages,
     postBySlug,
-    indexRoutes: buildPaginatedCollection({
+    taxonomies: buildGlobalTaxonomies(previewData, categoryCountBySlug, tagCountBySlug),
+    frontPageRoute,
+    indexRoutes: buildPostIndexRoutes({
+      enabled: effectivePostIndexEnabled,
+      paginate: effectivePostIndexPaginate,
       items: previewData.content.posts,
       postsPerPage: previewData.site.postsPerPage,
-      basePath: '/',
+      basePath: postIndexBasePath,
       outputStyle: previewData.site.permalinks.output_style,
-    }).map((entry) => ({
-      path: entry.path,
-      page: entry.page,
-      totalPages: entry.totalPages,
-      posts: buildStructuredPostCollection(entry.items, postBySlug),
-      pagination: buildStructuredPagination(entry.paginationData),
-    })),
+      postBySlug,
+      frontPage,
+    }),
     archiveRoutes: buildPaginatedCollection({
       items: previewData.content.posts,
       postsPerPage: previewData.site.postsPerPage,
@@ -458,6 +661,101 @@ 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 buildFrontPageRoute(frontPage, pages, effectivePostIndexEnabled, postIndexBasePath) {
+  if (frontPage.type === 'theme_index') {
+    if (effectivePostIndexEnabled && postIndexBasePath === '/') {
+      return null;
+    }
+
+    return {
+      path: '/',
+      front_page_type: 'theme_index',
+      posts: buildStructuredPostCollection([], new Map()),
+      pagination: buildStructuredPagination(buildDisabledPaginationData(0)),
+    };
+  }
+
+  if (frontPage.type === 'page') {
+    const page = pages.find((entry) => entry.slug === frontPage.page_slug);
+    if (!page) {
+      throw new Error(`Invalid front page configuration: site.front_page.page_slug "${frontPage.page_slug}" does not match a page.`);
+    }
+
+    return {
+      path: '/',
+      front_page_type: 'page',
+      page,
+    };
+  }
+
+  if (frontPage.type === 'standalone_html') {
+    if (!normalizeOptionalRawString(frontPage.html)) {
+      throw new Error('Invalid front page configuration: site.front_page.html is required for standalone_html.');
+    }
+
+    return {
+      path: '/',
+      front_page_type: 'standalone_html',
+      html: frontPage.html,
+    };
+  }
+
+  return null;
+}
+
+function buildPostIndexRoutes(options) {
+  if (!options.enabled) {
+    return [];
+  }
+
+  if (!options.paginate) {
+    const items = options.items.slice(0, options.postsPerPage);
+    return [{
+      path: options.basePath,
+      route_type: 'post_index',
+      is_front_page: options.basePath === '/' && options.frontPage.type === 'theme_index',
+      is_post_index: true,
+      page: 1,
+      totalPages: 1,
+      posts: buildStructuredPostCollection(items, options.postBySlug),
+      pagination: buildStructuredPagination(buildDisabledPaginationData(options.items.length)),
+    }];
+  }
+
+  return buildPaginatedCollection({
+    items: options.items,
+    postsPerPage: options.postsPerPage,
+    basePath: options.basePath,
+    outputStyle: options.outputStyle,
+  }).map((entry) => ({
+    path: entry.path,
+    route_type: 'post_index',
+    is_front_page: entry.path === '/' && options.frontPage.type === 'theme_index',
+    is_post_index: true,
+    page: entry.page,
+    totalPages: entry.totalPages,
+    posts: buildStructuredPostCollection(entry.items, options.postBySlug),
+    pagination: buildStructuredPagination(entry.paginationData),
+  }));
+}
+
+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 {};
@@ -852,6 +1150,7 @@ function buildPaginationData(currentPage, totalPages, totalPosts, basePath, outp
   const buildPageUrl = (page) => routePathToPublicUrl(buildPaginatedPath(basePath, page), outputStyle);
 
   return {
+    enabled: true,
     currentPage,
     totalPages,
     totalPosts,
@@ -870,8 +1169,23 @@ function buildPaginationData(currentPage, totalPages, totalPosts, basePath, outp
   };
 }
 
+function buildDisabledPaginationData(totalPosts) {
+  return {
+    enabled: false,
+    currentPage: 1,
+    totalPages: 1,
+    totalPosts,
+    hasNext: false,
+    hasPrev: false,
+    nextUrl: undefined,
+    prevUrl: undefined,
+    pages: [],
+  };
+}
+
 function buildStructuredPagination(paginationData) {
   return {
+    enabled: paginationData.enabled !== false,
     current_page: paginationData.currentPage,
     total_pages: paginationData.totalPages,
     total_items: paginationData.totalPosts,
@@ -1144,6 +1458,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;
@@ -1311,10 +1629,20 @@ function createRenderContext(site, currentUrl) {
   };
 }
 
+function buildRouteContext(type, url, options = {}) {
+  return {
+    type,
+    is_front_page: options.isFrontPage === true,
+    is_post_index: options.isPostIndex === true,
+    path: url,
+    url,
+  };
+}
+
 function buildPageMeta(site, options = {}) {
   const resolvedTitle = normalizeNonEmptyString(options.title, site.title);
   const resolvedDescription = normalizeOptionalString(options.description);
-  const canonicalUrl = resolveMetaCanonicalUrl(site, options.currentUrl);
+  const canonicalUrl = resolveMetaCanonicalUrl(site, options.canonicalUrl || options.currentUrl);
   const ogImage = resolveMetaImageUrl(options.image);
   const ogType = normalizeNonEmptyString(options.ogType, 'website');
   const publishedTime = normalizeOptionalString(options.publishedTime);
@@ -1494,6 +1822,22 @@ function routePathToPublicUrl(routePath, outputStyle = DEFAULT_PERMALINKS.output
   return normalizedPath;
 }
 
+function pagePathToPublicUrl(routePath, outputStyle = DEFAULT_PERMALINKS.output_style) {
+  const normalizedPath = normalizeRoutePath(routePath);
+  if (outputStyle !== 'html-extension') {
+    return routePathToPublicUrl(normalizedPath, outputStyle);
+  }
+
+  const withoutTrailingSlash = normalizedPath.replace(/\/$/, '');
+  if (withoutTrailingSlash === '/index') {
+    return '/';
+  }
+  if (withoutTrailingSlash.endsWith('/index')) {
+    return `${withoutTrailingSlash.slice(0, -'/index'.length)}/`;
+  }
+  return withoutTrailingSlash;
+}
+
 function normalizeRoutePath(routePath) {
   if (!routePath || routePath === '/') {
     return '/';
@@ -1504,7 +1848,7 @@ function normalizeRoutePath(routePath) {
 
 function resolvePagePermalink(site, page) {
   if (normalizeOptionalString(page.path)) {
-    return buildRouteInfo(page.path, site.permalinks.output_style);
+    return buildRouteInfo(page.path, site.permalinks.output_style, { pagePath: true });
   }
   return resolvePermalink(site, 'pages', page);
 }
@@ -1514,15 +1858,21 @@ function resolvePermalink(site, kind, item) {
   return buildRouteInfo(applyPermalinkPattern(pattern, kind, item, site), site.permalinks.output_style);
 }
 
-function buildRouteInfo(routePath, outputStyle) {
+function buildRouteInfo(routePath, outputStyle, options = {}) {
   const path = normalizeRoutePath(routePath);
   return {
     path,
-    url: routePathToPublicUrl(path, outputStyle),
+    url: options.pagePath ? pagePathToPublicUrl(path, outputStyle) : routePathToPublicUrl(path, outputStyle),
     outputPath: routePathToOutputPath(path, outputStyle),
   };
 }
 
+function pageToOutputPath(page, outputStyle) {
+  return normalizeOptionalString(page.path)
+    ? routePathToOutputPath(page.path, outputStyle)
+    : routePathToOutputPath(page.url, outputStyle);
+}
+
 function applyPermalinkPattern(pattern, kind, item, site) {
   const tokenValues = buildPermalinkTokenValues(kind, item, site);
   const body = String(pattern || '').replace(/^\/+|\/+$/g, '');
@@ -1579,7 +1929,7 @@ function assertPlannedOutputPathsSafe(state) {
   }
 
   for (const page of state.renderData.pages) {
-    assertSafeSlugDerivedOutputPath(page.slug, routePathToOutputPath(page.url, outputStyle));
+    assertSafeSlugDerivedOutputPath(page.slug, pageToOutputPath(page, outputStyle));
   }
 
   for (const category of state.previewData.content.categories) {
@@ -1591,6 +1941,10 @@ function assertPlannedOutputPathsSafe(state) {
   }
 
   const routeEntries = [
+    ...(state.renderData.frontPageRoute ? [{
+      url: '/',
+      outputPath: 'index.html',
+    }] : []),
     ...state.renderData.indexRoutes.map((route) => ({
       url: routePathToPublicUrl(route.path, outputStyle),
       outputPath: routePathToOutputPath(route.path, outputStyle),
@@ -1613,7 +1967,7 @@ function assertPlannedOutputPathsSafe(state) {
     })),
     ...state.renderData.pages.map((page) => ({
       url: page.url,
-      outputPath: routePathToOutputPath(page.url, outputStyle),
+      outputPath: pageToOutputPath(page, outputStyle),
     })),
   ];
   assertUniqueRoutes(routeEntries);
@@ -1625,7 +1979,7 @@ function assertPlannedOutputPathsSafe(state) {
   ];
 
   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');
     }
@@ -1724,6 +2078,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;
@@ -1732,14 +2092,36 @@ 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.frontPage
+      ? [{
+        url: emitted.frontPage.url,
+        changefreq: 'daily',
+        priority: 1.0,
+      }]
+      : []),
     ...emitted.indexRoutes
-      .filter((route) => route.url === '/')
+      .filter((route) => route.page === 1)
       .map((route) => ({
         url: route.url,
         changefreq: 'daily',
-        priority: 1.0,
+        priority: route.url === '/' ? 1.0 : 0.7,
       })),
     ...emitted.posts.map((post) => ({
       url: post.url,
@@ -1747,11 +2129,13 @@ function buildSitemapXml(site, emitted, generatedAt) {
       changefreq: 'weekly',
       priority: 0.8,
     })),
-    ...emitted.pages.map((page) => ({
-      url: page.url,
-      changefreq: 'monthly',
-      priority: 0.7,
-    })),
+    ...emitted.pages
+      .filter((page) => page.includeInSitemap !== false)
+      .map((page) => ({
+        url: page.url,
+        changefreq: 'monthly',
+        priority: 0.7,
+      })),
   ];
 
   const body = entries.map((entry) => {
@@ -1788,38 +2172,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

@@ -3,6 +3,13 @@ import hljs from 'highlight.js';
 import anchor from 'markdown-it-anchor';
 
 const TOC_LEVELS = new Set([2, 3, 4]);
+const ALERT_TYPES = new Map([
+  ['NOTE', { className: 'note', title: 'Note' }],
+  ['TIP', { className: 'tip', title: 'Tip' }],
+  ['IMPORTANT', { className: 'important', title: 'Important' }],
+  ['WARNING', { className: 'warning', title: 'Warning' }],
+  ['CAUTION', { className: 'caution', title: 'Caution' }],
+]);
 
 export function renderDocumentContent(content, documentType = 'markdown') {
   return renderDocument(content, documentType).html;
@@ -62,6 +69,8 @@ function createMarkdownRenderer(toc) {
     },
   });
 
+  markdown.use(markdownTaskLists);
+  markdown.use(markdownAlerts);
   markdown.use(anchor, {
     slugify: slugify,
     callback(token, { slug, title }) {
@@ -82,6 +91,189 @@ function createMarkdownRenderer(toc) {
   return markdown;
 }
 
+function markdownTaskLists(markdown) {
+  markdown.core.ruler.after('inline', 'zeropress_task_lists', (state) => {
+    const listStack = [];
+    const listItemStack = [];
+
+    for (let index = 0; index < state.tokens.length; index += 1) {
+      const token = state.tokens[index];
+
+      if (token.type === 'bullet_list_open' || token.type === 'ordered_list_open') {
+        listStack.push(index);
+        continue;
+      }
+
+      if (token.type === 'bullet_list_close' || token.type === 'ordered_list_close') {
+        listStack.pop();
+        continue;
+      }
+
+      if (token.type === 'list_item_open') {
+        listItemStack.push({
+          index,
+          listIndex: listStack[listStack.length - 1],
+        });
+        continue;
+      }
+
+      if (token.type === 'list_item_close') {
+        listItemStack.pop();
+        continue;
+      }
+
+      if (token.type !== 'inline' || listItemStack.length === 0) {
+        continue;
+      }
+
+      const markerMatch = token.content.match(/^\s*\[([ xX])\](?:\s+|$)/);
+      if (!markerMatch) {
+        continue;
+      }
+
+      const listItem = listItemStack[listItemStack.length - 1];
+      const listToken = state.tokens[listItem.listIndex];
+      const listItemToken = state.tokens[listItem.index];
+      if (!listToken || !listItemToken) {
+        continue;
+      }
+
+      addTokenClass(listToken, 'contains-task-list');
+      addTokenClass(listItemToken, 'task-list-item');
+
+      const checkboxToken = new state.Token('html_inline', '', 0);
+      const checked = markerMatch[1].toLowerCase() === 'x' ? ' checked' : '';
+      checkboxToken.content = `<input class="task-list-item-checkbox" type="checkbox"${checked} disabled> `;
+
+      const strippedContent = token.content.slice(markerMatch[0].length);
+      token.content = strippedContent;
+      token.children = [];
+      state.md.inline.parse(strippedContent, state.md, state.env, token.children);
+      token.children.unshift(checkboxToken);
+    }
+  });
+}
+
+function markdownAlerts(markdown) {
+  markdown.core.ruler.after('inline', 'zeropress_alerts', (state) => {
+    for (let index = 0; index < state.tokens.length; index += 1) {
+      const token = state.tokens[index];
+      if (token.type !== 'blockquote_open') {
+        continue;
+      }
+
+      const closeIndex = findMatchingBlockquoteClose(state.tokens, index);
+      if (closeIndex === -1) {
+        continue;
+      }
+
+      const firstParagraph = findFirstParagraph(state.tokens, index + 1, closeIndex);
+      if (!firstParagraph) {
+        continue;
+      }
+
+      const inlineToken = state.tokens[firstParagraph.inlineIndex];
+      const alert = stripAlertMarker(inlineToken, state);
+      if (!alert) {
+        continue;
+      }
+
+      token.tag = 'aside';
+      token.attrSet('class', `zp-alert zp-alert--${alert.className}`);
+      token.attrSet('role', 'note');
+      state.tokens[closeIndex].tag = 'aside';
+
+      if (inlineToken.content.trim() === '') {
+        state.tokens.splice(firstParagraph.openIndex, 3);
+      }
+
+      state.tokens.splice(index + 1, 0, ...createAlertTitleTokens(state, alert.title));
+      index += 3;
+    }
+  });
+}
+
+function findMatchingBlockquoteClose(tokens, openIndex) {
+  let depth = 0;
+
+  for (let index = openIndex; index < tokens.length; index += 1) {
+    if (tokens[index].type === 'blockquote_open') {
+      depth += 1;
+      continue;
+    }
+
+    if (tokens[index].type === 'blockquote_close') {
+      depth -= 1;
+      if (depth === 0) {
+        return index;
+      }
+    }
+  }
+
+  return -1;
+}
+
+function findFirstParagraph(tokens, startIndex, endIndex) {
+  if (
+    startIndex + 2 < endIndex
+    && tokens[startIndex].type === 'paragraph_open'
+    && tokens[startIndex + 1].type === 'inline'
+    && tokens[startIndex + 2].type === 'paragraph_close'
+  ) {
+    return {
+      openIndex: startIndex,
+      inlineIndex: startIndex + 1,
+      closeIndex: startIndex + 2,
+    };
+  }
+
+  return null;
+}
+
+function stripAlertMarker(inlineToken, state) {
+  const markerMatch = inlineToken.content.match(/^\s*\[!([A-Za-z]+)\][ \t]*(?:\n)?/);
+  if (!markerMatch) {
+    return null;
+  }
+
+  const alertType = ALERT_TYPES.get(markerMatch[1].toUpperCase());
+  if (!alertType) {
+    return null;
+  }
+
+  const strippedContent = inlineToken.content.slice(markerMatch[0].length);
+  inlineToken.content = strippedContent;
+  inlineToken.children = [];
+  state.md.inline.parse(strippedContent, state.md, state.env, inlineToken.children);
+
+  return alertType;
+}
+
+function createAlertTitleTokens(state, title) {
+  const openToken = new state.Token('paragraph_open', 'p', 1);
+  openToken.attrSet('class', 'zp-alert__title');
+
+  const inlineToken = new state.Token('inline', '', 0);
+  inlineToken.content = title;
+  const textToken = new state.Token('text', '', 0);
+  textToken.content = title;
+  inlineToken.children = [textToken];
+
+  const closeToken = new state.Token('paragraph_close', 'p', -1);
+
+  return [openToken, inlineToken, closeToken];
+}
+
+function addTokenClass(token, className) {
+  const existingValue = token.attrGet('class') || '';
+  const existingClasses = existingValue.split(/\s+/).filter(Boolean);
+  if (existingClasses.includes(className)) {
+    return;
+  }
+
+  token.attrJoin('class', className);
+}
+
 function normalizeDocumentType(value) {
   return value === 'plaintext' || value === 'html' ? value : 'markdown';
 }
@@ -113,16 +305,18 @@ function sanitizeHtml(html) {
     'strong', 'em', 'u', 's', 'code', 'pre',
     'a', 'img',
     'ul', 'ol', 'li',
-    'blockquote',
+    'blockquote', 'aside',
     'table', 'thead', 'tbody', 'tr', 'th', 'td',
     'div', 'span', 'nav',
-    'iframe',
+    'iframe', 'input',
   ]);
 
   const allowedAttributes = {
     a: new Set(['href', 'title', 'class', 'id']),
+    aside: new Set(['role', 'class', 'id']),
     img: new Set(['src', 'alt', 'title', 'class', 'id', 'width', 'height']),
     iframe: new Set(['src', 'width', 'height', 'frameborder', 'allowfullscreen', 'class']),
+    input: new Set(['type', 'checked', 'disabled', 'class', 'id']),
     '*': new Set(['class', 'id']),
   };
 
@@ -163,11 +357,15 @@ function sanitizeHtml(html) {
           continue;
         }
 
+        if (normalizedTag === 'input' && attributeName === 'type' && attributeValue !== 'checkbox') {
+          continue;
+        }
+
         filteredAttributes.push(`${attributeName}="${attributeValue}"`);
       }
     }
 
-    const isSelfClosing = match.endsWith('/>') || normalizedTag === 'br' || normalizedTag === 'hr' || normalizedTag === 'img';
+    const isSelfClosing = match.endsWith('/>') || normalizedTag === 'br' || normalizedTag === 'hr' || normalizedTag === 'img' || normalizedTag === 'input';
     const attributeSuffix = filteredAttributes.length > 0 ? ` ${filteredAttributes.join(' ')}` : '';
     return isSelfClosing ? `<${normalizedTag}${attributeSuffix} />` : `<${normalizedTag}${attributeSuffix}>`;
   });

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) => {