@rettangoli/sites 1.0.0-rc4 → 1.0.1

package/README.md

@@ -69,6 +69,12 @@ markdownit:
     fallback: section
 build:
   keepMarkdownFiles: false
+imports:
+  templates:
+    base: https://example.com/templates/base.yaml
+    docs: https://example.com/templates/docs.yaml
+  partials:
+    docs/nav: https://example.com/partials/docs-nav.yaml
 ```
 
 In the default starter template, CDN runtime scripts are controlled via `data/site.yaml`:
@@ -87,8 +93,73 @@ 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`
 
+`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`
+
+Imported files are cached on disk under `.rettangoli/sites/imports/{templates|partials}/` (hashed filenames).
+Alias/url/hash mapping is tracked in `.rettangoli/sites/imports/index.yaml`.
+Build is cache-first: if a cached file exists, it is used without a network request.
+
+When an alias exists both remotely and locally, local files under `templates/` and `partials/` override the imported one.
+
 If you want to publish a manual `llms.txt`, place it in `static/llms.txt`; it will be copied to `_site/llms.txt`.
 
+## System Frontmatter
+
+Use `_bind` to map global data keys into page-local variables.
+
+Example:
+
+```yaml
+---
+template: base
+_bind:
+  docs: feDocs
+---
+```
+
+This resolves `docs` from `data/feDocs.yaml` for that page.
+`_bind` is a system property and is not exposed to templates directly.
+
+Rules:
+
+- `_bind` must be an object
+- each `_bind` value must be a non-empty string
+- each `_bind` value must point to an existing `data/*.yaml` key
+- `_bind` is removed from public frontmatter before rendering/collections
+
+Binding order:
+
+1. build page context from `deepMerge(globalData, frontmatterWithoutSystemKeys)`
+2. apply `_bind` aliases on top (alias wins for that key)
+
+## Reusable Asset Package
+
+`@rettangoli/sites` is the engine only.
+
+Reusable themes, templates, partials, helper assets, schemas, and VT coverage now live in `packages/rettangoli-sitekit/` and publish from `@rettangoli/sitekit`.
+
+Use `@rettangoli/sitekit` when you want curated importable site assets.
+Keep `@rettangoli/sites` for build/watch/init behavior.
+
+## Template Authoring Pattern
+
+Keep base templates as shells with minimal logic:
+
+- document root (`html`, `head`, `body`)
+- main content slot (`"${content}"`)
+- stable layout containers
+
+Put variant-specific behavior and data wiring in partials instead.
+Partials accept explicit parameters via `$partial`, so they are the preferred place for:
+
+- section-specific navigation data
+- conditional UI branches
+- reusable interactive blocks
+
+This keeps one template reusable across many page variants and avoids duplicated template files.
+
 ## Commands
 
 ```bash
@@ -116,12 +187,14 @@ Available in YAML templates/pages without extra setup:
 - `formatDate(value, format = "YYYYMMDDHHmmss", useUtc = true)`
 - `now(format = "YYYYMMDDHHmmss", useUtc = true)`
 - `sort(list, key, order = "asc")`
+- `chunk(list, size = 1, pad = false, fillValue = null)`
 - `md(content)`
 - `toQueryString(object)`
 
-`formatDate` tokens: `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`.
+`formatDate` tokens: `YYYY`, `MMM`, `MM`, `DD`, `D`, `HH`, `mm`, `ss`.
 `decodeURI`/`decodeURIComponent` return the original input when decoding fails.
 `sort` supports `order` as `asc` or `desc` (default: `asc`), accepts dot-path keys (for example `data.date`), and returns a new array.
+`chunk` splits arrays into rows of `size`; with `pad = true`, the last row is padded with `fillValue`.
 `md` returns raw rendered HTML from Markdown for template insertion.
 
 ## Screenshots
@@ -134,6 +207,16 @@ Use VT against your generated site:
 2. Add `vt` config in `rettangoli.config.yaml`.
 3. Run `rtgl vt generate`, `rtgl vt report`, and `rtgl vt accept`.
 
+Docker runtime (recommended for stable Playwright/browser versions):
+
+```bash
+IMAGE="han4wluc/rtgl:playwright-v1.57.0-rtgl-v1.0.5"
+docker pull "$IMAGE"
+docker run --rm -v "$PWD:/workspace" -w /workspace "$IMAGE" rtgl vt screenshot
+docker run --rm -v "$PWD:/workspace" -w /workspace "$IMAGE" rtgl vt report
+docker run --rm -v "$PWD:/workspace" -w /workspace "$IMAGE" rtgl vt accept
+```
+
 Example:
 
 ```yaml
@@ -157,6 +240,8 @@ url: /
 
 `bun run preview` (or any equivalent local server command) must serve your built site on `vt.url` (for example serving `_site/` on port `4173`).
 
+For a maintained example asset pack and VT lab, see `packages/rettangoli-sitekit/`.
+
 ## Full Architecture And Analysis
 
 See `docs/architecture-and-analysis.md` for:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rettangoli/sites",
-  "version": "1.0.0-rc4",
+  "version": "1.0.1",
   "description": "Generate static sites using Markdown and YAML for docs, blogs, and marketing sites.",
   "author": {
     "name": "Luciano Hanyon Wu",
@@ -48,6 +48,11 @@
     "admin",
     "dashboard"
   ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yuusoft-org/rettangoli",
+    "directory": "packages/rettangoli-sites"
+  },
   "bugs": {
     "url": "https://github.com/yuusoft-org/rettangoli/issues"
   },

package/src/builtinTemplateFunctions.js

@@ -25,16 +25,20 @@ function formatDateImpl(value, format = 'YYYYMMDDHHmmss', useUtc = true) {
   }
 
   const read = (localGetter, utcGetter) => (useUtc ? utcGetter.call(date) : localGetter.call(date));
