@rettangoli/sites 1.0.3 → 1.2.0

package/README.md

@@ -32,11 +32,12 @@ my-site/
 
 - YAML pages rendered through `jempl` + `yahtml`
 - Markdown pages rendered through `markdown-it` + Shiki (default `rtglMarkdown`)
-- Frontmatter (`template`, `tags`, arbitrary page metadata)
+- Frontmatter (`template`, `url`, `tags`, arbitrary page metadata)
 - Global data from `data/*.yaml` and optional inline `sites.config.yaml data`
 - Collections built from page tags
 - `$if`, `$for`, `$partial`, template functions
 - Static file copying from `static/` to `_site/`
+- Default sitemap generation when `data.site.baseUrl` is configured
 - Watch mode with local dev server + websocket reload
 
 ## Site Config
@@ -76,8 +77,20 @@ imports:
   partials:
     docs/nav: https://example.com/partials/docs-nav.yaml
 data:
+  site:
+    baseUrl: https://example.com
   themeCssHref: /public/theme.css
   themeBodyClass: dark
+sitemap:
+  outputPath: sitemap.xml
+  defaults:
+    changefreq: weekly
+    priority: 0.5
+  exclude:
+    - /drafts/*
+  pages:
+    /:
+      priority: 1
 ```
 
 In the default starter template, CDN runtime scripts are controlled via `data/site.yaml`:
@@ -96,6 +109,66 @@ Example mappings:
 - `pages/index.md` -> `_site/index.html` and `_site/index.md`
 - `pages/docs/intro.md` -> `_site/docs/intro/index.html` and `_site/docs/intro.md`
 
+For Markdown pages with a custom `url`, the copied `.md` file follows the custom URL path.
+For example, `url: /guides/start/` writes `_site/guides/start/index.html` and `_site/guides/start.md`.
+
+Pages use their file path as the URL by default:
+- `pages/index.*` -> `/`
+- `pages/about.*` -> `/about/`
+- `pages/docs/intro.*` -> `/docs/intro/`
+
+Set `url` in page frontmatter to override that path:
+
+```md
+---
+title: Company
+url: /company/
+---
+```
+
+`url` is normalized to a site-relative clean URL with a leading and trailing slash, so `company` becomes `/company/`.
+External URLs, query strings, fragments, whitespace, and `.` / `..` path segments are rejected.
+Duplicate page URLs are rejected after normalization.
+
+## Sitemap
+
+Sites writes `_site/sitemap.xml` by default when `data.site.baseUrl` is configured. Use `sitemap` in `sites.config.yaml` to customize output, or set `sitemap: false` to disable it.
+
+```yaml
+data:
+  site:
+    baseUrl: https://example.com
+sitemap:
+  outputPath: sitemap.xml
+  defaults:
+    changefreq: weekly
+    priority: 0.5
+  exclude:
+    - /drafts/*
+  pages:
+    /:
+      priority: 1
+      changefreq: daily
+      lastmod: "2026-05-25"
+    /private/: false
+```
+
+If you do not use `data.site.baseUrl`, set `sitemap.siteUrl` instead.
+Generated entries use normalized page URLs, including page frontmatter `url` overrides.
+Use page frontmatter for per-page control:
+
+```md
+---
+sitemap:
+  changefreq: monthly
+  priority: 0.8
+  lastmod: "2026-05-25"
+---
+```
+
+Set `sitemap: false` in page frontmatter to exclude one page.
+`sitemap.exclude` accepts exact page URLs and prefix patterns ending in `*`, such as `/drafts/*`.
+
 `imports` lets you map aliases to remote YAML files (HTTP/HTTPS only). Use aliases in pages/templates:
 - page frontmatter: `template: base` or `template: docs`
 - template/page content: `$partial: docs/nav`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rettangoli/sites",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Generate static sites using Markdown and YAML for docs, blogs, and marketing sites.",
   "author": {
     "name": "Luciano Hanyon Wu",

package/src/cli/build.js

@@ -8,6 +8,7 @@ import { loadSiteConfig } from '../utils/loadSiteConfig.js';
  * @param {string} options.rootDir - Root directory of the site (defaults to cwd)
  * @param {string} options.outputPath - Output directory path (relative to rootDir by default)
  * @param {Object} options.md - Optional markdown renderer
+ * @param {Object|boolean} options.sitemap - Optional sitemap generation config
  * @param {boolean} options.quiet - Suppress build output logs
  * @param {boolean} options.isScreenshotMode - Optional build flag exposed to templates via build.isScreenshotMode
  */
@@ -17,6 +18,7 @@ export const buildSite = async (options = {}) => {
     outputPath = '_site',
     md,
     functions,
+    sitemap,
     quiet = false,
     isScreenshotMode = false
   } = options;
