Typograms (typographic diagrams) is a lightweight image format (text/typogram) useful for defining simple diagrams in technical documentation.
Like markdown, typograms is heavily inspired by pre-existing conventions found in ASCII diagrams. A small set of primitives and rules to connect them is defined, which you can use to build larger diagrams.
Typograms optimizes for editability and portability (e.g. plain text is easy to maintain, change, store and transmit), at the cost of expressivity (e.g. SVG is more expressive) and ergonomics (e.g. higher level tools produce diagrams faster).
A comparison with related work is available below.
A JS renderer is available that allows you use to use it in browsers.
Installation
To get started, the easiest way to use typograms is to link from our CDN:
<body>
<script src="https://google.github.io/typograms/typograms.js"></script>
<script type="text/typogram">
+----+
| |---> My first diagram!
+----+
</script>
</body>
From there, you can download the library directly to serve yourself.
You can also use it as a command line tool or a node library:
https://github.com/google/typograms
Primitives
Typograms are composed of primitives and connectors that combine them: pipes (| - _ \ / : ~), dots arrows (> ^ * o # v < ) and Connectors (+ . -).
By putting them together, you can form a lot of different diagrams.
Pipes
Dots
Arrows
Text
Examples
Protocols
Mocks
Architecture
Components
Layers
Tables
Flow charts
Trees
Shapes
Big Shapes
Small Shapes
Overlaps and intersections
Grids
Big grids
Small grids
Dot grids
Time series
Chips
Circuits
Mindmaps
Scribbles
Lines with decorations
Line ends
Graph with small nodes
Graphic diagrams
Work in Progress
This is a list of constructions that are currently looking into supporting.
UT8 Diagram Characters Are Off
Triangles connected without + aren't pointy
Diagonals don't join with underscores
Text detection gets confused
Small curved steps
Parenthesis and spheres
Diagonal Side-way Arrows
Related Work
The closest work to typograms is svgbob: it renders diagrams from ASCII and works in browsers (through a webassembly port which spits out SVGs). It supports a similar set of features (with the notable exception of its support for circle drawing) and picks a similar set of typographic conventions (with the notable exception of text rendering). It is well-specified. I ran into enough challenges with (a) the text rendering and (b) running in the browser through the webassembly port that motivated me to write an ASCII diagram renderer in JS (svgbob is written in rust), but is otherwise a perfectly valid (more mature) alternative.
From there, there is a series of projects that rendered images from ASCII diagrams but weren't either (a) particularly good to be used in isolation (i.e. just diagrams) or (b) on webpages (i.e. running natively in browsers): asciitosvg, ditaa and markdeep (and the go port GoAT) most notably.
Unlike libraries like mermaid, typograms are defined typographically (WYSWYG), rather than semantically (a transformation from a high level description to graphics), which picks a different trade-off: it gives you more control over the rendering (expressivity) at the cost of making you type more (productivity).