mdorigin 0.1.3 → 0.1.5

package/README.md

@@ -77,6 +77,8 @@ Current stable hooks are:
 - `renderPage(page, context, next)`
 - `transformHtml(html, context)`
 
+All render hooks that receive a `RenderHookContext` (`renderHeader`, `renderFooter`, `renderPage`, and `transformHtml`) can read the normalized markdown frontmatter for the current document via `context.page.meta`, including custom fields such as `syndication`.
+
 The intended boundary is:
 
 - `mdorigin` owns routing and normalized content semantics

package/dist/cli/build-cloudflare.js

@@ -4,6 +4,10 @@ import { writeCloudflareBundle } from '../cloudflare.js';
 import { applySiteConfigFrontmatterDefaults, loadUserSiteConfig, } from '../core/site-config.js';
 export async function runBuildCloudflareCommand(argv) {
     const args = parseArgs(argv);
+    if (args.help) {
+        console.log('Usage: mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search]');
+        return;
+    }
     if (!args.root) {
         console.error('Usage: mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search]');
         process.exitCode = 1;
@@ -31,6 +35,10 @@ function parseArgs(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         const nextValue = argv[index + 1];
+        if (argument === '--help' || argument === '-h') {
+            result.help = true;
+            continue;
+        }
         if (argument === '--root' && nextValue) {
             result.root = nextValue;
             index += 1;
@@ -49,7 +57,9 @@ function parseArgs(argv) {
         if (argument === '--search' && nextValue) {
             result.search = nextValue;
             index += 1;
+            continue;
         }
+        throw new Error(`Unknown argument for mdorigin build cloudflare: ${argument}`);
     }
     return result;
 }

package/dist/cli/build-index.js

@@ -3,6 +3,10 @@ import { buildDirectoryIndexes } from '../index-builder.js';
 import { loadUserSiteConfig } from '../core/site-config.js';
 export async function runBuildIndexCommand(argv) {
     const args = parseArgs(argv);
+    if (args.help) {
+        console.log('Usage: mdorigin build index (--root <content-dir> | --dir <content-dir>) [--config <config-file>]');
+        return;
+    }
     if (!args.root && !args.dir) {
         console.error('Usage: mdorigin build index (--root <content-dir> | --dir <content-dir>) [--config <config-file>]');
         process.exitCode = 1;
@@ -30,6 +34,10 @@ function parseArgs(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         const nextValue = argv[index + 1];
+        if (argument === '--help' || argument === '-h') {
+            result.help = true;
+            continue;
+        }
         if (argument === '--root' && nextValue) {
             result.root = nextValue;
             index += 1;
@@ -43,7 +51,9 @@ function parseArgs(argv) {
         if (argument === '--config' && nextValue) {
             result.config = nextValue;
             index += 1;
+            continue;
         }
+        throw new Error(`Unknown argument for mdorigin build index: ${argument}`);
     }
     return result;
 }

package/dist/cli/build-search.js

@@ -4,6 +4,10 @@ import { applySiteConfigFrontmatterDefaults, loadUserSiteConfig, } from '../core
 import { createFileSystemContentStore } from '../adapters/node.js';
 export async function runBuildSearchCommand(rawArgs) {
     const args = parseArgs(rawArgs);
+    if (args.help) {
+        console.log('Usage: mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]');
+        return;
+    }
     if (!args.root) {
         throw new Error('Usage: mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]');
     }
@@ -25,15 +29,27 @@ export async function runBuildSearchCommand(rawArgs) {
 }
 function parseArgs(rawArgs) {
     const parsed = {};
+    const supportedFlags = new Set(['root', 'out', 'embedding-backend', 'model', 'config']);
     for (let index = 0; index < rawArgs.length; index += 1) {
         const arg = rawArgs[index];
+        if (arg === '--help' || arg === '-h') {
+            parsed.help = 'true';
+            continue;
+        }
         if (arg.startsWith('--')) {
+            const flag = arg.slice(2);
+            if (!supportedFlags.has(flag)) {
+                throw new Error(`Unknown argument for mdorigin build search: ${arg}`);
+            }
             const value = rawArgs[index + 1];
             if (value && !value.startsWith('--')) {
-                parsed[arg.slice(2)] = value;
+                parsed[flag] = value;
                 index += 1;
+                continue;
             }
+            throw new Error(`Incomplete argument for mdorigin build search: ${arg}`);
         }
+        throw new Error(`Unknown positional argument for mdorigin build search: ${arg}`);
     }
     return {
         root: parsed.root,
@@ -41,5 +57,6 @@ function parseArgs(rawArgs) {
         embeddingBackend: parsed['embedding-backend'],
         model: parsed.model,
         config: parsed.config,
+        help: parsed.help === 'true',
     };
 }

package/dist/cli/dev.js

@@ -4,6 +4,10 @@ import { applySiteConfigFrontmatterDefaults, loadUserSiteConfig, } from '../core
 import { createSearchApiFromDirectory } from '../search.js';
 export async function runDevCommand(argv) {
     const args = parseArgs(argv);
+    if (args.help) {
+        console.log('Usage: mdorigin dev --root <content-dir> [--port 3000] [--config <config-file>] [--search ./dist/search]');
+        return;
+    }
     if (!args.root) {
         console.error('Usage: mdorigin dev --root <content-dir> [--port 3000] [--config <config-file>] [--search ./dist/search]');
         process.exitCode = 1;
@@ -39,6 +43,10 @@ function parseArgs(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         const nextValue = argv[index + 1];
+        if (argument === '--help' || argument === '-h') {
+            result.help = true;
+            continue;
+        }
         if (argument === '--root' && nextValue) {
             result.root = nextValue;
             index += 1;
@@ -57,7 +65,9 @@ function parseArgs(argv) {
         if (argument === '--search' && nextValue) {
             result.search = nextValue;
             index += 1;
+            continue;
         }
+        throw new Error(`Unknown argument for mdorigin dev: ${argument}`);
     }
     return result;
 }

package/dist/cli/help.d.ts

@@ -0,0 +1,4 @@
+export declare const ROOT_USAGE_LINES: string[];
+export declare const BUILD_USAGE_LINES: string[];
+export declare const INIT_USAGE_LINES: string[];
+export declare function printUsage(lines: readonly string[], error?: boolean): void;

package/dist/cli/help.js

@@ -0,0 +1,32 @@
+export const ROOT_USAGE_LINES = [
+    'Usage:',
+    '  mdorigin dev --root <content-dir> [--port 3000] [--config <config-file>] [--search ./dist/search]',
+    '  mdorigin build index (--root <content-dir> | --dir <content-dir>) [--config <config-file>]',
+    '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]',
+    '  mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search]',
+    '  mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--force]',
+    '  mdorigin search --index <search-dir> [--top-k 10] <query>',
+    '  mdorigin version',
+    '',
+    'Global options:',
+    '  -h, --help     Show help',
+    '  -V, --version  Show version',
+];
+export const BUILD_USAGE_LINES = [
+    'Usage:',
+    '  mdorigin build index (--root <content-dir> | --dir <content-dir>) [--config <config-file>]',
+    '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]',
+    '  mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search]',
+];
+export const INIT_USAGE_LINES = [
+    'Usage:',
+    '  mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--force]',
+];
+export function printUsage(lines, error = false) {
+    const output = lines.join('\n');
+    if (error) {
+        console.error(output);
+        return;
+    }
+    console.log(output);
+}

package/dist/cli/init-cloudflare.js

@@ -3,6 +3,10 @@ import { readFile } from 'node:fs/promises';
 import { initCloudflareProject } from '../cloudflare.js';
 export async function runInitCloudflareCommand(argv) {
     const args = parseArgs(argv);
+    if (args.help) {
+        console.log('Usage: mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--force]');
+        return;
+    }
     const projectDir = path.resolve(args.dir ?? '.');
     const workerEntry = path.resolve(projectDir, args.entry ?? 'dist/cloudflare/worker.mjs');
     const siteTitle = args.name ? undefined : await inferSiteTitleFromWorkerEntry(workerEntry);
@@ -21,6 +25,10 @@ function parseArgs(argv) {
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         const nextValue = argv[index + 1];
+        if (argument === '--help' || argument === '-h') {
+            result.help = true;
+            continue;
+        }
         if (argument === '--dir' && nextValue) {
             result.dir = nextValue;
             index += 1;
@@ -43,7 +51,9 @@ function parseArgs(argv) {
         }
         if (argument === '--force') {
             result.force = true;
+            continue;
         }
+        throw new Error(`Unknown argument for mdorigin init cloudflare: ${argument}`);
     }
     return result;
 }

package/dist/cli/main.js

@@ -1,16 +1,42 @@
 #!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { runBuildIndexCommand } from './build-index.js';
 import { runBuildCloudflareCommand } from './build-cloudflare.js';
 import { runBuildSearchCommand } from './build-search.js';
 import { runDevCommand } from './dev.js';
+import { BUILD_USAGE_LINES, INIT_USAGE_LINES, ROOT_USAGE_LINES, printUsage } from './help.js';
 import { runInitCloudflareCommand } from './init-cloudflare.js';
 import { runSearchCommand } from './search.js';
 async function main() {
-    const [command, subcommand, ...rest] = process.argv.slice(2);
+    const argv = process.argv.slice(2);
+    const [command, subcommand, ...rest] = argv;
+    if (argv.length === 0 || command === 'help' || command === '--help' || command === '-h') {
+        if (command === 'help' && subcommand === 'build') {
+            printUsage(BUILD_USAGE_LINES);
+            return;
+        }
+        if (command === 'help' && subcommand === 'init') {
+            printUsage(INIT_USAGE_LINES);
+            return;
+        }
+        printUsage(ROOT_USAGE_LINES);
+        return;
+    }
+    if (command === '--version' || command === '-V' || command === 'version') {
+        console.log(getCliVersion());
+        return;
+    }
     if (command === 'dev') {
         await runDevCommand([subcommand, ...rest].filter(isDefined));
         return;
     }
+    if (command === 'build' && (subcommand === '--help' || subcommand === '-h' || !subcommand)) {
+        printUsage(BUILD_USAGE_LINES, subcommand === undefined);
+        process.exitCode = subcommand === undefined ? 1 : 0;
+        return;
+    }
     if (command === 'build' && subcommand === 'cloudflare') {
         await runBuildCloudflareCommand(rest);
         return;
@@ -27,19 +53,17 @@ async function main() {
         await runInitCloudflareCommand(rest);
         return;
     }
+    if (command === 'init' && (subcommand === '--help' || subcommand === '-h' || !subcommand)) {
+        printUsage(INIT_USAGE_LINES, subcommand === undefined);
+        process.exitCode = subcommand === undefined ? 1 : 0;
+        return;
+    }
     if (command === 'search') {
         await runSearchCommand([subcommand, ...rest].filter(isDefined));
         return;
     }
-    console.error([
-        'Usage:',
-        '  mdorigin dev --root <content-dir> [--port 3000] [--config <config-file>] [--search ./dist/search]',
-        '  mdorigin build index (--root <content-dir> | --dir <content-dir>) [--config <config-file>]',
-        '  mdorigin build search --root <content-dir> [--out ./dist/search] [--embedding-backend model2vec|hashing] [--model sentence-transformers/all-MiniLM-L6-v2] [--config <config-file>]',
-        '  mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search]',
-        '  mdorigin init cloudflare [--dir .] [--entry ./dist/cloudflare/worker.mjs] [--name <worker-name>] [--compatibility-date 2026-03-20] [--force]',
-        '  mdorigin search --index <search-dir> [--top-k 10] <query>',
-    ].join('\n'));
+    console.error(`Unknown command: ${argv.join(' ')}`);
+    printUsage(ROOT_USAGE_LINES, true);
     process.exitCode = 1;
 }
 void main().catch((error) => {
@@ -49,3 +73,8 @@ void main().catch((error) => {
 function isDefined(value) {
     return value !== undefined;
 }
+function getCliVersion() {
+    const packageJsonPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    return packageJson.version ?? '0.0.0';
+}

package/dist/cli/search.js

@@ -2,6 +2,10 @@ import path from 'node:path';
 import { searchBundle } from '../search.js';
 export async function runSearchCommand(rawArgs) {
     const args = parseArgs(rawArgs);
+    if (args.help) {
+        console.log('Usage: mdorigin search --index <search-dir> [--top-k 10] <query>');
+        return;
+    }
     if (!args.indexDir || !args.query) {
         throw new Error('Usage: mdorigin search --index <search-dir> [--top-k 10] <query>');
     }
@@ -15,15 +19,25 @@ export async function runSearchCommand(rawArgs) {
 function parseArgs(rawArgs) {
     const flags = {};
     const positionals = [];
+    const supportedFlags = new Set(['index', 'top-k']);
     for (let index = 0; index < rawArgs.length; index += 1) {
         const arg = rawArgs[index];
+        if (arg === '--help' || arg === '-h') {
+            flags.help = 'true';
+            continue;
+        }
         if (arg.startsWith('--')) {
+            const flag = arg.slice(2);
+            if (!supportedFlags.has(flag)) {
+                throw new Error(`Unknown argument for mdorigin search: ${arg}`);
+            }
             const value = rawArgs[index + 1];
             if (value && !value.startsWith('--')) {
-                flags[arg.slice(2)] = value;
+                flags[flag] = value;
                 index += 1;
+                continue;
             }
-            continue;
+            throw new Error(`Incomplete argument for mdorigin search: ${arg}`);
         }
         positionals.push(arg);
     }
@@ -32,5 +46,6 @@ function parseArgs(rawArgs) {
         indexDir: flags.index,
         topK: Number.isInteger(topK) && topK > 0 ? topK : undefined,
         query: positionals.join(' ').trim(),
+        help: flags.help === 'true',
     };
 }

package/dist/core/extensions.d.ts

@@ -1,4 +1,4 @@
-import type { ManagedIndexEntry } from './markdown.js';
+import type { ManagedIndexEntry, ParsedDocumentMeta } from './markdown.js';
 import type { EditLinkConfig, ResolvedSiteConfig, SiteLogo, SiteNavItem, SiteSocialLink } from './site-config.js';
 import type { TemplateName } from '../html/template-kind.js';
 import type { BuiltInThemeName } from '../html/theme.js';
@@ -21,6 +21,7 @@ export interface PageRenderModel {
     socialImage?: string;
     logo?: SiteLogo;
     title: string;
+    meta: ParsedDocumentMeta;
     bodyHtml: string;
     summary?: string;
     date?: string;

package/dist/core/request-handler.js

@@ -150,6 +150,7 @@ function buildPageRenderModel(options) {
         socialImage: options.siteConfig.socialImage,
         logo: options.siteConfig.logo,
         title: getDocumentTitle(options.parsed),
+        meta: options.parsed.meta,
         bodyHtml: options.renderedBodyHtml,
         summary: options.siteConfig.showSummary === false
             ? undefined

package/dist/index-builder.js

@@ -78,6 +78,9 @@ export async function buildManagedIndexBlock(directoryPath, plugins = []) {
         const fullPath = path.join(directoryPath, entry.name);
         const entryStats = await stat(fullPath);
         if (entryStats.isDirectory()) {
+            if (!(await hasMeaningfulDirectoryContent(fullPath))) {
+                continue;
+            }
             const resolvedEntry = await resolveDirectoryEntry(fullPath, entry.name);
             if (resolvedEntry.draft) {
                 continue;
@@ -215,6 +218,9 @@ async function listDirectoriesRecursivelyInternal(rootDir, visitedRealDirectorie
         if (!childStats.isDirectory()) {
             continue;
         }
+        if (!(await hasMeaningfulDirectoryContent(childPath))) {
+            continue;
+        }
         directories.push(childPath);
         const childIndexPath = await resolveDirectoryIndexFile(childPath);
         if (childIndexPath !== null) {
@@ -229,6 +235,42 @@ async function listDirectoriesRecursivelyInternal(rootDir, visitedRealDirectorie
     }
     return directories;
 }
+async function hasMeaningfulDirectoryContent(directoryPath, visitedRealDirectories = new Set()) {
+    const realDirectoryPath = await realpath(directoryPath);
+    if (visitedRealDirectories.has(realDirectoryPath)) {
+        return false;
+    }
+    visitedRealDirectories.add(realDirectoryPath);
+    const shape = await inspectDirectoryShape(directoryPath);
+    const indexPath = await resolveDirectoryIndexFile(directoryPath);
+    if (indexPath !== null ||
+        shape.hasExtraMarkdownFiles ||
+        shape.hasAssetFiles ||
+        shape.hasSkillIndex) {
+        return true;
+    }
+    if (!shape.hasChildDirectories) {
+        return false;
+    }
+    const entries = await readdir(directoryPath, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name.startsWith('.')) {
+            continue;
+        }
+        if (shape.hasSkillIndex && isIgnoredSkillSupportDirectory(entry.name)) {
+            continue;
+        }
+        const childPath = path.join(directoryPath, entry.name);
+        const childStats = await stat(childPath);
+        if (!childStats.isDirectory()) {
+            continue;
+        }
+        if (await hasMeaningfulDirectoryContent(childPath, visitedRealDirectories)) {
+            return true;
+        }
+    }
+    return false;
+}
 async function inspectDirectoryShape(directoryPath) {
     const entries = await readdir(directoryPath, { withFileTypes: true });
     let hasSkillIndex = false;

package/dist/index.d.ts

@@ -1,2 +1,3 @@
 export { defineConfig, type SiteConfig, type UserSiteConfig, type SiteNavItem, type SiteLogo, type SiteSocialLink, type EditLinkConfig, } from './core/site-config.js';
 export type { MdoPlugin, PageRenderModel, RenderHookContext, IndexTransformContext, } from './core/extensions.js';
+export type { ParsedDocumentMeta } from './core/markdown.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdorigin",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Markdown-first publishing for humans and agents.",
   "repository": {