TiXL 文档工程化从 Wiki 迁移到.help/基于 MkDocs Vercel 的发布流水线与 Operator 参考自动生成【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3本文是 TiXL实时动态图形创作工具文档系统重构的完整技术方案解读。核心目标是把面向用户的文档从 GitHub wiki 迁移到仓库内的.help/目录作为唯一事实来源并通过 MkDocs Material Vercel 构建部署为独立文档站点同时把Lib.*运算符库的 662 页参考文档改为由编辑器内的SymbolUi元数据自动生成配合 MkDocs 构建钩子实现[OperatorName]语法的自动链接。读完本文你将掌握这套内容进仓库、构建在云端、参考自动生成、链接自动解析的文档流水线的完整设计分层判据、目录信息架构、mkdocs.yml/vercel.json关键配置、横幅迁移脚本、导出器与自动链接钩子的源码级实现以及后续运营图片、版本化、编辑审查的注意事项。方案对应的规划文档为仓库中的 .agentic/Plans/archive/Plan_UpdateHelp.md文中所有配置、脚本与生成器均已落地在仓库内可直接对照源码验证。一、为什么要把文档从 Wiki 迁进仓库一条清晰的分界线TiXL 的文档原先全部托管在 GitHub wiki 上混合了面向使用者的帮助页与面向开发者的贡献页。本次迁移的核心不是搬家而是按读者类型彻底切分内容的所有权.help/目录 —— 面向用户。安装、UI 使用、How-to、FAQ、自定义 Shader / 自定义 Operator 编写、现场演出、进阶功能。它是唯一事实来源single source of truth随代码一起发布构建后部署到文档站点凡是从 wiki 迁移过来的页面wiki 原页顶部都会挂一条跳转横幅指向新地址。GitHub wiki —— 面向开发者。从源码构建 TiXL、编码规范、CI、集成测试、RenderDoc、git 工作流、发版流程、临时设计讨论。这些页面留在 wiki 上保持可编辑不迁移、不加横幅。规划的原文给了一条可操作的判据Plan_UpdateHelp.md如果做动态图形或现场视觉的用户会想读它就放进.help/如果只有打开t3.sln的人会想读它就留在 wiki。这条分界线也同步固化在 .help/README.md 与 .help/docs/STYLE.md 中前者描述目录职责后者开篇即声明 user-facing here, contributor-facing there。这样划分的直接收益是——用户文档可以随代码一起走 PR 评审、随版本发布而不是游离在独立的 wiki 仓库里等着被人遗忘。二、信息架构IA面向读者的五段式导航迁移过程中原来的general//setup//ui/三段式结构被重构为按读者旅程组织的五段式外加一个自动生成的运算符参考区.help/ ├── README.md # 贡献者导览不发布 ├── mkdocs.yml # 站点配置 ├── requirements-docs.txt # Python 依赖 ├── vercel.json # Vercel 安装/构建/输出配置 ├── docs/ # mkdocs docs_dir —— 全部 Markdown │ ├── index.md STYLE.md .pages │ ├── getting-started/ install/ using/ advanced/ contributing/ operators/ ├── site/ # 构建输出gitignore ├── .venv/ # 构建虚拟环境Vercel 本地gitignore └── .src/ # 未来页面的原始素材不发布getting-started/TiXL 是什么、概念、视频教程、SkillQuest、从 Tooll3 迁移、报 Bug、社区install/Windows / Linux / macOS 安装、开发环境搭建using/日常参考 —— UI、时间线、导出、预设快照、现场演出、OSC/ArtNet、性能优化等advanced/自定义 Shader、C# Operator、字体contributing/文档与开发入口operators/由符号图自动生成的运算符参考见第五节。每个 section 目录都有自己的README.md列出已有页面和**Still to write待写清单**。规划文档明确要求主题缺失时不要创建空占位页而是在 README 的 Still to write 里加一行等有具体内容再补页。这种做法避免了空页面噪音也让贡献者一眼看到缺口。导航顺序由 .help/docs/.pages 驱动根级与每个 section 级都有.pages文件被awesome-pages插件读取# .help/docs/.pages —— 根级导航顺序 nav: - index.md - getting-started - install - using - advanced - contributing - operators在仓库的 .help/docs 目录中可以看到这套结构已经完整落地且using/下比规划时又新增了Audio.md、CharacterAnimation.md、ImportingAssets.md、MidiFileImport.md、ProceduralGeometry.md、Recording.md、SwiftCamSetup.md、Timeline.md等页面说明该框架具备良好的持续生长能力。三、MkDocs Vercel站点配置与云端构建3.1mkdocs.yml关键配置解读站点配置见 .help/mkdocs.yml逐项拆解site_name: TiXL Documentation site_url: https://help.tixl.app/ docs_dir: docs # 源码目录相对于配置文件 site_dir: site # 构建输出目录gitignore use_directory_urls: true strict: true # 死链/缺图即构建失败要点docs_dir: docs、site_dir: site均相对配置文件解析因此整个构建产物都收在.help/内仓库根目录保持干净。strict: true规划执行初期为false2026-04-18 已翻转为true——从此死链、缺失图片会直接让 Vercel 构建失败而不是作为警告悄悄放行。这是内容质量作为发布门禁的关键一步。主题 Material启用navigation.tabs顶级 section 显示为标签页、navigation.sections侧边栏分组、navigation.footer自动生成上一页/下一页、navigation.instant客户端导航、search.suggest/search.highlight、content.action.edit每页在 GitHub 上编辑入口、content.code.copy代码块复制按钮。配色支持跟随系统深浅色切换。插件searchawesome-pages读取.pages文件控制排序。Markdown 扩展admonition提示块、attr_list、md_in_html、tables、toc带 permalink、pymdownx.details可折叠块、pymdownx.highlight、inlinehilite、superfences、tabbed、snippets。hooks注册了 .help/scripts/docs/op_autolinks.py——运算符自动链接钩子详见第六节。它在index.json尚未生成时静默空转因此 Vercel 构建在导出器运行前也不会失败。3.2vercel.json为什么需要 venv 构建.help/vercel.json 是云端构建的核心规划中特别解释了背景Vercel 的 Python 环境受 PEP 668 约束externally-managed不能直接pip install因此必须用uv或标准venv隔离{ installCommand: python3 -m venv .venv .venv/bin/pip install -r requirements-docs.txt, buildCommand: .venv/bin/mkdocs build, outputDirectory: site, framework: null }配套注意点Vercel 项目名为tixl-help的Root Directory 设置为.helpvercel.json里所有路径都相对该目录。framework: null不走框架预设完全由自定义命令驱动。.gitignore排除.help/site/与.help/.venv/构建产物与虚拟环境都不入库。部署行为每次 push 到main即触发构建站点即当前main的文档快照。依赖清单见 .help/requirements-docs.txtmkdocs-material9.5 mkdocs-awesome-pages-plugin2.9 pymdown-extensions10.0刻意不引入mike版本化插件因为其基于gh-pages分支的机制与 Vercel 的部署模型不兼容见 3.4。3.3 本地预览构建环境与本地开发共用同一份依赖与配置pip install -r .help/requirements-docs.txt mkdocs serve -f .help/mkdocs.yml预览地址为http://127.0.0.1:8000/docs/下内容变更会热重载。3.4 版本化明确延后留有两条后路规划明确Versioning — deferredmike把各版本文档发布到gh-pages分支而 Vercel 并不理解这种机制。当版本化真正变得重要时有两条候选路径把文档迁到 GitHub Pages原生使用mike手写按版本分子目录的构建脚本提交到 Vercel 可服务的docs-publish分支。在此之前help.tixl.app直接服务当前main需要永久链接的外部引用可以通过 Edit on GitHub 固定到某个 git commit。另有一个成本极低的可选后续方案——在 Figma 托管的tixl.app项目上加一条 rewrite把文档挂到tixl.app/help/...路径{ rewrites: [{ source: /help/:path*, destination: https://help.tixl.app/:path* }] }若执行该方案再把mkdocs.yml的site_url改回https://tixl.app/help/即可。四、防漂移机制横幅脚本与 wiki 侧边栏切分文档迁移最怕两件事wiki 旧页继续被编辑导致内容分叉、读者从旧链接进来找不到新家。方案用三层机制解决4.1 迁移横幅TIXL_MOVED_BANNER36 个已迁移页面全部面向用户的help.*页外加dev.WritingCodeOps、Installation.md、(wip)-Your-first-C#-operator.md在 wiki 原页顶部插入如下横幅marker 是 HTML 注释便于脚本定位!-- TIXL_MOVED_BANNER -- ⚠ **This page has moved.** It is now maintained in the main repo at .help/path.md. Edits made on the wiki will be lost — please edit the source in the repo instead.4.2 横幅更新脚本以规划文档的映射表为唯一事实来源站点上线后横幅需要从指向 GitHub 源码路径升级为指向渲染后的页面 URL。实现位于 .help/scripts/wiki/update_banners.py其设计有两点值得借鉴映射表即源码脚本直接解析规划文档 Plan_UpdateHelp.md 第五节的那张 Markdown 表格| Legacy wiki page | .help/ source | Rendered URL |解析出{wiki 文件名: 渲染路径}字典因此规划文档保持唯一事实来源更新表格后重跑脚本即可幂等idempotent用--dry-run先预览重复运行安全脚本会区分updated / already-current / no-banner / missing四种状态并汇总输出。关键用法python .help/scripts/wiki/update_banners.py [--wiki-dir ../t3.wiki] [--dry-run]脚本默认期望在仓库根目录的同级位置有一个t3.wiki检出横幅块由!-- TIXL_MOVED_BANNER --加紧跟的一整段以开头的 blockquote 组成用正则^!-- TIXL_MOVED_BANNER --\n((?:.*\n))匹配替换块外内容原样保留。4.3 wiki 侧边栏切分与不锁库策略wiki 的_Sidebar.md被拆成两组用户文档组所有链接指向help.tixl.app和开发者文档组wiki 相对路径的dev.*链接。规划明确两点原则不做发布时同步文档站点完全取代 wiki 副本横幅把旧链接的访客引导到新地址不存在第二个需要保持一致的事实来源不锁定 wiki开发者页面仍需可编辑不做权限限制靠横幅 侧边栏自然引导编辑者去正确的位置。同时按迁移判据清理了过时页面dev.WikiConventions.md、dev.ContributingToTheWiki.md、dev.DocumentationPush.md因被.help/STYLE.md与本文档取代而删除。4.4 留在 wiki 的开发者页面清单以下页面不迁移、不加横幅由 wiki 侧边栏Developer docs分组持续维护dev.UsingDev、dev.StandAloneBuilds、dev.TixlVsTooll3、dev.DevelopingOperators、dev.IntegrationTests、dev.UsingRenderDoc、dev.WorkingWithGit、dev.DebuggingPlayer、dev.ContextVariables、dev.UpdatingHomeTemplate、dev.Contributing、dev.ManualTestingPlan、dev.CodingConventions、dev.OperatorConventions、dev.ChangingFilePathFormat、dev.ProposedBreakingChangesForMain、dev.VisualStudioCodeSetup、dev.TransformGizmos、dev.AudioRoadmap、dev.IdeasForOperators、dev.TixlReleaseIssues。另有不迁移也不保留的类别meetup.*.md活动笔记移往论坛/Discord、update.*.md与ReleaseNotes.*.md发版说明归CHANGELOG.md或 Releases 页、UserTests.DeadMau5.md与MainDevNotes.md内部笔记归档或删除、wiki 的lib/与operators/目录由自动生成管线接管见下节。五、Operator 参考从编辑器符号图自动生成这是整个方案中技术含量最高的一环运算符文档不再手写而是从编辑器内的符号图直接生成生成器是 Editor/Gui/UiHelpers/Wiki/ExportWikiDocumentation.cs。5.1 生成器工作流程ExportWikiDocumentation.ExportWiki()遍历EditorSymbolPackage.AllSymbolUis编辑器内全部符号 UI按以下规则筛选并导出只处理Namespace.StartsWith(Lib.)的符号跳过以_开头的内部符号symbol.Name.StartsWith(_)与含._的内部命名空间每个符号写一个 Markdown 文件到.help/docs/operators/内容包含标题# 符号名、指向同目录README.md的命名空间回链*in [Lib.field.adjust](https://link.gitcode.com/i/5a5bfc4d111b4f103b214e899379e752)*、来自SymbolUi.Description的描述、Input Parameters 表格名称、类型、Relevancy 标注、UI 层描述与Outputs 表格名称、类型。若没有描述占位文案为*No description yet. Edit this operators description in the TiXL editor to populate this page.*——刻意把内容生产的入口指向编辑器本身。描述为空时页面会提示在 TiXL 编辑器中编辑该运算符的描述来生成此页即内容的地基是SymbolUi.Description与输入/输出元数据它们随代码存放在一起在编辑器内编辑。5.2 目标 URL 形态与嵌套目录布局URL 规则规划 4c 节 源码中的NamespaceToRelDir/NamespaceToUrlPath实现命名空间段全部小写Lib.field.adjust→lib/field/adjust运算符名保留 PascalCasePushPullSDF全程无连字符生成器保证标识符安全。生成的目录与 URL 一一对应.help/docs/operators/ lib/ field/ adjust/ PushPullSDF.md image/ adjust/ AdjustColors.md对应 URLhelp.tixl.app/ops/lib/field/adjust/PushPullSDF/生成器源码中GetOperatorUrl当前输出/operators/lib/...形态。规划中同时说明了 mike 版本化落地后的形态help.tixl.app/v4.2/ops/...将成为外部链接可依赖的不可变 URL。v1 阶段无版本前缀。实现细节NamespaceToRelDir把命名空间按.拆分、全部小写、替换为目录分隔符逐级mkdir -p后在叶级写入{SymbolName}.md。5.3 命名空间索引页与 index.json除每运算符一页外生成器还做两件事每层命名空间生成README.md索引列出子命名空间链到各自README.md与当前层的运算符带短描述链接到同目录页面取代原先单一扁平的lib.mdTOC。例如 .help/docs/operators/lib/README.md。页脚标注*Auto-generated from the operator library.*。生成.help/docs/operators/index.json旁车文件WriteLinkerIndexJson供自动链接钩子消费结构如下仓库中 .help/docs/operators/index.json 已实际生成规模约 5000 行{ by_fullpath: { Lib.field.adjust.PushPullSDF: { url: /operators/lib/field/adjust/PushPullSDF/, summary: Makes the incoming SDF volumes thicker or thinner by pushing or pulling the surface by adding a constant value to the distance. } }, by_shortname: { PushPullSDF: [Lib.field.adjust.PushPullSDF], Value: [Lib.numbers.float.basic.Value, Lib.numbers.int.basic.Value] } }url是站点绝对路径但不带版本前缀——若将来启用 mike由 mike 在构建时注入版本前缀钩子无需感知。by_shortname用数组保存全部匹配便于链接器在短名撞名时报告歧义。5.4 生成器的调用方式与所有权导出器运行在 TiXL 编辑器内部它需要完整的符号/UI 图当前触发方式是菜单操作作者点击Documentation → Export as WIKI文件重新生成后提交。规划中的升级路径是发布前在 CI 中无头模式启动 TiXL 重新生成以消除忘了重新导出的风险但依赖无头启动改造本轮不实施。.help/STYLE.md中会注明运算符文档是生成物、禁止手编。六、自动链接钩子让[OperatorName]变成可点击链接这是配合生成器运转的 MkDocs 构建钩子实现在 .help/scripts/docs/op_autolinks.py在mkdocs.yml的hooks:中注册。它只在on_page_markdown阶段把方括号包住的运算符名改写为链接让作者写作时零成本引用运算符。6.1 解析规则钩子在构建开始时一次性加载docs/operators/index.json然后对每页 Markdown 应用正则\[([A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z0-9])*)\](?![\(\[:])规则如下正文写法处理结果[Lib.image.color.AdjustColors]完整路径直接链接到该运算符[lib.image.color.AdjustColors]小写前缀容错归一化为 PascalCase 后解析[AdjustColors]短名且by_shortname唯一命中链接到该运算符[Value]短名命中多个保持原文 构建警告提示用命名空间限定其他无命中可能只是散文引用保持原文钩子明确不碰以下内容围栏代码块、缩进代码块、内联代码段用占位符 stash/restore 保护、已有 Markdown 链接Foo靠尾部(负向断言排除、引用式链接定义[Foo]: ...。它还跳过operators/目录下自动生成的页面本身避免对回链二次包裹。生成的链接只展示最后一段名称不把Lib.field.adjust.PushPullSDF整串塞进正文并利用 Material 的 tooltip 能力title属性在悬停时显示运算符摘要。6.2 写作约定STYLE.md 规则配套的写作规范固化在 .help/docs/STYLE.md用方括号引用运算符[AdjustColors]而不是裸写AdjustColors或the AdjustColors op优先用短名短名撞名时构建日志会警告并给出候选此时才用完整命名空间限定非运算符概念的value等词不要加括号不要手编.help/operators/下的文件——它们由代码重新生成改描述要改编辑器里的SymbolUi.Description。这套约定让作者控制力与零摩擦链接兼得只有加了括号的引用才被改写。七、页面迁移清单完整映射表规划第五节给出了所有已迁移 wiki 页面到新位置的映射表update_banners.py的解析依据现完整继承如下。其中 URL 列为站点上线后的渲染路径/section/page/Legacy wiki page.help/sourceRendered URL (once live)help.AddingFontsadvanced/AddingFonts.md/advanced/AddingFonts/help.ArtnetAndDMXusing/ArtnetAndDMX.md/using/ArtnetAndDMX/help.Backupsusing/Backups.md/using/Backups/help.Conceptsgetting-started/Concepts.md/getting-started/Concepts/help.ConvertSDFsadvanced/ConvertSDFs.md/advanced/ConvertSDFs/help.CreatingNewOpsadvanced/CreatingNewOps.md/advanced/CreatingNewOps/help.ExportExecutablesusing/ExportExecutables.md/using/ExportExecutables/help.ExportVideosusing/ExportVideos.md/using/ExportVideos/help.FAQusing/FAQ.md/using/FAQ/help.FaqBuildingContentusing/FaqBuildingContent.md/using/FaqBuildingContent/help.FaqDevOpsadvanced/FaqDevOps.md/advanced/FaqDevOps/help.HowTixlWorksgetting-started/HowTixlWorks.md/getting-started/HowTixlWorks/help.Installationinstall/Installation.md/install/Installation/help.InstallationT3(not migrated — stays on wiki)—help.InstallDevinstall/InstallDev.md/install/InstallDev/help.InstallLinuxinstall/InstallLinux.md/install/InstallLinux/help.InstallMacOSinstall/InstallMacOS.md/install/InstallMacOS/help.Introductiongetting-started/Introduction.md/getting-started/Introduction/help.KeyboardShortcutsusing/KeyboardShortcuts.md/using/KeyboardShortcuts/help.LivePerformancesusing/LivePerformances.md/using/LivePerformances/help.OSCusing/OSC.md/using/OSC/help.OptimizingRenderingPerformanceusing/OptimizingRenderingPerformance.md/using/OptimizingRenderingPerformance/help.PresetsAndSnapshotsusing/PresetsAndSnapshots.md/using/PresetsAndSnapshots/help.RealtimeRenderingusing/RealtimeRendering.md/using/RealtimeRendering/help.RemoveStaticBackgroundusing/RemoveStaticBackground.md/using/RemoveStaticBackground/help.ReportBugsgetting-started/ReportBugs.md/getting-started/ReportBugs/help.ShaderDevelopmentExampleadvanced/ShaderDevelopmentExample.md/advanced/ShaderDevelopmentExample/help.SharingExampleProjectsusing/SharingExampleProjects.md/using/SharingExampleProjects/help.SkillQuestgetting-started/SkillQuest.md/getting-started/SkillQuest/help.SvgLineFontsadvanced/SvgLineFonts.md/advanced/SvgLineFonts/help.TixlChangesgetting-started/MigratingFromTooll3.md/getting-started/MigratingFromTooll3/help.ui.TimeLineusing/Timeline.md/using/Timeline/help.UsingCustomShadersadvanced/UsingCustomShaders.md/advanced/UsingCustomShaders/help.VideoTutorialsgetting-started/VideoTutorials.md/getting-started/VideoTutorials/dev.WritingCodeOpsadvanced/WritingCodeOps.md/advanced/WritingCodeOps/Installationinstall/Installation.md/install/Installation/几点迁移决策值得记录help.TixlChanges在迁移时改名为MigratingFromTooll3.md——Tooll3 已是历史版本该页定位是迁移辅助而非 v3 文档help.InstallationT3故意不迁移Tooll3 的安装说明属于历史参考留在 wiki 并移除横幅保持独立(wip)-Your-first-C#-operator.md并入advanced/WritingCodeOps.md2026-04-18并新增了TiXL 即 SDK的定位表述与第二条组合现有运算符为新类型的演练路径wiki 原页删除general/、setup/、ui/三分法废弃全部按 4.1 的 IA 重排横幅经映射脚本统一重写。八、图片资产策略规划将图片处理从独立阶段并入编辑审查大部分本地图片已集中到.help/docs/images/树如images/MosaicEffect/、images/MigrateFromT3/、images/timeline/等子目录剩余的缺图警告随编辑逐页就地修复不再批量处理。留有几项机会性收尾任务外部图片 URL 本地化页面中残留的github.com/user-attachments/...、user-images.githubusercontent.com/...等外链当前仍可渲染风险是 GitHub 日后轮换图片地址编辑到该页时顺手本地化即可不为此事单独开 PR压缩图片树稳定后对.help/docs/images/下的 PNG 跑oxipng/pngquant、GIF 跑gifsicle -O3一次性清理路径约定现有页面用站点绝对路径/images/...在站点以域名根服务时有效若将来重写到子路径如tixl.app/help/*需全局扫一遍改成相对../images/...属脚本级小事新增图片的目标规格宽 ≤1600 px截图 ≤500 KB动画 ≤2 MB。九、写作规范STYLE.md 要点.help/docs/STYLE.md 是迁移后所有页面的写作准则核心条目语气与篇幅面向学习者的平实英文、短句、第二人称一页回答一个问题单页目标 150–400 行低于 50 行通常说明应并入父页无营销腔。结构H1 与文件名一致首段一到两句说明页面覆盖内容与适用时机H2 为叙事主体H3 最多三层列表只用于有序步骤或并列选项可选 See also 结尾。链接.help/内用带.md的相对路径外链给完整 URL 且需要上下文引入同页避免重复链接同一术语。代码与 UI 引用围栏代码块必须带语言标签csharp/hlsl/bashUI 元素首次出现加粗类名文件名用行内代码快捷键写作CtrlShiftS。与代码同步用户可见的 UI 或行为变更要在同一 PR 更新对应文档页功能移除则删除对应章节git 历史就是废弃日志发现页面描述漂移就开 issue而不是静默留错。捕获口传知识把 Discord 问答、meet-up 演示、一对一帮助中的高价值内容沉淀为 FAQ 条目或页面趁新鲜写十分钟优于一周后补一小时。十、编辑审查的典型发现运营参考规划第六节记录了迁移审查中逐页发现的问题类型可作为后续内容维护的检查清单范例版本过时InstallDev.md中 Visual Studio 一节提到 .NET 4.7.1当前目标是 .NET 9SDK 版本应链接到仓库的global.json而非硬编码转录痕迹Introduction.md源自视频逐字稿需改写为对照真实 UI 的导览FaqBuildingContent.md的问答体与❔作者口吻需统一断链与缺图HowTixlWorks.md指向不存在的 Render Context 页面TimeLine.md引用的images/timeline/*图片当时尚未入库多处外部图片 URL 待本地化内容归属AddingFonts.md重复页已在迁移时去重LivePerformances.md过长建议拆分其 Future Features 一节带有路线图/营销色彩应移到社区站点命名与拼写TimeLine.md建议改名为Timeline.mdUI 中的标准拼写InstallMacOS.md中 wintricks 应为 winetricks算子引用校验正文提及的[RandomCamera]、[Layer2d]等运算符名需确认仍然存在。十一、Agent 协作约定与执行顺序方案第七节要求把一条约定写入CLAUDE.md的 Project Conventions用户可见的变更要更新文档。当你交付用户能感知到的 UI 或行为变更时更新.help/下对应页面若没有合适页面新增一个或在计划文档中标注。文档遵循.help/STYLE.md。第八节给出执行顺序其中已完成项包括36 个 wiki 页横幅、全部用户页复制、IA 重排、MkDocs awesome-pages 就位、三份构建配置文件入库、Vercel 部署上线、横幅 URL 更新35 页、wiki 侧边栏拆分、导出器重定向到.help/docs/operators/、自动链接钩子启用、(wip)-Your-first-C#-operator.md合并、过时 wiki 页删除。剩余优先工作是按 STYLE.md 对已迁移页面做编辑审查每清掉一个警告就离strict: true的门禁更近一步更长远的待办是版本化mike 或自建子目录、tixl.app/help/*rewrite 以及批量图片压缩。十二、从本方案可复用的工程范式这套方案对任何文档长期漂移的开源项目都有直接参考价值按读者切分文档所有权用户文档进仓库随代码发版、开发者文档留 wiki用 IA 目录 .pages文件 section README 的 Still to write 清单管理信息架构与内容缺口而不是靠空占位页strict: true 云端 CI 构建让文档质量成为发布门禁从代码元数据生成 API/算子参考SymbolUi.Description→ Markdown →index.json内容随代码走、禁止手编构建钩子 约定式语法[OperatorName]实现零摩擦自动链接短名歧义由构建日志兜底迁移脚本以规划文档的映射表为唯一事实来源且幂等横幅可反复重写。上述所有环节在 TiXL 仓库中均已落地为可运行的配置与脚本.help/mkdocs.yml、.help/vercel.json、.help/requirements-docs.txt、.help/scripts/docs/op_autolinks.py、.help/scripts/wiki/update_banners.py、Editor/Gui/UiHelpers/Wiki/ExportWikiDocumentation.cs以及已生成的 .help/docs/operators/index.json 与 .help/docs/operators/index.md。如需为 TiXL 贡献文档请从阅读 .help/README.md 与 .help/docs/STYLE.md 开始本地用pip install -r .help/requirements-docs.txt mkdocs serve -f .help/mkdocs.yml即可预览全站。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TiXL 文档工程化：从 Wiki 迁移到 `.help/`，基于 MkDocs + Vercel 的发布流水线与 Operator 参考自动生成
TiXL 文档工程化从 Wiki 迁移到.help/基于 MkDocs Vercel 的发布流水线与 Operator 参考自动生成【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3本文是 TiXL实时动态图形创作工具文档系统重构的完整技术方案解读。核心目标是把面向用户的文档从 GitHub wiki 迁移到仓库内的.help/目录作为唯一事实来源并通过 MkDocs Material Vercel 构建部署为独立文档站点同时把Lib.*运算符库的 662 页参考文档改为由编辑器内的SymbolUi元数据自动生成配合 MkDocs 构建钩子实现[OperatorName]语法的自动链接。读完本文你将掌握这套内容进仓库、构建在云端、参考自动生成、链接自动解析的文档流水线的完整设计分层判据、目录信息架构、mkdocs.yml/vercel.json关键配置、横幅迁移脚本、导出器与自动链接钩子的源码级实现以及后续运营图片、版本化、编辑审查的注意事项。方案对应的规划文档为仓库中的 .agentic/Plans/archive/Plan_UpdateHelp.md文中所有配置、脚本与生成器均已落地在仓库内可直接对照源码验证。一、为什么要把文档从 Wiki 迁进仓库一条清晰的分界线TiXL 的文档原先全部托管在 GitHub wiki 上混合了面向使用者的帮助页与面向开发者的贡献页。本次迁移的核心不是搬家而是按读者类型彻底切分内容的所有权.help/目录 —— 面向用户。安装、UI 使用、How-to、FAQ、自定义 Shader / 自定义 Operator 编写、现场演出、进阶功能。它是唯一事实来源single source of truth随代码一起发布构建后部署到文档站点凡是从 wiki 迁移过来的页面wiki 原页顶部都会挂一条跳转横幅指向新地址。GitHub wiki —— 面向开发者。从源码构建 TiXL、编码规范、CI、集成测试、RenderDoc、git 工作流、发版流程、临时设计讨论。这些页面留在 wiki 上保持可编辑不迁移、不加横幅。规划的原文给了一条可操作的判据Plan_UpdateHelp.md如果做动态图形或现场视觉的用户会想读它就放进.help/如果只有打开t3.sln的人会想读它就留在 wiki。这条分界线也同步固化在 .help/README.md 与 .help/docs/STYLE.md 中前者描述目录职责后者开篇即声明 user-facing here, contributor-facing there。这样划分的直接收益是——用户文档可以随代码一起走 PR 评审、随版本发布而不是游离在独立的 wiki 仓库里等着被人遗忘。二、信息架构IA面向读者的五段式导航迁移过程中原来的general//setup//ui/三段式结构被重构为按读者旅程组织的五段式外加一个自动生成的运算符参考区.help/ ├── README.md # 贡献者导览不发布 ├── mkdocs.yml # 站点配置 ├── requirements-docs.txt # Python 依赖 ├── vercel.json # Vercel 安装/构建/输出配置 ├── docs/ # mkdocs docs_dir —— 全部 Markdown │ ├── index.md STYLE.md .pages │ ├── getting-started/ install/ using/ advanced/ contributing/ operators/ ├── site/ # 构建输出gitignore ├── .venv/ # 构建虚拟环境Vercel 本地gitignore └── .src/ # 未来页面的原始素材不发布getting-started/TiXL 是什么、概念、视频教程、SkillQuest、从 Tooll3 迁移、报 Bug、社区install/Windows / Linux / macOS 安装、开发环境搭建using/日常参考 —— UI、时间线、导出、预设快照、现场演出、OSC/ArtNet、性能优化等advanced/自定义 Shader、C# Operator、字体contributing/文档与开发入口operators/由符号图自动生成的运算符参考见第五节。每个 section 目录都有自己的README.md列出已有页面和**Still to write待写清单**。规划文档明确要求主题缺失时不要创建空占位页而是在 README 的 Still to write 里加一行等有具体内容再补页。这种做法避免了空页面噪音也让贡献者一眼看到缺口。导航顺序由 .help/docs/.pages 驱动根级与每个 section 级都有.pages文件被awesome-pages插件读取# .help/docs/.pages —— 根级导航顺序 nav: - index.md - getting-started - install - using - advanced - contributing - operators在仓库的 .help/docs 目录中可以看到这套结构已经完整落地且using/下比规划时又新增了Audio.md、CharacterAnimation.md、ImportingAssets.md、MidiFileImport.md、ProceduralGeometry.md、Recording.md、SwiftCamSetup.md、Timeline.md等页面说明该框架具备良好的持续生长能力。三、MkDocs Vercel站点配置与云端构建3.1mkdocs.yml关键配置解读站点配置见 .help/mkdocs.yml逐项拆解site_name: TiXL Documentation site_url: https://help.tixl.app/ docs_dir: docs # 源码目录相对于配置文件 site_dir: site # 构建输出目录gitignore use_directory_urls: true strict: true # 死链/缺图即构建失败要点docs_dir: docs、site_dir: site均相对配置文件解析因此整个构建产物都收在.help/内仓库根目录保持干净。strict: true规划执行初期为false2026-04-18 已翻转为true——从此死链、缺失图片会直接让 Vercel 构建失败而不是作为警告悄悄放行。这是内容质量作为发布门禁的关键一步。主题 Material启用navigation.tabs顶级 section 显示为标签页、navigation.sections侧边栏分组、navigation.footer自动生成上一页/下一页、navigation.instant客户端导航、search.suggest/search.highlight、content.action.edit每页在 GitHub 上编辑入口、content.code.copy代码块复制按钮。配色支持跟随系统深浅色切换。插件searchawesome-pages读取.pages文件控制排序。Markdown 扩展admonition提示块、attr_list、md_in_html、tables、toc带 permalink、pymdownx.details可折叠块、pymdownx.highlight、inlinehilite、superfences、tabbed、snippets。hooks注册了 .help/scripts/docs/op_autolinks.py——运算符自动链接钩子详见第六节。它在index.json尚未生成时静默空转因此 Vercel 构建在导出器运行前也不会失败。3.2vercel.json为什么需要 venv 构建.help/vercel.json 是云端构建的核心规划中特别解释了背景Vercel 的 Python 环境受 PEP 668 约束externally-managed不能直接pip install因此必须用uv或标准venv隔离{ installCommand: python3 -m venv .venv .venv/bin/pip install -r requirements-docs.txt, buildCommand: .venv/bin/mkdocs build, outputDirectory: site, framework: null }配套注意点Vercel 项目名为tixl-help的Root Directory 设置为.helpvercel.json里所有路径都相对该目录。framework: null不走框架预设完全由自定义命令驱动。.gitignore排除.help/site/与.help/.venv/构建产物与虚拟环境都不入库。部署行为每次 push 到main即触发构建站点即当前main的文档快照。依赖清单见 .help/requirements-docs.txtmkdocs-material9.5 mkdocs-awesome-pages-plugin2.9 pymdown-extensions10.0刻意不引入mike版本化插件因为其基于gh-pages分支的机制与 Vercel 的部署模型不兼容见 3.4。3.3 本地预览构建环境与本地开发共用同一份依赖与配置pip install -r .help/requirements-docs.txt mkdocs serve -f .help/mkdocs.yml预览地址为http://127.0.0.1:8000/docs/下内容变更会热重载。3.4 版本化明确延后留有两条后路规划明确Versioning — deferredmike把各版本文档发布到gh-pages分支而 Vercel 并不理解这种机制。当版本化真正变得重要时有两条候选路径把文档迁到 GitHub Pages原生使用mike手写按版本分子目录的构建脚本提交到 Vercel 可服务的docs-publish分支。在此之前help.tixl.app直接服务当前main需要永久链接的外部引用可以通过 Edit on GitHub 固定到某个 git commit。另有一个成本极低的可选后续方案——在 Figma 托管的tixl.app项目上加一条 rewrite把文档挂到tixl.app/help/...路径{ rewrites: [{ source: /help/:path*, destination: https://help.tixl.app/:path* }] }若执行该方案再把mkdocs.yml的site_url改回https://tixl.app/help/即可。四、防漂移机制横幅脚本与 wiki 侧边栏切分文档迁移最怕两件事wiki 旧页继续被编辑导致内容分叉、读者从旧链接进来找不到新家。方案用三层机制解决4.1 迁移横幅TIXL_MOVED_BANNER36 个已迁移页面全部面向用户的help.*页外加dev.WritingCodeOps、Installation.md、(wip)-Your-first-C#-operator.md在 wiki 原页顶部插入如下横幅marker 是 HTML 注释便于脚本定位!-- TIXL_MOVED_BANNER -- ⚠ **This page has moved.** It is now maintained in the main repo at .help/path.md. Edits made on the wiki will be lost — please edit the source in the repo instead.4.2 横幅更新脚本以规划文档的映射表为唯一事实来源站点上线后横幅需要从指向 GitHub 源码路径升级为指向渲染后的页面 URL。实现位于 .help/scripts/wiki/update_banners.py其设计有两点值得借鉴映射表即源码脚本直接解析规划文档 Plan_UpdateHelp.md 第五节的那张 Markdown 表格| Legacy wiki page | .help/ source | Rendered URL |解析出{wiki 文件名: 渲染路径}字典因此规划文档保持唯一事实来源更新表格后重跑脚本即可幂等idempotent用--dry-run先预览重复运行安全脚本会区分updated / already-current / no-banner / missing四种状态并汇总输出。关键用法python .help/scripts/wiki/update_banners.py [--wiki-dir ../t3.wiki] [--dry-run]脚本默认期望在仓库根目录的同级位置有一个t3.wiki检出横幅块由!-- TIXL_MOVED_BANNER --加紧跟的一整段以开头的 blockquote 组成用正则^!-- TIXL_MOVED_BANNER --\n((?:.*\n))匹配替换块外内容原样保留。4.3 wiki 侧边栏切分与不锁库策略wiki 的_Sidebar.md被拆成两组用户文档组所有链接指向help.tixl.app和开发者文档组wiki 相对路径的dev.*链接。规划明确两点原则不做发布时同步文档站点完全取代 wiki 副本横幅把旧链接的访客引导到新地址不存在第二个需要保持一致的事实来源不锁定 wiki开发者页面仍需可编辑不做权限限制靠横幅 侧边栏自然引导编辑者去正确的位置。同时按迁移判据清理了过时页面dev.WikiConventions.md、dev.ContributingToTheWiki.md、dev.DocumentationPush.md因被.help/STYLE.md与本文档取代而删除。4.4 留在 wiki 的开发者页面清单以下页面不迁移、不加横幅由 wiki 侧边栏Developer docs分组持续维护dev.UsingDev、dev.StandAloneBuilds、dev.TixlVsTooll3、dev.DevelopingOperators、dev.IntegrationTests、dev.UsingRenderDoc、dev.WorkingWithGit、dev.DebuggingPlayer、dev.ContextVariables、dev.UpdatingHomeTemplate、dev.Contributing、dev.ManualTestingPlan、dev.CodingConventions、dev.OperatorConventions、dev.ChangingFilePathFormat、dev.ProposedBreakingChangesForMain、dev.VisualStudioCodeSetup、dev.TransformGizmos、dev.AudioRoadmap、dev.IdeasForOperators、dev.TixlReleaseIssues。另有不迁移也不保留的类别meetup.*.md活动笔记移往论坛/Discord、update.*.md与ReleaseNotes.*.md发版说明归CHANGELOG.md或 Releases 页、UserTests.DeadMau5.md与MainDevNotes.md内部笔记归档或删除、wiki 的lib/与operators/目录由自动生成管线接管见下节。五、Operator 参考从编辑器符号图自动生成这是整个方案中技术含量最高的一环运算符文档不再手写而是从编辑器内的符号图直接生成生成器是 Editor/Gui/UiHelpers/Wiki/ExportWikiDocumentation.cs。5.1 生成器工作流程ExportWikiDocumentation.ExportWiki()遍历EditorSymbolPackage.AllSymbolUis编辑器内全部符号 UI按以下规则筛选并导出只处理Namespace.StartsWith(Lib.)的符号跳过以_开头的内部符号symbol.Name.StartsWith(_)与含._的内部命名空间每个符号写一个 Markdown 文件到.help/docs/operators/内容包含标题# 符号名、指向同目录README.md的命名空间回链*in [Lib.field.adjust](https://link.gitcode.com/i/5a5bfc4d111b4f103b214e899379e752)*、来自SymbolUi.Description的描述、Input Parameters 表格名称、类型、Relevancy 标注、UI 层描述与Outputs 表格名称、类型。若没有描述占位文案为*No description yet. Edit this operators description in the TiXL editor to populate this page.*——刻意把内容生产的入口指向编辑器本身。描述为空时页面会提示在 TiXL 编辑器中编辑该运算符的描述来生成此页即内容的地基是SymbolUi.Description与输入/输出元数据它们随代码存放在一起在编辑器内编辑。5.2 目标 URL 形态与嵌套目录布局URL 规则规划 4c 节 源码中的NamespaceToRelDir/NamespaceToUrlPath实现命名空间段全部小写Lib.field.adjust→lib/field/adjust运算符名保留 PascalCasePushPullSDF全程无连字符生成器保证标识符安全。生成的目录与 URL 一一对应.help/docs/operators/ lib/ field/ adjust/ PushPullSDF.md image/ adjust/ AdjustColors.md对应 URLhelp.tixl.app/ops/lib/field/adjust/PushPullSDF/生成器源码中GetOperatorUrl当前输出/operators/lib/...形态。规划中同时说明了 mike 版本化落地后的形态help.tixl.app/v4.2/ops/...将成为外部链接可依赖的不可变 URL。v1 阶段无版本前缀。实现细节NamespaceToRelDir把命名空间按.拆分、全部小写、替换为目录分隔符逐级mkdir -p后在叶级写入{SymbolName}.md。5.3 命名空间索引页与 index.json除每运算符一页外生成器还做两件事每层命名空间生成README.md索引列出子命名空间链到各自README.md与当前层的运算符带短描述链接到同目录页面取代原先单一扁平的lib.mdTOC。例如 .help/docs/operators/lib/README.md。页脚标注*Auto-generated from the operator library.*。生成.help/docs/operators/index.json旁车文件WriteLinkerIndexJson供自动链接钩子消费结构如下仓库中 .help/docs/operators/index.json 已实际生成规模约 5000 行{ by_fullpath: { Lib.field.adjust.PushPullSDF: { url: /operators/lib/field/adjust/PushPullSDF/, summary: Makes the incoming SDF volumes thicker or thinner by pushing or pulling the surface by adding a constant value to the distance. } }, by_shortname: { PushPullSDF: [Lib.field.adjust.PushPullSDF], Value: [Lib.numbers.float.basic.Value, Lib.numbers.int.basic.Value] } }url是站点绝对路径但不带版本前缀——若将来启用 mike由 mike 在构建时注入版本前缀钩子无需感知。by_shortname用数组保存全部匹配便于链接器在短名撞名时报告歧义。5.4 生成器的调用方式与所有权导出器运行在 TiXL 编辑器内部它需要完整的符号/UI 图当前触发方式是菜单操作作者点击Documentation → Export as WIKI文件重新生成后提交。规划中的升级路径是发布前在 CI 中无头模式启动 TiXL 重新生成以消除忘了重新导出的风险但依赖无头启动改造本轮不实施。.help/STYLE.md中会注明运算符文档是生成物、禁止手编。六、自动链接钩子让[OperatorName]变成可点击链接这是配合生成器运转的 MkDocs 构建钩子实现在 .help/scripts/docs/op_autolinks.py在mkdocs.yml的hooks:中注册。它只在on_page_markdown阶段把方括号包住的运算符名改写为链接让作者写作时零成本引用运算符。6.1 解析规则钩子在构建开始时一次性加载docs/operators/index.json然后对每页 Markdown 应用正则\[([A-Za-z][A-Za-z0-9]*(?:\.[A-Za-z0-9])*)\](?![\(\[:])规则如下正文写法处理结果[Lib.image.color.AdjustColors]完整路径直接链接到该运算符[lib.image.color.AdjustColors]小写前缀容错归一化为 PascalCase 后解析[AdjustColors]短名且by_shortname唯一命中链接到该运算符[Value]短名命中多个保持原文 构建警告提示用命名空间限定其他无命中可能只是散文引用保持原文钩子明确不碰以下内容围栏代码块、缩进代码块、内联代码段用占位符 stash/restore 保护、已有 Markdown 链接Foo靠尾部(负向断言排除、引用式链接定义[Foo]: ...。它还跳过operators/目录下自动生成的页面本身避免对回链二次包裹。生成的链接只展示最后一段名称不把Lib.field.adjust.PushPullSDF整串塞进正文并利用 Material 的 tooltip 能力title属性在悬停时显示运算符摘要。6.2 写作约定STYLE.md 规则配套的写作规范固化在 .help/docs/STYLE.md用方括号引用运算符[AdjustColors]而不是裸写AdjustColors或the AdjustColors op优先用短名短名撞名时构建日志会警告并给出候选此时才用完整命名空间限定非运算符概念的value等词不要加括号不要手编.help/operators/下的文件——它们由代码重新生成改描述要改编辑器里的SymbolUi.Description。这套约定让作者控制力与零摩擦链接兼得只有加了括号的引用才被改写。七、页面迁移清单完整映射表规划第五节给出了所有已迁移 wiki 页面到新位置的映射表update_banners.py的解析依据现完整继承如下。其中 URL 列为站点上线后的渲染路径/section/page/Legacy wiki page.help/sourceRendered URL (once live)help.AddingFontsadvanced/AddingFonts.md/advanced/AddingFonts/help.ArtnetAndDMXusing/ArtnetAndDMX.md/using/ArtnetAndDMX/help.Backupsusing/Backups.md/using/Backups/help.Conceptsgetting-started/Concepts.md/getting-started/Concepts/help.ConvertSDFsadvanced/ConvertSDFs.md/advanced/ConvertSDFs/help.CreatingNewOpsadvanced/CreatingNewOps.md/advanced/CreatingNewOps/help.ExportExecutablesusing/ExportExecutables.md/using/ExportExecutables/help.ExportVideosusing/ExportVideos.md/using/ExportVideos/help.FAQusing/FAQ.md/using/FAQ/help.FaqBuildingContentusing/FaqBuildingContent.md/using/FaqBuildingContent/help.FaqDevOpsadvanced/FaqDevOps.md/advanced/FaqDevOps/help.HowTixlWorksgetting-started/HowTixlWorks.md/getting-started/HowTixlWorks/help.Installationinstall/Installation.md/install/Installation/help.InstallationT3(not migrated — stays on wiki)—help.InstallDevinstall/InstallDev.md/install/InstallDev/help.InstallLinuxinstall/InstallLinux.md/install/InstallLinux/help.InstallMacOSinstall/InstallMacOS.md/install/InstallMacOS/help.Introductiongetting-started/Introduction.md/getting-started/Introduction/help.KeyboardShortcutsusing/KeyboardShortcuts.md/using/KeyboardShortcuts/help.LivePerformancesusing/LivePerformances.md/using/LivePerformances/help.OSCusing/OSC.md/using/OSC/help.OptimizingRenderingPerformanceusing/OptimizingRenderingPerformance.md/using/OptimizingRenderingPerformance/help.PresetsAndSnapshotsusing/PresetsAndSnapshots.md/using/PresetsAndSnapshots/help.RealtimeRenderingusing/RealtimeRendering.md/using/RealtimeRendering/help.RemoveStaticBackgroundusing/RemoveStaticBackground.md/using/RemoveStaticBackground/help.ReportBugsgetting-started/ReportBugs.md/getting-started/ReportBugs/help.ShaderDevelopmentExampleadvanced/ShaderDevelopmentExample.md/advanced/ShaderDevelopmentExample/help.SharingExampleProjectsusing/SharingExampleProjects.md/using/SharingExampleProjects/help.SkillQuestgetting-started/SkillQuest.md/getting-started/SkillQuest/help.SvgLineFontsadvanced/SvgLineFonts.md/advanced/SvgLineFonts/help.TixlChangesgetting-started/MigratingFromTooll3.md/getting-started/MigratingFromTooll3/help.ui.TimeLineusing/Timeline.md/using/Timeline/help.UsingCustomShadersadvanced/UsingCustomShaders.md/advanced/UsingCustomShaders/help.VideoTutorialsgetting-started/VideoTutorials.md/getting-started/VideoTutorials/dev.WritingCodeOpsadvanced/WritingCodeOps.md/advanced/WritingCodeOps/Installationinstall/Installation.md/install/Installation/几点迁移决策值得记录help.TixlChanges在迁移时改名为MigratingFromTooll3.md——Tooll3 已是历史版本该页定位是迁移辅助而非 v3 文档help.InstallationT3故意不迁移Tooll3 的安装说明属于历史参考留在 wiki 并移除横幅保持独立(wip)-Your-first-C#-operator.md并入advanced/WritingCodeOps.md2026-04-18并新增了TiXL 即 SDK的定位表述与第二条组合现有运算符为新类型的演练路径wiki 原页删除general/、setup/、ui/三分法废弃全部按 4.1 的 IA 重排横幅经映射脚本统一重写。八、图片资产策略规划将图片处理从独立阶段并入编辑审查大部分本地图片已集中到.help/docs/images/树如images/MosaicEffect/、images/MigrateFromT3/、images/timeline/等子目录剩余的缺图警告随编辑逐页就地修复不再批量处理。留有几项机会性收尾任务外部图片 URL 本地化页面中残留的github.com/user-attachments/...、user-images.githubusercontent.com/...等外链当前仍可渲染风险是 GitHub 日后轮换图片地址编辑到该页时顺手本地化即可不为此事单独开 PR压缩图片树稳定后对.help/docs/images/下的 PNG 跑oxipng/pngquant、GIF 跑gifsicle -O3一次性清理路径约定现有页面用站点绝对路径/images/...在站点以域名根服务时有效若将来重写到子路径如tixl.app/help/*需全局扫一遍改成相对../images/...属脚本级小事新增图片的目标规格宽 ≤1600 px截图 ≤500 KB动画 ≤2 MB。九、写作规范STYLE.md 要点.help/docs/STYLE.md 是迁移后所有页面的写作准则核心条目语气与篇幅面向学习者的平实英文、短句、第二人称一页回答一个问题单页目标 150–400 行低于 50 行通常说明应并入父页无营销腔。结构H1 与文件名一致首段一到两句说明页面覆盖内容与适用时机H2 为叙事主体H3 最多三层列表只用于有序步骤或并列选项可选 See also 结尾。链接.help/内用带.md的相对路径外链给完整 URL 且需要上下文引入同页避免重复链接同一术语。代码与 UI 引用围栏代码块必须带语言标签csharp/hlsl/bashUI 元素首次出现加粗类名文件名用行内代码快捷键写作CtrlShiftS。与代码同步用户可见的 UI 或行为变更要在同一 PR 更新对应文档页功能移除则删除对应章节git 历史就是废弃日志发现页面描述漂移就开 issue而不是静默留错。捕获口传知识把 Discord 问答、meet-up 演示、一对一帮助中的高价值内容沉淀为 FAQ 条目或页面趁新鲜写十分钟优于一周后补一小时。十、编辑审查的典型发现运营参考规划第六节记录了迁移审查中逐页发现的问题类型可作为后续内容维护的检查清单范例版本过时InstallDev.md中 Visual Studio 一节提到 .NET 4.7.1当前目标是 .NET 9SDK 版本应链接到仓库的global.json而非硬编码转录痕迹Introduction.md源自视频逐字稿需改写为对照真实 UI 的导览FaqBuildingContent.md的问答体与❔作者口吻需统一断链与缺图HowTixlWorks.md指向不存在的 Render Context 页面TimeLine.md引用的images/timeline/*图片当时尚未入库多处外部图片 URL 待本地化内容归属AddingFonts.md重复页已在迁移时去重LivePerformances.md过长建议拆分其 Future Features 一节带有路线图/营销色彩应移到社区站点命名与拼写TimeLine.md建议改名为Timeline.mdUI 中的标准拼写InstallMacOS.md中 wintricks 应为 winetricks算子引用校验正文提及的[RandomCamera]、[Layer2d]等运算符名需确认仍然存在。十一、Agent 协作约定与执行顺序方案第七节要求把一条约定写入CLAUDE.md的 Project Conventions用户可见的变更要更新文档。当你交付用户能感知到的 UI 或行为变更时更新.help/下对应页面若没有合适页面新增一个或在计划文档中标注。文档遵循.help/STYLE.md。第八节给出执行顺序其中已完成项包括36 个 wiki 页横幅、全部用户页复制、IA 重排、MkDocs awesome-pages 就位、三份构建配置文件入库、Vercel 部署上线、横幅 URL 更新35 页、wiki 侧边栏拆分、导出器重定向到.help/docs/operators/、自动链接钩子启用、(wip)-Your-first-C#-operator.md合并、过时 wiki 页删除。剩余优先工作是按 STYLE.md 对已迁移页面做编辑审查每清掉一个警告就离strict: true的门禁更近一步更长远的待办是版本化mike 或自建子目录、tixl.app/help/*rewrite 以及批量图片压缩。十二、从本方案可复用的工程范式这套方案对任何文档长期漂移的开源项目都有直接参考价值按读者切分文档所有权用户文档进仓库随代码发版、开发者文档留 wiki用 IA 目录 .pages文件 section README 的 Still to write 清单管理信息架构与内容缺口而不是靠空占位页strict: true 云端 CI 构建让文档质量成为发布门禁从代码元数据生成 API/算子参考SymbolUi.Description→ Markdown →index.json内容随代码走、禁止手编构建钩子 约定式语法[OperatorName]实现零摩擦自动链接短名歧义由构建日志兜底迁移脚本以规划文档的映射表为唯一事实来源且幂等横幅可反复重写。上述所有环节在 TiXL 仓库中均已落地为可运行的配置与脚本.help/mkdocs.yml、.help/vercel.json、.help/requirements-docs.txt、.help/scripts/docs/op_autolinks.py、.help/scripts/wiki/update_banners.py、Editor/Gui/UiHelpers/Wiki/ExportWikiDocumentation.cs以及已生成的 .help/docs/operators/index.json 与 .help/docs/operators/index.md。如需为 TiXL 贡献文档请从阅读 .help/README.md 与 .help/docs/STYLE.md 开始本地用pip install -r .help/requirements-docs.txt mkdocs serve -f .help/mkdocs.yml即可预览全站。【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考