Skip to main content

Working With Other Tools

ASCII Diagram is not trying to replace every other way of making diagrams.

It is designed to coexist with tools that already make sense for a given workflow.

Git​

Git is one of the main reasons ASCII Diagram exists in the first place.

Useful patterns:

  • commit diagrams with code changes
  • review diagram edits in pull requests
  • diff structure over time
  • keep long-term history beside the project it documents

Markdown​

Rendered ASCII is comfortable inside Markdown-heavy workflows:

  • READMEs
  • design notes
  • issue templates
  • ADRs
  • runbooks

You can keep the .asciid file as source and paste the rendered text wherever it is useful.

Mermaid​

Mermaid is excellent when the diagram should be authored directly as code-like text inside Markdown or supported docs systems.

ASCII Diagram is a better fit when you want:

  • a visual editor
  • freeform box placement on a grid
  • structured file source without requiring a declarative diagram language

PlantUML​

PlantUML is powerful for diagram types that map well to a textual DSL.

ASCII Diagram is simpler and more freeform. It is better for lightweight technical sketches where boxes, text, and arrows are enough.

Graphviz​

Graphviz is great when automatic layout is the main requirement.

ASCII Diagram is different: it lets you place the layout manually and keep the result easy to copy into text-first environments.

Any text editor​

Because the source is JSON, any editor can inspect the file.

That matters for:

  • debugging
  • bulk edits
  • quick renames
  • future migrations

Why this matters​

If ASCII Diagram ever is not the right tool for a task, your work is not trapped.

That is the point of file-first software: the tool should be useful without becoming mandatory.