维护指南

本百科是 Gitea Wiki, 内容存放在独立的 wiki Git 仓库中。本页说明如何新增/修改页面、如何保持与代码文档同步。

1. Wiki 仓库

浏览: http://gitea.bitnasdaq.vip/wandering1/STM32F4-Base/wiki
克隆:

git clone http://gitea.bitnasdaq.vip/wandering1/STM32F4-Base.wiki.git

需要仓库写权限。Gitea 的 Wiki 也支持网页端直接新建/编辑页面; 批量修改建议走 Git。

2. 页面与文件

文件	用途
`Home.md`	首页(默认页)
`_Sidebar.md`	全站侧边栏(特殊页, 不出现在页面列表)
`_Footer.md`	全站页脚(特殊页)
`快速开始.md`、`项目架构.md` …	普通页面; 文件名即页面标题

约定:

页面名不含空格; 中文页面名直接用中文;
一页一个主题, 长内容拆页, 不要把所有内容堆在 Home;
页面之间用相对页面链接(Gitea 会把它拼到 /wiki/ 下, 不要带 /wandering1/... 前缀): [项目架构](项目架构);
指向仓库源码/文档用: http://gitea.bitnasdaq.vip/wandering1/STM32F4-Base/src/branch/master/<path>;
不要复制大段源码或私有数据; 需要细节时链接到 docs/。

3. 本地编辑与发布

# 1. 拉到最新
git pull

# 2. 新建或编辑 Markdown 文件
#    例如: 新增 常见问题.md

# 3. 本地预览(可选)
#    任意 Markdown 预览器; 表格/代码块/相对链接需按 Gitea 行为检查

# 4. 提交并推送
git add .
git commit -m "docs(wiki): add FAQ page"
git push

推送后 Gitea 会自动刷新 Wiki 页面。若页面未出现, 检查:

文件名是否以 .md 结尾;
是否推到了 wiki 仓库(不是主代码仓库);
是否有写权限;
页面名是否与链接中的名字一致。

4. 与主仓库文档同步

本百科是入口与摘要, 权威内容在主仓库 docs/ 与代码中。以下变更需要回来更新百科:

主仓库变更	需要更新
任务表 / 栈大小(`Src/freertos.c`)	项目架构任务表
网络端口 / FTP 鉴权	网络子系统
引脚 / 硬件版本	硬件平台
ADC 链路 / 保护任务 / 104	采集与算法
存储栈 / FatFs 配置	存储子系统
UI 菜单 / 字体 / 模拟器	UI子系统
构建/测试命令、门禁数量	快速开始、测试与调试、开发指南
新增高频陷阱	已知陷阱
文档增删/改名	文档地图

同步原则:

以 master 的最新代码与 AGENTS.md 为准;
数字容易漂移(栈、内存、用例数), 能写范围就不写死; 必须写死时注明“截至日期”;
不在百科里维护第二套“需求文档”; 需要完整需求时链接主仓库。

5. 写作风格

先给结论/规则, 再给原因和细节;
命令用代码块, 标明 PowerShell;
表格用于对照, 不要用大段文字堆参数;
每个页面末尾给出“延伸阅读”, 链接到主仓库文档;
页面顶部标注最后整理日期;
中文标点统一; 代码、路径、宏名用反引号;
不写未经验证的“应该可以”; 不确定的内容标注“待确认”或链接到源码。

6. 提交信息

建议使用:

docs(wiki): <一句话说明>

例如:

docs(wiki): update network ports and FTP auth
docs(wiki): add RS-485 status note

7. 页面清单

当前页面:

新增页面后, 请同时更新 _Sidebar.md 与本页清单。

8. 权限与安全

Wiki 跟随仓库权限; 无写权限的用户只能阅读;
不要在 Wiki 放口令、密钥、内网地址以外的敏感信息;
FTP 默认口令等现场配置只作为“必须修改”的提醒, 不要写真实口令;
涉及客户/现场数据的内容不要贴到 Wiki。

STM32F4-Base 百科

入门

子系统

开发与验证

参考

仓库

STM32F4-Base 百科 · 基于仓库 master 分支整理 · 最后更新: 2026-11-01

内容以源码、AGENTS.md 与 docs/ 为准; 发现页面过期, 请在维护指南中按流程更新。