@@ -32,6 +34,7 @@ export const buildSite = async (options = {}) => {
     keepMarkdownFiles: config.build?.keepMarkdownFiles === true,
     imports: config.imports || {},
     data: config.data || {},
+    sitemap: sitemap === undefined ? config.sitemap : sitemap,
     functions: functions || {},
     quiet,
     isScreenshotMode

package/src/createSiteBuilder.js

@@ -8,6 +8,7 @@ import matter from 'gray-matter';
 import MarkdownIt from 'markdown-it';
 import rtglMarkdown from './rtglMarkdown.js';
 import builtinTemplateFunctions from './builtinTemplateFunctions.js';
+import { buildSitemapXml, resolveSitemapOutputPath } from './sitemap.js';
 
 const MATTER_OPTIONS = {
   engines: {
@@ -228,6 +229,123 @@ function isSchemaSidecarFile(fileName) {
   return fileName.endsWith('.schema.yaml') || fileName.endsWith('.schema.yml');
 }
 
+function hasPageExtension(fileName) {
+  return fileName.endsWith('.yaml') || fileName.endsWith('.yml') || fileName.endsWith('.md');
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function normalizeRelativeUrlPath(relativePath) {
+  return relativePath.replace(/\\/g, '/');
+}
+
+function derivePageUrlFromRelativePath(relativePath) {
+  const normalizedPath = normalizeRelativeUrlPath(relativePath);
+  const pathWithoutExtension = normalizedPath.replace(/\.(yaml|yml|md)$/, '');
+  const pageName = path.posix.basename(pathWithoutExtension);
+
+  if (pageName === 'index') {
+    const dirName = path.posix.dirname(pathWithoutExtension);
+    return dirName === '.' ? '/' : `/${dirName}/`;
+  }
+
+  return `/${pathWithoutExtension}/`;
+}
+
+function normalizePageUrlOverride(rawUrl, pagePath) {
+  if (typeof rawUrl !== 'string') {
+    throw new Error(`Invalid url in ${pagePath}: expected a string.`);
+  }
+
+  if (rawUrl === '') {
+    throw new Error(`Invalid url in ${pagePath}: expected a non-empty string.`);
+  }
+
+  if (/[\u0000-\u001F\u007F]/u.test(rawUrl)) {
+    throw new Error(`Invalid url in ${pagePath}: must not contain control characters.`);
+  }
+
+  if (/\s/u.test(rawUrl)) {
+    throw new Error(`Invalid url in ${pagePath}: must not contain whitespace.`);
+  }
+
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:/u.test(rawUrl) || rawUrl.startsWith('//')) {
+    throw new Error(`Invalid url in ${pagePath}: expected a site-relative URL path.`);
+  }
+
+  if (rawUrl.includes('\\')) {
+    throw new Error(`Invalid url in ${pagePath}: must use forward slashes.`);
+  }
+
+  if (rawUrl.includes('?') || rawUrl.includes('#')) {
+    throw new Error(`Invalid url in ${pagePath}: must not include query strings or fragments.`);
+  }
+
+  const withLeadingSlash = rawUrl.startsWith('/') ? rawUrl : `/${rawUrl}`;
+  const collapsedUrl = withLeadingSlash.replace(/\/+/g, '/');
+  const pathWithoutSlashes = collapsedUrl.replace(/^\/+|\/+$/g, '');
+
+  if (pathWithoutSlashes === '') {
+    return '/';
+  }
+
+  const segments = pathWithoutSlashes.split('/');
+  for (const segment of segments) {
+    let decodedSegment;
+    try {
+      decodedSegment = decodeURIComponent(segment);
+    } catch (error) {
+      throw new Error(`Invalid url in ${pagePath}: contains invalid URL encoding.`);
+    }
+
+    if (decodedSegment === '.' || decodedSegment === '..') {
+      throw new Error(`Invalid url in ${pagePath}: must not contain "." or ".." segments.`);
+    }
+
+    if (decodedSegment.includes('/') || decodedSegment.includes('\\')) {
+      throw new Error(`Invalid url in ${pagePath}: must not include encoded slashes or backslashes.`);
+    }
+
+    if (/[\u0000-\u001F\u007F]/u.test(decodedSegment)) {
+      throw new Error(`Invalid url in ${pagePath}: must not contain control characters.`);
+    }
+
+    if (/\s/u.test(decodedSegment)) {
+      throw new Error(`Invalid url in ${pagePath}: must not contain whitespace.`);
+    }
+  }
+
+  return `/${segments.join('/')}/`;
+}
+
+function resolvePageUrl(publicFrontmatter, relativePath, pagePath) {
+  if (hasOwn(publicFrontmatter, 'url')) {
+    return normalizePageUrlOverride(publicFrontmatter.url, pagePath);
+  }
+
+  return derivePageUrlFromRelativePath(relativePath);
+}
+
+function htmlOutputRelativePathFromUrl(url) {
+  if (url === '/') {
+    return 'index.html';
+  }
+
+  return `${url.slice(1, -1)}/index.html`;
+}
+
+function markdownOutputRelativePathFromUrl(url) {
+  if (url === '/') {
+    return 'index.md';
+  }
+
+  const segments = url.slice(1, -1).split('/');
+  const fileName = `${segments.pop()}.md`;
+  return [...segments, fileName].join('/');
+}
+
 async function fetchRemoteYaml(url, fetchImpl, aliasLabel) {
   const effectiveFetch = fetchImpl || globalThis.fetch;
   if (typeof effectiveFetch !== 'function') {
@@ -318,6 +436,7 @@ export function createSiteBuilder({
   keepMarkdownFiles = false,
   imports = {},
   data = {},
+  sitemap,
   fetchImpl,
   functions = {},
   quiet = false,
@@ -485,12 +604,11 @@ export function createSiteBuilder({
       };
     }
 
-    // Function to scan all pages and build collections
-    function buildCollections() {
-      const collections = {};
+    function collectPageEntries() {
+      const pageEntries = [];
       const pagesDir = path.join(rootDir, 'pages');
 
-      function scanPages(dir, basePath = '') {
+      function scanPages(basePath = '') {
         const fullDir = path.join(pagesDir, basePath);
         if (!fs.existsSync(fullDir)) return;
 
@@ -502,82 +620,122 @@ export function createSiteBuilder({
           const itemKind = resolveDirentKind(fs, itemPath, item);
 
           if (itemKind === 'directory') {
-            // Recursively scan subdirectories
-            scanPages(dir, relativePath);
-          } else if (itemKind === 'file' && (item.name.endsWith('.yaml') || item.name.endsWith('.yml') || item.name.endsWith('.md'))) {
-            // Extract frontmatter and content
+            scanPages(relativePath);
+          } else if (itemKind === 'file' && hasPageExtension(item.name)) {
             const { frontmatter, content } = extractFrontmatterAndContent(itemPath);
-            const { frontmatter: publicFrontmatter } = splitSystemFrontmatter(frontmatter, globalData, itemPath);
+            const { frontmatter: publicFrontmatter, bindings } = splitSystemFrontmatter(frontmatter, globalData, itemPath);
+            const hasCustomUrl = hasOwn(publicFrontmatter, 'url');
+            const url = resolvePageUrl(publicFrontmatter, relativePath, itemPath);
+            const exposedFrontmatter = hasCustomUrl
+              ? { ...publicFrontmatter, url }
+              : publicFrontmatter;
+
+            pageEntries.push({
+              pagePath: itemPath,
+              relativePath: normalizeRelativeUrlPath(relativePath),
+              isMarkdown: item.name.endsWith('.md'),
+              content,
+              frontmatter: exposedFrontmatter,
+              bindings,
+              url,
+              hasCustomUrl
+            });
+          }
+        }
+      }
 
-            // Calculate URL
-            const baseFileName = item.name.replace(/\.(yaml|yml|md)$/, '');
-            let url;
+      scanPages();
+      return pageEntries;
+    }
 
-            // Special case: index files remain at root, others become directories
-            if (baseFileName === 'index') {
-              url = basePath ? '/' + basePath.replace(/\\/g, '/') : '/';
-              if (url !== '/') {
-                url = url + '/';
-              }
-            } else {
-              const pagePath = basePath ? path.join(basePath, baseFileName) : baseFileName;
-              url = '/' + pagePath.replace(/\\/g, '/') + '/';
-            }
+    function assertUniquePageUrls(pageEntries) {
+      const seen = new Map();
 
-            // Process tags
-            if (publicFrontmatter.tags) {
-              // Normalize tags to array
-              const tags = Array.isArray(publicFrontmatter.tags) ? publicFrontmatter.tags : [publicFrontmatter.tags];
-
-              // Add to collections
-              tags.forEach(tag => {
-                if (typeof tag === 'string' && tag.trim()) {
-                  const trimmedTag = tag.trim();
-                  if (!collections[trimmedTag]) {
-                    collections[trimmedTag] = [];
-                  }
-                  collections[trimmedTag].push({
-                    data: publicFrontmatter,
-                    url: url,
-                    content: content
-                  });
-                }
+      for (const entry of pageEntries) {
+        const existingEntry = seen.get(entry.url);
+        if (existingEntry) {
+          throw new Error(`Duplicate page URL "${entry.url}" in ${entry.pagePath}; already used by ${existingEntry.pagePath}.`);
+        }
+        seen.set(entry.url, entry);
+      }
+    }
+
+    function assertUniqueMarkdownOutputPaths(pageEntries) {
+      if (!keepMarkdownFiles) {
+        return;
+      }
+
+      const seen = new Map();
+      for (const entry of pageEntries) {
+        if (!entry.isMarkdown) {
+          continue;
+        }
+
+        const markdownOutputRelativePath = entry.hasCustomUrl
+          ? markdownOutputRelativePathFromUrl(entry.url)
+          : entry.relativePath;
+        const existingEntry = seen.get(markdownOutputRelativePath);
+        if (existingEntry) {
+          throw new Error(`Duplicate markdown output path "${markdownOutputRelativePath}" in ${entry.pagePath}; already used by ${existingEntry.pagePath}.`);
+        }
+        seen.set(markdownOutputRelativePath, entry);
+      }
+    }
+
+    // Function to scan all pages and build collections
+    function buildCollections(pageEntries) {
+      const collections = {};
+
+      for (const entry of pageEntries) {
+        const publicFrontmatter = entry.frontmatter;
+
+        // Process tags
+        if (publicFrontmatter.tags) {
+          // Normalize tags to array
+          const tags = Array.isArray(publicFrontmatter.tags) ? publicFrontmatter.tags : [publicFrontmatter.tags];
+
+          // Add to collections
+          tags.forEach(tag => {
+            if (typeof tag === 'string' && tag.trim()) {
+              const trimmedTag = tag.trim();
+              if (!collections[trimmedTag]) {
+                collections[trimmedTag] = [];
+              }
+              collections[trimmedTag].push({
+                data: publicFrontmatter,
+                url: entry.url,
+                content: entry.content
               });
             }
-          }
+          });
         }
       }
 
-      scanPages('');
       return collections;
     }
 
+    const pageEntries = collectPageEntries();
+    assertUniquePageUrls(pageEntries);
+    assertUniqueMarkdownOutputPaths(pageEntries);
+
     // Build collections in first pass
     if (!quiet) console.log('Building collections...');
-    const collections = buildCollections();
+    const collections = buildCollections(pageEntries);
 
     // Function to process a single page file
-    async function processPage(pagePath, outputRelativePath, isMarkdown = false, markdownOutputRelativePath = null) {
-      if (!quiet) console.log(`Processing ${pagePath}...`);
-
-      const { frontmatter, content: rawContent } = extractFrontmatterAndContent(pagePath);
-      const { frontmatter: publicFrontmatter, bindings: boundData } = splitSystemFrontmatter(frontmatter, globalData, pagePath);
-
-      // Calculate URL for current page
-      let url;
-      const fileName = path.basename(outputRelativePath, '.html');
-      const basePath = path.dirname(outputRelativePath);
+    async function processPage(pageEntry) {
+      const {
+        pagePath,
+        content: rawContent,
+        frontmatter: publicFrontmatter,
+        bindings: boundData,
+        isMarkdown,
+        url,
+        hasCustomUrl,
+        relativePath
+      } = pageEntry;
 
-      // Special case: index files remain at root, others become directories
-      if (fileName === 'index') {
-        url = basePath && basePath !== '.' ? '/' + basePath.replace(/\\/g, '/') : '/';
-        if (url !== '/') {
-          url = url + '/';
-        }
-      } else {
-        const pagePath = basePath && basePath !== '.' ? path.join(basePath, fileName) : fileName;
-        url = '/' + pagePath.replace(/\\/g, '/') + '/';
-      }
+      if (!quiet) console.log(`Processing ${pagePath}...`);
 
       // Deep merge global data with frontmatter and collections for the page context
       const pageData = deepMerge(globalData, publicFrontmatter);
@@ -648,35 +806,9 @@ export function createSiteBuilder({
         htmlString = convertToHtml(resultArray);
       }
 
-      // Create output directory and file path for new index.html structure
-      const pageFileName = path.basename(outputRelativePath, '.html');
-      const dirPath = path.dirname(outputRelativePath);
-
-      let outputPath, outputDir;
-
-      // Special case: index files remain as index.html, others become directory/index.html
-      if (pageFileName === 'index') {
-        if (dirPath && dirPath !== '.') {
-          // Nested index file: pages/blog/index.yaml -> _site/blog/index.html
-          outputPath = path.join(outputRootDir, dirPath, 'index.html');
-          outputDir = path.join(outputRootDir, dirPath);
-        } else {
-          // Root index file: pages/index.yaml -> _site/index.html
-          outputPath = path.join(outputRootDir, 'index.html');
-          outputDir = path.join(outputRootDir);
-        }
-      } else {
-        // Regular file: pages/test.yaml -> _site/test/index.html
-        if (dirPath && dirPath !== '.') {
-          // Nested regular file: pages/blog/post.yaml -> _site/blog/post/index.html
-          outputPath = path.join(outputRootDir, dirPath, pageFileName, 'index.html');
-          outputDir = path.join(outputRootDir, dirPath, pageFileName);
-        } else {
-          // Root level regular file: pages/test.yaml -> _site/test/index.html
-          outputPath = path.join(outputRootDir, pageFileName, 'index.html');
-          outputDir = path.join(outputRootDir, pageFileName);
-        }
-      }
+      const outputRelativePath = htmlOutputRelativePathFromUrl(url);
+      const outputPath = path.join(outputRootDir, ...outputRelativePath.split('/'));
+      const outputDir = path.dirname(outputPath);
 
       if (!fs.existsSync(outputDir)) {
         fs.mkdirSync(outputDir, { recursive: true });
@@ -686,8 +818,11 @@ export function createSiteBuilder({
       fs.writeFileSync(outputPath, htmlString);
       if (!quiet) console.log(`  -> Written to ${outputPath}`);
 
-      if (isMarkdown && keepMarkdownFiles && typeof markdownOutputRelativePath === 'string') {
-        const markdownOutputPath = path.join(outputRootDir, markdownOutputRelativePath);
+      if (isMarkdown && keepMarkdownFiles) {
+        const markdownOutputRelativePath = hasCustomUrl
+          ? markdownOutputRelativePathFromUrl(url)
+          : relativePath;
+        const markdownOutputPath = path.join(outputRootDir, ...markdownOutputRelativePath.split('/'));
         const markdownOutputDir = path.dirname(markdownOutputPath);
         if (!fs.existsSync(markdownOutputDir)) {
           fs.mkdirSync(markdownOutputDir, { recursive: true });
@@ -697,38 +832,28 @@ export function createSiteBuilder({
       }
     }
 
-    // Process all YAML and Markdown files in pages directory recursively
-    async function processAllPages(dir, basePath = '') {
-      const pagesDir = path.join(rootDir, 'pages');
-      const fullDir = path.join(pagesDir, basePath);
-
-      if (!fs.existsSync(fullDir)) return;
+    async function processAllPages() {
+      for (const pageEntry of pageEntries) {
+        await processPage(pageEntry);
+      }
+    }
 
-      const items = fs.readdirSync(fullDir, { withFileTypes: true });
+    function writeSitemap() {
+      const sitemapXml = buildSitemapXml({ pageEntries, sitemap, globalData });
+      if (sitemapXml === null) {
+        return;
+      }
 
-      for (const item of items) {
-        const itemPath = path.join(fullDir, item.name);
-        const relativePath = basePath ? path.join(basePath, item.name) : item.name;
-        const itemKind = resolveDirentKind(fs, itemPath, item);
+      const sitemapOutputRelativePath = resolveSitemapOutputPath(sitemap);
+      const sitemapOutputPath = path.join(outputRootDir, ...sitemapOutputRelativePath.split('/'));
+      const sitemapOutputDir = path.dirname(sitemapOutputPath);
 
-        if (itemKind === 'directory') {
-          // Recursively process subdirectories
-          await processAllPages(dir, relativePath);
-        } else if (itemKind === 'file') {
-          if (item.name.endsWith('.yaml') || item.name.endsWith('.yml')) {
-            // Process YAML file
-            const outputFileName = item.name.replace(/\.(yaml|yml)$/, '.html');
-            const outputRelativePath = basePath ? path.join(basePath, outputFileName) : outputFileName;
-            await processPage(itemPath, outputRelativePath, false);
-          } else if (item.name.endsWith('.md')) {
-            // Process Markdown file
-            const outputFileName = item.name.replace('.md', '.html');
-            const outputRelativePath = basePath ? path.join(basePath, outputFileName) : outputFileName;
-            await processPage(itemPath, outputRelativePath, true, relativePath);
-          }
-          // Ignore other file types
-        }
+      if (!fs.existsSync(sitemapOutputDir)) {
+        fs.mkdirSync(sitemapOutputDir, { recursive: true });
       }
+
+      fs.writeFileSync(sitemapOutputPath, sitemapXml);
+      if (!quiet) console.log(`  -> Written sitemap to ${sitemapOutputPath}`);
     }
 
     // Function to copy static files recursively
@@ -784,7 +909,10 @@ export function createSiteBuilder({
     copyStaticFiles();
 
     // Process all pages (can overwrite static files)
-    await processAllPages('');
+    await processAllPages();
+
+    // Generate sitemap after pages so it can overwrite static files if configured.
+    writeSitemap();
 
     if (!quiet) console.log('Build complete!');
   };

package/src/sitemap.js

@@ -0,0 +1,466 @@
+const ALLOWED_CHANGEFREQS = new Set(['always', 'hourly', 'daily', 'weekly', 'monthly', 'yearly', 'never']);
+const ALLOWED_TOP_LEVEL_KEYS = new Set(['enabled', 'siteUrl', 'outputPath', 'defaults', 'exclude', 'pages']);
+const ALLOWED_DEFAULT_KEYS = new Set(['changefreq', 'priority', 'lastmod']);
+const ALLOWED_ENTRY_KEYS = new Set(['changefreq', 'priority', 'lastmod', 'exclude']);
+const SITEMAP_DATE_RE = /^\d{4}-\d{2}-\d{2}(?:T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}))?$/u;
+
+function isPlainObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasOwn(object, key) {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function rejectInvalidUrlString(rawUrl, contextLabel) {
+  if (typeof rawUrl !== 'string') {
+    throw new Error(`${contextLabel}: expected a string.`);
+  }
+
+  if (rawUrl === '') {
+    throw new Error(`${contextLabel}: expected a non-empty string.`);
+  }
+
+  if (/[\u0000-\u001F\u007F]/u.test(rawUrl)) {
+    throw new Error(`${contextLabel}: must not contain control characters.`);
+  }
+
+  if (/\s/u.test(rawUrl)) {
+    throw new Error(`${contextLabel}: must not contain whitespace.`);
+  }
+
+  if (/^[A-Za-z][A-Za-z0-9+.-]*:/u.test(rawUrl) || rawUrl.startsWith('//')) {
+    throw new Error(`${contextLabel}: expected a site-relative URL path.`);
+  }
+
+  if (rawUrl.includes('\\')) {
+    throw new Error(`${contextLabel}: must use forward slashes.`);
+  }
+
+  if (rawUrl.includes('?') || rawUrl.includes('#')) {
+    throw new Error(`${contextLabel}: must not include query strings or fragments.`);
+  }
+}
+
+export function normalizeSitemapUrlPath(rawUrl, contextLabel) {
+  rejectInvalidUrlString(rawUrl, contextLabel);
+
+  const withLeadingSlash = rawUrl.startsWith('/') ? rawUrl : `/${rawUrl}`;
+  const collapsedUrl = withLeadingSlash.replace(/\/+/g, '/');
+  const pathWithoutSlashes = collapsedUrl.replace(/^\/+|\/+$/g, '');
+
+  if (pathWithoutSlashes === '') {
+    return '/';
+  }
+
+  const segments = pathWithoutSlashes.split('/');
+  for (const segment of segments) {
+    let decodedSegment;
+    try {
+      decodedSegment = decodeURIComponent(segment);
+    } catch {
+      throw new Error(`${contextLabel}: contains invalid URL encoding.`);
+    }
+
+    if (decodedSegment === '.' || decodedSegment === '..') {
+      throw new Error(`${contextLabel}: must not contain "." or ".." segments.`);
+    }
+
+    if (decodedSegment.includes('/') || decodedSegment.includes('\\')) {
+      throw new Error(`${contextLabel}: must not include encoded slashes or backslashes.`);
+    }
+
+    if (/[\u0000-\u001F\u007F]/u.test(decodedSegment)) {
+      throw new Error(`${contextLabel}: must not contain control characters.`);
+    }
+
+    if (/\s/u.test(decodedSegment)) {
+      throw new Error(`${contextLabel}: must not contain whitespace.`);
+    }
+  }
+
+  return `/${segments.join('/')}/`;
+}
+
+function normalizeSitemapUrlPattern(rawPattern, contextLabel) {
+  if (typeof rawPattern !== 'string') {
+    throw new Error(`${contextLabel}: expected a string.`);
+  }
+
+  if (rawPattern.endsWith('*')) {
+    const rawPrefix = rawPattern.slice(0, -1);
+    return `${normalizeSitemapUrlPath(rawPrefix, contextLabel)}*`;
+  }
+
+  return normalizeSitemapUrlPath(rawPattern, contextLabel);
+}
+
+function validateSiteUrl(siteUrl, contextLabel) {
+  if (typeof siteUrl !== 'string' || siteUrl.trim() === '') {
+    throw new Error(`${contextLabel}: expected a non-empty URL string.`);
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(siteUrl);
+  } catch {
+    throw new Error(`${contextLabel}: "${siteUrl}" is not a valid URL.`);
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    throw new Error(`${contextLabel}: protocol "${parsed.protocol}" is not supported. Allowed protocols: http:, https:.`);
+  }
+
+  if (parsed.search || parsed.hash) {
+    throw new Error(`${contextLabel}: must not include query strings or fragments.`);
+  }
+
+  parsed.pathname = parsed.pathname.replace(/\/+$/u, '');
+  return parsed.toString().replace(/\/$/u, '');
+}
+
+function validateOutputPath(outputPath, contextLabel) {
+  if (typeof outputPath !== 'string' || outputPath.trim() === '') {
+    throw new Error(`${contextLabel}: expected a non-empty string.`);
+  }
+
+  if (/[\u0000-\u001F\u007F]/u.test(outputPath)) {
+    throw new Error(`${contextLabel}: must not contain control characters.`);
+  }
+
+  if (/\s/u.test(outputPath)) {
+    throw new Error(`${contextLabel}: must not contain whitespace.`);
+  }
+
+  if (outputPath.startsWith('/') || /^[A-Za-z][A-Za-z0-9+.-]*:/u.test(outputPath)) {
+    throw new Error(`${contextLabel}: expected a relative output path.`);
+  }
+
+  if (outputPath.includes('\\') || outputPath.includes('?') || outputPath.includes('#')) {
+    throw new Error(`${contextLabel}: must be a clean relative file path.`);
+  }
+
+  const segments = outputPath.split('/').filter(Boolean);
+  if (segments.length === 0) {
+    throw new Error(`${contextLabel}: expected a relative file path.`);
+  }
+
+  for (const segment of segments) {
+    if (segment === '.' || segment === '..') {
+      throw new Error(`${contextLabel}: must not contain "." or ".." segments.`);
+    }
+  }
+
+  return segments.join('/');
+}
+
+function normalizeLastmod(lastmod, contextLabel) {
+  if (lastmod instanceof Date) {
+    if (Number.isNaN(lastmod.getTime())) {
+      throw new Error(`${contextLabel}: expected a valid date.`);
+    }
+    return lastmod.toISOString();
+  }
+
+  if (typeof lastmod !== 'string' || lastmod.trim() === '') {
+    throw new Error(`${contextLabel}: expected an ISO date string.`);
+  }
+
+  const trimmed = lastmod.trim();
+  if (!SITEMAP_DATE_RE.test(trimmed)) {
+    throw new Error(`${contextLabel}: expected an ISO date string like "2026-05-25" or "2026-05-25T12:00:00Z".`);
+  }
+
+  return trimmed;
+}
+
+function normalizePriority(priority, contextLabel) {
+  if (typeof priority !== 'number' || !Number.isFinite(priority)) {
+    throw new Error(`${contextLabel}: expected a number from 0 to 1.`);
+  }
+
+  if (priority < 0 || priority > 1) {
+    throw new Error(`${contextLabel}: expected a number from 0 to 1.`);
+  }
+
+  return priority;
+}
+
+function normalizeChangefreq(changefreq, contextLabel) {
+  if (typeof changefreq !== 'string' || changefreq.trim() === '') {
+    throw new Error(`${contextLabel}: expected a non-empty string.`);
+  }
+
+  const normalized = changefreq.trim();
+  if (!ALLOWED_CHANGEFREQS.has(normalized)) {
+    throw new Error(`${contextLabel}: expected one of ${Array.from(ALLOWED_CHANGEFREQS).join(', ')}.`);
+  }
+
+  return normalized;
+}
+
+function normalizeEntryOptions(value, contextLabel, { allowExclude }) {
+  if (!isPlainObject(value)) {
+    throw new Error(`${contextLabel}: expected an object.`);
+  }
+
+  const allowedKeys = allowExclude ? ALLOWED_ENTRY_KEYS : ALLOWED_DEFAULT_KEYS;
+  const normalized = {};
+
+  for (const key of Object.keys(value)) {
+    if (!allowedKeys.has(key)) {
+      throw new Error(`${contextLabel}: unsupported option "${key}". Supported options: ${Array.from(allowedKeys).join(', ')}.`);
+    }
+  }
+
+  if (value.changefreq !== undefined) {
+    normalized.changefreq = normalizeChangefreq(value.changefreq, `${contextLabel}.changefreq`);
+  }
+
+  if (value.priority !== undefined) {
+    normalized.priority = normalizePriority(value.priority, `${contextLabel}.priority`);
+  }
+
+  if (value.lastmod !== undefined) {
+    normalized.lastmod = normalizeLastmod(value.lastmod, `${contextLabel}.lastmod`);
+  }
+
+  if (allowExclude && value.exclude !== undefined) {
+    if (typeof value.exclude !== 'boolean') {
+      throw new Error(`${contextLabel}.exclude: expected a boolean.`);
+    }
+    normalized.exclude = value.exclude;
+  }
+
+  return normalized;
+}
+
+function normalizePagesConfig(value, configPath) {
+  if (!isPlainObject(value)) {
+    throw new Error(`Invalid sitemap.pages in "${configPath}": expected an object.`);
+  }
+
+  const pages = {};
+  for (const [rawUrl, rawOptions] of Object.entries(value)) {
+    const url = normalizeSitemapUrlPath(rawUrl, `Invalid sitemap.pages URL "${rawUrl}" in "${configPath}"`);
+    if (rawOptions === false) {
+      pages[url] = { exclude: true };
+      continue;
+    }
+
+    pages[url] = normalizeEntryOptions(rawOptions, `Invalid sitemap.pages.${rawUrl} in "${configPath}"`, { allowExclude: true });
+  }
+
+  return pages;
+}
+
+export function normalizeSitemapConfig(value, configPath = 'sitemap config') {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  if (typeof value === 'boolean') {
+    return { enabled: value };
+  }
+
+  if (!isPlainObject(value)) {
+    throw new Error(`Invalid sitemap config in "${configPath}": expected a boolean or object.`);
+  }
+
+  const normalized = { enabled: true };
+
+  for (const key of Object.keys(value)) {
+    if (!ALLOWED_TOP_LEVEL_KEYS.has(key)) {
+      throw new Error(
+        `Unsupported sitemap option "${key}" in "${configPath}". Supported options: ${Array.from(ALLOWED_TOP_LEVEL_KEYS).join(', ')}.`
+      );
+    }
+  }
+
+  if (value.enabled !== undefined) {
+    if (typeof value.enabled !== 'boolean') {
+      throw new Error(`Invalid sitemap.enabled in "${configPath}": expected a boolean.`);
+    }
+    normalized.enabled = value.enabled;
+  }
+
+  if (value.siteUrl !== undefined) {
+    normalized.siteUrl = validateSiteUrl(value.siteUrl, `Invalid sitemap.siteUrl in "${configPath}"`);
+  }
+
+  if (value.outputPath !== undefined) {
+    normalized.outputPath = validateOutputPath(value.outputPath, `Invalid sitemap.outputPath in "${configPath}"`);
+  }
+
+  if (value.defaults !== undefined) {
+    normalized.defaults = normalizeEntryOptions(value.defaults, `Invalid sitemap.defaults in "${configPath}"`, { allowExclude: false });
+  }
+
+  if (value.exclude !== undefined) {
+    if (!Array.isArray(value.exclude)) {
+      throw new Error(`Invalid sitemap.exclude in "${configPath}": expected an array.`);
+    }
+    normalized.exclude = value.exclude.map((pattern, index) => (
+      normalizeSitemapUrlPattern(pattern, `Invalid sitemap.exclude[${index}] in "${configPath}"`)
+    ));
+  }
+
+  if (value.pages !== undefined) {
+    normalized.pages = normalizePagesConfig(value.pages, configPath);
+  }
+
+  return normalized;
+}
+
+function resolveSitemapSiteUrl(sitemap, globalData, { required = true } = {}) {
+  if (sitemap.siteUrl) {
+    return sitemap.siteUrl;
+  }
+
+  const baseUrl = globalData?.site?.baseUrl;
+  if (baseUrl === undefined) {
+    if (!required) {
+      return null;
+    }
+    throw new Error('Sitemap generation requires sitemap.siteUrl or data.site.baseUrl.');
+  }
+
+  return validateSiteUrl(baseUrl, 'Invalid data.site.baseUrl');
+}
+
+function matchesExclude(url, pattern) {
+  if (pattern.endsWith('*')) {
+    return url.startsWith(pattern.slice(0, -1));
+  }
+
+  return url === pattern;
+}
+
+function normalizePageSitemapOptions(rawSitemap, pagePath) {
+  if (rawSitemap === undefined || rawSitemap === null) {
+    return {};
+  }
+
+  if (rawSitemap === false) {
+    return { exclude: true };
+  }
+
+  if (rawSitemap === true) {
+    return {};
+  }
+
+  return normalizeEntryOptions(rawSitemap, `Invalid sitemap frontmatter in ${pagePath}`, { allowExclude: true });
+}
+
+function escapeXml(value) {
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function formatPriority(priority) {
+  return String(Number(priority.toFixed(3))).replace(/\.0+$/u, '');
+}
+
+function joinSiteUrl(siteUrl, pageUrl) {
+  const parsed = new URL(siteUrl);
+  const basePath = parsed.pathname.replace(/\/+$/u, '');
+  parsed.pathname = `${basePath}${pageUrl}`.replace(/\/+/g, '/');
+  return parsed.toString();
+}
+
+function buildUrlEntryXml(entry) {
+  const lines = [
+    '  <url>',
+    `    <loc>${escapeXml(entry.loc)}</loc>`
+  ];
+
+  if (entry.lastmod !== undefined) {
+    lines.push(`    <lastmod>${escapeXml(entry.lastmod)}</lastmod>`);
+  }
+
+  if (entry.changefreq !== undefined) {
+    lines.push(`    <changefreq>${escapeXml(entry.changefreq)}</changefreq>`);
+  }
+
+  if (entry.priority !== undefined) {
+    lines.push(`    <priority>${formatPriority(entry.priority)}</priority>`);
+  }
+
+  lines.push('  </url>');
+  return lines.join('\n');
+}
+
+export function buildSitemapXml({ pageEntries, sitemap, globalData }) {
+  if (sitemap === false || sitemap?.enabled === false) {
+    return null;
+  }
+
+  const hasExplicitSitemapConfig = sitemap !== undefined && sitemap !== null;
+  const normalizedSitemap = normalizeSitemapConfig(hasExplicitSitemapConfig ? sitemap : true);
+  if (normalizedSitemap.enabled === false) {
+    return null;
+  }
+
+  const siteUrl = resolveSitemapSiteUrl(normalizedSitemap, globalData, {
+    required: hasExplicitSitemapConfig
+  });
+  if (siteUrl === null) {
+    return null;
+  }
+  const excludePatterns = normalizedSitemap.exclude || [];
+  const defaultOptions = normalizedSitemap.defaults || {};
+  const pageOptions = normalizedSitemap.pages || {};
+
+  const entries = [];
+  for (const pageEntry of pageEntries) {
+    const url = pageEntry.url;
+    const configuredOptions = pageOptions[url] || {};
+    const frontmatterOptions = normalizePageSitemapOptions(pageEntry.frontmatter?.sitemap, pageEntry.pagePath);
+    const options = {
+      ...defaultOptions,
+      ...configuredOptions,
+      ...frontmatterOptions
+    };
+
+    if (excludePatterns.some((pattern) => matchesExclude(url, pattern)) || options.exclude === true) {
+      continue;
+    }
+
+    const entry = {
+      loc: joinSiteUrl(siteUrl, url)
+    };
+
+    if (hasOwn(options, 'lastmod')) {
+      entry.lastmod = options.lastmod;
+    }
+
+    if (hasOwn(options, 'changefreq')) {
+      entry.changefreq = options.changefreq;
+    }
+
+    if (hasOwn(options, 'priority')) {
+      entry.priority = options.priority;
+    }
+
+    entries.push(entry);
+  }
+
+  entries.sort((left, right) => left.loc.localeCompare(right.loc));
+
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">',
+    ...entries.map(buildUrlEntryXml),
+    '</urlset>',
+    ''
+  ].join('\n');
+}
+
+export function resolveSitemapOutputPath(sitemap) {
+  const normalizedSitemap = normalizeSitemapConfig(sitemap);
+  return normalizedSitemap?.outputPath || 'sitemap.xml';
+}

package/src/utils/loadSiteConfig.js

@@ -1,8 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'js-yaml';
+import { normalizeSitemapConfig } from '../sitemap.js';
 
-const ALLOWED_TOP_LEVEL_KEYS = new Set(['markdown', 'markdownit', 'build', 'imports', 'data']);
+const ALLOWED_TOP_LEVEL_KEYS = new Set(['markdown', 'markdownit', 'build', 'imports', 'data', 'sitemap']);
 const MARKDOWN_BOOLEAN_KEYS = new Set(['html', 'linkify', 'typographer', 'breaks', 'xhtmlOut']);
 const MARKDOWN_STRING_KEYS = new Set(['langPrefix', 'quotes', 'preset']);
 const MARKDOWN_NUMBER_KEYS = new Set(['maxNesting']);
@@ -219,7 +220,7 @@ function validateConfig(rawConfig, configPath) {
   for (const key of Object.keys(config)) {
     if (!ALLOWED_TOP_LEVEL_KEYS.has(key)) {
       throw new Error(
-        `Unsupported key "${key}" in "${configPath}". Supported keys: markdownit (recommended), markdown (legacy alias), build, imports, data.`
+        `Unsupported key "${key}" in "${configPath}". Supported keys: markdownit (recommended), markdown (legacy alias), build, imports, data, sitemap.`
       );
     }
   }
@@ -315,6 +316,10 @@ function validateConfig(rawConfig, configPath) {
     normalizedConfig.data = validateDataConfig(config.data, configPath);
   }
 
+  if (config.sitemap !== undefined) {
+    normalizedConfig.sitemap = normalizeSitemapConfig(config.sitemap, configPath);
+  }
+
   return normalizedConfig;
 }