+  const monthIndex = read(date.getMonth, date.getUTCMonth);
+  const day = read(date.getDate, date.getUTCDate);
   const tokens = {
     YYYY: String(read(date.getFullYear, date.getUTCFullYear)),
-    MM: pad2(read(date.getMonth, date.getUTCMonth) + 1),
-    DD: pad2(read(date.getDate, date.getUTCDate)),
+    MMM: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'][monthIndex],
+    MM: pad2(monthIndex + 1),
+    DD: pad2(day),
+    D: String(day),
     HH: pad2(read(date.getHours, date.getUTCHours)),
     mm: pad2(read(date.getMinutes, date.getUTCMinutes)),
     ss: pad2(read(date.getSeconds, date.getUTCSeconds)),
   };
 
-  return String(format).replace(/YYYY|MM|DD|HH|mm|ss/g, (token) => tokens[token]);
+  return String(format).replace(/YYYY|MMM|MM|DD|D|HH|mm|ss/g, (token) => tokens[token]);
 }
 
 function jsonStringify(value, space = 0) {
@@ -141,6 +145,32 @@ function sortImpl(value, key, order = 'asc') {
   });
 }
 
+function chunkImpl(value, size = 1, pad = false, fillValue = null) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const parsedSize = Number(size);
+  if (!Number.isFinite(parsedSize) || parsedSize <= 0) {
+    return [];
+  }
+
+  const chunkSize = Math.max(1, Math.trunc(parsedSize));
+  const rows = [];
+  for (let index = 0; index < value.length; index += chunkSize) {
+    rows.push(value.slice(index, index + chunkSize));
+  }
+
+  if (pad && rows.length > 0) {
+    const lastRow = rows[rows.length - 1];
+    while (lastRow.length < chunkSize) {
+      lastRow.push(fillValue);
+    }
+  }
+
+  return rows;
+}
+
 function mdImpl(content) {
   return {
     __html: markdownRenderer.render(String(content ?? '')),
@@ -156,6 +186,7 @@ export const builtinTemplateFunctions = {
   formatDate: formatDateImpl,
   now: (format = 'YYYYMMDDHHmmss', useUtc = true) => formatDateImpl(new Date(), format, useUtc),
   sort: sortImpl,
+  chunk: chunkImpl,
   md: mdImpl,
   toQueryString,
 };

package/src/cli/build.js

@@ -30,6 +30,7 @@ export const buildSite = async (options = {}) => {
     md,
     markdown: config.markdown || {},
     keepMarkdownFiles: config.build?.keepMarkdownFiles === true,
+    imports: config.imports || {},
     functions: functions || {},
     quiet,
     isScreenshotMode

package/src/cli/watch.js

@@ -7,6 +7,14 @@ import { loadSiteConfig } from '../utils/loadSiteConfig.js';
 
 const RELOAD_MODES = new Set(['body', 'full']);
 
+function normalizePort(port) {
+  const normalizedPort = Number(port);
+  if (!Number.isInteger(normalizedPort) || normalizedPort < 1 || normalizedPort > 65535) {
+    throw new Error(`Invalid port "${port}". Allowed values: integers from 1 to 65535.`);
+  }
+  return normalizedPort;
+}
+
 export function createClientScript(reloadMode = 'body') {
   const shouldUseBodyReplacement = reloadMode === 'body';
   const reloadSnippet = shouldUseBodyReplacement
@@ -332,6 +340,7 @@ const watchSite = async (options = {}) => {
     quiet = false,
     reloadMode = 'body'
   } = options;
+  const normalizedPort = normalizePort(port);
   const normalizedReloadMode = String(reloadMode).toLowerCase();
   if (!RELOAD_MODES.has(normalizedReloadMode)) {
     throw new Error(`Invalid reload mode "${reloadMode}". Allowed values: body, full.`);
@@ -347,7 +356,7 @@ const watchSite = async (options = {}) => {
   logger.log('Initial build complete');
 
   // Start custom dev server
-  const server = new DevServer(port, path.resolve(rootDir, outputPath), logger, normalizedReloadMode);
+  const server = new DevServer(normalizedPort, path.resolve(rootDir, outputPath), logger, normalizedReloadMode);
   server.start();
 
   // Watch all relevant directories

package/src/createSiteBuilder.js

@@ -1,6 +1,7 @@
 import { convertToHtml } from 'yahtml';
 import { parseAndRender } from 'jempl';
 import path from 'path';
+import { createHash } from 'crypto';
 import yaml from 'js-yaml';
 import matter from 'gray-matter';
 
@@ -39,6 +40,272 @@ function isObject(item) {
   return item && typeof item === 'object' && !Array.isArray(item);
 }
 
+function splitSystemFrontmatter(frontmatter, globalData, pagePath) {
+  const normalized = isObject(frontmatter) ? { ...frontmatter } : {};
+  const bindConfig = normalized._bind;
+  delete normalized._bind;
+
+  if (bindConfig === undefined) {
+    return { frontmatter: normalized, bindings: {} };
+  }
+
+  if (!isObject(bindConfig)) {
+    throw new Error(`Invalid _bind in ${pagePath}: expected an object mapping local names to global data keys.`);
+  }
+
+  const bindings = {};
+  for (const [rawLocalKey, rawSourceKey] of Object.entries(bindConfig)) {
+    const localKey = String(rawLocalKey).trim();
+    if (localKey === '') {
+      throw new Error(`Invalid _bind in ${pagePath}: local key names must be non-empty.`);
+    }
+
+    if (typeof rawSourceKey !== 'string' || rawSourceKey.trim() === '') {
+      throw new Error(`Invalid _bind in ${pagePath} for "${localKey}": expected a non-empty global data key string.`);
+    }
+
+    const sourceKey = rawSourceKey.trim();
+    if (!Object.prototype.hasOwnProperty.call(globalData, sourceKey)) {
+      throw new Error(`Invalid _bind in ${pagePath} for "${localKey}": global data key "${sourceKey}" not found.`);
+    }
+
+    bindings[localKey] = globalData[sourceKey];
+  }
+
+  return { frontmatter: normalized, bindings };
+}
+
+function parseYamlWithContext(content, contextLabel) {
+  try {
+    return yaml.load(content, { schema: yaml.JSON_SCHEMA });
+  } catch (error) {
+    throw new Error(`${contextLabel}: Invalid YAML: ${error.message}`);
+  }
+}
+
+function buildImportCacheHash(url) {
+  return createHash('sha256').update(url).digest('hex');
+}
+
+function buildImportCachePath(rootDir, importGroup, hash) {
+  return path.join(rootDir, '.rettangoli', 'sites', 'imports', importGroup, `${hash}.yaml`);
+}
+
+function buildImportIndexPath(rootDir) {
+  return path.join(rootDir, '.rettangoli', 'sites', 'imports', 'index.yaml');
+}
+
+function toRelativePath(rootDir, absolutePath) {
+  const relativePath = path.relative(rootDir, absolutePath);
+  return relativePath.replace(/\\/g, '/');
+}
+
+function normalizeImportIndex(rawIndex, indexPath) {
+  if (rawIndex == null) {
+    return { version: 1, entries: [] };
+  }
+
+  if (!isObject(rawIndex)) {
+    throw new Error(`Invalid import index "${indexPath}": expected a YAML object.`);
+  }
+
+  if (rawIndex.version !== undefined && rawIndex.version !== 1) {
+    throw new Error(`Unsupported import index version "${rawIndex.version}" in "${indexPath}".`);
+  }
+
+  const rawEntries = rawIndex.entries ?? [];
+  if (!Array.isArray(rawEntries)) {
+    throw new Error(`Invalid import index "${indexPath}": expected "entries" to be an array.`);
+  }
+
+  const entries = rawEntries.map((entry, index) => {
+    if (!isObject(entry)) {
+      throw new Error(`Invalid import index "${indexPath}" at entries[${index}]: expected an object.`);
+    }
+
+    const normalizedEntry = {
+      alias: entry.alias,
+      type: entry.type,
+      url: entry.url,
+      hash: entry.hash,
+      path: entry.path
+    };
+
+    for (const [key, value] of Object.entries(normalizedEntry)) {
+      if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`Invalid import index "${indexPath}" at entries[${index}].${key}: expected a non-empty string.`);
+      }
+    }
+
+    return normalizedEntry;
+  });
+
+  return { version: 1, entries };
+}
+
+function readImportIndex(fs, rootDir) {
+  const indexPath = buildImportIndexPath(rootDir);
+  if (!fs.existsSync(indexPath)) {
+    return { version: 1, entries: [] };
+  }
+
+  const indexContent = fs.readFileSync(indexPath, 'utf8');
+  const parsed = parseYamlWithContext(indexContent, `import index "${indexPath}"`);
+  return normalizeImportIndex(parsed, indexPath);
+}
+
+function upsertImportIndexEntry(importIndex, entry) {
+  const existingIndex = importIndex.entries.findIndex((item) => item.type === entry.type && item.alias === entry.alias);
+  if (existingIndex === -1) {
+    importIndex.entries.push(entry);
+    return;
+  }
+  importIndex.entries[existingIndex] = entry;
+}
+
+function writeImportIndex(fs, rootDir, importIndex) {
+  const indexPath = buildImportIndexPath(rootDir);
+  const indexDir = path.dirname(indexPath);
+  if (!fs.existsSync(indexDir)) {
+    fs.mkdirSync(indexDir, { recursive: true });
+  }
+
+  const sortedEntries = [...importIndex.entries].sort((a, b) => {
+    const left = `${a.type}:${a.alias}`;
+    const right = `${b.type}:${b.alias}`;
+    return left.localeCompare(right);
+  });
+
+  const output = {
+    version: 1,
+    entries: sortedEntries
+  };
+  fs.writeFileSync(indexPath, yaml.dump(output, { noRefs: true, lineWidth: -1 }));
+}
+
+function readImportedYamlFromCache(fs, cachePath, aliasLabel) {
+  if (!fs.existsSync(cachePath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(cachePath, 'utf8');
+  return parseYamlWithContext(content, `${aliasLabel} (cache: ${cachePath})`);
+}
+
+function resolveDirentKind(fs, itemPath, item) {
+  if (item.isDirectory()) {
+    return 'directory';
+  }
+
+  if (item.isFile()) {
+    return 'file';
+  }
+
+  if (typeof item.isSymbolicLink === 'function' && item.isSymbolicLink()) {
+    let stats;
+    try {
+      stats = fs.statSync(itemPath);
+    } catch (error) {
+      throw new Error(`Broken symbolic link at "${itemPath}": ${error.message}`);
+    }
+
+    if (stats.isDirectory()) {
+      return 'directory';
+    }
+
+    if (stats.isFile()) {
+      return 'file';
+    }
+  }
+
+  return null;
+}
+
+function isSchemaSidecarFile(fileName) {
+  return fileName.endsWith('.schema.yaml') || fileName.endsWith('.schema.yml');
+}
+
+async function fetchRemoteYaml(url, fetchImpl, aliasLabel) {
+  const effectiveFetch = fetchImpl || globalThis.fetch;
+  if (typeof effectiveFetch !== 'function') {
+    throw new Error(`${aliasLabel}: Remote imports require global fetch support (Node.js 18+).`);
+  }
+
+  const response = await effectiveFetch(url);
+  if (!response.ok) {
+    throw new Error(`${aliasLabel}: HTTP ${response.status} ${response.statusText}`.trim());
+  }
+
+  const content = await response.text();
+  const parsed = parseYamlWithContext(content, aliasLabel);
+  return { parsed, content };
+}
+
+function writeImportedYamlCache(fs, cachePath, content) {
+  const cacheDir = path.dirname(cachePath);
+  if (!fs.existsSync(cacheDir)) {
+    fs.mkdirSync(cacheDir, { recursive: true });
+  }
+
+  try {
+    fs.writeFileSync(cachePath, content);
+  } catch (error) {
+    // Non-fatal: build can still proceed with fetched content.
+  }
+}
+
+async function loadImportedAliases({
+  fs,
+  rootDir,
+  importMap,
+  importGroup,
+  typeLabel,
+  fetchImpl,
+  importIndex
+}) {
+  const resolved = {};
+  if (!isObject(importMap)) {
+    return resolved;
+  }
+
+  for (const [alias, url] of Object.entries(importMap)) {
+    const aliasLabel = `imported ${typeLabel} "${alias}" from "${url}"`;
+    const hash = buildImportCacheHash(url);
+    const cachePath = buildImportCachePath(rootDir, importGroup, hash);
+    const relativeCachePath = toRelativePath(rootDir, cachePath);
+
+    const cachedValue = readImportedYamlFromCache(fs, cachePath, aliasLabel);
+    if (cachedValue !== null) {
+      resolved[alias] = cachedValue;
+      upsertImportIndexEntry(importIndex, {
+        alias,
+        type: typeLabel,
+        url,
+        hash,
+        path: relativeCachePath
+      });
+      continue;
+    }
+
+    try {
+      const fetched = await fetchRemoteYaml(url, fetchImpl, aliasLabel);
+      writeImportedYamlCache(fs, cachePath, fetched.content);
+      resolved[alias] = fetched.parsed;
+      upsertImportIndexEntry(importIndex, {
+        alias,
+        type: typeLabel,
+        url,
+        hash,
+        path: relativeCachePath
+      });
+    } catch (error) {
+      throw new Error(`Failed to load ${aliasLabel}: ${error.message}`);
+    }
+  }
+
+  return resolved;
+}
+
 export function createSiteBuilder({
   fs,
   rootDir = '.',
@@ -46,6 +313,8 @@ export function createSiteBuilder({
   md,
   markdown = {},
   keepMarkdownFiles = false,
+  imports = {},
+  fetchImpl,
   functions = {},
   quiet = false,
   isScreenshotMode = false
@@ -79,24 +348,67 @@ export function createSiteBuilder({
       fs.mkdirSync(outputRootDir, { recursive: true });
     }
 
+    const importIndex = readImportIndex(fs, rootDir);
+
+    const importedTemplates = await loadImportedAliases({
+      fs,
+      rootDir,
+      importMap: imports.templates,
+      importGroup: 'templates',
+      typeLabel: 'template',
+      fetchImpl,
+      importIndex
+    });
+    const importedPartials = await loadImportedAliases({
+      fs,
+      rootDir,
+      importMap: imports.partials,
+      importGroup: 'partials',
+      typeLabel: 'partial',
+      fetchImpl,
+      importIndex
+    });
+
+    if (importIndex.entries.length > 0) {
+      writeImportIndex(fs, rootDir, importIndex);
+    }
+
     // Read all partials and create a JSON object
     const partialsDir = path.join(rootDir, 'partials');
-    const partials = {};
+    const partials = { ...importedPartials };
 
-    if (fs.existsSync(partialsDir)) {
-      const files = fs.readdirSync(partialsDir, { withFileTypes: true });
-      files.forEach(file => {
-        if (!file.isFile() || (!file.name.endsWith('.yaml') && !file.name.endsWith('.yml'))) {
+    function readPartialsRecursively(dir, basePath = '') {
+      if (!fs.existsSync(dir)) return;
+
+      const items = fs.readdirSync(dir, { withFileTypes: true });
+      items.forEach(item => {
+        const itemPath = path.join(dir, item.name);
+        const itemKind = resolveDirentKind(fs, itemPath, item);
+        if (itemKind === 'directory') {
+          const newBasePath = basePath ? `${basePath}/${item.name}` : item.name;
+          readPartialsRecursively(itemPath, newBasePath);
           return;
         }
-        const filePath = path.join(partialsDir, file.name);
-        const fileContent = fs.readFileSync(filePath, 'utf8');
-        const nameWithoutExt = path.basename(file.name, path.extname(file.name));
-        // Convert partial content from YAML string to JSON
-        partials[nameWithoutExt] = yaml.load(fileContent, { schema: yaml.JSON_SCHEMA });
+
+        if (
+          itemKind !== 'file' ||
+          (!item.name.endsWith('.yaml') && !item.name.endsWith('.yml')) ||
+          isSchemaSidecarFile(item.name)
+        ) {
+          return;
+        }
+
+        const fileContent = fs.readFileSync(itemPath, 'utf8');
+        const nameWithoutExt = path.basename(item.name, path.extname(item.name));
+        const partialKey = basePath ? `${basePath}/${nameWithoutExt}` : nameWithoutExt;
+        partials[partialKey] = yaml.load(fileContent, { schema: yaml.JSON_SCHEMA });
       });
     }
 
+    if (fs.existsSync(partialsDir)) {
+      readPartialsRecursively(partialsDir);
+    }
+
     // Read all data files and create a JSON object
     const dataDir = path.join(rootDir, 'data');
     const globalData = {};
@@ -116,7 +428,7 @@ export function createSiteBuilder({
 
     // Read all templates and create a JSON object
     const templatesDir = path.join(rootDir, 'templates');
-    const templates = {};
+    const templates = { ...importedTemplates };
 
     function readTemplatesRecursively(dir, basePath = '') {
       if (!fs.existsSync(dir)) return;
@@ -125,12 +437,17 @@ export function createSiteBuilder({
 
       items.forEach(item => {
         const itemPath = path.join(dir, item.name);
+        const itemKind = resolveDirentKind(fs, itemPath, item);
 
-        if (item.isDirectory()) {
+        if (itemKind === 'directory') {
           // Recursively read subdirectories
           const newBasePath = basePath ? `${basePath}/${item.name}` : item.name;
           readTemplatesRecursively(itemPath, newBasePath);
-        } else if (item.isFile() && (item.name.endsWith('.yaml') || item.name.endsWith('.yml'))) {
+        } else if (
+          itemKind === 'file' &&
+          (item.name.endsWith('.yaml') || item.name.endsWith('.yml')) &&
+          !isSchemaSidecarFile(item.name)
+        ) {
           // Read and convert YAML file
           const fileContent = fs.readFileSync(itemPath, 'utf8');
           const nameWithoutExt = path.basename(item.name, path.extname(item.name));
@@ -172,13 +489,15 @@ export function createSiteBuilder({
         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);
 
-          if (item.isDirectory()) {
+          if (itemKind === 'directory') {
             // Recursively scan subdirectories
             scanPages(dir, relativePath);
-          } else if (item.isFile() && (item.name.endsWith('.yaml') || item.name.endsWith('.yml') || item.name.endsWith('.md'))) {
+          } else if (itemKind === 'file' && (item.name.endsWith('.yaml') || item.name.endsWith('.yml') || item.name.endsWith('.md'))) {
             // Extract frontmatter and content
             const { frontmatter, content } = extractFrontmatterAndContent(itemPath);
+            const { frontmatter: publicFrontmatter } = splitSystemFrontmatter(frontmatter, globalData, itemPath);
 
             // Calculate URL
             const baseFileName = item.name.replace(/\.(yaml|yml|md)$/, '');
@@ -196,9 +515,9 @@ export function createSiteBuilder({
             }
 
             // Process tags
-            if (frontmatter.tags) {
+            if (publicFrontmatter.tags) {
               // Normalize tags to array
-              const tags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [frontmatter.tags];
+              const tags = Array.isArray(publicFrontmatter.tags) ? publicFrontmatter.tags : [publicFrontmatter.tags];
 
               // Add to collections
               tags.forEach(tag => {
@@ -208,7 +527,7 @@ export function createSiteBuilder({
                     collections[trimmedTag] = [];
                   }
                   collections[trimmedTag].push({
-                    data: frontmatter,
+                    data: publicFrontmatter,
                     url: url,
                     content: content
                   });
@@ -232,6 +551,7 @@ export function createSiteBuilder({
       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;
@@ -250,7 +570,8 @@ export function createSiteBuilder({
       }
 
       // Deep merge global data with frontmatter and collections for the page context
-      const pageData = deepMerge(globalData, frontmatter);
+      const pageData = deepMerge(globalData, publicFrontmatter);
+      Object.assign(pageData, boundData);
       pageData.collections = collections;
       pageData.page = { url };
       pageData.build = { isScreenshotMode };
@@ -282,11 +603,11 @@ export function createSiteBuilder({
 
       // Find the template specified in frontmatter
       let templateToUse = null;
-      if (frontmatter.template) {
+      if (publicFrontmatter.template) {
         // Look up template by exact path
-        templateToUse = templates[frontmatter.template];
+        templateToUse = templates[publicFrontmatter.template];
         if (!templateToUse) {
-          throw new Error(`Template "${frontmatter.template}" not found in ${pagePath}. Available templates: ${Object.keys(templates).join(', ')}`);
+          throw new Error(`Template "${publicFrontmatter.template}" not found in ${pagePath}. Available templates: ${Object.keys(templates).join(', ')}`);
         }
       }
 
@@ -378,11 +699,12 @@ export function createSiteBuilder({
       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);
 
-        if (item.isDirectory()) {
+        if (itemKind === 'directory') {
           // Recursively process subdirectories
           await processAllPages(dir, relativePath);
-        } else if (item.isFile()) {
+        } else if (itemKind === 'file') {
           if (item.name.endsWith('.yaml') || item.name.endsWith('.yml')) {
             // Process YAML file
             const outputFileName = item.name.replace(/\.(yaml|yml)$/, '.html');

package/src/utils/loadSiteConfig.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import yaml from 'js-yaml';
 
-const ALLOWED_TOP_LEVEL_KEYS = new Set(['markdown', 'markdownit', 'build']);
+const ALLOWED_TOP_LEVEL_KEYS = new Set(['markdown', 'markdownit', 'build', 'imports']);
 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']);
@@ -27,6 +27,8 @@ const ALLOWED_HEADING_ANCHORS_KEYS = new Set([...HEADING_ANCHORS_BOOLEAN_KEYS, .
 const ALLOWED_HEADING_ANCHOR_SLUG_MODES = new Set(['ascii', 'unicode']);
 const BUILD_BOOLEAN_KEYS = new Set(['keepMarkdownFiles']);
 const ALLOWED_BUILD_KEYS = new Set([...BUILD_BOOLEAN_KEYS]);
+const ALLOWED_IMPORT_GROUP_KEYS = new Set(['templates', 'partials']);
+const ALLOWED_IMPORT_PROTOCOLS = new Set(['http:', 'https:']);
 let didWarnLegacyMarkdownKey = false;
 
 function isPlainObject(value) {
@@ -119,6 +121,71 @@ function validateBuildConfig(value, configPath) {
   return { ...value };
 }
 
+function validateImportUrl(url, configPath, groupKey, alias) {
+  if (typeof url !== 'string' || url.trim() === '') {
+    throw new Error(`Invalid imports.${groupKey} value for alias "${alias}" in "${configPath}": expected a non-empty URL string.`);
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid imports.${groupKey} URL for alias "${alias}" in "${configPath}": "${url}" is not a valid URL.`);
+  }
+
+  if (!ALLOWED_IMPORT_PROTOCOLS.has(parsed.protocol)) {
+    throw new Error(
+      `Invalid imports.${groupKey} URL for alias "${alias}" in "${configPath}": protocol "${parsed.protocol}" is not supported. Allowed protocols: http:, https:.`
+    );
+  }
+
+  return parsed.toString();
+}
+
+function validateImportGroup(value, configPath, groupKey) {
+  if (!isPlainObject(value)) {
+    throw new Error(`Invalid imports.${groupKey} in "${configPath}": expected an object of alias-to-URL mappings.`);
+  }
+
+  const normalized = {};
+
+  for (const [rawAlias, rawUrl] of Object.entries(value)) {
+    const alias = String(rawAlias).trim();
+    if (alias === '') {
+      throw new Error(`Invalid imports.${groupKey} in "${configPath}": alias keys must be non-empty.`);
+    }
+    normalized[alias] = validateImportUrl(rawUrl, configPath, groupKey, alias);
+  }
+
+  return normalized;
+}
+
+function validateImportsConfig(value, configPath) {
+  if (!isPlainObject(value)) {
+    throw new Error(`Invalid imports config in "${configPath}": expected an object.`);
+  }
+
+  const normalized = {};
+
+  for (const key of Object.keys(value)) {
+    if (!ALLOWED_IMPORT_GROUP_KEYS.has(key)) {
+      throw new Error(
+        `Unsupported imports group "${key}" in "${configPath}". Supported groups: ${Array.from(ALLOWED_IMPORT_GROUP_KEYS).join(', ')}.`
+      );
+    }
+  }
+
+  if (value.templates !== undefined) {
+    normalized.templates = validateImportGroup(value.templates, configPath, 'templates');
+  }
+
+  if (value.partials !== undefined) {
+    normalized.partials = validateImportGroup(value.partials, configPath, 'partials');
+  }
+
+  return normalized;
+}
+
 function validateConfig(rawConfig, configPath) {
   if (rawConfig == null) {
     return {};
@@ -133,7 +200,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.`
+        `Unsupported key "${key}" in "${configPath}". Supported keys: markdownit (recommended), markdown (legacy alias), build, imports.`
       );
     }
   }
@@ -221,6 +288,10 @@ function validateConfig(rawConfig, configPath) {
     normalizedConfig.build = validateBuildConfig(config.build, configPath);
   }
 
+  if (config.imports !== undefined) {
+    normalizedConfig.imports = validateImportsConfig(config.imports, configPath);
+  }
+
   return normalizedConfig;
 }
 

package/templates/default/README.md

@@ -228,12 +228,14 @@ Use these directly in `${...}` expressions:
 - `formatDate(value, format = "YYYYMMDDHHmmss", useUtc = true)`
 - `now(format = "YYYYMMDDHHmmss", useUtc = true)`
 - `sort(list, key, order = "asc")`
+- `chunk(list, size = 1, pad = false, fillValue = null)`
 - `md(content)`
 - `toQueryString(object)`
 
-Date format tokens: `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`.
+Date format tokens: `YYYY`, `MMM`, `MM`, `DD`, `D`, `HH`, `mm`, `ss`.
 `decodeURI`/`decodeURIComponent` return the original input when decoding fails.
 `sort` supports `order` as `asc` or `desc` (default: `asc`), accepts dot-path keys (for example `data.date`), and returns a new array.
+`chunk` splits arrays into rows of `size`; with `pad = true`, the last row is padded with `fillValue`.
 `md` returns raw rendered HTML from Markdown for template insertion.
 
 ## Static Files
@@ -242,3 +244,22 @@ Everything in `static/` is copied to `_site/`:
 
 - `static/css/theme.css` → `_site/css/theme.css`
 - `static/images/logo.png` → `_site/images/logo.png`
+
+## Theme Classes
+
+`static/css/theme.css` now includes multiple themes in one file.
+Set exactly one class on `body` (or `html`) to choose the active palette.
+
+Examples:
+- `slate-dark` (default in starter templates)
+- `slate-light`
+- `mono-dark`
+- `mono-light`
+- `catppuccin-mocha`
+- `catppuccin-macchiato`
+- `catppuccin-frappe`
+- `catppuccin-latte`
+- `github-dark`
+- `github-light`
+- `nord-dark`
+- `nord-light`

package/templates/default/static/css/theme.css

@@ -23,7 +23,7 @@ body {
   height: 100%;
   width: 100%;
   margin: 0;
-  font-family: system-ui, -apple-system, "Helvetica Neue", sans-serif;
+  font-family: var(--font-family-sans);
   display: flex;
   flex-direction: column;
   background-color: var(--background);
@@ -34,14 +34,16 @@ body {
 }
 
 a {
-  color: inherit;
-  text-decoration: underline;
+  color: var(--anchor-color);
+  text-decoration: var(--anchor-text-decoration);
   text-decoration-thickness: 1px;
   text-underline-offset: 4px;
   text-decoration-color: var(--muted-foreground);
 }
 
 a:hover {
+  color: var(--anchor-color-hover);
+  text-decoration: var(--anchor-text-decoration-hover);
   text-decoration-color: var(--foreground);
 }
 
@@ -51,6 +53,7 @@ a:hover {
 
 :root {
   --width-stretch: 100%;
+  --font-family-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
 
   --spacing-xs: 2px;
   --spacing-sm: 4px;
@@ -64,6 +67,7 @@ a:hover {
   --border-radius-lg: 8px;
   --border-radius-xl: 16px;
   --border-radius-f: 50%;
+  --border-radius-full: 9999px;
 
   --border-width-xs: 1px;
   --border-width-sm: 2px;
@@ -71,9 +75,9 @@ a:hover {
   --border-width-lg: 8px;
   --border-width-xl: 16px;
 
-  --shadow-sm: 0px 2px 6px rgba(0, 0, 0, .45);
-  --shadow-md: 0px 5px 12px rgba(0, 0, 0, .45);
-  --shadow-lg: 0px 10px 24px rgba(0, 0, 0, .45);
+  --shadow-sm: 0px 2px 6px rgba(0, 0, 0, .45), 0px 3px 5px rgba(0, 0, 0, .35), inset 0px .5px 0px rgba(255, 255, 255, .08), inset 0px 0px .5px rgba(255, 255, 255, .35);
+  --shadow-md: 0px 5px 12px rgba(0, 0, 0, .45), 0px 3px 5px rgba(0, 0, 0, .35), inset 0px .5px 0px rgba(255, 255, 255, .08), inset 0px 0px .5px rgba(255, 255, 255, .35);
+  --shadow-lg: 0px 10px 24px rgba(0, 0, 0, .45), 0px 3px 5px rgba(0, 0, 0, .35), inset 0px .5px 0px rgba(255, 255, 255, .08), inset 0px 0px .5px rgba(255, 255, 255, .35);
 
   --h1-font-size: 3rem;
   --h1-font-weight: 600;
@@ -115,10 +119,74 @@ a:hover {
   --xs-line-height: 1;
   --xs-letter-spacing: normal;
 
+  --anchor-color: inherit;
+  --anchor-color-hover: inherit;
+  --anchor-text-decoration: underline;
+  --anchor-text-decoration-hover: underline;
+
+  /* Sensible fallback in case no theme class is set. */
+  --primary: oklch(0.922 0 0);
+  --primary-foreground: oklch(0.305 0 0);
+  --secondary: oklch(0.269 0 0);
+  --secondary-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --destructive-foreground: oklch(0.985 0 0);
+  --background: rgb(29 29 29);
+  --foreground: rgb(242 242 242);
+  --muted: oklch(0.269 0 0);
+  --muted-foreground: oklch(0.708 0 0);
+  --accent: oklch(0.371 0 0);
+  --accent-foreground: oklch(0.985 0 0);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.556 0 0);
+}
+
+/* rtgl mono */
+.mono-light {
+  --primary: #171717;
+  --primary-foreground: #fafafa;
+  --secondary: #f5f5f5;
+  --secondary-foreground: #171717;
+  --destructive: #e40014;
+  --destructive-foreground: #fcf3f3;
+  --background: #ffffff;
+  --foreground: #0a0a0a;
+  --muted: #f5f5f5;
+  --muted-foreground: #737373;
+  --accent: #f5f5f5;
+  --accent-foreground: #171717;
+  --border: #e5e5e5;
+  --input: #e5e5e5;
+  --ring: #a1a1a1;
+}
+
+.mono-dark {
+  --background: #0a0a0a;
+  --foreground: #fafafa;
+  --primary: #e5e5e5;
+  --primary-foreground: #171717;
+  --secondary: #262626;
+  --secondary-foreground: #fafafa;
+  --muted: #262626;
+  --muted-foreground: #a1a1a1;
+  --accent: #404040;
+  --accent-foreground: #fafafa;
+  --destructive: #ff6568;
+  --destructive-foreground: #df2225;
+  --border: #ffffff1a;
+  --input: #ffffff26;
+  --ring: #737373;
+}
+
+/* rtgl slate */
+.slate-light {
   --primary: oklch(0.205 0 0);
   --primary-foreground: oklch(0.985 0 0);
   --secondary: oklch(0.97 0 0);
   --secondary-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.145 0 0);
   --background: oklch(1 0 0);
   --foreground: oklch(0.145 0 0);
   --muted: oklch(0.97 0 0);
@@ -130,9 +198,9 @@ a:hover {
   --ring: oklch(0.708 0 0);
 }
 
-.dark {
-  --background: oklch(0.145 0 0);
-  --foreground: oklch(0.985 0 0);
+.slate-dark {
+  --background: rgb(29 29 29);
+  --foreground: rgb(242 242 242);
   --primary: oklch(0.922 0 0);
   --primary-foreground: oklch(0.305 0 0);
   --secondary: oklch(0.269 0 0);
@@ -141,11 +209,160 @@ a:hover {
   --muted-foreground: oklch(0.708 0 0);
   --accent: oklch(0.371 0 0);
   --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --destructive-foreground: oklch(0.985 0 0);
   --border: oklch(1 0 0 / 10%);
   --input: oklch(1 0 0 / 15%);
   --ring: oklch(0.556 0 0);
 }
 
+/* catppuccin */
+.catppuccin-latte {
+  --primary: #1e66f5;
+  --primary-foreground: #eff1f5;
+  --secondary: #ccd0da;
+  --secondary-foreground: #4c4f69;
+  --destructive: #d20f39;
+  --destructive-foreground: #eff1f5;
+  --background: #eff1f5;
+  --foreground: #4c4f69;
+  --muted: #e6e9ef;
+  --muted-foreground: #6c6f85;
+  --accent: #dce0e8;
+  --accent-foreground: #4c4f69;
+  --border: #bcc0cc;
+  --input: #ccd0da;
+  --ring: #7287fd;
+}
+
+.catppuccin-frappe {
+  --primary: #8caaee;
+  --primary-foreground: #303446;
+  --secondary: #414559;
+  --secondary-foreground: #c6d0f5;
+  --destructive: #e78284;
+  --destructive-foreground: #303446;
+  --background: #303446;
+  --foreground: #c6d0f5;
+  --muted: #414559;
+  --muted-foreground: #a5adce;
+  --accent: #51576d;
+  --accent-foreground: #c6d0f5;
+  --border: #626880;
+  --input: #51576d;
+  --ring: #babbf1;
+}
+
+.catppuccin-macchiato {
+  --primary: #8aadf4;
+  --primary-foreground: #24273a;
+  --secondary: #363a4f;
+  --secondary-foreground: #cad3f5;
+  --destructive: #ed8796;
+  --destructive-foreground: #24273a;
+  --background: #24273a;
+  --foreground: #cad3f5;
+  --muted: #363a4f;
+  --muted-foreground: #a5adcb;
+  --accent: #494d64;
+  --accent-foreground: #cad3f5;
+  --border: #6e738d;
+  --input: #494d64;
+  --ring: #b7bdf8;
+}
+
+.catppuccin-mocha {
+  --background: #1e1e2e;
+  --foreground: #cdd6f4;
+  --primary: #89b4fa;
+  --primary-foreground: #1e1e2e;
+  --secondary: #313244;
+  --secondary-foreground: #cdd6f4;
+  --muted: #313244;
+  --muted-foreground: #a6adc8;
+  --accent: #45475a;
+  --accent-foreground: #cdd6f4;
+  --destructive: #f38ba8;
+  --destructive-foreground: #1e1e2e;
+  --border: #585b70;
+  --input: #45475a;
+  --ring: #b4befe;
+}
+
+/* common extras */
+.github-light {
+  --background: #ffffff;
+  --foreground: #1f2328;
+  --primary: #0969da;
+  --primary-foreground: #ffffff;
+  --secondary: #f6f8fa;
+  --secondary-foreground: #24292f;
+  --muted: #f6f8fa;
+  --muted-foreground: #57606a;
+  --accent: #ddf4ff;
+  --accent-foreground: #0969da;
+  --destructive: #cf222e;
+  --destructive-foreground: #ffffff;
+  --border: #d0d7de;
+  --input: #d0d7de;
+  --ring: #0969da;
+}
+
+.github-dark {
+  --background: #0d1117;
+  --foreground: #c9d1d9;
+  --primary: #58a6ff;
+  --primary-foreground: #0d1117;
+  --secondary: #21262d;
+  --secondary-foreground: #c9d1d9;
+  --muted: #21262d;
+  --muted-foreground: #8b949e;
+  --accent: #30363d;
+  --accent-foreground: #c9d1d9;
+  --destructive: #f85149;
+  --destructive-foreground: #0d1117;
+  --border: #30363d;
+  --input: #30363d;
+  --ring: #58a6ff;
+}
+
+.nord-light {
+  --background: #eceff4;
+  --foreground: #2e3440;
+  --primary: #5e81ac;
+  --primary-foreground: #eceff4;
+  --secondary: #e5e9f0;
+  --secondary-foreground: #2e3440;
+  --muted: #e5e9f0;
+  --muted-foreground: #4c566a;
+  --accent: #d8dee9;
+  --accent-foreground: #2e3440;
+  --destructive: #bf616a;
+  --destructive-foreground: #eceff4;
+  --border: #d8dee9;
+  --input: #d8dee9;
+  --ring: #81a1c1;
+}
+
+.nord-dark {
+  --background: #2e3440;
+  --foreground: #eceff4;
+  --primary: #88c0d0;
+  --primary-foreground: #2e3440;
+  --secondary: #3b4252;
+  --secondary-foreground: #eceff4;
+  --muted: #3b4252;
+  --muted-foreground: #d8dee9;
+  --accent: #434c5e;
+  --accent-foreground: #eceff4;
+  --destructive: #bf616a;
+  --destructive-foreground: #eceff4;
+  --border: #4c566a;
+  --input: #4c566a;
+  --ring: #88c0d0;
+}
+
+
 h1 {
   font-size: var(--h1-font-size);
   font-weight: var(--h1-font-weight);

package/templates/default/templates/base.yaml

@@ -7,8 +7,8 @@
         - $if site.assets.loadConstructStyleSheetsPolyfill:
             - script src="https://cdn.jsdelivr.net/npm/construct-style-sheets-polyfill@3.1.0/dist/adoptedStyleSheets.min.js":
         - $if site.assets.loadUiFromCdn:
-            - script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@0.1.32/dist/rettangoli-iife-ui.min.js":
-    - body.dark:
+            - script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/rettangoli-iife-ui.min.js":
+    - body.slate-dark:
         - rtgl-view w="f":
             - rtgl-view h="64":
             - rtgl-view w="f" ah="c":

package/templates/default/templates/post.yaml

@@ -7,8 +7,8 @@
         - $if site.assets.loadConstructStyleSheetsPolyfill:
             - script src="https://cdn.jsdelivr.net/npm/construct-style-sheets-polyfill@3.1.0/dist/adoptedStyleSheets.min.js":
         - $if site.assets.loadUiFromCdn:
-            - script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@0.1.32/dist/rettangoli-iife-ui.min.js":
-    - body.dark:
+            - script src="https://cdn.jsdelivr.net/npm/@rettangoli/ui@1.0.0-rc15/dist/rettangoli-iife-ui.min.js":
+    - body.slate-dark:
         - rtgl-view h="64":
         - rtgl-view w="f" ah="c":
             - rtgl-view d="h" g="xl" pb="lg" md-w="100vw" lg-w="768" w="1024" ph="lg":