Markdeep – plain text documents with diagrams, equations, and Markdown syntax | Hacker News Reader

Markdeep – plain text documents with diagrams, equations, and Markdown syntax

casual-effects.com

360 pointsthunderbong108 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.

Diagrams with PlantUML in AsciiDoc are quite efficient. Faster than powerpoint.

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.

PlantUML syntax is also a lot easier to maintain and update than an ascii chart which is basically a low res pixel art.

Have you run into this?

https://github.com/asciidoctor/asciidoctor/issues/1087

I love all the features of asciidoc but it bothers me they can't get the actual HTML generation right.

An alternative to both I like is the blockdiag programs, including seqdiag, netdiag, and rackdiag. Diagrams as text that can be properly automated.

neat, thanks

http://blockdiag.com/en/nwdiag/index.html

An alternative to both I like is the blockdiag programs, including seqdiag, netdiag, and netdiag. Diagrams as text that can be properly automated.

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

[0] https://dot-to-ascii.ggerganov.com/

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;
    })

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.

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

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/

http://asciiflow.com/

This is cool, but could benefit from some figlet-like text options

There's also https://monodraw.helftone.com that lets you draw directly in ASCII.

Well actually that's more like Unicode Art ;)

Of course it's Mac only. :(

I like it when these use actual box-drawing characters, ie https://en.wikipedia.org/wiki/Box-drawing_character or https://en.wikipedia.org/wiki/Code_page_437.

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 remember playing with those ansí box characters back in the late 1990s... shit norton , microsoft and every other "graphical" ui for DOS used it.

I like to use the vim plugin DrawIt for ascii diagrams:

https://www.thegeekstuff.com/2009/12/how-to-create-ascii-dra...

https://github.com/vim-scripts/DrawIt

Pretty easy to create comments for code that need a drawing for clear expositions.

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.

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.

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

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.

Sounds interesting, would you mind sharing your workflow and your makefile? I tried graphviz ages ago and think it's a powerful and underused tool.

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.

thanks

Sure! I use pandoc to render Markdown, but you can use whatever Markdown processor you like in place of pandoc.

Makefile

    all: example.html

    example.html: example.md example.png
        pandoc $< -o $@

    example.png: example.dot
        dot -Tpng $< -o $@

example.dot

    digraph G {
        foo -> bar;
    }

example.md

    # Example

    ![example graph](example.png)

thanks a lot!

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

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.

Perl to the rescue!

https://codeyarns.com/2017/10/21/how-to-convert-dot-graph-to...

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.

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.

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.

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”

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

There's no reason images can't be displayed in terminals other "that's not how terminals work" historical baggage.

iTerm2, as one example, can display images just fine.

If I wanted images in my text I would use Code.

Images are fine as long as they don't fuck with line counts or column counts.

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.

XML (via svg) can potentially be great for that... it saves the "what" so we only need software that does something useful with it.

Plaintext gives you straightforward integration with git though, which is waaaay better than the built-in collaborative version control you have in MS Office.

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

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.

"Reveal Codes" IIRC.

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.

I don't think the selling point on this is the flavor so much as the "add a line to your markdown and now it's an browser-viewable HTML file" aspect.

Take a look at https://github.com/susam/texme. It does not introduce a new Markdown flavor. Just the regular Markdown + support for Latex.

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

But, I don't.

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?

If you can get down with emacs, then org mode had you covered: https://orgmode.org/manual/Paragraphs.html

Thank you! I'd never heard of it. And, it's even one of the input formats to PanDoc. Huh.

That doesn’t cover you for lines of poetry that are broken across lines of dialog.

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.

Where can I see a screenshot of a correct result

See the examples in the manual for the LaTeX verse environment: https://rcweb.dartmouth.edu/doc/texmf-dist/doc/latex/verse/v...

Pandoc calls these "Line blocks": https://pandoc.org/MANUAL.html#line-blocks

For film scripts check out Screenplay Markdown now known as Fountain

reStructuredText handles this sort of thing well with its line blocks: https://docutils.sourceforge.io/docs/ref/rst/restructuredtex...

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

2 - https://github.com/getpelican/pelican

You're likely looking at the output of a build process, instead you should have a look in the source code that is likely on github.

> you should have a look in the source code that is likely on github

I did and it's not there. The repo in my link _is_ the source, unfortunately.

> Why javascript projects tend to be this way?

Because "you don't need $LIBRARY" / "bundling is crap" / "Vanilla JS is better". Some combination of those three.

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 :).

[1] https://glinscott.github.io/lz/

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.

Now you've posted this comment using a mobile device, try reading it. Did you find it annoying? Perhaps you could edit it. Thank you.

There are better ways of pointing out that the markup used isn’t optimal.

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.

Does it support diagrams and equations?

Sort of.

=begin HTML

=end HTML

Is pretty broadly supported for output formats that can support it.

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.

As far as I understand, you can convert Markdeep to static HTML using rasterizer: https://github.com/romainguy/markdeep-rasterizer

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.

This is what stops me. Where I work I need an autogenerated table of contents.

I need TOC, search, predictable URLs, plain markdown (no templates, no complexity, etc), and all the features of this thing.

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.

[1] https://docsify.js.org/

I strongly dislike projects that don't have a visible demo page. How do I even know if I like this without setting everything up first?

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.

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.

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.

ASCII seems like a lot. Are there no simpler methods?

https://mermaid-js.github.io/mermaid/#/examples

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?

Reply on news.ycombinator.com