Merge pull request #297 from terrastruct/gifs

add line about limitation of shapes

Author: alixander

blog/ascii.md

@@ -59,6 +59,43 @@ some post-processing to further compact it.
   - Sometimes the downscaling results in a box with uneven spacing, e.g. a rectangle with
 width 5 and the label is 2 chars. Due to discrete coordinate space in ASCII renders, some
 outputs may look less even than their SVG counterparts.
+- Certain things just can't render
+    - Special text, e.g. Markdown, Latex, Code
+    - Images and icons
+    - UML classes and SQL tables
+    - Right now these aren't special-handled -- whether removing them from the diagram or
+using some placeholder is the right choice is tbd.
+- Not all shapes are supported
+  - Here's what all the shapes render as in ASCII. Some of these, like cloud and circle,
+  have curves that don't translate well to ASCII. We render these as a rectangle and add
+  a little icon for what it's supposed to represent in the top-left. These are subject to
+change. For now we recommend rendering without custom shapes.
+
+```txt
+                                                      ┌────────┐         ***
+                  ╱‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾╱   ╱‾‾‾‾‾‾‾‾‾╱╲    │callout │     ****   ****     ╱‾‾‾‾‾‾‾‾‾╲
+ ┌──────────┐    ╱               ╱   │         │  │   └────────┘  ***  diamond  *** ╱           ╲
+ │rectangle │   ╱ parallelogram ╱    │   queue │  │        │ ╱      ****     ****   ╲  hexagon  ╱
+ │          │  ╱_______________╱      ╲________ ╲╱         │╱           *****        ╲_________╱
+ └──────────┘
+       │                 │                  │              │              │                │
+       ▼                 ▼                  ▼              ▼              │                ▼
+  ┌─────────┐      ┌──────────┐        ┌────┐        ╱‾‾‾‾‾‾‾‾‾‾‾╱        ▼          ┌☁─────────┐
+  │         │      │ document │        │    └────┐  ╱           ╱    ┌⬭────────┐     │          │
+  │ square  │      │     .-`-.│        │ package │ │ stored_data     │  oval   │     │  cloud   │
+  │         │       `-.-`              └─────────┘  ╲           ╲    │         │     │          │
+  │         │                                        ╲___________╲   └─────────┘     │          │
+  └─────────┘            │                  │              │              │          └──────────┘
+       │                 │                  │              │              │
+       ▼                 ▼                  ▼              ▼              │
+   ┌─────┐          .-‾‾‾‾-.          ╲‾‾‾‾‾‾‾ ╲         ╱‾‾╲             ▼
+   │     ╲┐        │╲-____-╱│          ╲        ╲        ╲__╱        ┌⬭────────┐
+   │ page │        │        │           ╲        ╲      ╱‾‾‾‾╲       │         │
+   │      │        │        │           ╱ step   ╱      ‾‾‾‾‾‾       │ circle  │
+   └──────┘        │cylinder│          ╱        ╱       person       │         │
+                   │        │         ╱_______ ╱                     │         │
+                    ╲-____-╱                                         └─────────┘
+```
 
 ## Try it yourself