▲ 360 points
back
108 comments
If I need graphic charts/diagrams, I've already passed the markdown stage. There's absolutely no workflow I can think of that is improved by my sitting there and trying to ASCII Art my way into a diagram. Does anyone go, hey, you know what would make my note-taking or web design faster and easier? Spending 20 minutes making an ascii art diagram instead of slapping the same three figures out in powerpoint in 20 seconds.
I love markdown. It's an elegant tool for many situations. My own workflow depends on using Kiwi and Noteplan on my phone with a common dropbox directory for their files, which is a project directory for Sublime on my notebook and desktop. All of my organization is a centralized set of markdown'd text documents, be it my calendar or my knowledge base, sync'd across all of my devices and super-easily edited, searched, or converted to web pages.
But there is a point where using a simple and elegant tool stops being simple and elegant - it can only be tortured so far outside its intended use-case before it stops being useful.
The main advantage I see is that the markdown diagram is understandable in plaintext. That's quite a powerful idea because you don't need to understand any intermediate language. Graphviz and mermaid are interpretable, but not in an immediately visual way.
I would be interested in a solution that can take graphviz files and output markdown-friendly diagrams, which can then be compiled back into vector diagrams.
I kind of want the opposite of this: A GUI tool I can draw some diagram stuff out in that renders down to ASCII art.
Bonus points if it renders to Markdeep (or an equivalent) to be re-rendered as SVGs or whatever later on.
Edit: Here we go - http://asciiflow.com/
I actually like using ascii diagrams for relatively simple graphs, because I can incorporate them directly in my source code comments. Recently I even made a simple web page where you can create easily ascii diagrams using dot [0]
For simple graph diagrams it's easy enough to open up a separate graphviz .dot file, write up a graph specification, run it through dot or neato, and include the .png in your markdown file. And then automate this with a Makefile.
> Does anyone go, hey, you know what would make my note-taking or web design faster and easier? Spending 20 minutes making an ascii art diagram instead of slapping the same three figures out in powerpoint in 20 seconds.
Yes, I do. I spend my time in a terminal all day and ASCII art is way more useful than an image reference which will never be able to load.
Show me a tool to export that powerpoint to ASCII and I'll be happy.
Diagrams with PlantUML in AsciiDoc are quite efficient. Faster than powerpoint.
In my opinion it's way better to have things all in one program. The clumsiness of needing to open up a heavyweight program like Powerpoint to then copy and paste the figure somehow into your document every time you revise is very annoying to me. Plus it's less portable.
> There's absolutely no workflow I can think of that is improved by my sitting there and trying to ASCII Art my way into a diagram. Does anyone go, hey, you know what would make my note-taking or web design faster and easier?
Documentation embedded in code docstrings. Yes, I could link to an external SVG but if you did that it wouldn't look great if I have to query the documentation via REPL.
I agree, but maybe it’s syntax. MermaidJS has pretty quick and easy syntax that makes whipping up diagrams simple enough for me to convert.
I'd be pretty happy with the ability to do inline graphviz diagrams. If I'm using Markdown then I'm not really after super great presentation quality, so not having a lot of control over layout doesn't necessarily bother me as long as I can describe the graph quickly.
An alternative to both I like is the blockdiag programs, including seqdiag, netdiag, and rackdiag. Diagrams as text that can be properly automated.
Yeah, I thought the same when looking at this. Text editing my way to ASCII diagrams is time consuming and brings little value for my time.
> If I need graphic charts/diagrams, I've already passed the markdown stage.
I disagree. Linux kernel documentation and many manpages contain ascii diagrams that proved extremity useful for helping me understanding the them.
I really hope to see diagrams adopted into the markdown standard (CommonMark).
Yeah ASCII Art is not ideal for drawings like this. I get frustrated enough at work writing comments requiring drawings. I can’t imagine trying to do that here.
Maybe something very simple: A->B<-C similar to the syntax described for causal diagrams in Judea Pearl’s “The Book of Why”
Plaintext gives you straightforward integration with git though, which is waaaay better than the built-in collaborative version control you have in MS Office.
An alternative to both I like is the blockdiag programs, including seqdiag, netdiag, and netdiag. Diagrams as text that can be properly automated.
ASCII diagrams aren't competing with powerpoint, diagrams made with sequence js, mermaid js, etc. are.
For the particular offerings of these libraries, a higher quality, professional looking output is generated in a shorter time than powerpoint.
And most importantly, one can version control it, as the source is plain text
> But there is a point where using a simple and elegant tool stops being simple and elegant - it can only be tortured so far outside its intended use-case before it stops being useful.
An alternative tool I've begun to like is TeXMe: https://github.com/susam/texme. It is like Markdeep but minimal--does not support any fancy features. Just plain Markdown and Latex. Very useful for note taking in a file that can publish itself. I don't think I can draw fancy diagrams while taking notes live so I don't need diagrams. So this simple tool serves me well.
Markdeep is a great project and supports a lot of impressive features. However, if you care about conforming to CommonMark, I would request you to try out TeXMe. I initially wrote TeXMe for me and my friends. After a Show HN post about it, it has found a lot of other users too. TeXMe has a very minimal feature set but it cares about CommonMark.
TeXMe on GitHub: https://github.com/susam/texme
TeXMe Demo: https://opendocs.github.io/texme/examples/demo.html
Detailed comparison between TeXMe and Markdeep: https://news.ycombinator.com/item?id=18314175
Anybody remeber the dos version of Wordperfect 5 or 5.5? It had a mode, AFAIK triggered by pressing F11 or was it F12 where every formatting operation like inserting a new page, bold or italics was displayed as a control sequence. Wordperfect didn't care if you five times marked a text as bold and required you to "unbold" five times to continue writing in regular font.
I used to be a wizzard operating in this mode and many of my school-mates reached out for me to get their homework assignment properly formatted.
Somehow this WP5.5 format reminds me of that Markdown extension. Thankfully markdown is much richer in semantics.
My mother published 5 books with WordPerfect and adamantly refused to learn any desktop publishing system that didn't have Reveal Codes.
When she says she doesn't understand what I do for a living, I tell her that I work with Reveal Codes, all day. It's more right than wrong.
I don't get why we need these Markdown "flavors". Most Markdown renderers allow you to pick and choose different extensions, and graphs have been possible in Markdown for a long time with things like Mermaid, which I think does graphs a lot better than this time consuming ASCII-art format.
The implementation is clever, but. But. Does it do the one damn thing that no other MarkXXX dialect properly supports: poetry? by which I mean, can you have a text block ("stanza") in which each line is a block that has full formatting (i.e. do not try to pawn me off with a code block!) but in which white space if fully respected (i.e. arbitrary indention is retained), and the ability to right-align an annotation ("line number") is available?
And can you use it to write a play script (see any copy of Hamlet) and/or a film script?
I've been using https://github.com/rust-lang/mdBook with plugins: https://github.com/dylanowen/mdbook-graphviz the plugins are all done via stdio so any language works
There already is support for this (and more) in man pages.
https://www.troff.org/prog.html#dformat
https://en.wikipedia.org/wiki/Pic_language
$ <<EOF nroff -p | col -b
> .PS
> lineht = lineht / 2
>
> box "\fIletter.tr\fP"
> arrow
> circle "tbl"
> arrow
> Eqn: circle "eqn"
> arrow
> Troff: circle "troff"
> arc cw
> line down
> arc cw
> left
> arrow
> circle "grops"
> arrow
> box "\fIletter.ps\fP"
>
> up
> line <- from Troff.n
> arc
> line
> box "\fItmac.m\fP"
> .PE
>
──────
tmac.m
│
letter.tr──── tbl ───── eqn ─────troff
│
───── ─────
letter.ps grops(Not-so)-fun fact - the source of Markdeep is a single 5000 line long javascript file :( [1]
I wanted to integrate it with my Pelican[2] workflow but I'm not touching that with a 10-foot pole.
Why javascript projects tend to be this way?
1 - https://github.com/morgan3d/markdeep/blob/master/1.09/markde...
Markdeep is fantastic. I wrote a fairly long article [1] with a lot of code samples, and it was so nice to not worry about formatting. The styling is elegant without having to try :).
Its seems much more time consuming to do ASCII art than easy programing functions as plot(x, y, …) or box("content",black-line), circle("content",red-fill), "content"arrow(blue-line)"content" and so on.
For those who, like me, thought at first glance that this might be deep learning related, there's an explanation near the bottom:
(Bear with me, posting this from mobile)
The name "markdown" conveys styling in the opposite direction of the "markup" tag syntax. Markdown beautifies text without explicit tags, based on common practices from ASCII e-mail and plain-text documents.
"Markdeep" is farther "down" from "markdown" on the autostyling and beautification path. Markdeep combines an easy-to-use and browser-friendly packaging with new unique features such as diagrams.Another alternative is Perl's "POD" format, even if you're doing something not at all Perl related.
It's a fairly established common format that can be translated into text, HTML, markdown, man pages, etc.
Neat, but the browser-side rendering for some examples is very slow on my tablet (tens of seconds). At first I assumed the article I was reading was plain text.
It should probably be done server-side with a static site generator.
Check out Markdown Preview Enhanced https://shd101wyy.github.io/markdown-preview-enhanced/#/
This has support for mermaid, slides etc.
All these ascii diagramming tools look very promising. I just shudder to edit a diagram, though, and, say, move a box a bit to the left... How are these diagrams not write-once edit-never?
I'd like to be storing design docs and specs in git instead of confluence with draw.io diagrams, but so far haven't found any WYSIWYG round-trip-able integrated-into-intellij tools.
Intellij supports plantuml and doubtless a few other schemes, but do any of them have the equiv of a draw.io editor integrated?
Just to add a point of reference, here is one slide set (of many) that I have prepared exclusively using Markdeep. It is full of character-based diagrams, of course. Font: Pragmata Pro.
https://db.inf.uni-tuebingen.de/staticfiles/publications/com...
Interesting, yet, I think diagrams require a graphical editor that can be used to author and modify diagrams. I’ve done plenty if ASCII-art-ish things in embedded/FPGA code (example: timing diagrams. Not something I would consider doing with any regularity. Creating them is painfully time consuming, editing even more so.
BTW, I use MarkdownPad with live side—by-side preview. Love it.
Does this index a file tree and create a document table of contents? I'd love to have a public version of g3docs.
I've been enjoying using a similar tool called docsify[1], which is a static page that renders markdown files in browser. Basically as self-contained as Markdeep / TeXMe but more flexible.
Every such project has to strike a balance, and the balance struck here looks really good to me. Nice job.
Most good ASCII diagram generators are mac only. Like monodraw.
I wish there was something of similar quality for linux (or web generated).
No asciiflow doesn't come close.
I have also been trying to use mermaidjs, but asset quality is not close to monodraw
native chart elements in HTML would be useful I think
particularly for applications like wikipedia, where a lot of graphs are pasted images and the original data is gone
styling them and dealing with different chart types will be tricky in the same way every charting tool out there is tricky to use (d3, matplotlib, everything that doesn't restrict to a small set of chart types & push default style)
autoreload every 5 seconds (usefull while editing):
<meta http-equiv="refresh" content="5" >Those ASCII drawings doesn't become more sexy by converting to SVG. Use a SVG editor (or hand code it, it's fairly simple xml). Not only will it be faster then drawing using text, it will also look better.
ASCII seems like a lot. Are there no simpler methods?
I could have sworn there was a renderer for gviz+dotty that did the left half (text ascii plots) but can't seem to DDG it for the life of me. Did I imagine it?