跳转至

工作室文档撰写与发布指南 (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:访问后台并登录

  1. 浏览器打开后台入口:https://docs.lynmio.com/admin/;
  2. 点击 Login with Gitea,使用工作室统一身份账号(Authentik / Gitea)完成授权;
  3. 登录成功后即可看到内容集合面板。

步骤 2:选择对应板块

左侧侧边栏预设了与仓库严格对应的分类集合:

步骤 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/
浏览器打开 http://127.0.0.1:8000/。 你在 VS Code 里编辑任何 .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
若出现死链、未闭合的代码块或非法 YAML 格式,终端会直接输出警报并提示具体文件名与行号。

步骤 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. 双轨协同防冲突守则

  1. 本地编写前先拉取 (git pull): 在本地修改文档前,建议先执行 git pull,确保把同事在 Sveltia CMS 上发布的新内容拉取到本地,避免产生分支冲突;
  2. 避免多端同时修改同一文件: 不要在本地 VS Code 未提交的同时,又去网页 CMS 后台打开同一个页面编辑;
  3. 大文件与媒体管理: 严禁将未经压缩的巨大原图(如数十兆的未裁切 4K 截图)直接扔进 Git 仓库。Sveltia CMS 会自动压缩;本地编写时请将图片转换为 WebP / 压缩格式后存放在 content/images/ 目录下。