You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
import Example from '@site/static/d2/ascii-ex.d2';
3
+
4
+
# ASCII output
5
+
6
+
In the latest release of D2 (0.7.1), we introduce ASCII outputs.
7
+
8
+
Any output file with extension `txt` will use the ASCII renderer to write to it.
9
+
10
+
```shell
11
+
d2 in.d2 out.txt
12
+
```
13
+
14
+
<!-- truncate -->
15
+
16
+
Here is an example of their rendering from the [D2 Vim extension](https://github.com/terrastruct/d2-vim). The user opens a `.d2` file and opens a preview window, which updates upon every save.
17
+
18
+
19
+
20
+
## Code documentation
21
+
22
+
Perhaps the most useful place for ASCII diagrams is in the source code comments. Small
23
+
simple diagrams next to functions or classes can serve to be much clearer than describing
24
+
a flow.
25
+
26
+
Here again the Vim extension demonstrates a functionality to write some d2 code and
27
+
replace the selection with the ASCII render.
28
+
29
+
30
+
31
+
## Unicode and standard ASCII
32
+
33
+
The default character set of ASCII renders is unicode, which has nicer box-drawing
34
+
characters. If you'd like true ASCII for maximum portability, you can specify this with
35
+
the flag `--ascii-mode=standard`.
36
+
37
+
## Limitations
38
+
39
+
:::info Alpha
40
+
Note that the ASCII renderer should be considered in alpha stage. There will be many
41
+
corner cases, areas of improvements, and outright bugs. If you enjoy using it, we'd
42
+
appreciate you taking the time to file any issues you run into:
Copy file name to clipboardExpand all lines: docs/tour/exports.md
+55Lines changed: 55 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,6 +8,7 @@ On the CLI, you may export `.d2` into
8
8
*[PDF](#pdf)
9
9
*[PPTX](#pptx)
10
10
*[GIF](#gif)
11
+
*[ASCII](#ascii)
11
12
*[Stdout](#stdout)
12
13
13
14
## SVG
@@ -102,6 +103,60 @@ For example, show two Scenarios, show a couple of steps. Something that the audi
102
103
digest in a loop that lasts a couple of seconds without needing to flip through it
103
104
manually.
104
105
106
+
## ASCII
107
+
108
+
:::warning Beta
109
+
ASCII outputs are new as of 0.7.1. They are to be considered in beta, and many diagrams
110
+
may not render correctly.
111
+
:::
112
+
113
+
ASCII exports render diagrams as text-based art, perfect for documentation, terminals, and environments where graphical formats aren't suitable. D2 automatically detects the `.txt` file extension and renders in ASCII format.
114
+
115
+
```shell
116
+
d2 in.d2 out.txt
117
+
```
118
+
119
+
### Character sets
120
+
121
+
D2 supports two ASCII character modes:
122
+
123
+
#### Extended mode (default)
124
+
Uses Unicode box-drawing characters for cleaner output:
125
+
126
+
```shell
127
+
d2 in.d2 out.txt
128
+
```
129
+
130
+
```
131
+
┌───────┐ ┌───────┐
132
+
│ Hello │──────▶│ World │
133
+
└───────┘ └───────┘
134
+
```
135
+
136
+
#### Standard mode
137
+
Uses basic ASCII characters for maximum compatibility:
138
+
139
+
```shell
140
+
d2 --ascii-mode standard in.d2 out.txt
141
+
```
142
+
143
+
```
144
+
+-------+ +-------+
145
+
| Hello |------>| World |
146
+
+-------+ +-------+
147
+
```
148
+
149
+
### Notes
150
+
151
+
- Renders only with ELK and TALA, due to curved lines not rendering well in ASCII. If
152
+
Dagre (or unspecified) is chosen, it will render in ELK.
153
+
- Some shapes are supported, like Person, but some shapes are hard to represent cleanly in
154
+
ASCII. It's best to avoid using these shapes when the output is ASCII, but if it can't
155
+
be avoided, in these cases, an icon on the top-left corner represents what the shape is
156
+
meant to be.
157
+
- Many styles are moot in ASCII, such as shadow or multiple or animated. It's best to keep
158
+
it as simple box and arrow type diagrams.
159
+
105
160
## Stdout
106
161
107
162
D2 accepts `-` in place of the input and/or output arguments. SVG is used as the format
0 commit comments