everkm-publish（毓知发布） 与 Hugo、Jekyll、Zola 一样，都是把 Markdown 变成静态网站的工具。我们做它，不是为了再造一个「博客生成器」，而是为了让笔记、文档、知识库在长期积累后，仍能稳定地被组织、被发现、被链接——这是 Everkm 生态从第一天就在解决的问题。
下面按能力对比，说明我们和常见 SSG 的分水岭在哪里。完整能力见 Everkm Publish。
共同点
- 无需数据库
- 本地预览 + 静态导出
- 部署到 Nginx、CDN、GitHub Pages、Vercel 等任意静态托管
- 内容与外观分离：Markdown 写正文，主题管布局
最终都是标准 HTML，SEO 友好，无运行时依赖。
1. 定位：博客、文档、知识库都能做，结构由你定义
Everkm Publish 不是「只能做 Wiki」。同一套工具可以同时承载：
| 形态 | 怎么做 |
|---|---|
| 博客 | template: list + 标签 / 列表页 |
| 书籍 / 文档站 | template: book + _nav.md 章节树 |
| 知识库 / Wiki | 内链互联 + 多层级目录 |
| 产品官网 | 首页 + 文档 / 更新日志分区 |
Hugo / Zola 偏通用站点，Jekyll 偏博客；Everkm 同样覆盖这些形态，但站点结构由 folders 决定，而不是锁死在「首页 → 分类 → 文章」的博客骨架上。
与 Abox Note 同源索引语义，从写作到发布是一条链路，而不是两套互不相干的工具。
详见：概念与架构、目录配置、Everkm Publish — Markdown 静态站点生成器。
2. 站点结构：folders 配置 vs 约定式目录
这是差异最大的地方之一。
Everkm 在 everkm.yaml#folders 里按路径声明规则：
- 每目录指定模板（
book/list/post等） - URL 与磁盘目录解耦（
url_slug、hide_in_url） - 哈希分散存储（
hash_scatter） - 面包屑、
query（如nav_file）沿祖先链继承合并
磁盘上的 /blog/2025/hello.md，对外可以是 /posts/hello.html——中间目录不必出现在 URL 里。
| Everkm Publish | Hugo | Jekyll | Zola | |
|---|---|---|---|---|
| 结构定义 | 显式 folders YAML | content/ + sections | _posts/ + collections | content/ + sections |
| URL 控制 | 目录级配置 + 稳定 id | permalinks / slug | permalink 模板 | slug / section path |
| 文档导航 | _nav.md + nav_tree 内建 | 主题或插件 | 插件 | 自定义 |
详见：目录配置。
3. 稳定 URL ID：标题改了，链接还能到
通用 SSG 里，URL 往往跟标题 / slug 绑死：改个标题，旧外链就断。
Everkm 默认把稳定页面 ID编进 URL（url_id_suffix: true）：
/blog/hello-abc123.html ← slug + 稳定 id
- 标题、slug 可变，
id不变 - 宿主平台按 ID 解析或重定向，旧链接仍能到达同一篇
- 需要短路径时可关：
url_id_suffix: false→/blog/hello.html
纯静态文件不会自己跳转，需要导出元数据 + 平台支持：
| 能力 | 说明 |
|---|---|
| 导出元数据 | 索引 / file-meta 输出含发布 URL 的页面元数据；别名、permalink 进入重定向图 |
| Nginx | --with-nginx-map 生成 url_map |
| Vercel | --with-vercel 生成平台重定向配置 |
| 追加规则 | everkm.yaml#redirects，与索引别名、permalink map 合并 |
我们把「稳定 ID → URL 映射 → Nginx / Vercel 配置」串进发布链路，就是为了「知识会改标题，外链不能断」。
详见：目录配置、文章元数据、导出与发布、站点配置、CLI 速查。
4. Markdown 方言：毓知 Markdown
在标准 Markdown 与 GitHub Flavored Markdown 之上，我们加了一层面向写作与互联的扩展（完整说明见 毓知Markdown格式）：
| 扩展 | 作用 |
|---|---|
[[内链]] | 站内页面 / 媒体互引，导出时解析为最终 URL；歧义在 lint / 导出时报错 |
宏 macro/toc、macro/include | 自动 TOC；嵌入 Markdown、表格、代码等外部文件 |
| dCard | 正文声明展示卡片（下载、音视频等），主题渲染为 HTML |
| 区块 / 行内扩展属性 | {.class}、#id、对齐、颜色、背景、圆角等，作用在标题、段落、表格、链接、图片 |
| 下划线 / 上标 / 下标 / 高亮 | {ul}#…#、^…^、~…~、… |
_nav.md | 章节目录，配合 nav_tree 做书籍侧栏 |
链接怎么写，分场景：
- 正文 Markdown：内链
[[...]]写法很灵活——按 slug / 标题、相对目录[[./faq/]]、站点根路径[[/docs/guide/quick-start.md]]、锚点[[./page#section-id]]、自定义文案[[./faq/|常见问题]]等均可（见 链接与内链）。 - 导出限制：站内页面互跳不要用标准 Markdown 的相对路径链接（如
[下一页](./next.html)），导出时会被校验拦截；应改用内链。 - 模板：
nav_tree、post_detail等的from_file/path参数同样用[[...]]，不要用相对文件路径。 - 校验：
everkm-publish lint检查坏链与歧义；导出 / CI 遇无法解析或歧义内链会立即报错，预览时以虚线下划线标出但不中断整页。
Hugo 有 ref/relref，Jekyll 靠插件，Zola 有部分短链语法——我们把内链、属性集、宏、dCard 做成同一套方言，并纳入发布校验。
详见：毓知Markdown格式、链接与内链、导航与目录、展示卡片 (dcard)。
5. 主题：远程安装 + Jinja2 / TSX 双轨并行
| Everkm Publish | Hugo | Jekyll | Zola | |
|---|---|---|---|---|
| 模板引擎 | Jinja2 语法与 TSX / JS 渲染 并列，任选其一或组合 | Go templates | Liquid | Tera |
| 主题分发 | theme install 远程 / ZIP | Modules / submodule | Gem | 手动复制 |
| 站点覆盖 | __everkm/extend/ | layouts/ | _layouts/ | templates/ |
主题 ≠ 页面模板。 主题是完整皮肤包；folders.template 指定某一目录用哪套页面模板。
经典主题：
Jinja2 与 TSX 没有主次之分，同一主题里可以并存：简单页面用 Jinja2，复杂布局用 TSX / JS 渲染，按场景选择即可。
TSX 路径推荐 SolidJS——比 React 轻量得多，无虚拟 DOM，适合生成期 JS 沙箱。你只需要 TSX 语法来写 HTML 结构，不必引入路由、状态管理、响应式变量等框架全家桶；编译后输出 everkm-render.js，在沙箱里一次性渲染出静态 HTML，不是带运行时的 SSR。官方参考实现见 theme-youlog 与 主题开发。
相比层层传递模板变量，组件化 TSX 结构更清晰、大型主题更易维护。
6. 构建与导出：默认爬取，可补入口
默认导出：
从 /index.html 出发 → 跟踪内链 → 导出被引用的页面与资源
未被引用的资源不会进 dist/；需要额外文件时放 __everkm/extend/assets/。
若有页面内链爬不到（例如仅作深链入口），CLI 可用 --start-urls 追加遍历起点，再纳入导出图。
Hugo / Jekyll / Zola 通常是「扫完 content 全量编译」。我们默认只发布被连到的内容，更贴近知识站；需要全量时，用入口参数补齐即可。
详见：导出与发布。
7. 搜索：Algolia 串进导出
config.algolia+push_on_export: true→ 导出后自动 reset + pushsite/channel区分多站、多栏目- 也可单独用
everkm-publish algolia
其他 SSG 也能接 Algolia，但多半靠插件或自写 CI；我们把「导出 → 推索引」做成官方推荐路径。
详见：嵌入式搜索。
8. 构建期渲染
生成阶段即可完成：
- 服务端代码高亮（无需浏览器再加载高亮库）
- 服务端公式渲染为内联 SVG（无需浏览器公式引擎）
用 everkm.yaml 开关控制；对比侧各自靠内置高亮或插件，我们把开关收进站点配置。
详见：站点配置。
9. 工具链与生态
| 能力 | Everkm Publish | Hugo / Jekyll / Zola |
|---|---|---|
| CLI | serve / lint / theme / algolia / web / file-meta | 各自 CLI |
| Lint | Front Matter + 内链，可 --auto-fix | 多为外部工具 |
| 多语言 | 语言目录 + @i18n: + --lang | Hugo 强；其余不一 |
| 插件生态 | 主题 + extend + dCard | Modules / Plugins 更成熟 |
| URL 稳定性 | 稳定 id + Nginx / Vercel 元数据导出 | 多为手写 redirects |
| 与笔记互通 | Abox Note → 发布同链路 | 无 |
10. 怎么选
| 场景 | 说明 |
|---|---|
| 博客、营销页、文档站、知识库 | Everkm 都支持；Hugo / Jekyll / Zola 也都能做，差异在模型是否贴合长期知识 |
| Wiki 内链 + 发布前 lint | Everkm 一等公民 |
| 标题常改、外链要按 ID 到达 | Everkm + Nginx / Vercel |
| 导出即推送全文搜索 | Everkm + Algolia |
| 需要极成熟的第三方插件海 | Hugo / Jekyll 生态更大 |
| 已在 Everkm / Abox Note 写作 | 直接用 Publish 发布即可 |
差异概括
Everkm Publish（毓知发布） 是 Everkm 生态下的 Markdown 静态站点生成器：写 Markdown，选主题，本地预览，导出 HTML，部署到任意静态托管。
与 Hugo、Jekyll、Zola 一样，它无需数据库、产出标准 HTML、支持 CDN / Nginx / Vercel / GitHub Pages。差异在于，我们面向长期积累的知识，而不只是「发一篇博客」：
一、一种工具，多种站点形态
博客、书籍文档站、知识库 / Wiki、产品官网——同一套 CLI 都能做。站点结构由 folders 目录配置定义，不锁死在「首页 → 分类 → 文章」的博客骨架。经典主题 youlog（文档 / 知识站）与 paper（博客）即为例证。
二、URL 与目录解耦，标题改了链接不断
磁盘目录与对外 URL 可分离；默认 URL 含稳定页面 ID（slug-id），改标题 / slug 后 ID 不变。导出元数据并生成 Nginx / Vercel 重定向配置，旧外链仍可到达同一篇内容。
三、毓知 Markdown：为互联而写的方言
在标准 Markdown 之上扩展内链 [[...]]（支持 slug、相对路径、站点根路径、锚点、自定义文案等多种写法）、宏、dCard 卡片、区块 / 行内扩展属性、章节目录 _nav.md。站内页面互跳用内链；发布前 lint 检查坏链与歧义，守住知识网络。
四、主题双轨：Jinja2 与 TSX 并列
主题可用 Jinja2 语法，也可用 TSX / JS 渲染——二者并列、无主次，可按页面复杂度组合。TSX 推荐 SolidJS：比 React 轻量，只需 TSX 语法组织 HTML，无需路由、状态、响应式变量；编译后在生成期一次渲染出静态 HTML。主题可远程安装，站点通过 extend/ 覆盖。
五、导出贴近知识站，也可补全入口
默认从首页沿内链爬取导出；未被引用的页面不进 dist/。可用 --start-urls 追加遍历起点。未被正文引用的资源放 extend/assets/。
六、搜索与构建期能力内建
Algolia 全文搜索可配置「导出即推送」；多站 / 多栏目用 site / channel 隔离。代码高亮、公式渲染可在生成阶段完成，减少浏览器负担。
七、与 Abox Note 同源
从笔记写作到站点发布共用索引语义，不是两套互不相干的工具链。
通用 SSG 插件生态更广、自由度更高；Everkm Publish 更适合把长期积累的 Markdown，稳定地变成可组织、可互联、可搜索、改标题仍不断链的静态站点。
一句话总结
Everkm Publish 和 Hugo、Jekyll、Zola 一样能做出漂亮的静态站；我们多做的是：多形态站点、folders 解耦 URL、稳定 ID + 平台重定向、毓知 Markdown 内链与 lint、Jinja2 / TSX 双轨主题、爬取式导出、Algolia 与构建期渲染内建、Abox Note 同源——把「写出来」接到「被找到」。