Docsify vs Htmlpress

Docsify 是一款文档站点工具，它的做法与本节其他所有工具都不同：它不在构建时生成静态 HTML，而是只提供一个 index.html 加上一个 JavaScript 运行时，在浏览器中获取 Markdown 文件并即时渲染。没有构建步骤。

概览

架构

htmlpress 是一个 Rust 二进制文件，可从 npm（gethtmlpress）、PyPI 或 crates.io 安装。它把每个 HTML 页面包裹进同一个带导航和主题的布局中；没有打包器、没有 UI 框架，也没有插件 API。每个内置文件——布局、样式、脚本和每个组件——都可以被弹出：在 .htmlpress/ 下相同路径放置一个文件即可替换它。页面在构建时被预渲染为静态 HTML；编辑时，htmlpress start 会以实时重载的方式提供页面。

Docsify 没有构建流水线。一个站点就是一个 index.html，它从 CDN（或 node_modules）加载 docsify.js，并在 window.$docsify 上配置一个小型配置对象。运行时，脚本读取 URL 哈希（#/some/page），用 fetch() 获取对应的 .md 文件，交给 marked 解析 Markdown、Prism 做语法高亮，然后把结果注入页面。导航默认基于哈希；History API 模式需要手动开启，但要求服务器配置重写。

在 htmlpress 一侧，内容布局不受约束：它按 glob 扫描（htmlpress.yaml 中的 include/exclude，默认是所有 .html 文件），页面的 URL 跟随其在 glob 基础路径之下的文件路径，因此 docs/**/*.html 会把 docs/guide.html 提供在 /guide/。不要求存在 docs/ 文件夹。导航由文件夹和每个页面的 <meta name="order"> 构建；文件夹的 index.html 为其分组命名。Docsify 从单一源根目录读取（包含 index.html 的目录，可通过 basePath 配置），请求 URL 直接映射到磁盘上的文件路径——#/guide/install 会获取 guide/install.md。侧边栏导航需要在 _sidebar.md 中手动编写；没有自动生成的导航。

内容形式

Docsify 支持纯 Markdown（通过 marked 实现 CommonMark）以及少量内置扩展：辅助语法（通过 docsify-tabs 和 admonition 插件实现的 > [!TIP] 风格提示框）、HTML 直通，以及在加载可选 Vue 编译器时有限的 Vue 模板风格指令。没有 MDX，默认不解析 frontmatter（可由插件添加），也没有按页面的 React 组件。插件通过把函数推入 window.$docsify.plugins 来注册，并挂接到生命周期（init、mounted、 beforeEach、afterEach、doneEach、 ready）。

htmlpress 页面是纯语义化 HTML，主题直接根据元素本身设置样式。更丰富的区块是 htmlpress-* 自定义元素（htmlpress-callout、htmlpress-tabs、 htmlpress-filetree、htmlpress-cards……），其 CSS 和 JS 只在使用该标签的页面上链接。项目可以通过 .htmlpress/components/<name>/<name>.html 添加自己的标签，它会在构建时替换该标签。

htmlpress 没有 frontmatter：页面的元数据就是它自己的 <head>——<title>、 <meta name="description">、 <meta name="order">、<meta name="layout"> 和 <meta name="image">；其他 <head> 标签会被保留。

功能矩阵

输出与部署

这是两者分歧最大的地方。

htmlpress 生成一个由预渲染 HTML + 资源组成的目录（.htmlpress/build/）。每个页面都是真实的 HTML 文件；爬虫、链接预览和禁用 JS 的客户端都能看到渲染后的内容。htmlpress 把每个页面写为 .htmlpress/build/ 中的静态 HTML，同时写出 robots.txt、设置了 site 时的 sitemap.xml、每个页面的 Markdown 副本、llms.txt，以及位于 .well-known/agent-skills/ 下的智能体技能。base 键让站点在子路径下提供服务。托管平台指南见 部署。

Docsify 把原始 .md 文件与 index.html 一起发布。所谓“部署”就是把源目录上传到任意静态托管平台。代价是：零构建时间、编辑即刷新的写作体验，换来的是首次绘制时 HTML 为空——搜索引擎、社交预览和无 JS 客户端只能看到加载器外壳。该项目文档介绍了一种使用 docsify-ssr 或外部预渲染器的 SSR/预渲染工作流，用于为 SEO 敏感的站点缓解这一问题。

另请参阅

• 编写——htmlpress 的 HTML 写作面。
• 自定义——htmlpress 的配置键与弹出文件。
• 对比——返回索引。