这是本节的多页打印视图。 .

文档

了解项目、完成安装、跟随教程，并查询精确行为。

1: 简介
- 1.1: 项目概览
- 1.2: 架构
2: 快速上手
- 2.1: 前置条件
- 2.2: 安装
3: 教程
- 3.1: 完成第一次修改
- 3.2: 添加文档页面
4: 参考
- 4.1: 配置
- 4.2: 命令参考

文档采用经典的四条路径：先了解项目，再让它运行起来，随后通过实践学习，最后查询参考资料。

1 - 简介

了解项目以及它背后的核心思路。

第一次接触项目时，请从这里开始。

1.1 - 项目概览

说明项目做什么、服务谁，以及为什么存在。

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

要解决的问题

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

最终结果

说明用户采用项目之后，能够成功完成什么。

提示

一份好的概览，应该让读者在两分钟内决定是否继续了解。

1.2 - 架构

为读者提供一个稳定的项目心智模型。

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

系统地图

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

边界

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

2 - 快速上手

检查前置条件并完成第一次安装。

从一台干净的机器开始，得到一个可以工作的本地结果。

2.1 - 前置条件

列出安装前需要准备的工具与权限。

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

工具

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

验证

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

$ project --version
project 0.1.0

发布前请把占位命令换成你的真实命令。

2.2 - 安装

帮助新用户从源码走到可工作的结果。

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

安装

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

确认结果

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

重要

发布项目文档前，请替换所有大写占位符。

3 - 教程

通过完成一次小而完整的修改来学习项目。

跟随一个端到端任务，而不是只阅读彼此孤立的知识点。

3.1 - 完成第一次修改

完成一次小修改并在本地验证。

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

从已知状态开始

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

只修改一件事

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

验证

运行项目最小而相关的检查，然后打开修改过的界面亲自确认。

3.2 - 添加文档页面

创建页面，把它放入侧栏，并建立链接。

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

创建文件

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

在这里说明这项能力。

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

添加翻译

在旁边创建 new-capability.zh.md 与 new-capability.fr.md。各语言的显式标题 ID 应当保持一致。

预览

运行 hugo server，打开新页面，再通过语言切换器检查每个译文。

4 - 参考

不必重读教程，直接查询配置与命令。

当你已经知道自己要查什么时，请使用这一栏目。

4.1 - 配置

在一个地方记录支持的配置项、默认值与示例。

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

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

示例

listen: 0.0.0.0:8080
log_level: debug
read_only: true

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

4.2 - 命令参考

列出每条命令的用途、语法与退出行为。

`project start`

启动本地服务。

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

`project check`

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

project check [--config FILE]

请用真实 CLI 帮助输出中的命令替换这些占位内容。