Overview

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 polyfill 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

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 rewrite it 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).