工作室文档撰写与发布指南 (Docs Authoring Guide)
- Target Audience: 全体工作室成员(美术师、策划、TA、研发人员)
- Owner: @micho
- Status: Approved
- Scope: Lynmio Docs (
docs.lynmio.com) 知识库协同与维护
1. 双轨协作架构 (Dual-Track Workflow)
为兼顾非开发人员的轻量易用性与技术人员的代码级精确控制,Lynmio Docs 采用“双轨并行”的创作与维护体系:
flowchart TD
subgraph TrackA ["轨道 A: Web 在线可视化 (轻量 / 免命令行)"]
Browser["浏览器打开 Sveltia CMS 后台<br/>docs.lynmio.com/admin/"] --> GiteaOAuth["Authentik / Gitea 单点登录"]
GiteaOAuth --> FormEditor["图形化表单 + Markdown 可视化编辑"]
FormEditor --> EditorialWorkflow["Editorial Workflow (草稿 → 审阅 → 发布)"]
end
subgraph TrackB ["轨道 B: 本地 Docs-as-Code (沉浸 / 高度可控)"]
LocalFS["本地仓库: ~/Lynmio/Docs"] --> VSCode["VS Code / 文本编辑器 + Git GUI"]
VSCode --> LiveReload["uv run mkdocs serve<br/>(127.0.0.1:8000 本地实时秒级热重载)"]
LiveReload --> GitPush["Git 提交并推送至 git.lynmio.com"]
end
EditorialWorkflow --> GitRepo["Git 核心仓库 (studio-lynmio/docs)"]
GitPush --> GitRepo
GitRepo --> CI["自动化构建与边缘分发 (Cloudflare Pages)"]
CI --> PublicDocs["正式站点: https://docs.lynmio.com"]
| 对比维度 | 轨道 A: Web 在线可视化 (Sveltia CMS) | 轨道 B: 本地 Docs-as-Code (VS Code + Git) |
|---|---|---|
| 主要面向人群 | 美术师、策划、快速记录者、移动端排查 | TA、流程开发、长篇架构编写者 |
| 环境门槛 | 零配置:只需现代浏览器 + 工作室统一账号 | 需安装本地 Python (uv) 与 Git 客户端 |
| 编写体验 | 所见即所得表单,图片拖拽自动转码 WebP | 沉浸式多光标编辑、Mermaid 实时图表、批量重构 |
| 实时预览 | 双栏分屏简易预览 | 浏览器 127.0.0.1:8000 完整热更新渲染 |
| 推荐适用场景 | 错别字修复、查漏补缺、新增简短规范与流程 | 编写整套系统技术方案、大型重构、复杂流程图 |
2. 轨道 A:Web 在线可视化写 (Sveltia CMS)
[!TIP] 适合不想打开终端、不想在本地装环境的创作者。
步骤 1:访问后台并登录
- 浏览器打开后台入口:https://docs.lynmio.com/admin/;
- 点击 Login with Gitea,使用工作室统一身份账号(Authentik / Gitea)完成授权;
- 登录成功后即可看到内容集合面板。
步骤 2:选择对应板块
左侧侧边栏预设了与仓库严格对应的分类集合:
- 核心规范 (Specs):约束性规矩(如命名规范、资产导入标准);
- 流程清单 (Workflows):跨部门交接与检查清单(Checklist);
- 避坑手册 (Manuals):工具配置、环境初始化、排错指南(本篇即属于此);
- 架构决策 (ADR):重大技术选型背景与权衡留痕;
- 草稿沙盒 (Sandbox):不成熟构想、免检讨论稿。
步骤 3:填写表单与编写正文
点击右上角 新建条目 (New Item),在表单中填写:
* 标题 (Title):清晰明确的页面名称;
* 描述 (Description):一句话总结本篇核心主旨;
* 审阅日期与周期 (Review Cycle):默认 90 天,系统根据此周期自动提醒更新,防止“文档腐烂”;
* 图片插入:直接拖拽本地截图到编辑器正文,Sveltia CMS 会自动将其无损转换为高质量 WebP 并安全存入 content/images/uploads/;
* 正文 (Body):标准 Markdown 格式,右侧提供实时排版预览。
步骤 4:草稿保存与发布流程 (Editorial Workflow)
Sveltia CMS 开启了审核流,确保线上文档的严肃性:
1. 保存草稿 (Draft):点击 Save,后台会在 Git 仓库自动建立一个临时草稿分支,不会影响主干生产;
2. 提交审阅 (In Review):在顶部状态栏切换为 In Review,触发自动化构建测试;
3. 正式发布 (Publish):确认无误后点击 Publish,后台自动合并入 main 分支,Cloudflare 边缘节点在 60 秒内全网分发完成。
3. 轨道 B:本地沉浸式编写 (VS Code + Git + 实时热预览)
[!TIP] 适合需要编写长篇文档、大段代码块、Mermaid 拓扑图或进行全库重构的技术人员。
步骤 1:定位本地工程
在 macOS 终端中,你可以通过统一软链接直接进入文档工程:
cd ~/Lynmio/Docs
# 物理路径位于: /Users/micho/MichoDev/Antigravity/lynmio-docs
用 VS Code 打开该目录:
code .
步骤 2:启动本地实时热重载服务 (Live Preview)
无需手动配置复杂的 Python 依赖,直接通过 uv 运行服务:
uv run mkdocs serve
终端会输出:
INFO - Building documentation...
INFO - Serving on http://127.0.0.1:8000/
.md 文件并保存(Cmd + S),浏览器页面无需手动 F5 刷新,会在 0.2 秒内自动热更新呈现!
步骤 3:推荐 VS Code 插件生态
为了获得最佳编写体验,建议在 VS Code 中安装以下插件: 1. Markdown All in One:快捷键自动加粗、列表自动缩进、自动生成目录; 2. Markdown Preview Mermaid Support:在本地原生渲染 Flowchart、Sequence、State 等拓扑图; 3. GitLens / GitKraken:可视化对比修改历史、分支树及提交记录。
步骤 4:标准文档元数据模板 (Frontmatter)
在 content/ 旗下对应文件夹新建 .md 文件时,请务必在文件顶部保留 Frontmatter 元数据块:
---
title: 文档名称 (中文或双语)
description: 一句话概述该文档的目的与作用
last_reviewed: '2026-11-20'
review_cycle_days: 90
tools:
- Maya
- Rez
---
步骤 5:本地语法与死链校验 (Build Test)
完成编写后,在终端运行一次构建检测:
uv run mkdocs build
步骤 6:版本提交与同步 (Git Push)
你可以使用 VS Code 左侧自带的 源代码管理 (Source Control) 面板(快捷键 Ctrl + Shift + G):
1. 在变更列表勾选暂存(Stage Changes);
2. 填写清晰的 Commit 信息,遵循 Conventional Commits 规范(如 docs(manuals): add new rig checklist);
3. 点击 Commit 并点击 Sync Changes (同步) 推送至 git.lynmio.com。
终端用户亦可使用常规 Git 命令:
git add content/manuals/your-new-doc.md
git commit -m "docs(manuals): add your-new-doc"
git push origin main
4. 双轨协同防冲突守则
- 本地编写前先拉取 (
git pull): 在本地修改文档前,建议先执行git pull,确保把同事在 Sveltia CMS 上发布的新内容拉取到本地,避免产生分支冲突; - 避免多端同时修改同一文件: 不要在本地 VS Code 未提交的同时,又去网页 CMS 后台打开同一个页面编辑;
- 大文件与媒体管理:
严禁将未经压缩的巨大原图(如数十兆的未裁切 4K 截图)直接扔进 Git 仓库。Sveltia CMS 会自动压缩;本地编写时请将图片转换为 WebP / 压缩格式后存放在
content/images/目录下。