@shevky/core 0.0.6 → 0.0.8

package/README.md

@@ -23,6 +23,56 @@ npm run build
 npm run dev
 ```
 
+## Build Memory Setting
+
+For large projects you can limit in-memory page buffering during build:
+
+```json
+{
+  "build": {
+    "pageBufferLimit": 20
+  }
+}
+```
+
+- `pageBufferLimit`: Number of rendered pages kept in memory before flushing to disk.
+- Default: `20`
+- Environment override: `SHEVKY_PAGE_BUFFER_LIMIT`
+
+## Output Aliases
+
+If you want to keep markdown generation (plugins/layout/meta) but publish an
+additional file path, you can define build aliases:
+
+```json
+{
+  "build": {
+    "outputAliases": [
+      { "from": "~/404/", "to": "~/404.html" },
+      { "from": "~/en/404/", "to": "~/en/404.html" }
+    ]
+  }
+}
+```
+
+- `from`: Generated page URL/path.
+- `to`: Extra copied output URL/path.
+
+## Content Root Directories
+
+You can copy selected `src/content` directories directly to dist root:
+
+```json
+{
+  "build": {
+    "contentRootDirectories": [".well-known"]
+  }
+}
+```
+
+- Default: `[".well-known"]`
+- Example: `src/content/.well-known/apple-app-site-association` -> `dist/.well-known/apple-app-site-association`
+
 ## Technical Documentation
 
 The tech documentation is preparing for Shevky with Shevky. You will find it under [Shevky Project](https://tatoglu.net/project/shevky) page.

package/engines/pluginEngine.js

@@ -1,4 +1,4 @@
-import { log as _log, plugin as _plugin } from "@shevky/base";
+import { i18n as _i18n, log as _log, plugin as _plugin } from "@shevky/base";
 import { PluginRegistry } from "../registries/pluginRegistry.js";
 import { ContentRegistry } from "../registries/contentRegistry.js";
 import { Project } from "../lib/project.js";
@@ -27,6 +27,11 @@ export class PluginEngine {
    */
   #_metaEngine;
 
+  /**
+   * @type {Record<string, any>}
+   */
+  #_runtimeContext = {};
+
   /**
    * @param {PluginRegistry} pluginRegistry
    * @param {ContentRegistry} contentRegistry
@@ -38,6 +43,22 @@ export class PluginEngine {
     this.#_metaEngine = metaEngine;
   }
 
+  /**
+   * @param {Record<string, any>} runtimeContext
+   * @returns {void}
+   */
+  setRuntimeContext(runtimeContext) {
+    this.#_runtimeContext =
+      runtimeContext && typeof runtimeContext === "object" ? runtimeContext : {};
+  }
+
+  /**
+   * @returns {void}
+   */
+  clearRuntimeContext() {
+    this.#_runtimeContext = {};
+  }
+
   /**
    * @param {string} hook
    * @returns {Promise<void>}
@@ -82,6 +103,7 @@ export class PluginEngine {
     return {
       ...baseContext,
       paths: this.#_project.toObject(),
+      i18n: _i18n,
 
       // content:load
       ...(hook === _plugin.hooks.CONTENT_LOAD
@@ -98,6 +120,7 @@ export class PluginEngine {
             contentIndex: this.#_contentRegistry.buildContentIndex(),
           }
         : {}),
+      ...this.#_runtimeContext,
     };
   }
 }

package/engines/renderEngine.js

@@ -16,6 +16,33 @@ import { PageRegistry } from "../registries/pageRegistry.js";
 
 /** @typedef {import("../types/index.d.ts").Placeholder} Placeholder */
 
+const PAGINATED_SCHEMA_TYPE_RULES = {
+  home: "collection",
+};
+
+/** @param {unknown} value */
+function normalizeSchemaType(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+
+  return value.trim().toLowerCase();
+}
+
+/** @param {unknown} schemaType @param {number} pageIndex */
+function resolvePaginatedSchemaType(schemaType, pageIndex) {
+  const normalizedType = normalizeSchemaType(schemaType);
+  if (!normalizedType) {
+    return "";
+  }
+
+  if (pageIndex <= 1) {
+    return normalizedType;
+  }
+
+  return PAGINATED_SCHEMA_TYPE_RULES[normalizedType] ?? normalizedType;
+}
+
 export class RenderEngine {
   /**
    * @type {TemplateRegistry}
@@ -181,7 +208,7 @@ export class RenderEngine {
    *  layout: string,
    *  template?: string,
    *  front: Record<string, unknown>,
-   *  view: Record<string, unknown>,
+   *  view?: Record<string, unknown>,
    *  html: string,
    *  sourcePath?: string,
    *  outputPath?: string,
@@ -436,6 +463,14 @@ export class RenderEngine {
         frontForPage.collectionType = collectionType;
       }
 
+      const paginatedSchemaType = resolvePaginatedSchemaType(
+        frontForPage.schemaType,
+        pageIndex,
+      );
+      if (paginatedSchemaType) {
+        frontForPage.schemaType = paginatedSchemaType;
+      }
+
       const renderedContent = await renderContentTemplate(
         templateName,
         contentHtml,
@@ -445,7 +480,11 @@ export class RenderEngine {
         listing,
       );
 
-      const pageMeta = metaEngine.buildPageMeta(frontForPage, lang, pageSlug);
+      const pageMeta = await metaEngine.buildPageMeta(
+        frontForPage,
+        lang,
+        pageSlug,
+      );
       const activeMenuKey = menuEngine.resolveActiveMenuKey(frontForPage);
       const view = buildViewPayload({
         lang,
@@ -687,7 +726,7 @@ export class RenderEngine {
             lang,
             dictionary,
           );
-          const pageMeta = metaEngine.buildPageMeta(front, lang, slug);
+          const pageMeta = await metaEngine.buildPageMeta(front, lang, slug);
           const layoutName = "default";
           const activeMenuKey = menuEngine.resolveActiveMenuKey(front);
           const view = buildViewPayload({
@@ -812,14 +851,7 @@ export class RenderEngine {
 
 /** @param {Record<string, any> | { raw?: unknown } | null | undefined} front */
 function normalizeFrontMatter(front) {
-  if (!front || typeof front !== "object") {
-    return {};
-  }
-
-  const raw =
-    "raw" in front && front.raw && typeof front.raw === "object"
-      ? front.raw
-      : front;
-
-  return typeof raw === "object" && raw !== null ? { ...raw } : {};
+  const frontRecord = _fmt.toRecord(front);
+  const rawRecord = _fmt.pickFirstRecord(frontRecord?.raw, frontRecord);
+  return rawRecord ? { ...rawRecord } : {};
 }

package/lib/contentFile.js

@@ -68,6 +68,10 @@ export class ContentFile {
     return this._header.template;
   }
 
+  get schemaType() {
+    return this._header.schemaType;
+  }
+
   get isFeatured() {
     return this._header.isFeatured;
   }

package/lib/contentHeader.js

@@ -104,6 +104,12 @@ export class ContentHeader {
       : "";
   }
 
+  get schemaType() {
+    return typeof this._frontMatter.schemaType === "string"
+      ? this._frontMatter.schemaType.trim().toLowerCase()
+      : "";
+  }
+
   get related() {
     return Array.isArray(this._frontMatter.related)
       ? this._frontMatter.related
@@ -124,9 +130,10 @@ export class ContentHeader {
 
   get tags() {
     const tags = _fmt.normalizeStringArray(this._frontMatter.tags);
-    return tags.map((t) => {
-      return _fmt.slugify(t);
-    });
+    const normalized = tags
+      .map((tag) => _fmt.slugify(tag))
+      .filter((tag) => tag.length > 0);
+    return [...new Set(normalized)];
   }
 
   get keywords() {
@@ -154,6 +161,10 @@ export class ContentHeader {
   }
 
   get isPolicy() {
+    if (this.schemaType) {
+      return _fmt.boolean(this.schemaType === "policy");
+    }
+
     const category =
       typeof this._frontMatter.category === "string"
         ? this._frontMatter.category.trim()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shevky/core",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "A minimal, dependency-light static site generator.",
   "type": "module",
   "main": "shevky.js",
@@ -36,12 +36,15 @@
   },
   "homepage": "https://github.com/shevky/core#readme",
   "dependencies": {
-    "@shevky/base": "^0.0.3",
-    "@types/node": "^20.11.30",
-    "@types/mustache": "^4.2.6",
-    "@types/html-minifier-terser": "^7.0.2",
+    "@shevky/base": "^0.0.5",
     "@tailwindcss/typography": "^0.5.19",
+    "@types/html-minifier-terser": "^7.0.2",
+    "@types/mustache": "^4.2.6",
+    "@types/node": "^20.11.30",
     "autoprefixer": "^10.4.21",
+    "command-line-args": "^6.0.1",
+    "command-line-usage": "^7.0.3",
+    "degit": "^2.8.4",
     "gray-matter": "^4.0.3",
     "highlight.js": "^11.11.1",
     "html-minifier-terser": "^6.1.0",
@@ -49,10 +52,7 @@
     "marked-highlight": "^2.2.3",
     "mustache": "^4.2.0",
     "postcss": "^8.5.6",
-    "tailwindcss": "^4.1.14",
-    "command-line-args": "^6.0.1",
-    "command-line-usage": "^7.0.3",
-    "degit": "^2.8.4"
+    "tailwindcss": "^4.1.14"
   },
   "engines": {
     "node": ">=18"

package/registries/contentRegistry.js

@@ -1,4 +1,4 @@
-import { io as _io, config as _cfg } from "@shevky/base";
+import { io as _io, config as _cfg, log as _log } from "@shevky/base";
 import matter from "gray-matter";
 
 import { ContentFile } from "../lib/contentFile.js";
@@ -37,6 +37,7 @@ export class ContentRegistry {
     }
 
     const files = await _io.directory.read(path);
+    let hasChanges = false;
     for (const entry of files) {
       if (!entry.endsWith(".md")) {
         continue;
@@ -49,10 +50,14 @@ export class ContentRegistry {
       }
 
       const contentFile = await this.#_loadFromFile(filePath);
-      this.#_cache.push(contentFile);
+      if (this.#_addUniqueContent(contentFile)) {
+        hasChanges = true;
+      }
     }
 
-    this.#_resetCaches();
+    if (hasChanges) {
+      this.#_resetCaches();
+    }
   }
 
   get count() {
@@ -72,8 +77,9 @@ export class ContentRegistry {
     }
 
     if (input instanceof ContentFile) {
-      this.#_cache.push(input);
-      this.#_resetCaches();
+      if (this.#_addUniqueContent(input)) {
+        this.#_resetCaches();
+      }
       return;
     }
 
@@ -92,8 +98,9 @@ export class ContentRegistry {
     const isValid = typeof input.isValid === "boolean" ? input.isValid : true;
 
     const contentFile = new ContentFile(header, content, sourcePath, isValid);
-    this.#_cache.push(contentFile);
-    this.#_resetCaches();
+    if (this.#_addUniqueContent(contentFile)) {
+      this.#_resetCaches();
+    }
   }
 
   /**
@@ -117,7 +124,7 @@ export class ContentRegistry {
         !file.isValid ||
         file.isDraft ||
         !file.isPublished ||
-        file.category !== "policy"
+        file.schemaType !== "policy"
       ) {
         continue;
       }
@@ -325,4 +332,48 @@ export class ContentRegistry {
     });
     return sorted;
   }
+
+  /**
+   * Adds content only if required fields exist and id+lang is unique.
+   * @param {ContentFile} contentFile
+   */
+  #_addUniqueContent(contentFile) {
+    if (!(contentFile instanceof ContentFile)) {
+      return false;
+    }
+
+    const id = typeof contentFile.id === "string" ? contentFile.id.trim() : "";
+    const lang =
+      typeof contentFile.lang === "string" ? contentFile.lang.trim() : "";
+    const sourcePath =
+      typeof contentFile.sourcePath === "string" &&
+      contentFile.sourcePath.trim().length > 0
+        ? contentFile.sourcePath
+        : "unknown source";
+
+    /** @type {string[]} */
+    const missingFields = [];
+    if (!id) missingFields.push("id");
+    if (!lang) missingFields.push("lang");
+    if (missingFields.length > 0) {
+      _log.warn(
+        `[content] Skipped content: missing required field(s): ${missingFields.join(", ")} (${sourcePath})`,
+      );
+      return false;
+    }
+
+    const hasExisting = this.#_cache.some((entry) => {
+      const existingId = typeof entry.id === "string" ? entry.id.trim() : "";
+      const existingLang =
+        typeof entry.lang === "string" ? entry.lang.trim() : "";
+      return existingId === id && existingLang === lang;
+    });
+
+    if (hasExisting) {
+      return false;
+    }
+
+    this.#_cache.push(contentFile);
+    return true;
+  }
 }

package/scripts/build.js

@@ -86,6 +86,7 @@ const DEFAULT_IMAGE = _cfg.seo.defaultImage;
 const FALLBACK_TAGLINES = { tr: "-", en: "-" };
 /** @type {Record<string, any>} */
 const COLLECTION_CONFIG = _cfg.content.collections;
+const PAGE_BUFFER_LIMIT = resolvePageBufferLimit();
 
 const GENERATED_PAGES = new Set();
 
@@ -145,16 +146,9 @@ function normalizeLogPath(pathValue) {
 
 /** @param {FrontMatter | { raw?: unknown } | null | undefined} front */
 function normalizeFrontMatter(front) {
-  if (!front || typeof front !== "object") {
-    return {};
-  }
-
-  const raw =
-    "raw" in front && front.raw && typeof front.raw === "object"
-      ? front.raw
-      : front;
-
-  return typeof raw === "object" && raw !== null ? { ...raw } : {};
+  const frontRecord = _fmt.toRecord(front);
+  const rawRecord = _fmt.pickFirstRecord(frontRecord?.raw, frontRecord);
+  return rawRecord ? { ...rawRecord } : {};
 }
 
 async function ensureDist() {
@@ -196,16 +190,14 @@ function injectAlternateLocaleMeta(html, locales) {
 function resolvePaginationSegment(lang) {
   /** @type {Record<string, string>} */
   const segmentConfig = _cfg?.content?.pagination?.segment ?? {};
-  if (
-    typeof segmentConfig[lang] === "string" &&
-    segmentConfig[lang].trim().length > 0
-  ) {
-    return segmentConfig[lang].trim();
+  const langSegment = _fmt.text(segmentConfig[lang]);
+  if (langSegment) {
+    return langSegment;
   }
 
-  const defaultSegment = segmentConfig[_i18n.default];
-  if (typeof defaultSegment === "string" && defaultSegment.trim().length > 0) {
-    return defaultSegment.trim();
+  const defaultSegment = _fmt.text(segmentConfig[_i18n.default]);
+  if (defaultSegment) {
+    return defaultSegment;
   }
 
   return "page";
@@ -252,7 +244,17 @@ async function writeHtmlFile(relativePath, html, meta = {}) {
   });
 }
 
-async function flushPages() {
+/** @param {{ force?: boolean }} [options] */
+async function flushPages(options = {}) {
+  const force = _fmt.boolean(options.force);
+  if (pageRegistry.count === 0) {
+    return;
+  }
+
+  if (!force && pageRegistry.count < PAGE_BUFFER_LIMIT) {
+    return;
+  }
+
   const pages = pageRegistry
     .list()
     .sort((a, b) => (a.outputPath || "").localeCompare(b.outputPath || ""));
@@ -262,6 +264,7 @@ async function flushPages() {
     }
     await writeHtmlFile(page.outputPath, page.html, page.writeMeta ?? {});
   }
+  pageRegistry.clear();
 }
 
 /** @param {string} html @param {string} langKey */
@@ -508,12 +511,12 @@ async function renderFragmentTemplate(
   templateName,
   listingOverride,
 ) {
-  const template =
-    typeof templateName === "string" && templateName.trim().length > 0
-      ? templateRegistry.getTemplate(TYPE_TEMPLATE, templateName.trim())
-      : null;
-  if (templateName && !template) {
-    _log.warn(`[build] Fragment template not found: ${templateName}`);
+  const resolvedTemplateName = _fmt.text(templateName);
+  const template = resolvedTemplateName
+    ? templateRegistry.getTemplate(TYPE_TEMPLATE, resolvedTemplateName)
+    : null;
+  if (resolvedTemplateName && !template) {
+    _log.warn(`[build] Fragment template not found: ${resolvedTemplateName}`);
   }
   const {
     normalizedFront,
@@ -523,7 +526,7 @@ async function renderFragmentTemplate(
     languageFlags,
     resolvedDictionary,
   } = buildContentRenderContext(front, lang, dictionary, listingOverride);
-  const decorated = decorateHtml(contentHtml, templateName ?? "");
+  const decorated = decorateHtml(contentHtml, resolvedTemplateName);
   const templateContent = template?.content ?? "{{{content.html}}}";
 
   return Mustache.render(
@@ -559,10 +562,7 @@ function buildContentRenderContext(front, lang, dictionary, listingOverride) {
   const baseFront = normalizeFrontMatter(front);
   /** @type {string[]} */
   const normalizedTags = Array.isArray(front.tags)
-    ? front.tags.filter(
-        (/** @type {string} */ tag) =>
-          typeof tag === "string" && tag.trim().length > 0,
-      )
+    ? front.tags.filter((/** @type {string} */ tag) => _fmt.hasText(tag))
     : [];
   const tagLinks = normalizedTags
     .map((/** @type {string} */ tag) => {
@@ -570,10 +570,8 @@ function buildContentRenderContext(front, lang, dictionary, listingOverride) {
       return url ? { label: tag, url } : null;
     })
     .filter(Boolean);
-  const categorySlug =
-    typeof front.category === "string" && front.category.trim().length > 0
-      ? _fmt.slugify(front.category)
-      : "";
+  const categoryLabel = _fmt.text(front.category);
+  const categorySlug = categoryLabel ? _fmt.slugify(categoryLabel) : "";
   const categoryUrl = categorySlug
     ? metaEngine.buildContentUrl(null, lang, categorySlug)
     : null;
@@ -584,10 +582,7 @@ function buildContentRenderContext(front, lang, dictionary, listingOverride) {
     tagLinks,
     hasTags: normalizedTags.length > 0,
     categoryUrl,
-    categoryLabel:
-      typeof front.category === "string" && front.category.trim().length > 0
-        ? front.category.trim()
-        : "",
+    categoryLabel,
     dateDisplay: _fmt.date(front.date, lang),
     updatedDisplay: _fmt.date(front.updated, lang),
     cover: front.cover ?? DEFAULT_IMAGE,
@@ -633,28 +628,29 @@ async function renderPage({ layoutName, view, front, lang, slug, writeMeta }) {
     minifyHtml,
   });
   const relativePath = buildOutputPath(front, lang, slug);
+  const templateName = _fmt.text(front?.template);
+  const pageType = _fmt.text(writeMeta?.type) || templateName;
+  const collectionType = normalizeCollectionTypeValue(front?.collectionType);
+  const slimFront = collectionType
+    ? /** @type {FrontMatter} */ ({ collectionType })
+    : /** @type {FrontMatter} */ ({});
   const page = renderEngine.createPage({
     kind: "page",
-    type:
-      typeof writeMeta?.type === "string" && writeMeta.type.length > 0
-        ? writeMeta.type
-        : typeof front?.template === "string"
-          ? front.template
-          : "",
+    type: pageType,
     lang,
     slug,
     canonical: metaEngine.buildContentUrl(front?.canonical, lang, slug),
     layout: layoutName,
-    template: typeof front?.template === "string" ? front.template : "",
-    front,
-    view,
+    template: templateName,
+    front: slimFront,
     html: finalHtml,
-    sourcePath: typeof writeMeta?.source === "string" ? writeMeta.source : "",
+    sourcePath: _fmt.text(writeMeta?.source),
     outputPath: relativePath,
     writeMeta,
   });
   GENERATED_PAGES.add(toPosixPath(relativePath));
   registerLegacyPaths(lang, slug);
+  await flushPages();
   return page;
 }
 
@@ -698,6 +694,150 @@ function toPosixPath(value) {
   return value.split(_io.path.separator).join("/");
 }
 
+/** @param {FrontMatter | { header?: FrontMatter } | null | undefined} input */
+function resolveFrontMatterInput(input) {
+  const inputRecord = _fmt.toRecord(input);
+  const resolved = _fmt.pickFirstRecord(
+    inputRecord?.raw,
+    inputRecord?.header,
+    inputRecord,
+  );
+  return /** @type {FrontMatter} */ (resolved ?? {});
+}
+
+/** @param {unknown} value */
+function normalizeSchemaTypeValue(value) {
+  if (typeof value !== "string") {
+    return "";
+  }
+
+  return value.trim().toLowerCase();
+}
+
+/**
+ * @param {Record<string, any> | null | undefined} front
+ * @param {Record<string, any> | null | undefined} [derived]
+ */
+function resolveSchemaTypeForGeneration(front, derived) {
+  const frontSchemaType = normalizeSchemaTypeValue(front?.schemaType);
+  if (_plugin.isSchemaType(frontSchemaType)) {
+    return frontSchemaType;
+  }
+
+  const derivedSchemaType = normalizeSchemaTypeValue(derived?.schemaType);
+  if (_plugin.isSchemaType(derivedSchemaType)) {
+    return derivedSchemaType;
+  }
+
+  const collectionType = normalizeCollectionTypeValue(
+    front?.collectionType ?? derived?.collectionType,
+  );
+  if (collectionType) {
+    return "collection";
+  }
+
+  return "page";
+}
+
+/**
+ * @param {Record<string, any> | null | undefined} front
+ * @param {Record<string, any> | null | undefined} [derived]
+ */
+function injectSchemaTypeForGeneration(front, derived) {
+  if (!front || typeof front !== "object") {
+    return;
+  }
+
+  const resolvedType = resolveSchemaTypeForGeneration(front, derived);
+  const currentFrontType = normalizeSchemaTypeValue(front.schemaType);
+
+  if (!_plugin.isSchemaType(currentFrontType)) {
+    try {
+      front.schemaType = resolvedType;
+    } catch {
+      // Ignore read-only objects.
+    }
+  }
+
+  if (derived && typeof derived === "object") {
+    const currentDerivedType = normalizeSchemaTypeValue(derived.schemaType);
+    if (!_plugin.isSchemaType(currentDerivedType)) {
+      try {
+        derived.schemaType = resolvedType;
+      } catch {
+        // Ignore read-only objects.
+      }
+    }
+  }
+}
+
+/** @param {FrontMatter} front @param {string} lang @param {string} slug */
+function buildMinimalPageMeta(front, lang, slug) {
+  const canonical = metaEngine.resolveUrl(
+    _fmt.text(front?.canonical) || metaEngine.buildContentUrl(null, lang, slug),
+  );
+  const alternates = metaEngine.buildAlternateUrlMap(front, lang, canonical);
+  const alternateLinks = metaEngine.buildAlternateLinkList(alternates);
+
+  return {
+    title: _fmt.text(front?.metaTitle) || _fmt.text(front?.title),
+    description: _fmt.text(front?.description),
+    robots: _fmt.text(front?.robots) || "index,follow",
+    canonical,
+    alternates,
+    alternateLinks,
+    og: _fmt.toRecord(front?.og, {}),
+    twitter: _fmt.toRecord(front?.twitter, {}),
+    structuredData: front?.structuredData ?? "",
+  };
+}
+
+/** @param {FrontMatter | { header?: FrontMatter } | null | undefined} input @param {string} lang @param {string} slug @param {Record<string, any> | null | undefined} [derived] */
+async function buildPageMetaWithPlugins(input, lang, slug, derived) {
+  const front = resolveFrontMatterInput(input);
+  const derivedFront =
+    derived && typeof derived === "object"
+      ? /** @type {Record<string, any>} */ (derived)
+      : front;
+  injectSchemaTypeForGeneration(front, derivedFront);
+  let pluginPageMeta = null;
+
+  pluginEngine.setRuntimeContext({
+    frontMatter: front,
+    derivedFrontMatter: derivedFront,
+    lang,
+    slug,
+    setPageMeta: (/** @type {Record<string, any>} */ meta) => {
+      pluginPageMeta = meta;
+    },
+  });
+
+  try {
+    await pluginEngine.execute(_plugin.hooks.PAGE_META);
+  } finally {
+    pluginEngine.clearRuntimeContext();
+  }
+
+  if (
+    pluginPageMeta &&
+    typeof pluginPageMeta === "object" &&
+    !Array.isArray(pluginPageMeta)
+  ) {
+    return /** @type {Record<string, any>} */ (pluginPageMeta);
+  }
+
+  const existingPageMeta = _fmt.toRecord(front?.pageMeta);
+  if (existingPageMeta) {
+    return existingPageMeta;
+  }
+
+  _log.debug(
+    `[build] Missing page meta from '${_plugin.hooks.PAGE_META}' hook for lang='${lang}' slug='${slug}'. Using front matter as page meta.`,
+  );
+
+  return buildMinimalPageMeta(front, lang, slug);
+}
+
 /** @param {FrontMatter} front @param {string} lang */
 function buildCollectionListing(front, lang) {
   const normalizedLang = lang ?? _i18n.default;
@@ -724,19 +864,13 @@ function buildCollectionListing(front, lang) {
 function buildSeriesListing(front, lang) {
   /** @type {string[]} */
   const relatedSource = Array.isArray(front?.related) ? front.related : [];
-  const seriesName =
-    typeof front?.seriesTitle === "string" &&
-    front.seriesTitle.trim().length > 0
-      ? front.seriesTitle.trim()
-      : typeof front?.series === "string"
-        ? front.series.trim()
-        : "";
-  const currentId = typeof front?.id === "string" ? front.id.trim() : "";
+  const seriesName = _fmt.text(front?.seriesTitle) || _fmt.text(front?.series);
+  const currentId = _fmt.text(front?.id);
   /** @type {Array<{ id: string, label: string, url: string, hasUrl?: boolean, isCurrent: boolean, isPlaceholder: boolean }>} */
   const items = [];
 
   relatedSource.forEach((/** @type {string} */ entry) => {
-    const value = typeof entry === "string" ? entry.trim() : "";
+    const value = _fmt.text(entry);
     if (!value) {
       items.push({
         id: "",
@@ -804,19 +938,16 @@ function resolveCollectionType(front, items, fallback) {
   }
 
   if (Array.isArray(items)) {
-    const entryWithType = items.find(
-      (entry) =>
-        typeof entry?.type === "string" && entry.type.trim().length > 0,
-    );
-    const entryType =
-      typeof entryWithType?.type === "string" ? entryWithType.type.trim() : "";
+    const entryWithType = items.find((entry) => _fmt.hasText(entry?.type));
+    const entryType = _fmt.text(entryWithType?.type);
     if (entryType) {
       return entryType.toLowerCase();
     }
   }
 
-  if (typeof fallback === "string" && fallback.trim().length > 0) {
-    return fallback.trim().toLowerCase();
+  const normalizedFallback = _fmt.text(fallback);
+  if (normalizedFallback) {
+    return normalizedFallback.toLowerCase();
   }
 
   return "";
@@ -858,20 +989,23 @@ function resolveListingKey(front) {
 function resolveListingEmpty(front, lang) {
   if (!front) return "";
   const { listingEmpty } = front;
-  if (typeof listingEmpty === "string" && listingEmpty.trim().length > 0) {
-    return listingEmpty.trim();
+  const direct = _fmt.text(listingEmpty);
+  if (direct) {
+    return direct;
   }
   if (listingEmpty && typeof listingEmpty === "object") {
     const listingEmptyMap = /** @type {Record<string, string>} */ (
       listingEmpty
     );
     const localized = listingEmptyMap[lang];
-    if (typeof localized === "string" && localized.trim().length > 0) {
-      return localized.trim();
+    const localizedValue = _fmt.text(localized);
+    if (localizedValue) {
+      return localizedValue;
     }
     const fallback = listingEmptyMap[_i18n.default];
-    if (typeof fallback === "string" && fallback.trim().length > 0) {
-      return fallback.trim();
+    const fallbackValue = _fmt.text(fallback);
+    if (fallbackValue) {
+      return fallbackValue;
     }
   }
   return "";
@@ -880,16 +1014,95 @@ function resolveListingEmpty(front, lang) {
 /** @param {FrontMatter} front */
 function resolveListingHeading(front) {
   if (!front) return "";
+  return _fmt.text(front.listHeading) || _fmt.text(front.title);
+}
+
+function resolvePageBufferLimit() {
+  const envValue = Number.parseInt(
+    process.env.SHEVKY_PAGE_BUFFER_LIMIT ?? "",
+    10,
+  );
+
+  if (Number.isFinite(envValue) && envValue > 0) {
+    return envValue;
+  }
+
+  const configValue = Number.parseInt(
+    String(_cfg?.build?.pageBufferLimit ?? ""),
+    10,
+  );
+
+  if (Number.isFinite(configValue) && configValue > 0) {
+    return configValue;
+  }
+
+  return 20;
+}
+
+/** @param {unknown} value */
+function resolveAliasOutputPath(value) {
+  const raw = _fmt.text(value);
+  if (!raw) {
+    return null;
+  }
+
+  const relative = metaEngine.canonicalToRelativePath(raw);
+  if (relative) {
+    const lastSegment = relative.split("/").pop()?.trim() ?? "";
+    if (lastSegment.includes(".")) {
+      return relative;
+    }
+    return _io.path.combine(relative, "index.html");
+  }
+
+  const normalizedRaw = raw.trim();
   if (
-    typeof front.listHeading === "string" &&
-    front.listHeading.trim().length > 0
+    normalizedRaw === "/" ||
+    normalizedRaw === "~/" ||
+    /^https?:\/\/[^/]+\/?$/i.test(normalizedRaw)
   ) {
-    return front.listHeading.trim();
+    return "index.html";
   }
-  if (typeof front.title === "string" && front.title.trim().length > 0) {
-    return front.title.trim();
+
+  return null;
+}
+
+async function applyOutputAliases() {
+  const aliases = Array.isArray(_cfg?.build?.outputAliases)
+    ? _cfg.build.outputAliases
+    : [];
+
+  for (const entry of aliases) {
+    const alias = _fmt.toRecord(entry);
+    if (!alias) {
+      continue;
+    }
+
+    const sourceRelative = resolveAliasOutputPath(alias.from);
+    const targetRelative = resolveAliasOutputPath(alias.to);
+    if (!sourceRelative || !targetRelative || sourceRelative === targetRelative) {
+      continue;
+    }
+
+    const sourcePath = _io.path.combine(DIST_DIR, sourceRelative);
+    if (!(await _io.file.exists(sourcePath))) {
+      _log.warn(
+        `[build] Output alias source not found: ${normalizeLogPath(sourcePath)}`,
+      );
+      continue;
+    }
+
+    const targetPath = _io.path.combine(DIST_DIR, targetRelative);
+    await _io.directory.create(_io.path.name(targetPath));
+    await _io.file.copy(sourcePath, targetPath);
+    GENERATED_PAGES.add(toPosixPath(targetRelative));
+
+    _log.step("COPY_ALIAS", {
+      source: normalizeLogPath(sourcePath),
+      target: normalizeLogPath(targetPath),
+      type: "alias",
+    });
   }
-  return "";
 }
 
 async function buildContentPages() {
@@ -932,10 +1145,7 @@ async function buildContentPages() {
     const rawFront = normalizeFrontMatter(file.header);
     const shouldBuildFragment = _fmt.boolean(rawFront.fragment);
     const fragmentTemplateName =
-      typeof rawFront.fragmentTemplate === "string" &&
-      rawFront.fragmentTemplate.trim().length > 0
-        ? rawFront.fragmentTemplate.trim()
-        : file.template;
+      _fmt.text(rawFront.fragmentTemplate) || file.template;
 
     if (file.template === "collection" || file.template === "home") {
       await renderEngine.buildPaginatedCollectionPages({
@@ -960,7 +1170,15 @@ async function buildContentPages() {
             buildEasterEggPayload,
           }),
         renderPage,
-        metaEngine,
+        metaEngine: {
+          buildPageMeta: async (frontForPage, pageLang, pageSlug) =>
+            buildPageMetaWithPlugins(
+              frontForPage,
+              pageLang,
+              pageSlug,
+              frontForPage,
+            ),
+        },
         menuEngine,
         resolveListingKey,
         resolveListingEmpty,
@@ -981,10 +1199,11 @@ async function buildContentPages() {
       file.lang,
       dictionary,
     );
-    const pageMeta = metaEngine.buildPageMeta(
+    const pageMeta = await buildPageMetaWithPlugins(
       file.header,
       file.lang,
       file.slug,
+      file,
     );
     const activeMenuKey = menuEngine.resolveActiveMenuKey(file.header);
     const view = renderEngine.buildViewPayload(
@@ -1043,10 +1262,7 @@ async function buildContentPages() {
             minifyHtml,
           },
         );
-        const fragmentLang =
-          typeof file.lang === "string" && file.lang.trim().length > 0
-            ? file.lang.trim()
-            : _i18n.default;
+        const fragmentLang = _fmt.text(file.lang) || _i18n.default;
         const fragmentPath = _io.path.combine(
           FRAGMENTS_DIR,
           fragmentLang,
@@ -1081,7 +1297,15 @@ async function buildContentPages() {
         buildEasterEggPayload,
       }),
     renderPage,
-    metaEngine,
+    metaEngine: {
+      buildPageMeta: async (frontForPage, pageLang, pageSlug) =>
+        buildPageMetaWithPlugins(
+          frontForPage,
+          pageLang,
+          pageSlug,
+          frontForPage,
+        ),
+    },
     menuEngine,
     resolveCollectionType,
     normalizeCollectionTypeValue,
@@ -1097,15 +1321,9 @@ async function buildContentPages() {
 function resolveCollectionDisplayKey(configKey, defaultKey, items) {
   if (configKey === "series" && Array.isArray(items)) {
     const entryWithTitle = items.find(
-      (entry) =>
-        entry &&
-        typeof entry.seriesTitle === "string" &&
-        entry.seriesTitle.trim().length > 0,
+      (entry) => entry && _fmt.hasText(entry.seriesTitle),
     );
-    const seriesTitle =
-      typeof entryWithTitle?.seriesTitle === "string"
-        ? entryWithTitle.seriesTitle.trim()
-        : "";
+    const seriesTitle = _fmt.text(entryWithTitle?.seriesTitle);
     if (seriesTitle) {
       return seriesTitle;
     }
@@ -1162,6 +1380,14 @@ async function copyHtmlRecursive(currentDir = SRC_DIR, relative = "") {
   for (const entry of entries) {
     const fullPath = _io.path.combine(currentDir, entry);
     const relPath = relative ? _io.path.combine(relative, entry) : entry;
+    const normalizedRelPath = toPosixPath(relPath);
+
+    if (
+      normalizedRelPath === "content" ||
+      normalizedRelPath.startsWith("content/")
+    ) {
+      continue;
+    }
 
     if (!entry.endsWith(".html")) {
       continue;
@@ -1209,6 +1435,83 @@ async function copyHtmlRecursive(currentDir = SRC_DIR, relative = "") {
   }
 }
 
+/** @param {string} currentDir */
+async function copyContentStaticRecursive(currentDir = CONTENT_DIR) {
+  if (!(await _io.directory.exists(currentDir))) {
+    return;
+  }
+
+  const contentRootDirectories = resolveContentRootDirectories();
+  const entries = await _io.directory.read(currentDir);
+  for (const entry of entries) {
+    const fullPath = _io.path.combine(currentDir, entry);
+    const relPath = entry;
+    const normalizedRelPath = toPosixPath(relPath);
+    const isXml = entry.endsWith(".xml");
+
+    if (
+      contentRootDirectories.some(
+        (directory) =>
+          normalizedRelPath === directory ||
+          normalizedRelPath.startsWith(`${directory}/`),
+      )
+    ) {
+      continue;
+    }
+
+    if (!(entry.endsWith(".html") || entry.endsWith(".xml"))) {
+      continue;
+    }
+
+    if (GENERATED_PAGES.has(toPosixPath(relPath))) {
+      continue;
+    }
+
+    const raw = await _io.file.read(fullPath);
+    const transformed = isXml
+      ? raw
+      : await renderEngine.transformHtml(raw, {
+          versionToken,
+          minifyHtml,
+        });
+
+    await writeHtmlFile(relPath, transformed, {
+      action: "COPY_HTML",
+      type: isXml ? "content-xml" : "content-static",
+      source: fullPath,
+      lang: _i18n.default,
+      inputBytes: byteLength(transformed),
+    });
+  }
+}
+
+function resolveContentRootDirectories() {
+  const configured = Array.isArray(_cfg?.build?.contentRootDirectories)
+    ? _cfg.build.contentRootDirectories
+    : [".well-known"];
+
+  return [...new Set(configured.map((entry) => _fmt.text(entry)).filter(Boolean))];
+}
+
+async function copyContentRootDirectories() {
+  const directories = resolveContentRootDirectories();
+  for (const directory of directories) {
+    const sourceDir = _io.path.combine(CONTENT_DIR, directory);
+    if (!(await _io.directory.exists(sourceDir))) {
+      continue;
+    }
+
+    const targetDir = _io.path.combine(DIST_DIR, directory);
+    await _io.directory.copy(sourceDir, targetDir);
+
+    _log.step("COPY_DIR", {
+      source: normalizeLogPath(sourceDir),
+      target: normalizeLogPath(targetDir),
+      type: "content-root-directory",
+    });
+  }
+}
+
 async function copyStaticAssets() {
   if (!(await _io.directory.exists(ASSETS_DIR))) {
     return;
@@ -1243,7 +1546,10 @@ async function main() {
 
   await buildContentPages();
   await copyHtmlRecursive();
-  await flushPages();
+  await copyContentStaticRecursive();
+  await copyContentRootDirectories();
+  await flushPages({ force: true });
+  await applyOutputAliases();
 }
 
 const API = {

package/scripts/main.js

@@ -4,7 +4,7 @@ import _cli from "./cli.js";
 import _build from "./build.js";
 import _init from "./init.js";
 
-const VERSION = "0.0.6";
+const VERSION = "0.0.8";
 
 const __filename = _io.url.toPath(import.meta.url);
 const __dirname = _io.path.name(__filename);

package/types/index.d.ts

@@ -55,6 +55,13 @@ export interface PluginExecutionContext extends BasePluginContext {
     Record<string, { id: string; lang: string; title: string; canonical: string }>
   >;
   footerPolicies?: Record<string, FooterPolicy[]>;
+  i18n?: Record<string, any>;
+  frontMatter?: FrontMatter;
+  derivedFrontMatter?: FrontMatter | Record<string, any>;
+  lang?: string;
+  slug?: string;
+  pageMeta?: Record<string, any> | null;
+  setPageMeta?: (meta: Record<string, any>) => void;
 }
 
 export type Placeholder = {