Docs Assembler - Treat Documentation Like Code

This is an experimental port from a c# server/database application - to a GitHub repo/vscode extension. A concept driven by transformational conversations with a robotics firm - HAL Robotics.

Solve documentation hell,

Sprawling, duplicated content across guides, manuals, and wikis.
Bug-prone updates make an edit in one place, miss it in ten others.
Brittle, unmanageable docs that can't handle complex, branching scenarios without becoming a nightmare.
Wasting time wrestling with static generators instead of building features.

by applying the principles of software engineering to your documentation,

Docs Assembler is a VS Code extension that lets you build documentation systems with modular, reusable components. Think of it like classes for your content.

Maps (.tsmap files): Self-contained documentation modules that can be nested and composed, just like classes. Encapsulate procedures, tutorials, or decision trees.
Variables: Define reusable text snippets (e.g., product names, error messages, URLs). Change one, update everywhere.
Inheritance & Composition: Build complex guides from simple, reusable blocks. A change in a base map propagates to all guides that use it.
Compile to Docs: Assemble these components on-the-fly into flawless, context-aware Markdown or HTML for your static site (like GitHub Pages).

and maintain a single source of truth for your documentation.

Designed for Developers, by Developers

The design of Docs Assembler was driven by a fundamental need to have a powerful system that respects developer workflows and sovereignty:

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 locked into 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 as 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 most 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 Rigor: It brings true software tooling to docs, with IntelliSense for variables, full validation before publish, and automatic adjustment of relative URLs.

GitHub Pages

Modular Documentation Demos:
Publish currently targets GitHub Pages, producing Jekyll Markdown.
After a Publish run a Git Commit and Push for GitHub Pages to make changes live.

Repo:
The sample maps are located in the /tsmaps/ folder and published guides in /docs/.

Hosting a website on GitHub Pages is free for public repos.

Bugs, questions or feedback? - Email us

team@netoftrees.com

After an extension update clear vscode history:

Open the Command Palette: Cmd+Shift+P
Type: Clear Editor History

Quick walkthrough

Using a fork of the HAL Robotics documentation repo, initialised to use maps - HAL.Documentation.maps.
It serves as a good example for simple use cases - as there are only shared variables and steps, no linked maps.

BE AWARE: This is not the current version of HAL Robotics documentation - see below

Maps

The main building block is a map.
It is a json file with a .tsmap extension.
Functions similarly to a class in software.
Maps are built to scale up easily

Switching between Map Editor and Map Json Editor:

Docs Assembler map json editor gif

Switching between Maps Diff and Maps Json Diff:

Docs Assembler diff map json gif

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.

Docs Assembler steps gif

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.

Docs Assembler charts gif

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.

Docs Assembler variables gif

Variables can reference other variables

A variable's markdown text can reference other variables.
Validation prevents circular references.

Docs Assembler variables nested gif

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 resuls into markdown or html files to the publish folder in your repo.

Docs Assembler publish gif

Compare published to live

Use the compare view to view changes between published files and the docs folder files.

Docs Assembler compare gif

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.

Docs Assembler live gif

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 buildor maintain without breaking it down into manageable, discrete, reusable, units. Just like we do in code with classes.

Example of published output

netoftrees C# server/database applications gif

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.