Oink: 用Markdown快速创建美观的现代网站
内容提要
Oink 是作者冯若航发布的本地优先 Markdown 文档框架，仅需 Markdown、Hugo 二进制和 Git 仓库即可建站，无需 Node.js 或外部 CDN。它统一支持文档、博客、书籍、下载页、Landing Page 和 API Reference 六类内容，坚持原生 Markdown、静态构建、离线可用，并为每页生成 .md 版本和 llms.txt 以适配 AI Agent。作者已将 18 个网站迁入，并以 Apache 2.0 开源。
延伸解读
为什么“本地优先”对文档很重要
Oink 强调本地优先，不仅指能在本地打开，更意味着内容、搜索索引、构建产物和运行时资源都掌握在自己手中。文章指出，文档不应因外部 CDN、字体服务或托管搜索停止工作而失效。对于需要内网、离线或长期归档的团队，这种设计能避免因外部依赖变化导致网站不可用，也便于迁移托管平台。
原生 Markdown 优先的取舍
Oink 尽量用原生 Markdown 表达内容，例如步骤用有序列表、Callout 用引用块、文件树用围栏块，仅在无法表达时才用 shortcode。这样做的好处是内容与表现逻辑分离，源文件对人类和 AI 都更干净，未来更换框架时内容本身不会被锁定。代价是某些复杂交互可能需要额外组件，但文章认为这比把内容写成私有方言更可持续。
为 AI Agent 设计的具体输出
Oink 为每个页面生成对应的 .md 版本，并在站点根目录生成 llms.txt，还提供“复制为 Markdown”“查看 Markdown 源码”等入口。这些是构建时生成的静态产物，不需要额外服务。文章强调，这能让 Agent 直接读取干净内容，而不必从 HTML 中剥离导航和脚本，适合作为可操作的工程知识库。
适用与不适用场景
Oink 适合开源项目作者、基础设施团队、需要内网或离线归档的团队，以及同时维护多个项目的人。但它不是万能框架：如果需要拖拽式 CMS、在线协作编辑、用户账号权限、大量动态状态或服务端实时计算，Oink 并不合适。它的边界是以 Markdown 和结构化数据为源，构建静态、现代、可靠的内容网站。
Q&A
Oink 是什么？它和普通 Hugo 主题有什么区别？
Oink 是一个开箱即用、本地优先的 Markdown 文档框架，只需 Markdown、Hugo Extended 二进制和 Git 仓库即可建站。它不只是主题，而是一套“文档发行版”，解决内容组织、多语言、版本管理、搜索、输出给浏览器/打印机/AI Agent 等整套问题。
Oink 支持哪些类型的内容？
Oink 统一支持六类内容：文档、博客、书籍、下载页、Landing Page 和 API Reference。它们共享同一套设计语言、搜索、语言切换、版本选择和组件体系。
Oink 如何支持 AI Agent 使用文档？
Oink 为每个页面生成对应的 .md 版本，在站点根目录生成 llms.txt，并提供“复制为 Markdown”“查看 Markdown 源码”以及可选的“在 ChatGPT / Claude 中打开”入口。这些是构建时生成的静态产物，不需要额外服务，也不会上传正文。
Oink 的本地优先体现在哪些方面？
Oink 构建不需要 Node.js、npm install、PostCSS、外部 CDN 或常驻后端服务；字体、样式、图标与交互运行时全部随项目本地交付，断网也能构建与服务。内容在 Git 仓库、资源在构建产物、搜索索引在站点内，构建可复现，托管平台可随时更换。
Oink 的全文搜索支持中文吗？
支持。Oink 的全文搜索完全在本地运行，Hugo 构建时为每种语言生成 JSON 索引，浏览器下载后在本地搜索。拉丁文字使用 Lunr，中文、日文等 CJK 查询有子串回退机制，不会出现英文能搜、中文形同虚设的情况。
谁适合使用 Oink？谁不适合？
适合开源项目作者、基础设施与工程软件团队、需要内网/离线/长期归档的团队、写书或维护大型知识库的人，以及同时维护多个项目的人。不适合需要拖拽式 CMS、在线协作编辑、复杂账号权限、大量动态业务状态或可随意嵌入 React 应用的前端平台等场景。
如何快速开始使用 Oink？
官方推荐的最快路径不是从空目录开始，而是克隆样例站，删掉不需要的部分，再替换成自己的内容。命令为：git clone https://github.com/pgsty/oink.pgsty.com my-docs，cd my-docs，hugo server。然后修改站点名称、域名和仓库地址，把 content/ 换成自己的内容即可。也可以直接把任务交给 Codex 或 Claude Code。
Oink 为什么坚持原生 Markdown 优先？
Oink 的第一原则是能用原生 Markdown 表达的东西就不发明新语法，比如步骤用普通有序列表、文件树用接近纯文本的围栏块、Callout 用普通引用块。只有当原生 Markdown 确实无法表达时才退回 shortcode。这样内容不会与表现逻辑纠缠，离开 Oink 后仍可被人类和其他 Markdown 工具读懂，框架过时后内容仍能长期存活。
Oink 的构建和部署需要哪些依赖？
只需要 Markdown、Hugo Extended 二进制和一个 Git 仓库。构建过程不需要 Node.js、npm install、PostCSS、外部 CDN，也没有必须常驻的后端服务。一条 hugo 命令即可生成完整的静态目录，可部署到 GitHub Pages、Cloudflare Pages、Netlify、Nginx、Caddy、对象存储、内网服务器或离线安装包等任何能托管静态文件的地方。
Oink 的测试和质量保障情况如何？
0.6 版本覆盖了 HTML、打印、Markdown、RSS 与 LLMS 等 40 个黄金输出面，包含 85 项迁移测试、38 项浏览器运行时测试，以及双语站点构建、大型站点性能测量和真实中英文浏览器检查。开发预览和生产发布采用不同错误策略：普通 hugo server 尽量警告并安全降级，生产构建使用 --panicOnWarning 让 CI 对警告保持严格。
