mdorigin 0.1.1 → 0.1.2

package/dist/core/api.js

@@ -0,0 +1,160 @@
+export async function handleApiRoute(pathname, searchParams, options) {
+    if (pathname === '/api/openapi.json') {
+        return json(200, buildOpenApiDocument(options));
+    }
+    if (pathname === '/api/search') {
+        if (!options.searchApi) {
+            return json(404, { error: 'search is not enabled for this site' });
+        }
+        const query = searchParams?.get('q')?.trim() ?? '';
+        if (query === '') {
+            return json(400, {
+                error: 'missing required query parameter: q',
+            });
+        }
+        const topK = normalizePositiveInteger(searchParams?.get('topK')) ?? 10;
+        const hits = await options.searchApi.search(query, { topK });
+        return json(200, {
+            query,
+            topK,
+            count: hits.length,
+            hits: hits.map(serializeSearchHit),
+        });
+    }
+    return null;
+}
+function buildOpenApiDocument(options) {
+    return {
+        openapi: '3.1.0',
+        info: {
+            title: `${options.siteConfig.siteTitle} API`,
+            version: '1.0.0',
+            description: 'Search API for a mdorigin site.',
+        },
+        servers: options.siteConfig.siteUrl
+            ? [{ url: options.siteConfig.siteUrl }]
+            : options.requestUrl
+                ? [{ url: new URL(options.requestUrl).origin }]
+                : undefined,
+        paths: {
+            '/api/search': {
+                get: {
+                    operationId: 'searchSite',
+                    summary: 'Search published site content',
+                    parameters: [
+                        {
+                            name: 'q',
+                            in: 'query',
+                            required: true,
+                            schema: { type: 'string' },
+                            description: 'Search query string.',
+                        },
+                        {
+                            name: 'topK',
+                            in: 'query',
+                            required: false,
+                            schema: { type: 'integer', minimum: 1, default: 10 },
+                            description: 'Maximum number of hits to return.',
+                        },
+                    ],
+                    responses: {
+                        '200': {
+                            description: 'Search results.',
+                            content: {
+                                'application/json': {
+                                    schema: {
+                                        type: 'object',
+                                        required: ['query', 'topK', 'count', 'hits'],
+                                        properties: {
+                                            query: { type: 'string' },
+                                            topK: { type: 'integer' },
+                                            count: { type: 'integer' },
+                                            hits: {
+                                                type: 'array',
+                                                items: {
+                                                    type: 'object',
+                                                    required: [
+                                                        'docId',
+                                                        'relativePath',
+                                                        'score',
+                                                        'metadata',
+                                                        'bestMatch',
+                                                    ],
+                                                    properties: {
+                                                        docId: { type: 'string' },
+                                                        relativePath: { type: 'string' },
+                                                        canonicalUrl: { type: 'string' },
+                                                        title: { type: 'string' },
+                                                        summary: { type: 'string' },
+                                                        score: { type: 'number' },
+                                                        metadata: { type: 'object', additionalProperties: true },
+                                                        bestMatch: {
+                                                            type: 'object',
+                                                            required: [
+                                                                'chunkId',
+                                                                'excerpt',
+                                                                'headingPath',
+                                                                'charStart',
+                                                                'charEnd',
+                                                                'score',
+                                                            ],
+                                                            properties: {
+                                                                chunkId: { type: 'number' },
+                                                                excerpt: { type: 'string' },
+                                                                headingPath: {
+                                                                    type: 'array',
+                                                                    items: { type: 'string' },
+                                                                },
+                                                                charStart: { type: 'integer' },
+                                                                charEnd: { type: 'integer' },
+                                                                score: { type: 'number' },
+                                                            },
+                                                        },
+                                                    },
+                                                },
+                                            },
+                                        },
+                                    },
+                                },
+                            },
+                        },
+                        '400': {
+                            description: 'Invalid request.',
+                        },
+                        '404': {
+                            description: 'Search API not enabled.',
+                        },
+                    },
+                },
+            },
+        },
+    };
+}
+function serializeSearchHit(hit) {
+    return {
+        docId: hit.docId,
+        relativePath: hit.relativePath,
+        canonicalUrl: hit.canonicalUrl,
+        title: hit.title,
+        summary: hit.summary,
+        metadata: hit.metadata,
+        score: hit.score,
+        bestMatch: hit.bestMatch,
+    };
+}
+function normalizePositiveInteger(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+function json(status, body) {
+    return {
+        status,
+        headers: {
+            'content-type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify(body, null, 2),
+    };
+}

package/dist/core/content-store.js

@@ -54,10 +54,15 @@ const MEDIA_TYPES = new Map([
     ['.json', 'application/json; charset=utf-8'],
     ['.md', 'text/markdown; charset=utf-8'],
     ['.pdf', 'application/pdf'],
+    ['.py', 'text/plain; charset=utf-8'],
     ['.png', 'image/png'],
+    ['.sh', 'text/plain; charset=utf-8'],
     ['.svg', 'image/svg+xml'],
     ['.txt', 'text/plain; charset=utf-8'],
+    ['.toml', 'text/plain; charset=utf-8'],
     ['.webp', 'image/webp'],
+    ['.yaml', 'text/plain; charset=utf-8'],
+    ['.yml', 'text/plain; charset=utf-8'],
 ]);
 export function getMediaTypeForPath(contentPath) {
     const extension = path.posix.extname(contentPath).toLowerCase();

package/dist/core/content-type.d.ts

@@ -1,6 +1,7 @@
 import type { ParsedDocumentMeta } from './markdown.js';
 export type ContentType = 'page' | 'post';
 export interface DirectoryShape {
+    hasSkillIndex: boolean;
     hasChildDirectories: boolean;
     hasExtraMarkdownFiles: boolean;
     hasAssetFiles: boolean;

package/dist/core/content-type.js

@@ -9,6 +9,9 @@ export function inferDirectoryContentType(meta, shape) {
     if (typeof meta.date === 'string' && meta.date !== '') {
         return 'post';
     }
+    if (shape.hasSkillIndex) {
+        return 'post';
+    }
     if (shape.hasChildDirectories || shape.hasExtraMarkdownFiles) {
         return 'page';
     }

package/dist/core/directory-index.d.ts

@@ -1,2 +1,2 @@
-export declare const DIRECTORY_INDEX_FILENAMES: readonly ["index.md", "README.md"];
+export declare const DIRECTORY_INDEX_FILENAMES: readonly ["index.md", "README.md", "SKILL.md"];
 export declare function getDirectoryIndexCandidates(directoryPath: string): string[];

package/dist/core/directory-index.js

@@ -1,5 +1,9 @@
 import path from 'node:path';
-export const DIRECTORY_INDEX_FILENAMES = ['index.md', 'README.md'];
+export const DIRECTORY_INDEX_FILENAMES = [
+    'index.md',
+    'README.md',
+    'SKILL.md',
+];
 export function getDirectoryIndexCandidates(directoryPath) {
     return DIRECTORY_INDEX_FILENAMES.map((filename) => directoryPath === '' ? filename : path.posix.join(directoryPath, filename));
 }

package/dist/core/markdown.d.ts

@@ -1,7 +1,9 @@
 export interface ParsedDocumentMeta {
     title?: string;
+    name?: string;
     date?: string;
     summary?: string;
+    description?: string;
     draft?: boolean;
     type?: string;
     order?: number;
@@ -20,6 +22,8 @@ export interface ManagedIndexEntry {
     href: string;
     detail?: string;
 }
+export declare function getDocumentTitle(meta: ParsedDocumentMeta, body: string, fallback: string): string;
+export declare function getDocumentSummary(meta: ParsedDocumentMeta, body: string): string | undefined;
 export declare function parseMarkdownDocument(sourcePath: string, markdown: string): Promise<ParsedDocument>;
 export declare function renderMarkdown(markdown: string): Promise<string>;
 export declare function rewriteMarkdownLinksInHtml(html: string): string;

package/dist/core/markdown.js

@@ -2,6 +2,15 @@ import matter from 'gray-matter';
 import { remark } from 'remark';
 import remarkGfm from 'remark-gfm';
 import remarkHtml from 'remark-html';
+export function getDocumentTitle(meta, body, fallback) {
+    return (firstNonEmptyString(meta.title, meta.name) ??
+        extractFirstHeading(body) ??
+        fallback);
+}
+export function getDocumentSummary(meta, body) {
+    return (firstNonEmptyString(meta.summary, meta.description) ??
+        extractFirstParagraph(body));
+}
 export async function parseMarkdownDocument(sourcePath, markdown) {
     const parsed = matter(markdown);
     const html = rewriteMarkdownLinksInHtml(await renderMarkdown(parsed.content));
@@ -83,6 +92,9 @@ function normalizeMeta(data) {
     if (typeof data.title === 'string') {
         meta.title = data.title;
     }
+    if (typeof data.name === 'string') {
+        meta.name = data.name;
+    }
     if (typeof data.date === 'string') {
         meta.date = data.date;
     }
@@ -92,6 +104,9 @@ function normalizeMeta(data) {
     if (typeof data.summary === 'string') {
         meta.summary = data.summary;
     }
+    if (typeof data.description === 'string') {
+        meta.description = data.description;
+    }
     if (typeof data.draft === 'boolean') {
         meta.draft = data.draft;
     }
@@ -143,6 +158,12 @@ function rewriteMarkdownPath(pathname) {
     if (pathname.toLowerCase() === 'readme.md') {
         return './';
     }
+    if (pathname.toLowerCase().endsWith('/skill.md')) {
+        return pathname.slice(0, -'SKILL.md'.length);
+    }
+    if (pathname.toLowerCase() === 'skill.md') {
+        return './';
+    }
     return pathname.slice(0, -'.md'.length);
 }
 function shouldPreserveHref(href) {
@@ -168,3 +189,35 @@ function normalizeManagedIndexHref(href) {
     }
     return href;
 }
+function extractFirstHeading(markdown) {
+    for (const line of markdown.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed.startsWith('#')) {
+            continue;
+        }
+        const heading = trimmed.replace(/^#+\s*/, '').trim();
+        if (heading !== '') {
+            return heading;
+        }
+    }
+    return undefined;
+}
+function extractFirstParagraph(markdown) {
+    const paragraphs = markdown
+        .split(/\n\s*\n/g)
+        .map((paragraph) => paragraph.trim())
+        .filter((paragraph) => paragraph !== '');
+    for (const paragraph of paragraphs) {
+        if (paragraph.startsWith('#') ||
+            paragraph.startsWith('<!--') ||
+            paragraph.startsWith('- ') ||
+            paragraph.startsWith('* ')) {
+            continue;
+        }
+        return paragraph.replace(/\s+/g, ' ');
+    }
+    return undefined;
+}
+function firstNonEmptyString(...values) {
+    return values.find((value) => typeof value === 'string' && value !== '');
+}

package/dist/core/request-handler.d.ts

@@ -1,9 +1,13 @@
 import type { ContentStore } from './content-store.js';
 import type { ResolvedSiteConfig } from './site-config.js';
+import type { SearchApi } from '../search.js';
 export interface HandleSiteRequestOptions {
     draftMode: 'include' | 'exclude';
     siteConfig: ResolvedSiteConfig;
     acceptHeader?: string;
+    searchParams?: URLSearchParams;
+    requestUrl?: string;
+    searchApi?: SearchApi;
 }
 export interface SiteResponse {
     status: number;

package/dist/core/request-handler.js

@@ -1,14 +1,25 @@
 import path from 'node:path';
 import { inferDirectoryContentType } from './content-type.js';
 import { getDirectoryIndexCandidates } from './directory-index.js';
-import { extractManagedIndexEntries, parseMarkdownDocument, stripManagedIndexBlock, stripManagedIndexLinks, } from './markdown.js';
+import { extractManagedIndexEntries, getDocumentSummary, getDocumentTitle as getParsedDocumentTitle, parseMarkdownDocument, stripManagedIndexBlock, stripManagedIndexLinks, } from './markdown.js';
+import { handleApiRoute } from './api.js';
 import { normalizeRequestPath, resolveRequest } from './router.js';
-import { escapeHtml, renderDocument } from '../html/template.js';
+import { escapeHtml, renderCatalogArticleItems, renderDocument, } from '../html/template.js';
 export async function handleSiteRequest(store, pathname, options) {
+    const searchEnabled = options.searchApi !== undefined;
+    const apiRoute = await handleApiRoute(pathname, options.searchParams, {
+        searchApi: options.searchApi,
+        siteConfig: options.siteConfig,
+        requestUrl: options.requestUrl,
+    });
+    if (apiRoute !== null) {
+        return apiRoute;
+    }
     if (pathname === '/sitemap.xml') {
         return renderSitemap(store, options);
     }
     const resolved = resolveRequest(pathname);
+    const catalogFragmentRequest = getCatalogFragmentRequest(options.searchParams);
     const negotiatedMarkdown = shouldServeMarkdownForRequest(resolved, options.acceptHeader);
     if (resolved.kind === 'not-found' || !resolved.sourcePath) {
         const aliasRedirect = await tryRedirectAlias(store, pathname, options);
@@ -36,7 +47,7 @@ export async function handleSiteRequest(store, pathname, options) {
             if (directoryIndexResponse !== null) {
                 return directoryIndexResponse;
             }
-            return renderDirectoryListing(store, resolved.requestPath, options.siteConfig);
+            return renderDirectoryListing(store, resolved.requestPath, options.siteConfig, searchEnabled);
         }
         return notFound();
     }
@@ -72,6 +83,10 @@ export async function handleSiteRequest(store, pathname, options) {
     const catalogEntries = options.siteConfig.template === 'catalog'
         ? extractManagedIndexEntries(renderedBody)
         : [];
+    if (catalogFragmentRequest !== null &&
+        options.siteConfig.template === 'catalog') {
+        return renderCatalogPostsFragment(catalogEntries, catalogFragmentRequest);
+    }
     const documentBody = options.siteConfig.template === 'catalog'
         ? stripManagedIndexBlock(renderedBody)
         : renderedBody;
@@ -91,7 +106,9 @@ export async function handleSiteRequest(store, pathname, options) {
             logo: options.siteConfig.logo,
             title: getDocumentTitle(parsed),
             body: renderedParsed.html,
-            summary: options.siteConfig.showSummary === false ? undefined : parsed.meta.summary,
+            summary: options.siteConfig.showSummary === false
+                ? undefined
+                : getDocumentSummary(parsed.meta, parsed.body),
             date: options.siteConfig.showDate === false ? undefined : parsed.meta.date,
             showSummary: options.siteConfig.showSummary,
             showDate: options.siteConfig.showDate,
@@ -106,6 +123,51 @@ export async function handleSiteRequest(store, pathname, options) {
             canonicalPath: getCanonicalHtmlPathForContentPath(resolved.sourcePath),
             alternateMarkdownPath: getMarkdownRequestPathForContentPath(resolved.sourcePath),
             catalogEntries,
+            catalogRequestPath: resolved.requestPath,
+            catalogInitialPostCount: options.siteConfig.catalogInitialPostCount,
+            catalogLoadMoreStep: options.siteConfig.catalogLoadMoreStep,
+            searchEnabled,
+        }),
+    };
+}
+function getCatalogFragmentRequest(searchParams) {
+    if (searchParams?.get('catalog-format') !== 'posts') {
+        return null;
+    }
+    const offset = normalizeNonNegativeInteger(searchParams.get('catalog-offset'));
+    const limit = normalizePositiveInteger(searchParams.get('catalog-limit'));
+    if (offset === null || limit === null) {
+        return null;
+    }
+    return { offset, limit };
+}
+function normalizeNonNegativeInteger(value) {
+    if (value === null) {
+        return 0;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : null;
+}
+function normalizePositiveInteger(value) {
+    if (value === null) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+}
+function renderCatalogPostsFragment(entries, request) {
+    const articles = entries.filter((entry) => entry.kind === 'article');
+    const visibleArticles = articles.slice(request.offset, request.offset + request.limit);
+    const nextOffset = request.offset + visibleArticles.length;
+    return {
+        status: 200,
+        headers: {
+            'content-type': 'application/json; charset=utf-8',
+        },
+        body: JSON.stringify({
+            itemsHtml: renderCatalogArticleItems(visibleArticles),
+            hasMore: nextOffset < articles.length,
+            nextOffset,
         }),
     };
 }
@@ -195,13 +257,11 @@ function appendVary(existing, value) {
     return `${existing}, ${value}`;
 }
 function getDocumentTitle(parsed) {
-    if (parsed.meta.title) {
-        return parsed.meta.title;
-    }
     const basename = path.posix.basename(parsed.sourcePath, '.md');
-    return basename === 'index'
+    const fallback = basename === 'index' || basename === 'README' || basename === 'SKILL'
         ? path.posix.basename(path.posix.dirname(parsed.sourcePath)) || 'mdorigin'
         : basename;
+    return getParsedDocumentTitle(parsed.meta, parsed.body, fallback);
 }
 async function collectSitemapEntries(store, directoryPath, options) {
     const entries = await store.listDirectory(directoryPath);
@@ -247,7 +307,7 @@ function dedupeSitemapEntries(entries) {
     }
     return Array.from(deduped.values());
 }
-async function renderDirectoryListing(store, requestPath, siteConfig) {
+async function renderDirectoryListing(store, requestPath, siteConfig, searchEnabled) {
     const directoryPath = requestPath === '/' ? '' : requestPath.slice(1).replace(/\/$/, '');
     const entries = await store.listDirectory(directoryPath);
     if (entries === null) {
@@ -286,6 +346,7 @@ async function renderDirectoryListing(store, requestPath, siteConfig) {
             stylesheetContent: siteConfig.stylesheetContent,
             canonicalPath: requestPath,
             alternateMarkdownPath: getMarkdownRequestPathForContentPath(getDirectoryIndexContentPathForRequestPath(requestPath)),
+            searchEnabled,
         }),
     };
 }
@@ -338,6 +399,11 @@ async function tryRenderAlternateDirectoryIndex(store, requestPath, options) {
         const catalogEntries = options.siteConfig.template === 'catalog'
             ? extractManagedIndexEntries(renderedBody)
             : [];
+        const catalogFragmentRequest = getCatalogFragmentRequest(options.searchParams);
+        if (catalogFragmentRequest !== null &&
+            options.siteConfig.template === 'catalog') {
+            return renderCatalogPostsFragment(catalogEntries, catalogFragmentRequest);
+        }
         const documentBody = options.siteConfig.template === 'catalog'
             ? stripManagedIndexBlock(renderedBody)
             : renderedBody;
@@ -357,7 +423,9 @@ async function tryRenderAlternateDirectoryIndex(store, requestPath, options) {
                 logo: options.siteConfig.logo,
                 title: getDocumentTitle(parsed),
                 body: renderedParsed.html,
-                summary: options.siteConfig.showSummary === false ? undefined : parsed.meta.summary,
+                summary: options.siteConfig.showSummary === false
+                    ? undefined
+                    : getDocumentSummary(parsed.meta, parsed.body),
                 date: options.siteConfig.showDate === false ? undefined : parsed.meta.date,
                 showSummary: options.siteConfig.showSummary,
                 showDate: options.siteConfig.showDate,
@@ -372,6 +440,10 @@ async function tryRenderAlternateDirectoryIndex(store, requestPath, options) {
                 canonicalPath: requestPath,
                 alternateMarkdownPath: getMarkdownRequestPathForContentPath(candidatePath),
                 catalogEntries,
+                catalogRequestPath: requestPath,
+                catalogInitialPostCount: options.siteConfig.catalogInitialPostCount,
+                catalogLoadMoreStep: options.siteConfig.catalogLoadMoreStep,
+                searchEnabled: options.searchApi !== undefined,
             }),
         };
     }
@@ -585,9 +657,7 @@ async function resolveDirectoryNav(store, entry) {
         const parsed = await parseMarkdownDocument(candidatePath, contentEntry.text);
         const shape = await inspectDirectoryShape(store, entry.path);
         return {
-            title: typeof parsed.meta.title === 'string' && parsed.meta.title !== ''
-                ? parsed.meta.title
-                : entry.name,
+            title: getParsedDocumentTitle(parsed.meta, parsed.body, entry.name),
             type: inferDirectoryContentType(parsed.meta, shape),
             order: parsed.meta.order,
         };
@@ -601,11 +671,13 @@ async function inspectDirectoryShape(store, directoryPath) {
     const entries = await store.listDirectory(directoryPath);
     if (entries === null) {
         return {
+            hasSkillIndex: false,
             hasChildDirectories: false,
             hasExtraMarkdownFiles: false,
             hasAssetFiles: false,
         };
     }
+    let hasSkillIndex = false;
     let hasChildDirectories = false;
     let hasExtraMarkdownFiles = false;
     let hasAssetFiles = false;
@@ -619,7 +691,10 @@ async function inspectDirectoryShape(store, directoryPath) {
         }
         const extension = path.posix.extname(entry.name).toLowerCase();
         if (extension === '.md') {
-            if (entry.name !== 'index.md' && entry.name !== 'README.md') {
+            if (entry.name === 'SKILL.md') {
+                hasSkillIndex = true;
+            }
+            else if (entry.name !== 'index.md' && entry.name !== 'README.md') {
                 hasExtraMarkdownFiles = true;
             }
             continue;
@@ -627,6 +702,7 @@ async function inspectDirectoryShape(store, directoryPath) {
         hasAssetFiles = true;
     }
     return {
+        hasSkillIndex,
         hasChildDirectories,
         hasExtraMarkdownFiles,
         hasAssetFiles,

package/dist/core/site-config.d.ts

@@ -35,6 +35,8 @@ export interface SiteConfig {
     socialLinks?: SiteSocialLink[];
     editLink?: EditLinkConfig;
     showHomeIndex?: boolean;
+    catalogInitialPostCount?: number;
+    catalogLoadMoreStep?: number;
 }
 export interface ResolvedSiteConfig {
     siteTitle: string;
@@ -52,6 +54,8 @@ export interface ResolvedSiteConfig {
     socialLinks: SiteSocialLink[];
     editLink?: EditLinkConfig;
     showHomeIndex: boolean;
+    catalogInitialPostCount: number;
+    catalogLoadMoreStep: number;
     stylesheetContent?: string;
     siteTitleConfigured: boolean;
     siteDescriptionConfigured: boolean;

package/dist/core/site-config.js

@@ -49,6 +49,8 @@ export async function loadSiteConfig(options = {}) {
         showHomeIndex: typeof parsedConfig.showHomeIndex === 'boolean'
             ? parsedConfig.showHomeIndex
             : normalizeTopNav(parsedConfig.topNav).length === 0,
+        catalogInitialPostCount: normalizePositiveInteger(parsedConfig.catalogInitialPostCount, 10),
+        catalogLoadMoreStep: normalizePositiveInteger(parsedConfig.catalogLoadMoreStep, 10),
         stylesheetContent,
         siteTitleConfigured: typeof parsedConfig.siteTitle === 'string' && parsedConfig.siteTitle !== '',
         siteDescriptionConfigured: typeof parsedConfig.siteDescription === 'string' &&
@@ -131,6 +133,18 @@ function normalizeTopNav(value) {
         return [];
     });
 }
+function normalizePositiveInteger(value, fallback) {
+    if (typeof value === 'number' && Number.isInteger(value) && value > 0) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const parsed = Number.parseInt(value, 10);
+        if (Number.isInteger(parsed) && parsed > 0) {
+            return parsed;
+        }
+    }
+    return fallback;
+}
 function normalizeLogo(value) {
     if (typeof value !== 'object' ||
         value === null ||

package/dist/html/template.d.ts

@@ -25,6 +25,11 @@ export interface RenderDocumentOptions {
     canonicalPath?: string;
     alternateMarkdownPath?: string;
     catalogEntries?: ManagedIndexEntry[];
+    catalogRequestPath?: string;
+    catalogInitialPostCount?: number;
+    catalogLoadMoreStep?: number;
+    searchEnabled?: boolean;
 }
 export declare function renderDocument(options: RenderDocumentOptions): string;
 export declare function escapeHtml(value: string): string;
+export declare function renderCatalogArticleItems(entries: readonly ManagedIndexEntry[]): string;