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.
InstallationTo get started, the easiest way to use typograms is to link from our CDN:
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
<body> <script src="https://google.github.io/typograms/typograms.js"></script> <script type="text/typogram"> +----+ | |---> My first diagram! +----+ </script> </body>
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.
Overlaps and intersections
Lines with decorations
Graph with small nodes
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
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).