Project Name

配置

Mon, 01 Jan 0001 00:00:00 +0000

请用项目真实的公开配置面替换这张小表。

配置项	类型	默认值	含义
`listen`	字符串	`127.0.0.1:8080`	本地服务器监听地址
`log_level`	字符串	`info`	输出日志的最低级别
`read_only`	布尔值	`false`	禁用会改变状态的操作

示例

listen: 0.0.0.0:8080
log_level: debug
read_only: true

请在配置项旁边说明校验与优先级，不要把它们藏在另一份指南里。

前置条件

Mon, 01 Jan 0001 00:00:00 +0000

前置条件应当简短、精确，而且可以验证。

工具

受支持的操作系统。
用于获取源码的 Git。
项目所需的运行时版本。

验证

为每个前置条件提供一条验证命令：

完成第一次修改

Mon, 01 Jan 0001 00:00:00 +0000

这篇示例教程展示一项完整任务：准备、修改、验证与复查。

从已知状态开始

git status --short
git switch -c docs/first-change

只修改一件事

修改一个可见字符串或一个小配置值。第一次任务应足够聚焦，让结果一目了然。

项目概览

Mon, 01 Jan 0001 00:00:00 +0000

请用对你的项目最短而有用的说明替换这一页。

要解决的问题

使用读者熟悉的语言描述问题。在读者理解项目价值之前，先不要陷入实现细节。

预览站点

Mon, 01 Jan 0001 00:00:00 +0000

OINK Starter 是一个 Hugo Module 站点。Git 下载源码，Go 解析锁定版本的主题，Hugo 负责完成全部构建。

前置条件

安装 Git、Go 1.27 或更新版本，以及 Hugo Extended 0.165.0 或更新版本。hugo version 输出中必须包含 extended。

安装

Mon, 01 Jan 0001 00:00:00 +0000

首先给出最短且受支持的安装路径。

安装

git clone https://github.com/OWNER/PROJECT.git
cd PROJECT
./project start

确认结果

准确告诉读者成功是什么样子：要打开哪个网址、会看到什么消息，或者哪条命令应当返回零。

架构

Mon, 01 Jan 0001 00:00:00 +0000

记录贡献者在修改代码之前必须理解的少数组件。

系统地图

部分	职责
接口	接收用户输入并呈现结果
核心	执行项目规则
适配器	连接外部系统

边界

明确项目刻意不负责什么。清晰的边界可以避免文档承诺软件并未提供的能力。

理解目录结构

Mon, 01 Jan 0001 00:00:00 +0000

这个模板把每项职责放在一个明显的位置。

地图

hugo.yaml 站点身份、语言与可选集成
data/home/ 每种语言一份精简首页数据
content/blog/ 文章、设计记录与版本发布
content/docs/ 经典四部曲文档树
content/book/ 这份连续教程
.github/workflows/ GitHub Pages 与 Cloudflare Pages 部署

每个栏目首页 front matter 中的 menus.main 创建顶部导航及其下拉菜单。Docs 与 Book 下面的目录树则创建各自侧栏。

命令参考

Mon, 01 Jan 0001 00:00:00 +0000

`project start`

启动本地服务。

project start [--config FILE] [--listen ADDRESS]

`project check`

只校验配置，不启动服务。退出状态 0 表示有效；任何非零状态都表示该配置不应部署。

添加文档页面

Mon, 01 Jan 0001 00:00:00 +0000

在 OINK 中，内容树就是文档侧栏。新增一个 Markdown 文件，就会新增一个页面。

创建文件

---
title: 新能力
description: 这项能力做什么。
weight: 30
---

在这里说明这项能力。

将它保存为 content/docs/reference/new-capability.md。

把模板变成你的站点

Mon, 01 Jan 0001 00:00:00 +0000

大多数项目只需要修改内容，以及两处配置值。

只修改一次身份

在 hugo.yaml 顶部替换 Project Name 与 https://example.org/。YAML 标题锚点会把名称带入三种语言。

发布站点

Mon, 01 Jan 0001 00:00:00 +0000

生成的 public/ 目录是一份静态站点。仓库内置两条彼此独立的部署路径。

GitHub Pages

在仓库设置中选择 Pages → Source → GitHub Actions。推送到 main 会运行 .github/workflows/github-pages.yaml，workflow 会自动计算正确的仓库子路径。

欢迎来到项目博客

Thu, 15 Jan 2026 00:00:00 +0000

Post 栏目适合放置新闻、解读，以及不属于参考文档的项目故事。

这里适合发布什么

为希望了解背景的读者写作：项目为什么存在、团队学到了什么、接下来要做什么。

一套可以自然生长的精简内容模型

Sat, 10 Jan 2026 00:00:00 +0000

这个模板为每种写作提供一个明显的归宿。这样的分工既让导航可预测，也不会过早锁死项目的分类体系。

三种阅读方式

博客说明项目如何随时间变化。
文档回答聚焦的问题。
书籍按顺序教授完整工作流。

只在需要时增加结构

先使用现有栏目。只有当读者确实需要另一条内容路径时，再增加新的分支。

Project 0.1.0

Thu, 01 Jan 2026 00:00:00 +0000

0.1.0 版本建立了项目第一个可用的公开基线。

主要内容

一条写清楚的安装路径。
一个小而稳定的公开接口。
一个明确的问题反馈入口。

升级说明

这是第一次发布，因此没有旧版本需要迁移。

Project Name

配置

示例

前置条件

工具

验证

完成第一次修改

从已知状态开始

只修改一件事

项目概览

要解决的问题

预览站点

前置条件

安装

安装

确认结果

架构

系统地图

边界

理解目录结构

地图

导航跟随内容

命令参考

project start

project check

添加文档页面

创建文件

把模板变成你的站点

只修改一次身份

发布站点

GitHub Pages

欢迎来到项目博客

这里适合发布什么

一套可以自然生长的精简内容模型

三种阅读方式

只在需要时增加结构

Project 0.1.0

主要内容

升级说明

`project start`

`project check`