Portable documentation

Keeping portable architecture context in Mermaid and Markdown

A diagram is easier to use when its explanation travels with it. Mermaid and Markdown offer a lightweight way to do that, with a structured model available when the diagram needs more identity and depth.

An architecture picture without context can leave readers guessing. Is it a deployment view, a request path, or a sketch of a proposal? Markdown gives a natural place to answer those questions, and Mermaid lets teams put a text-authored diagram in the same file. The combination keeps an explanation, a diagram, and their version history close together.

That portability is practical, not universal. A Mermaid block renders only in compatible Markdown viewers, and supported diagram types and syntax vary by renderer. A source block is still readable as text when rendering is unavailable, but readers may need the diagram’s purpose explained in surrounding prose.

Keep a small diagram near its explanation

Mermaid is well suited to compact flows that benefit from inline review. A README can show a request path beside its operational steps. A design note can sketch a proposed integration next to the trade-offs. Contributors can discuss changes to the source as part of a normal text diff.

flowchart LR
  client[Web client] --> api[API]
  api --> database[(Database)]

The example is intentionally small. If a diagram becomes hard to scan in a code review or pushes the prose far away, break it into a focused view or use a visual editor. Mermaid source describes a diagram; it does not automatically provide a shared inventory of architecture elements across many documents.

When a structured model adds value

A system that appears in multiple views often needs more than a set of independent pictures. Teams may want a stable identity for a service, a connection between a parent context view and a deeper component view, or a place to maintain important metadata. A structured model can supply reusable elements and relationships; Mermaid can remain a portable representation for a focused flow or document.

tlDiagram’s documentation describes exporting a view as Mermaid and associating Markdown notes with a diagram. Its integration uses annotated Mermaid code blocks to link blocks with tlDiagram views and elements. When a block is linked, the editor can show its relationship and support updating the Mermaid text from the current view. The metadata is stored in comments in the Mermaid source, so the block remains text and can be used by compatible renderers. The docs call this metadata experimental and subject to change.

Understand the synchronization boundary

tlDiagram documents best-effort import for most Mermaid flowcharts. Other diagram grammars have had initial work but remain in development; the project does not claim support for all Mermaid diagram types. In particular, do not promise that every sequence, class, state, or specialized diagram can be imported into a structured view. Try the exact block you plan to use and inspect the result.

There is also a difference between exporting or importing a diagram and synchronizing a linked block. A linked block carries identifiers and layout metadata that let the editor associate content with a view. An unrecognized Mermaid block can be imported where the supported grammar permits, but it does not automatically have a preexisting identity relationship to a tlDiagram view. Likewise, editing Mermaid in a separate Markdown tool does not guarantee that a linked diagram will update in the editor until its sync behavior is applied.

Make portable context useful to readers

1. State the question. Add a sentence that says what the view shows and what it leaves out.
2. Use meaningful names. Label the actual service or data store when the distinction matters; avoid unexplained abbreviations.
3. Keep the view bounded. Split a dense architecture into separate flows or levels instead of shrinking labels.
4. Check renderer compatibility. Preview the Markdown in the repository’s target environment and verify the Mermaid syntax it supports.
5. Review linked metadata carefully. When using tlDiagram sync, retain its comments and check the editor’s sync state before distributing a changed block.

Markdown notes can be local to the tld data directory, stored as files in a repository, or linked from an existing file, according to the product docs. A repository note can keep context close to code and under version control. A local note may be convenient for personal exploration, but it will not become a shared team artifact simply because it is attached to a diagram in one local environment.

Use each format for the work it does well

Mermaid and Markdown are a good fit when readers need a portable diagram beside a written explanation. A structured architecture model is useful when the same elements recur across views or when people need to navigate from an overview into more detail. They can coexist as long as their relationship is clear: one may be a generated or synchronized view of the other, or they may be separate artifacts for separate jobs.

Keep the scope modest, document the source of truth, and test the specific syntax and sync workflow your team relies on. A readable note with a bounded diagram is more useful than a promise of universal format compatibility.

Read the Mermaid and Markdown guide and explore the open-source tld repository for current integration details.