Docs Assembler - Treat Documentation Like Code
中文文档 | Chinese Documentation
We think in webs, yet are sentenced to lines.
Human knowledge branches, loops, and layers - a living web of what-ifs, dependencies, and context. Traditional documents force this into linear prose, losing the very structure that makes expertise usable.
Docs Assembler bridges the gap, giving form to the networks in a human mind - that others can follow, learn from, extend, or refine. It is a VS Code extension that lets you build documentation with modular, reusable components - like code classes for your content. Maps encapsulate text and decision trees, variables propagate everywhere. A change in one place updates every guide instantly.
Zero lock-in. It publishes to plain Markdown. Uninstall the extension and your docs still work in any static site generator.
Solve documentation hell...
- Sprawling, duplicated content across guides, manuals, and wikis.
- Bug-prone updates - edit one place, miss it in ten others.
- Brittle, unmanageable docs that can't handle complex, branching scenarios.
...by applying software engineering principles to text:
- Maps (.tsmap files): Self-contained documentation modules that can be nested and composed, just like classes. They encapsulate text, decision trees, or both.
- Variables: Define reusable text snippets. Change one, update everywhere.
- Inheritance & Composition: Build complex guides from simple, reusable blocks. A change in a base component propagates to all guides that use it.
- Compile to Docs: Assemble these components on-the-fly into context-aware Markdown or HTML.
...and maintain a single source of truth.
One minute. Two people. One source. Every branch updated instantly.
Watch two users take completely different paths through the same guide, merge back into shared content, expand hidden detail on demand, and see how one edit updates every branch instantly.
Explore the Live Demo yourself to go deeper.
Designed for Developers, by Developers
The design of Docs Assembler was driven by a fundamental need from teams like HAL Robotics: to have a powerful system that respects developer workflows and sovereignty. This isn't just a platform; it's a philosophy built on core principles that will feel immediately right:
- Familiarity & Control: The entire system is built on the tools you already know and trust. Your documentation lives in Git repos, right alongside your code. Content is written in Markdown files, editable in any editor. Structure is defined in JSON files you can view and edit manually.
- Absolute Ownership: You have physical possession of your documentation. It's your Markdown and JSON in your repo. You are never trapped in a subscription or held ransom by a SaaS platform.
- Zero Lock-In: This is a critical feature. There are no consequences if you stop using Docs Assembler. Since it publishes to standard Markdown, you can uninstall the extension and your documentation is still perfectly usable, editable, and ready for any other static site generator. Your content is always yours.
- Seamless Publishing: It's designed to publish directly to GitHub Pages, a platform developers already understand. Even Liquid scripts embedded in your Markdown work as expected.
- Built to Scale: Like classes break down massive software systems, Docs Assembler's modules are designed to decompose enormous documentation sets into manageable, distributable units that different teams can own.
- Engineering Rigour: It brings true software tooling to docs, with IntelliSense for variables, full validation before publish, and automatic handling of relative URLs that are defined as variables. This ensures any local files referenced by these URL variables are automatically discovered and copied to the publish folder, preventing broken links and ensuring robustness.
- Internationalisation by Design: The guide/fragment model suits analytic languages (English, Chinese) where word forms stay constant. In high-inflection languages (Russian, Arabic), the same sub-guide might need different gender, case, or number depending on where it is called. Display tools intentionally assemble the full path before rendering or translating, so authors write plain Markdown, and grammar adapts at the edge.
Install
- From VS Code:
- Search "Docs Assembler" in the Extensions panel and click Install.
- Manual install (.vsix):
- If you don't have marketplace access, download the latest release or browse all releases.
- Copy the downloaded .vsix to your desktop.
- In the vscode Extensions panel, click the three dots in the top right.
- Select
Install from VSIX...
- Browse to the .vsix file on your desktop.
Need help adopting Docs Assembler?
If the concept feels abstract, we can help. We offer a fixed-price "Docs Rescue" service: we audit your existing documentation, rebuild your most critical guide (onboarding, troubleshooting, or API reference) as a Docs Assembler project, and hand you a fully working Git repo. You own everything. You edit it yourself going forward, but you don't have to build the first version from scratch.
Open-source maintainers: If your project is non-commercial and publicly available, mention it when you reach out - we adjust our rates accordingly.
We can't see you - so tell us
Docs Assembler collects no analytics, usage data, or crash reports.
We cannot see your downloads, your location, or how you use this tool.
The only way we know you're using Docs Assembler is if you tell us:
Live demo
Live Demo GitHub Pages Site: See it in action
- Publish currently targets GitHub Pages, producing Jekyll Markdown.
- After a Publish, run a Git Commit and Push, for GitHub Pages to make changes live.
GitHub Pages Repository: Explore the repo
- The sample maps are located in the
/tsmaps/ folder and published guides in /docs/.
Template Repository: Template repo
- All-in-one repository with docs, FragmentRenderer, and Jekyll setup
- Supports full local workflow: assemble docs → publish → Jekyll build → local preview
- Everything needed to develop, test, and preview documentation changes locally
- Instructions on running repo locally with Jekyll coming soon.
Maps
Switching between Map Editor and Map Json Editor:
Switching between Maps Diff and Maps Json Diff:
Steps
- A map is a section of documentation divided into steps.
- Each step links to a markdown file with the step's documentation text.
- Markdown file can be shared between multiple steps.
- Markdown files are editable with the Visual Studio Code markdown editor.
Maps can reference other maps
- A map referenced within another map, appears as a single step.
- If a referenced map has exits, other maps or steps will need chained onto those exits.
- Validation prevents circular references.
Variables
- Variables define reusable markdown text.
- Variables that define relative links are adjusted to be always be valid for the published document they are used in.
Variables can reference other variables
- A variable's markdown text can reference other variables.
- Validation prevents circular references.
Compile to docs
On publish, the Docs Assembler reads the maps selected for publish - it validates and assembles all referenced maps, markdown files, expands any variables, copies over referenced assets, and compiles the results into markdown or html files to the publish folder in your repo.
Compare published to live
Use the compare view to view changes between published files and the docs folder files.
Move published to live
If the changes are as expected, click-move the published files to the docs folder. If you use GitHub Pages, docs would be the root folder.
Built to handle both complexity and scale
- At its simplest, a map has a single step and markdown file.
- A slightly more complex map would be a single pathway of steps, like a book or manual.
- At its most complicated, a map is a decision tree of steps, many pointing to other maps, which in turn point to other maps etc. The expanded result could be enormous, and impossible to build or maintain without breaking it down into manageable, discrete, reusable, units. Just like we do in code with classes.
Example of published output
Image above
- This shows the c# server/database application, where steps are stored in a database.
- It has all the ancillaries expanded.
- When all ancillaries are collapsed the guide shows enough information for an expert to complete the task.
- If a user expands an ancillary, they insert more steps on a topic.
- Ancillaries can be nested - so users can drill down.
- With all possible ancillaries expanded, all the steps for completing a task, as a novice, are laid out.
- Reusing maps makes it straight forward to build and maintain guides that a user can tailor to their skill set.
Image below
- This shows the editor for the c# server/database application.
- With the referenced maps, including nested ones, used to build the guide shown above.
- Most will be reused in other guides.
Docs Assembler intentionally keeps the authoring layer simple. We keep the editor experience lightweight and familiar while pushing rendering complexity to the display layer.
Docs Assembler's authoring model works especially well with analytic and low-inflection languages (English, Chinese, etc.), where words do not change shape based on gender, case, or tense. For high-inflection languages (Russian, Arabic, Polish, German, Basque, etc.), high-quality localisation is best handled at the display layer through full-path assembly before translation.
Display tool authors should read the Display Tool Contract. This document describes the boundaries and known challenges so display tool authors can build correctly. Guides can reference remote maps across repositories and domains; display tools handle cross-origin fragment loading via the proxy patterns described in the contract.
We actively welcome contributions toward reference display tool implementations - that demonstrate this pattern. Please open an issue before starting to align on the boundary definitions.
Released
- 0.9.40
- Map folders
- Markdown Intellisense, diagnostics and TextMate and semantic grammars for steps and variables
- Publish listed maps
- Moving or copying map folder corrects relative urls
- Map json editor
- Diff map json editor
- Maps explorer
- Map hyper links
- GitHub Pages integration
- Publish for referenced and nested maps
- Publish for ancillaries
- Update GitHub Pages site with a new demo showing referenced and nested map example using ancillaries
- Map and guide stacks - published, modified or never published.
- Move, clone, copy + paste of map folders adjusts relative urls.
- Move, rename of map asset files updates references and map hyperlinks.
- Shortcut keys
- Json step (video step) - json intellisense, diagnostics, textMate and semantic tokens
- Reference guides in remote banks
- Helicopter view
- Repo initialisation, resources update and migration
Next
- Video tutorials
- Help files
Upcoming
- Move or copy a section of a branch
- Make a section of a branch into a new map
- GitLab Pages integration
- Port from database version
- Light theme
Links
team@netoftrees.com
www.netoftrees.com
x.com/docsassembler
documentation:
docs.hal-robotics.com
documentation repo:
github.com/HALRobotics/HAL.Documentation
website:
hal-robotics.com
中文文档
英文文档 | English Documentation
我们本以网状思考，却被判以线性书写。
人类知识会分支、循环、分层--一张由假设与依赖构成的活网。传统文档却强行塞进线性文字，丢掉了让知识真正可用的结构。
Docs Assembler 填补了这个缺口，将人脑中的思维网络具象化--让他人能够沿着你的思路学习、扩展或完善。它是一个 VS Code 扩展，让你用模块化、可复用组件构建文档--可以理解为内容的代码类。映射封装文本与决策树，变量处处传播。一处改动，所有指南即时更新。
零锁定。 发布为纯 Markdown。卸载扩展后，你的文档仍可在任何静态站点生成器中正常工作。
终结文档地狱……
- 内容四处扩散、重复--指南、手册、Wiki 里到处都是。
- 更新极易出错：改一处，漏十处。
- 文档脆弱、不可维护，无法应对复杂分支场景。
……将软件工程原则应用于文本：
- 映射（.tsmap 文件）：自包含的文档模块，可嵌套组合，就像类。封装文本、决策树，或两者兼有。
- 变量：定义可复用文本片段。改一处，全局更新。
- 继承与组合：用简单可复用块搭建复杂指南。基类改动自动传播到所有引用处。
- 编译为文档：实时组装组件，输出上下文感知的 Markdown 或 HTML。
……并维护单一事实来源。
一分钟。两个人。一个来源。所有分支即时更新。
观看两位用户如何通过完全不同的路径浏览同一指南，合并回共享内容，按需展开隐藏细节，并了解一次编辑如何即时更新所有分支。
亲自探索在线演示，深入了解。
为开发者设计，由开发者打造
Docs Assembler 的设计源于 HAL Robotics 等团队的核心需求：一套强大、尊重开发者工作流与主权的系统。这不仅是一个平台，更是一套基于以下原则的哲学，会让你感到“理所当然”：
- 熟悉与掌控： 整个系统基于你已熟悉和信任的工具。文档与代码共存于 Git 仓库。内容用 Markdown 编写，任何编辑器均可编辑。结构用 JSON 定义，可手动查看和修改。
- 绝对所有权： 你实际持有自己的文档。它们是你仓库里的 Markdown 和 JSON。永远不会被订阅绑架，或被 SaaS 平台勒索。
- 零锁定： 这是关键特性。停止使用 Docs Assembler 毫无代价。因为它发布为标准 Markdown，直接卸载扩展即可--文档仍完全可用、可编辑，可直接用于任何其他静态站点生成器。你的内容永远属于你。
- 无缝发布： 设计上直接发布到 GitHub Pages，开发者已熟悉的平台。Markdown 中嵌入的 Liquid 脚本也能正常工作。
- 为规模而生： 正如类将大型软件系统拆分为小块，Docs Assembler 的模块将海量文档集分解为可管理、可分发的小单元，不同团队可分别维护。
- 工程级严谨： 为文档带来真正的开发工具--变量有 IntelliSense，发布前完整校验，自动处理作为变量定义的相对 URL。这些 URL 引用的本地文件会被自动发现并复制到发布文件夹，防止链接失效，确保健壮性。
- 国际化设计： 指南/片段模型适用于分析性语言（英语、中文），词形保持不变。在高屈折语言（俄语、阿拉伯语）中，同一子指南在不同调用位置可能需要不同的性、格或数。显示工具有意先组装完整路径再渲染或翻译，因此作者只需编写纯 Markdown，语法在边缘处自适应。
安装
- 通过 VS Code 安装：
- 在扩展面板中搜索 "Docs Assembler"，然后点击安装。
- 手动安装（.vsix）：
- 如果无法访问应用市场，请下载最新版本或浏览所有版本。
- 将下载的 .vsix 文件复制到桌面。
- 在 VS Code 扩展面板中，点击右上角的三点菜单。
- 选择
从 VSIX 安装...。
- 浏览到桌面上的 .vsix 文件。
我们看不到你--所以请告诉我们
Docs Assembler 不收集任何分析数据、使用数据或崩溃报告。
我们无法看到你的下载量、所在位置或使用方式。
我们唯一知道你正在使用 Docs Assembler 的方式，就是你主动告诉我们：
在线演示
GitHub Pages 演示站点：查看实际效果
- 目前发布目标为 GitHub Pages，生成 Jekyll Markdown。
- 发布后需执行 Git Commit 和 Push，GitHub Pages 才会生效。
GitHub Pages 仓库：探索仓库
- 示例映射位于
/tsmaps/ 文件夹，发布的指南在 /docs/。
模板仓库：模板仓库
- 包含文档、FragmentRenderer 和 Jekyll 配置的一体化仓库。
- 支持完整本地工作流：组装文档 → 发布 → Jekyll 构建 → 本地预览。
- 开发、测试和预览文档变更所需的一切。
- 本地使用 Jekyll 的说明即将发布。
扩展更新后请清除 VS Code 历史记录：
- 打开命令面板：
Cmd+Shift+P
- 输入：
Clear Editor History
映射
- 主要构建块是映射。
- 它是一个带 .tsmap 后缀的 json 文件。
- 功能类似软件中的类。
- 映射设计上易于扩展
在映射编辑器与映射 JSON 编辑器之间切换：
在映射差异视图与映射 JSON 差异视图之间切换：
步骤
- 映射是由步骤组成的文档段落。
- 每个步骤指向一个包含该步骤文档文本的 Markdown 文件。
- Markdown 文件可被多个步骤复用。
- Markdown 文件可用 Visual Studio Code 的 Markdown 编辑器编辑。
映射可引用其他映射
- 在另一映射中引用的映射，显示为单个步骤。
- 若被引用的映射有出口（exits），需将其他映射或步骤链接到这些出口上。
- 校验阻止循环引用。
变量
- 变量定义可复用的 Markdown 文本。
- 定义相对链接的变量，在发布到目标文档时自动调整，确保链接有效。
变量可引用其他变量
- 变量的 Markdown 文本可引用其他变量。
- 校验阻止循环引用。
编译为文档
发布时，Docs Assembler 读取选中的映射，校验并组装所有引用的映射和 Markdown 文件，展开变量，复制引用的资源文件，最终将结果编译为 Markdown 或 HTML 文件，输出到仓库中的发布文件夹。
对比已发布与线上版本
使用对比视图查看发布文件与 docs 文件夹中文件的差异。
将发布内容移至线上
若变更符合预期，点击移动按钮，将发布文件移至 docs 文件夹。若使用 GitHub Pages，docs 即为根文件夹。
既能处理复杂也能应对规模
- 最简单的映射：单个步骤和一个 Markdown 文件。
- 稍复杂：单一路径的步骤序列，如一本书或手册。
- 最复杂：映射是一个决策树，多个步骤指向其他映射，这些映射又指向更多映射……展开后的结果极为庞大，若不拆分为可管理、离散、可复用的单元，几乎无法构建或维护。正如代码中用类做拆分。
发布输出示例
上图说明
- 展示 C# 服务端/数据库应用，其中步骤存储在数据库中。
- 所有**附件（ancillaries）**已展开。
- 所有附件折叠时，指南呈现的信息足以让专家完成任务。
- 用户展开附件后，会插入该主题的更多步骤。
- 附件可嵌套，用户可层层深入。
- 所有可能的附件全部展开时，新手完成任务的所有步骤都会呈现。
- 复用映射可轻松构建和维护指南，用户可根据自身技能水平定制显示内容。
下图说明
- 展示 C# 服务端/数据库应用的编辑器界面。
- 显示构建上述指南所用的引用映射（含嵌套映射）。
- 大多数映射也会在其他指南中复用。
架构与显示工具约定
Docs Assembler 有意保持编写层简单。我们在将渲染复杂性推给显示层的同时，保持编辑器体验轻量且熟悉。
Docs Assembler 的编写模型尤其适用于分析性、低屈折变化的语言（英语、中文等），其单词不会根据性别、格或时态改变形态。对于高屈折变化的语言（俄语、阿拉伯语、波兰语、德语、巴斯克语等），高质量的本地化最好通过显示层在翻译前进行完整路径组装来处理。
显示工具作者应阅读 Display Tool Contract。该文档描述了边界和已知挑战，以便显示工具作者能够正确构建。指南可以跨仓库和域名引用远程映射；显示工具通过合约中描述的代理模式处理跨域片段加载。
我们积极欢迎对参考显示工具实现的贡献--以展示此模式。请在开始前提交 issue，以便就边界定义达成一致。
已发布版本
- 0.9.40
- 映射文件夹
- Markdown IntelliSense、诊断、TextMate 和语义语法高亮（针对步骤和变量）
- 发布列出的映射
- 移动或复制映射文件夹时自动矫正相对 URL
- 映射 JSON 编辑器
- 映射 JSON 差异编辑器
- 映射资源管理器
- 映射超链接
- GitHub Pages 集成
- 支持引用和嵌套映射的发布
- 支持附件的发布
- 更新 GitHub Pages 站点，新增展示引用和嵌套映射（含附件）的示例
- 映射和指南分组：已发布、已修改、从未发布
- 移动、克隆、复制粘贴映射文件夹时自动调整相对 URL
- 移动、重命名映射资源文件时自动更新引用和映射超链接
- 快捷键
- JSON 步骤（视频步骤）- JSON 智能提示、诊断、TextMate 和语义令牌
- 引用远程仓库中的指南
- 概览视图
- 仓库初始化、资源更新和迁移
下一步
即将推出
- 移动或复制分支中的一段
- 将分支中的某一段独立为新映射
- GitLab Pages 集成
- 从数据库版本移植
- 浅色主题
链接
team@netoftrees.com
www.netoftrees.com
x.com/docsassembler
关于 HAL Robotics 的最新信息
文档：
docs.hal-robotics.com
文档仓库：
github.com/HALRobotics/HAL.Documentation
官网：
hal-robotics.com
