mdorigin 0.1.1 → 0.1.3

package/README.md

@@ -2,34 +2,122 @@
 
 `mdorigin` is a markdown-first publishing engine.
 
-It treats markdown as the only source of truth, serves raw `.md` directly for agents, renders `.html` views for humans from the same directory tree, can return markdown from extensionless routes when clients send `Accept: text/markdown`, and supports frontmatter aliases for old URL redirects.
+It treats markdown as the only source of truth, serves raw `.md` directly for agents, renders HTML for humans from the same directory tree, and can expose the same content to both browsers and tools through stable routes.
+
+## Core Principle
+
+`mdorigin` is not meant to become a template system.
+
+Its core is:
+
+- routing rules
+- markdown tree normalization
+- document, index, asset, search, and site semantics
+- stable page models derived from the same content tree
+
+That means `mdorigin` should own content semantics, while page rendering remains extensible. In practice, this is the direction for advanced customization: users should be able to replace page-level rendering with code, without replacing the routing and content kernel itself.
+
+## Why mdorigin
+
+- markdown stays directly accessible at `.md` routes
+- extensionless routes render human-friendly HTML from the same files
+- `README.md`, `index.md`, and `SKILL.md` all fit into one routing model
+- the same core works in local preview and Cloudflare Workers
+- optional search is powered by [`indexbind`](https://github.com/jolestar/indexbind)
 
 ## Install
 
 ```bash
-npm install --save-dev mdorigin
+npm install -g mdorigin
 ```
 
-Then run it with `npx`:
+Then run it directly:
 
 ```bash
-npx mdorigin dev --root docs/site
+mdorigin dev --root docs/site
 ```
 
-## Repo Development
+If you prefer a project-local install instead, use `npm install --save-dev mdorigin` and run it with `npx --no-install mdorigin ...`.
+
+## Quick Start
 
 ```bash
-npm install
-npm run check
-npm run dev -- --root docs/site
-npm run build:index -- --root docs/site
+mdorigin dev --root docs/site
+mdorigin build index --root docs/site
+mdorigin build cloudflare --root docs/site
 ```
 
+That is enough to preview a site locally, keep directory indexes up to date, and generate a Cloudflare Worker bundle.
+
+## Code-Based Extensions
+
+`mdorigin` now supports a code config alongside `mdorigin.config.json`.
+
+Use `mdorigin.config.ts` when you want to customize rendering or indexing with code instead of asking for a template system:
+
+```ts
+export default {
+  siteTitle: "My Site",
+  plugins: [
+    {
+      name: "custom-footer",
+      renderFooter() {
+        return '<footer class="custom-footer">Built with mdorigin</footer>';
+      },
+    },
+  ],
+};
+```
+
+Current stable hooks are:
+
+- `transformIndex(entries, context)`
+- `renderHeader(context)`
+- `renderFooter(context)`
+- `renderPage(page, context, next)`
+- `transformHtml(html, context)`
+
+The intended boundary is:
+
+- `mdorigin` owns routing and normalized content semantics
+- plugins may replace page rendering
+- plugins do not replace the request kernel itself
+
+## Optional Search
+
+`mdorigin` can build a local retrieval bundle through the optional [`indexbind`](https://github.com/jolestar/indexbind) package. For the retrieval engine itself, see the `indexbind` docs: <https://indexbind.jolestar.workers.dev>.
+
+```bash
+npm install indexbind
+mdorigin build search --root docs/site
+mdorigin search --index dist/search "cloudflare deploy"
+```
+
+`build search` now defaults to the higher-quality `model2vec` backend. If you need a smaller or faster fallback, you can opt back into hashing:
+
+```bash
+mdorigin build search --root docs/site --embedding-backend hashing
+```
+
+To expose the same search bundle from the site runtime:
+
+```bash
+mdorigin dev --root docs/site --search dist/search
+mdorigin build cloudflare --root docs/site --search dist/search
+```
+
+Runtime endpoints:
+
+- `/api/search?q=cloudflare+deploy`
+- `/api/openapi.json`
+
 ## Docs
 
+- Docs site: <https://mdorigin.jolestar.workers.dev>
 - Getting started: [`docs/site/guides/getting-started.md`](docs/site/guides/getting-started.md)
 - Routing model: [`docs/site/concepts/routing.md`](docs/site/concepts/routing.md)
 - Directory indexes: [`docs/site/concepts/directory-indexes.md`](docs/site/concepts/directory-indexes.md)
 - Configuration: [`docs/site/reference/configuration.md`](docs/site/reference/configuration.md)
 - CLI: [`docs/site/reference/cli.md`](docs/site/reference/cli.md)
+- Search setup: [`docs/site/guides/getting-started.md`](docs/site/guides/getting-started.md#quick-start)
 - Cloudflare deployment: [`docs/site/guides/cloudflare.md`](docs/site/guides/cloudflare.md)

package/dist/adapters/cloudflare.d.ts

@@ -1,5 +1,7 @@
 import { type ContentEntryKind } from '../core/content-store.js';
+import type { MdoPlugin } from '../core/extensions.js';
 import type { ResolvedSiteConfig } from '../core/site-config.js';
+import { type SearchBundleEntry } from '../search.js';
 export interface CloudflareManifestEntry {
     path: string;
     kind: ContentEntryKind;
@@ -10,8 +12,12 @@ export interface CloudflareManifestEntry {
 export interface CloudflareManifest {
     entries: CloudflareManifestEntry[];
     siteConfig?: ResolvedSiteConfig;
+    searchEntries?: SearchBundleEntry[];
 }
 export interface ExportedHandlerLike {
     fetch(request: Request): Promise<Response>;
 }
-export declare function createCloudflareWorker(manifest: CloudflareManifest): ExportedHandlerLike;
+export interface CreateCloudflareWorkerOptions {
+    plugins?: MdoPlugin[];
+}
+export declare function createCloudflareWorker(manifest: CloudflareManifest, options?: CreateCloudflareWorkerOptions): ExportedHandlerLike;

package/dist/adapters/cloudflare.js

@@ -1,6 +1,7 @@
 import { MemoryContentStore, } from '../core/content-store.js';
 import { handleSiteRequest } from '../core/request-handler.js';
-export function createCloudflareWorker(manifest) {
+import { createSearchApiFromBundle } from '../search.js';
+export function createCloudflareWorker(manifest, options = {}) {
     const store = new MemoryContentStore(manifest.entries.map((entry) => {
         if (entry.kind === 'text') {
             return {
@@ -17,6 +18,9 @@ export function createCloudflareWorker(manifest) {
             bytes: decodeBase64(entry.base64 ?? ''),
         };
     }));
+    const searchApi = manifest.searchEntries && manifest.searchEntries.length > 0
+        ? createSearchApiFromBundle(manifest.searchEntries)
+        : undefined;
     return {
         async fetch(request) {
             const url = new URL(request.url);
@@ -37,10 +41,16 @@ export function createCloudflareWorker(manifest) {
                     socialLinks: [],
                     editLink: undefined,
                     showHomeIndex: true,
+                    catalogInitialPostCount: 10,
+                    catalogLoadMoreStep: 10,
                     siteTitleConfigured: false,
                     siteDescriptionConfigured: false,
                 },
                 acceptHeader: request.headers.get('accept') ?? undefined,
+                searchParams: url.searchParams,
+                requestUrl: request.url,
+                searchApi,
+                plugins: options.plugins,
             });
             const headers = new Headers(siteResponse.headers);
             const body = siteResponse.body instanceof Uint8Array

package/dist/adapters/node.d.ts

@@ -1,10 +1,14 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import type { ContentStore } from '../core/content-store.js';
+import type { MdoPlugin } from '../core/extensions.js';
 import type { ResolvedSiteConfig } from '../core/site-config.js';
+import type { SearchApi } from '../search.js';
 export interface NodeAdapterOptions {
     rootDir: string;
     draftMode: 'include' | 'exclude';
     siteConfig: ResolvedSiteConfig;
+    searchApi?: SearchApi;
+    plugins?: MdoPlugin[];
 }
 export declare function createFileSystemContentStore(rootDir: string): ContentStore;
 export declare function createNodeRequestListener(options: NodeAdapterOptions): (request: IncomingMessage, response: ServerResponse) => Promise<void>;

package/dist/adapters/node.js

@@ -1,5 +1,5 @@
 import { createServer } from 'node:http';
-import { readFile, readdir } from 'node:fs/promises';
+import { readFile, readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
 import { getMediaTypeForPath, isLikelyTextPath, normalizeContentPath, normalizeDirectoryPath, } from '../core/content-store.js';
 import { handleSiteRequest } from '../core/request-handler.js';
@@ -12,10 +12,14 @@ export function createFileSystemContentStore(rootDir) {
                 return null;
             }
             const filePath = path.resolve(resolvedRootDir, normalizedPath);
-            if (!filePath.startsWith(`${resolvedRootDir}${path.sep}`) && filePath !== resolvedRootDir) {
+            if (!isVisiblePathWithinRoot(resolvedRootDir, filePath)) {
                 return null;
             }
             try {
+                const fileStats = await stat(filePath);
+                if (!fileStats.isFile()) {
+                    return null;
+                }
                 const mediaType = getMediaTypeForPath(normalizedPath);
                 if (isLikelyTextPath(normalizedPath)) {
                     const text = await readFile(filePath, 'utf8');
@@ -47,21 +51,49 @@ export function createFileSystemContentStore(rootDir) {
                 return null;
             }
             const directoryPath = path.resolve(resolvedRootDir, normalizedPath);
-            if (!directoryPath.startsWith(`${resolvedRootDir}${path.sep}`) &&
-                directoryPath !== resolvedRootDir) {
+            if (!isVisiblePathWithinRoot(resolvedRootDir, directoryPath)) {
                 return null;
             }
             try {
+                const directoryStats = await stat(directoryPath);
+                if (!directoryStats.isDirectory()) {
+                    return null;
+                }
                 const entries = await readdir(directoryPath, { withFileTypes: true });
-                return entries
+                const resolvedEntries = await Promise.all(entries
                     .filter((entry) => !entry.name.startsWith('.'))
-                    .map((entry) => ({
-                    name: entry.name,
-                    path: normalizedPath === ''
+                    .map(async (entry) => {
+                    const childVisiblePath = normalizedPath === ''
                         ? entry.name
-                        : `${normalizedPath}/${entry.name}`,
-                    kind: entry.isDirectory() ? 'directory' : 'file',
-                }))
+                        : `${normalizedPath}/${entry.name}`;
+                    const childFilePath = path.resolve(resolvedRootDir, childVisiblePath);
+                    try {
+                        const childStats = await stat(childFilePath);
+                        if (childStats.isDirectory()) {
+                            return {
+                                name: entry.name,
+                                path: childVisiblePath,
+                                kind: 'directory',
+                            };
+                        }
+                        if (childStats.isFile()) {
+                            return {
+                                name: entry.name,
+                                path: childVisiblePath,
+                                kind: 'file',
+                            };
+                        }
+                    }
+                    catch (error) {
+                        if (isNodeNotFound(error)) {
+                            return null;
+                        }
+                        throw error;
+                    }
+                    return null;
+                }));
+                return resolvedEntries
+                    .filter((entry) => entry !== null)
                     .sort((left, right) => {
                     if (left.kind !== right.kind) {
                         return left.kind === 'directory' ? -1 : 1;
@@ -78,6 +110,10 @@ export function createFileSystemContentStore(rootDir) {
         },
     };
 }
+function isVisiblePathWithinRoot(rootDir, candidatePath) {
+    return (candidatePath === rootDir ||
+        candidatePath.startsWith(`${rootDir}${path.sep}`));
+}
 export function createNodeRequestListener(options) {
     const store = createFileSystemContentStore(options.rootDir);
     return async function onRequest(request, response) {
@@ -87,6 +123,10 @@ export function createNodeRequestListener(options) {
                 draftMode: options.draftMode,
                 siteConfig: options.siteConfig,
                 acceptHeader: request.headers.accept,
+                searchParams: url.searchParams,
+                requestUrl: url.toString(),
+                searchApi: options.searchApi,
+                plugins: options.plugins,
             });
             response.statusCode = siteResponse.status;
             for (const [headerName, headerValue] of Object.entries(siteResponse.headers)) {

package/dist/cli/build-cloudflare.js

@@ -1,26 +1,28 @@
 import path from 'node:path';
 import { createFileSystemContentStore } from '../adapters/node.js';
 import { writeCloudflareBundle } from '../cloudflare.js';
-import { applySiteConfigFrontmatterDefaults, loadSiteConfig, } from '../core/site-config.js';
+import { applySiteConfigFrontmatterDefaults, loadUserSiteConfig, } from '../core/site-config.js';
 export async function runBuildCloudflareCommand(argv) {
     const args = parseArgs(argv);
     if (!args.root) {
-        console.error('Usage: mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config mdorigin.config.json]');
+        console.error('Usage: mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config <config-file>] [--search ./dist/search]');
         process.exitCode = 1;
         return;
     }
     const rootDir = path.resolve(args.root);
-    const loadedSiteConfig = await loadSiteConfig({
+    const loadedConfig = await loadUserSiteConfig({
         cwd: process.cwd(),
         rootDir,
         configPath: args.config,
     });
     const store = createFileSystemContentStore(rootDir);
-    const siteConfig = await applySiteConfigFrontmatterDefaults(store, loadedSiteConfig);
+    const siteConfig = await applySiteConfigFrontmatterDefaults(store, loadedConfig.siteConfig);
     const result = await writeCloudflareBundle({
         rootDir,
         outDir: path.resolve(args.out ?? 'dist/cloudflare'),
         siteConfig,
+        searchDir: args.search ? path.resolve(args.search) : undefined,
+        configModulePath: loadedConfig.configModulePath,
     });
     console.log(`cloudflare worker written to ${result.workerFile}`);
 }
@@ -42,6 +44,11 @@ function parseArgs(argv) {
         if (argument === '--config' && nextValue) {
             result.config = nextValue;
             index += 1;
+            continue;
+        }
+        if (argument === '--search' && nextValue) {
+            result.search = nextValue;
+            index += 1;
         }
     }
     return result;

package/dist/cli/build-index.js

@@ -1,15 +1,24 @@
 import path from 'node:path';
 import { buildDirectoryIndexes } from '../index-builder.js';
+import { loadUserSiteConfig } from '../core/site-config.js';
 export async function runBuildIndexCommand(argv) {
     const args = parseArgs(argv);
     if (!args.root && !args.dir) {
-        console.error('Usage: mdorigin build index (--root <content-dir> | --dir <content-dir>)');
+        console.error('Usage: mdorigin build index (--root <content-dir> | --dir <content-dir>) [--config <config-file>]');
         process.exitCode = 1;
         return;
     }
+    const rootDir = args.root ? path.resolve(args.root) : undefined;
+    const dir = args.dir ? path.resolve(args.dir) : undefined;
+    const loadedConfig = await loadUserSiteConfig({
+        cwd: process.cwd(),
+        rootDir: rootDir ?? dir,
+        configPath: args.config,
+    });
     const result = await buildDirectoryIndexes({
-        rootDir: args.root ? path.resolve(args.root) : undefined,
-        dir: args.dir ? path.resolve(args.dir) : undefined,
+        rootDir,
+        dir,
+        plugins: loadedConfig.plugins,
     });
     console.log(`updated ${result.updatedFiles.length} index file(s)`);
     if (result.skippedDirectories.length > 0) {
@@ -29,6 +38,11 @@ function parseArgs(argv) {
         if (argument === '--dir' && nextValue) {
             result.dir = nextValue;
             index += 1;
+            continue;
+        }
+        if (argument === '--config' && nextValue) {
+            result.config = nextValue;
+            index += 1;
         }
     }
     return result;

package/dist/cli/build-search.d.ts

@@ -0,0 +1 @@
+export declare function runBuildSearchCommand(rawArgs: string[]): Promise<void>;

package/dist/cli/build-search.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+import { buildSearchBundle } from '../search.js';
+import { applySiteConfigFrontmatterDefaults, loadUserSiteConfig, } from '../core/site-config.js';
+import { createFileSystemContentStore } from '../adapters/node.js';
+export async function runBuildSearchCommand(rawArgs) {
+    const args = parseArgs(rawArgs);
+    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>]');
+    }
+    const rootDir = path.resolve(args.root);
+    const store = createFileSystemContentStore(rootDir);
+    const loadedConfig = await loadUserSiteConfig({
+        rootDir,
+        configPath: args.config,
+    });
+    const siteConfig = await applySiteConfigFrontmatterDefaults(store, loadedConfig.siteConfig);
+    const result = await buildSearchBundle({
+        rootDir,
+        outDir: path.resolve(args.out ?? 'dist/search'),
+        siteConfig,
+        embeddingBackend: args.embeddingBackend ?? 'model2vec',
+        model: args.model,
+    });
+    console.log(`search bundle written to ${result.outputDir} (${result.documentCount} documents, ${result.chunkCount} chunks)`);
+}
+function parseArgs(rawArgs) {
+    const parsed = {};
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const arg = rawArgs[index];
+        if (arg.startsWith('--')) {
+            const value = rawArgs[index + 1];
+            if (value && !value.startsWith('--')) {
+                parsed[arg.slice(2)] = value;
+                index += 1;
+            }
+        }
+    }
+    return {
+        root: parsed.root,
+        out: parsed.out,
+        embeddingBackend: parsed['embedding-backend'],
+        model: parsed.model,
+        config: parsed.config,
+    };
+}

package/dist/cli/dev.js

@@ -1,26 +1,31 @@
 import path from 'node:path';
 import { createFileSystemContentStore, createNodeServer } from '../adapters/node.js';
-import { applySiteConfigFrontmatterDefaults, loadSiteConfig, } from '../core/site-config.js';
+import { applySiteConfigFrontmatterDefaults, loadUserSiteConfig, } from '../core/site-config.js';
+import { createSearchApiFromDirectory } from '../search.js';
 export async function runDevCommand(argv) {
     const args = parseArgs(argv);
     if (!args.root) {
-        console.error('Usage: mdorigin dev --root <content-dir> [--port 3000] [--config mdorigin.config.json]');
+        console.error('Usage: mdorigin dev --root <content-dir> [--port 3000] [--config <config-file>] [--search ./dist/search]');
         process.exitCode = 1;
         return;
     }
     const rootDir = path.resolve(args.root);
     const port = args.port ?? 3000;
-    const loadedSiteConfig = await loadSiteConfig({
+    const loadedConfig = await loadUserSiteConfig({
         cwd: process.cwd(),
         rootDir,
         configPath: args.config,
     });
     const store = createFileSystemContentStore(rootDir);
-    const siteConfig = await applySiteConfigFrontmatterDefaults(store, loadedSiteConfig);
+    const siteConfig = await applySiteConfigFrontmatterDefaults(store, loadedConfig.siteConfig);
     const server = createNodeServer({
         rootDir,
         draftMode: 'include',
         siteConfig,
+        searchApi: args.search
+            ? await createSearchApiFromDirectory(path.resolve(args.search))
+            : undefined,
+        plugins: loadedConfig.plugins,
     });
     await new Promise((resolve, reject) => {
         server.once('error', reject);
@@ -47,6 +52,11 @@ function parseArgs(argv) {
         if (argument === '--config' && nextValue) {
             result.config = nextValue;
             index += 1;
+            continue;
+        }
+        if (argument === '--search' && nextValue) {
+            result.search = nextValue;
+            index += 1;
         }
     }
     return result;

package/dist/cli/main.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 import { runBuildIndexCommand } from './build-index.js';
 import { runBuildCloudflareCommand } from './build-cloudflare.js';
+import { runBuildSearchCommand } from './build-search.js';
 import { runDevCommand } from './dev.js';
 import { runInitCloudflareCommand } from './init-cloudflare.js';
+import { runSearchCommand } from './search.js';
 async function main() {
     const [command, subcommand, ...rest] = process.argv.slice(2);
     if (command === 'dev') {
@@ -17,16 +19,26 @@ async function main() {
         await runBuildIndexCommand(rest);
         return;
     }
+    if (command === 'build' && subcommand === 'search') {
+        await runBuildSearchCommand(rest);
+        return;
+    }
     if (command === 'init' && subcommand === 'cloudflare') {
         await runInitCloudflareCommand(rest);
         return;
     }
+    if (command === 'search') {
+        await runSearchCommand([subcommand, ...rest].filter(isDefined));
+        return;
+    }
     console.error([
         'Usage:',
-        '  mdorigin dev --root <content-dir> [--port 3000] [--config mdorigin.config.json]',
-        '  mdorigin build index (--root <content-dir> | --dir <content-dir>)',
-        '  mdorigin build cloudflare --root <content-dir> [--out ./dist/cloudflare] [--config mdorigin.config.json]',
+        '  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'));
     process.exitCode = 1;
 }

package/dist/cli/search.d.ts

@@ -0,0 +1 @@
+export declare function runSearchCommand(rawArgs: string[]): Promise<void>;

package/dist/cli/search.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { searchBundle } from '../search.js';
+export async function runSearchCommand(rawArgs) {
+    const args = parseArgs(rawArgs);
+    if (!args.indexDir || !args.query) {
+        throw new Error('Usage: mdorigin search --index <search-dir> [--top-k 10] <query>');
+    }
+    const hits = await searchBundle({
+        indexDir: path.resolve(args.indexDir),
+        query: args.query,
+        topK: args.topK,
+    });
+    console.log(JSON.stringify(hits, null, 2));
+}
+function parseArgs(rawArgs) {
+    const flags = {};
+    const positionals = [];
+    for (let index = 0; index < rawArgs.length; index += 1) {
+        const arg = rawArgs[index];
+        if (arg.startsWith('--')) {
+            const value = rawArgs[index + 1];
+            if (value && !value.startsWith('--')) {
+                flags[arg.slice(2)] = value;
+                index += 1;
+            }
+            continue;
+        }
+        positionals.push(arg);
+    }
+    const topK = flags['top-k'] ? Number.parseInt(flags['top-k'], 10) : undefined;
+    return {
+        indexDir: flags.index,
+        topK: Number.isInteger(topK) && topK > 0 ? topK : undefined,
+        query: positionals.join(' ').trim(),
+    };
+}

package/dist/cloudflare.d.ts

@@ -6,12 +6,15 @@ export type { CloudflareManifest, CloudflareManifestEntry };
 export interface BuildCloudflareManifestOptions {
     rootDir: string;
     siteConfig: ResolvedSiteConfig;
+    searchDir?: string;
 }
 export interface WriteCloudflareBundleOptions {
     rootDir: string;
     outDir: string;
     siteConfig: ResolvedSiteConfig;
     packageImport?: string;
+    searchDir?: string;
+    configModulePath?: string;
 }
 export interface InitCloudflareProjectOptions {
     projectDir: string;