mdorigin

Markdown-first publishing for humans and agents.

配置

站点配置位于内容根目录。

支持的配置入口文件：

多个文件同时存在时，mdorigin 优先 .ts，其次 .mjs、.js、.json。

常用字段：

代码配置

当你想要基于代码的定制而非纯静态设置时，使用 mdorigin.config.ts。

示例：

import { defineConfig } from "mdorigin";

export default defineConfig({
  siteTitle: "My Site",
  plugins: [
    {
      name: "custom-layout",
      renderPage(page, _context, next) {
        if (page.kind !== "listing") {
          return next(page);
        }

        const title = escapeHtml(page.title);
        return [
          "<!doctype html>",
          "<html><body>",
          `<main class="custom-listing"><h1>${title}</h1>${page.bodyHtml}</main>`,
          "</body></html>",
        ].join("");
      },
    },
  ],
});

function escapeHtml(value: string): string {
  return value
    .replaceAll("&", "&amp;")
    .replaceAll("<", "&lt;")
    .replaceAll(">", "&gt;")
    .replaceAll('"', "&quot;")
    .replaceAll("'", "&#39;");
}

defineConfig 是可选的，直接默认导出普通对象也可以。

当前稳定插件钩子：

设计边界是：

本地化

mdorigin 从类型化消息目录本地化内置 UI 文案（搜索面板、footer 操作、列表标签、404 页），内置 en 与 zh-CN 两份目录。

单语言站点设置：

{
  "locale": "zh-CN"
}

规则：

{
  "locale": "zh-CN",
  "messages": {
    "search.toggle": "搜一下"
  }
}

多语言内容站点改用 locales 配置。每个语言的内容放在以语言代码命名的顶层目录中，与 URL 前缀一一对应：

{
  "siteUrl": "https://example.com",
  "locales": [
    { "code": "en", "default": true },
    { "code": "zh-CN", "label": "中文" }
  ]
}

按上面的配置：

各语言字段：

默认语言也可以显式设置 pathPrefix（如 /en）；此时其内容位于 en/ 目录，/ 重定向到 /en/。

站点元数据

导航

品牌信息

示例：

{
  "siteUrl": "https://example.com",
  "favicon": "/favicon.svg",
  "socialImage": "/og.svg",
  "logo": {
    "src": "/logo.svg",
    "alt": "Example"
  }
}

RSS

mdorigin 可以在 /feed.xml 输出内置 RSS 订阅。

规则：

可选覆盖：

{
  "rss": {
    "title": "Example Feed",
    "description": "Latest updates from Example",
    "author": "editor@example.com",
    "maxItems": 20
  }
}

支持字段：

Footer

mdorigin 支持一小组显式 footer 设置：

示例：

{
  "footerNav": [
    { "label": "GitHub", "href": "https://github.com/example/repo" }
  ],
  "footerText": "Built with mdorigin.",
  "socialLinks": [
    { "icon": "github", "label": "GitHub", "href": "https://github.com/example/repo" }
  ],
  "editLink": {
    "baseUrl": "https://github.com/example/repo/edit/main/docs/"
  }
}

内置社交图标当前包括：

footerText 没有隐式默认值。省略时 mdorigin 不会自行渲染 footer 文案。

默认呈现

mdorigin 内置一种呈现。

当页面包含受管索引块时，默认渲染器把文章条目转换为结构化列表，并支持增量 Load more 分批。可以用以下配置调整列表行为：

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

规则：

搜索配置

当站点通过 mdorigin dev --search ... 或部署的搜索 API 暴露搜索包时，mdorigin 可以应用站点级搜索配置。

示例：

{
  "search": {
    "topK": 10,
    "mode": "hybrid",
    "minScore": 0.05,
    "reranker": {
      "kind": "embedding-v1",
      "candidatePoolSize": 25
    },
    "scoreAdjustment": {
      "metadataNumericMultiplier": "directory_weight"
    }
  }
}

支持字段：

规则：

查询感知策略示例：

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

目录类型

目录首页文件可在 frontmatter 声明内容类型：

---
title: Projects
type: page
---

---
title: Why mdorigin exists
type: post
---

规则：

Order

Markdown frontmatter 可以定义 order：

---
title: Getting Started
order: 10
---

规则：

渲染开关

别名

Markdown frontmatter 可以定义应重定向到当前规范路由的旧 URL：

---
title: Hello
aliases:
  - /hello-world
  - /old/hello
---

规则：