快速开始

快速上手

npm install -g mdorigin
mdorigin dev --root docs/site
mdorigin build index --root docs/site

这足以在本地预览站点、保持目录索引最新，并在接触部署之前确认内容模型。

之后要生成 Worker 包：

mdorigin build cloudflare --root docs/site

mdorigin 也非常适合与以 SKILL.md 为主文档的技能仓库配合。这类目录被视为文档包，而 scripts/、references/ 等辅助目录保持直接可访问，但不进入自动索引。

如果你的发布内容在 docs/site 下，而可复用内容在仓库其他位置，也可以用目录符号链接暴露它。例如：

docs/site/skills -> ../../skills

mdorigin dev、mdorigin build index 与 Cloudflare 包构建都会跟随这些符号链接目录。

开发期的本地检索，安装 indexbind 并构建搜索包：

npm install indexbind
mdorigin build search --root docs/site
mdorigin search --index dist/search --meta section=guides "cloudflare deploy"

indexbind 文档：

文档：https://indexbind.jolestar.workers.dev
仓库：https://github.com/holon-run/indexbind

build search 现在默认使用质量更高的 model2vec 后端。如果你想要更小的旧版回退，运行：

mdorigin build search --root docs/site --embedding-backend hashing

在本地预览时把同一个包暴露为站点 API：

mdorigin dev --root docs/site --search dist/search

可用端点：

/api/search?q=cloudflare+deploy
/api/openapi.json

也可以按元数据过滤搜索：

mdorigin search --index dist/search --meta type=post "cloudflare"
curl 'http://localhost:3000/api/search?q=cloudflare&meta.type=post'

如果你希望站点本身拥有默认检索配置，在 mdorigin.config.* 中配置：

import { defineConfig } from "mdorigin";

export default defineConfig({
  search: {
    topK: 10,
    mode: "hybrid",
    minScore: 0.05,
    reranker: {
      kind: "embedding-v1",
      candidatePoolSize: 25,
    },
  },
});

该配置作用于 mdorigin dev --search ... 与部署后的 /api/search 请求。HTTP API 仍只接受 q、可选的 topK 与 meta.<field> 过滤。

如果你的站点需要对短查询与较长说明式查询采用不同检索行为，可以添加可选的查询感知策略层：

import { defineConfig } from "mdorigin";

export default defineConfig({
  search: {
    topK: 10,
    mode: "hybrid",
    policy: {
      shortQuery: {
        maxChars: 6,
        minScore: 0.02,
        reranker: null,
      },
      longQuery: {
        minChars: 12,
        reranker: {
          kind: "heuristic-v1",
          candidatePoolSize: 20,
        },
      },
    },
  },
});

mdorigin 默认不启用任何动态搜索策略。如果 search.policy 缺省，站点只使用静态配置。

重复本地构建时，使用增量搜索索引：

mdorigin build search --root docs/site --incremental

安装

npm install -g mdorigin

如果偏好项目内安装，使用：

npm install --save-dev mdorigin

预览站点

使用一个内容根目录，例如 docs/site：

mdorigin dev --root docs/site

它会启动本地预览服务器，提供：

原始 markdown：/foo.md
HTML：/foo.html
默认人类路由：/foo
当客户端发送 Accept: text/markdown 时，无扩展名路由返回 markdown

例如：

curl -H "Accept: text/markdown" http://localhost:3000/guides/getting-started

站点配置

在内容根内创建配置文件，例如 docs/site/mdorigin.config.json 或 docs/site/mdorigin.config.ts。

如果没有配置文件，mdorigin 回退到根首页 frontmatter：

title 作为默认站点标题
summary 作为默认站点描述

如果设置了 stylesheet，CSS 文件会被读取并内联进渲染 HTML，本地预览与 Cloudflare 包一致。默认情况下加载器按以下优先级：

--config
<content-root>/mdorigin.config.ts、.mjs、.js 或 .json
当前工作目录的 mdorigin.config.ts、.mjs、.js 或 .json

内置呈现现在固定为默认 atlas 基线。直接配置元数据与导航：

{
  "siteUrl": "https://example.com",
  "favicon": "/favicon.svg",
  "footerNav": [
    { "label": "GitHub", "href": "https://github.com/example/repo" }
  ]
}

设置 siteUrl 后，mdorigin 还会启用：

/sitemap.xml
/feed.xml

如果你想关闭 RSS 或覆盖订阅元数据，添加：

{
  "rss": {
    "title": "Example Feed",
    "description": "Latest updates from Example",
    "maxItems": 20
  }
}

或完全禁用：

{
  "rss": false
}

当页面包含受管索引块时，默认渲染器自动把它呈现为结构化列表。mdorigin 不再暴露内置主题/模板变体作为产品配置。

如果你想现在就开始使用基于代码的扩展，把 JSON 配置换成 mdorigin.config.ts 并导出带 plugins 的配置对象。

稳定的钩子、页面模型与插件数据结构见扩展。

你仍然可以限制默认列表首批显示的文章条目数量：

{
  "listingInitialPostCount": 10,
  "listingLoadMoreStep": 10
}

构建目录索引

mdorigin build index --root docs/site