
Markdeep – plain text documents with diagrams, equations, and Markdown syntax - thunderbong
https://casual-effects.com/markdeep/
======
arkades
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.

~~~
timdorr
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/)

~~~
Razengan
There's also [https://monodraw.helftone.com](https://monodraw.helftone.com)
that lets you draw directly in ASCII.

~~~
munfred
Well actually that's more like Unicode Art ;)

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

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

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

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

~~~
cnf
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

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

------
dylanowen
I've been using [https://github.com/rust-lang/mdBook](https://github.com/rust-
lang/mdBook) with plugins: [https://github.com/dylanowen/mdbook-
graphviz](https://github.com/dylanowen/mdbook-graphviz) the plugins are all
done via stdio so any language works

------
mzs
There already is support for this (and more) in man pages.

[https://www.troff.org/prog.html#dformat](https://www.troff.org/prog.html#dformat)

[https://en.wikipedia.org/wiki/Pic_language](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

------
fernly
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?

~~~
CreRecombinase
If you can get down with emacs, then org mode had you covered:
[https://orgmode.org/manual/Paragraphs.html](https://orgmode.org/manual/Paragraphs.html)

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

------
kabacha
(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...](https://github.com/morgan3d/markdeep/blob/master/1.09/markdeep.js#L5006)

2 -
[https://github.com/getpelican/pelican](https://github.com/getpelican/pelican)

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

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

------
glinscott
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/](https://glinscott.github.io/lz/)

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

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

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

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

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

~~~
77pt77
Does it support diagrams and equations?

~~~
tyingq
Sort of.

=begin HTML

=end HTML

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

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

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

------
nablaoperator
Check out Markdown Preview Enhanced [https://shd101wyy.github.io/markdown-
preview-enhanced/#/](https://shd101wyy.github.io/markdown-preview-enhanced/#/)

This has support for mermaid, slides etc.

------
willvarfar
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?

------
0xff00ffee
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?

------
ivanceras
See also [https://ivanceras.github.io/svgbob-
editor/](https://ivanceras.github.io/svgbob-editor/)

------
ProfTeggy
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...](https://db.inf.uni-
tuebingen.de/staticfiles/publications/compiling-PLSQL-away-slides.pdf)

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

------
gravypod
Does this index a file tree and create a document table of contents? I'd love
to have a public version of g3docs.

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

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

------
tomtung
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/](https://docsify.js.org/)

~~~
Summershard
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?

~~~
tomtung
The link I provided (their documentation page) is the demo page. The source
code is at
[https://github.com/docsifyjs/docsify/tree/master/docs](https://github.com/docsifyjs/docsify/tree/master/docs)
which is a single static index.html that renders a bunch of markdown files.

------
rossjudson
Every such project has to strike a balance, and the balance struck here looks
really good to me. Nice job.

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

------
awinter-py
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)

------
boshomi
autoreload every 5 seconds (usefull while editing):

    
    
      <meta http-equiv="refresh" content="5" >

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

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

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

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

~~~
ravenstine
[https://mermaid-js.github.io/mermaid/#/examples](https://mermaid-
js.github.io/mermaid/#/examples)

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

------
susam
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](https://github.com/susam/texme)

TeXMe Demo:
[https://opendocs.github.io/texme/examples/demo.html](https://opendocs.github.io/texme/examples/demo.html)

Detailed comparison between TeXMe and Markdeep:
[https://news.ycombinator.com/item?id=18314175](https://news.ycombinator.com/item?id=18314175)

