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.
We could also use a higher-bandwidth format than plain text? There is a lot of technical content which could be improved greatly by easy graphical tools for diagrams, equations, and so on, which is going a bit by the wayside because of the all-in-on-plaintext attitude. I think there is a lot of opportunity for clearer communication being totally passed over because of our collective inertia with respect to making better tools which would allow this kind of thing.
The usual difficulty with moving beyond plain text is diffing/patching. Text has battle tested and decent visualisations for viewing the delta between two versions. Other formats generally don't.
How do you visualise the diff of a diagram? How do you integrate it with git? That seems hard.
visualizing the diff of an ascii-art diagram leaves a lot to be desired as well. addding an extra box or re-routing an arrow in the diagram on the markdeep homepage would produce a very messy diff. if you want good diffs for highly visual content, converting that content to ascii art doesn't seem like the right answer to me.
the "magic" of this would also make me uncomfortable. if i draw a diagram and the rendered output doesn't look the way i want it, i wouldn't know how to fix it.
It’s a fair point, but again I think that it’s a very small price to pay for the improved communication. Things do seem hard, but we solve very hard problems in programming all the time (or so it seems), except when it comes to our tools. Plain text is still king when it comes to code because it is so easy to diff (which I think is a good choice), but how about my silly comments explaining how a system works rather than just drawing it and embedding that in a comment? I think there is a lot of potential there.
Boxes made out of asterisks, dashes, and slashes appeal to me about as much as cutlery made out of recycled tin cans and coat hangers; it's the worst of both worlds, too ugly to qualify as real graphics and too distracting to be useful as text. Weirdly, the look worse than 'graphics' on the Commodore PET or TRS-80 (whose 'graphic' characters were helpfully printed on the keys and accessible through combination button presses).
Wow, I can't believe I went this long without realizing there were these characters specifically intended to be used in text based interfaces. It's funny, these are almost like the opposite of emojis, text trying to be graphics, rather than graphics trying to be text.
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.
AsciiDoctor has GraphViz (and PlantUML plus a few more) available inline (it handles the conversion for you). The syntax has a few differences to Markdown but it's not too hard to adapt plus it has a few other awesome features that I always miss when in Markdown.
> 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.
Or just use zim ( https://zim-wiki.org/ ) which allows you to embed graphviz diagrams in any 'page', and many other features.
> 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.
I've included plantuml stuff in our internal documentation at work for a long time, and have got a lot of complements from people on how great our documentation is. I attribute a lot of this to the diagrams (mostly component and sequence diagrams), many of which are there just because of how simple and fast it is to create+maintain them with inline plantuml.
Benefits:
Fairly easy to learn syntax, and powerful enough for most technical documentation needs.
Easy to edit, easy to consume. No launching some heavy desktop app, no worrying about keeping PNG+source files up to date. (I do often use liveuml.com for editing any non-trivial diagrams though.)
Works with version control
Consistent style even when different people are working on diagrams
Drawbacks:
Not that pretty. Someone even mildly proficient at PowerPoint can make better-looking diagrams (though it takes longer). If you're doing internal or technical docs this isn't worth it, but for marketing/end-user facing stuff, maybe. I'll often just give my plantuml diagram to marketing and let them have a graphic designer pretty it up.
Less intuitive. The learning curve is a bit of a barrier for people that have spent years doing stuff in PowerPoint, and haven't yet bought into the other benefits. Especially for a simple diagram, it's hard to convince them to spend a couple hours so they can learn how to build it in 5-10 minutes with plantuml, vs just spending 10 minutes in PowerPoint. I think this is exacerbated by the fact a lot of the benefits come later when trying to edit and it gets more complex.
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.
This is why Microsoft invented OLE many decades ago. Admittedly it was a clunky, heavy and proprietary solution just like most other tech out of that company.
> 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'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.
I think I kind of like how this thing lets you do either quick ASCII art diagrams or embed graphviz (via Gravizo). The syntax for inserting Gravizo diagrams isn't too bad:
![Figure [graph]: A more complex graph example](http://g.gravizo.com/svg?
digraph G {
main -> parse -> execute;
main -> init;
main -> cleanup;
execute -> make_string;
execute -> printf
init -> make_string;
main -> printf;
execute -> compare;
})
The worst part isn't that it's time consuming but simple changes often require you to redraw the whole thing again. So for the most part a simple mermaid or graphviz is much more appropriate.
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.
> 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.
TeX doesn't preclude diagrams. I use TikZ extensively, and I've found it much easier than any graphical diagram tool I've ever used. (As with most of TeX, it has a learning curve, but then a much easier steady-state after that learning curve.)
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.
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.
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.
I'm sure you know what you mean by the difference between Markdown "flavors" (bad, don't need) and Markdown renderers that let you pick and choose different extensions (good, more of that please).
A flavor is a slightly different syntax, a renderer is the software that outputs format x from markdown. So flavor A can only be rendered by renderer A, but vanilla markdown can be rendered by all renderers. Different renderers can produce different output based on the options you give them, though
Sure, and Markdeep handles vanilla Markdown just fine. It also offers some extensions, which can't be standard by definition. I don't see a problem with that, and I definitely don't understand the distinction the grandparent was trying to make.
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 think that there is going to be a limit to the intersection of ‘relatively simple markup for human authors’ and ‘can represent complex text formats’. For instance, TEI xml can do what you want (in fact, TEI markup for Shakespeare already exists), but of course it is a little more cumbersome, unless you are working in a good xml editor. And then, there is no good way to translate that back to HTML.
(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.
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.
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.
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.
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.
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.
The link I provided (their documentation page) is the demo page. The source code is at https://github.com/docsifyjs/docsify/tree/master/docs which is a single static index.html that renders a bunch of markdown files.
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)
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.
Depending on the svg editor and font's installed, you will get mixed results and not everyone has the time or skill to write correct svg by hand. Pretty quickly you will find out that this approach creates too many problems if you want to collaborate with more than 2 people.
yeh, I hate it when people edit my hand written SVG images in a program that makes them 100x larger and unreadable. Where all they had to do was to copy one line of xml and edit coordinates.
I'm guessing the parent is being down-voted for simply pasting a link with no context.
For the kind of diagrams I typically want to include in a Markdown document (a quick DB ERD, a class diagram, a deployment diagram, state charts, or sequence diagrams), those things can be described in a simple descriptive form and then drawn from that. I don't want to draw.
I think a good tool for that is Mermaid.JS (see the parent link).
However, what I think the Markdeep approach has over the Mermaid approach is that Markdeep fits the general ethos of Markdown much better: start with a readable doc. I would agree that an ASCII art picture is more readable than Mermaid.JS.
It'd be nice to see approaches like Mermaid with a bit more energy into making the markdown behind the diagrams a bit more readable relative to where they are now, so that consumers of the raw markdown have an easier time.
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?
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.