[HN Gopher] Markdeep - plain text documents with diagrams, equat...
___________________________________________________________________
Markdeep - plain text documents with diagrams, equations, and
Markdown syntax
Author : thunderbong
Score : 244 points
Date : 2020-02-17 15:11 UTC (7 hours ago)
(HTM) web link (casual-effects.com)
(TXT) w3m dump (casual-effects.com)
| chirau wrote:
| ASCII seems like a lot. Are there no simpler methods?
| ravenstine wrote:
| https://mermaid-js.github.io/mermaid/#/examples
| numbsafari wrote:
| 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.
| z3t4 wrote:
| 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.
| dylanowen wrote:
| 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
| 0xff00ffee wrote:
| 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?
| ravenstine wrote:
| 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.
| rcthompson wrote:
| 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.
| jimws wrote:
| Take a look at https://github.com/susam/texme. It does not
| introduce a new Markdown flavor. Just the regular Markdown +
| support for Latex.
| robomartin wrote:
| 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.
| willvarfar wrote:
| 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?
| rossjudson wrote:
| Every such project has to strike a balance, and the balance
| struck here looks really good to me. Nice job.
| _underfl0w_ wrote:
| 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 wrote:
| 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.
| ErotemeObelus wrote:
| This is good technology.
| jhoechtl wrote:
| 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.
| mmastrac wrote:
| "Reveal Codes" IIRC.
| awinter-py wrote:
| 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 wrote:
| autoreload every 5 seconds (usefull while editing):
| <meta http-equiv="refresh" content="5" >
| susam wrote:
| 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
| arkades wrote:
| 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.
| dnautics wrote:
| > 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.
| johnjungles wrote:
| 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.
| ggerganov wrote:
| 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/
| jimws wrote:
| > 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.
| JoshTriplett wrote:
| 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.)
| timdorr wrote:
| 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/
| Razengan wrote:
| There's also https://monodraw.helftone.com that lets you draw
| directly in ASCII.
| anigbrowl wrote:
| 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).
| tiziano88 wrote:
| http://asciiflow.com/
| rozab wrote:
| This is cool, but could benefit from some figlet-like text
| options
| sergiomattei wrote:
| 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.
| sipjca wrote:
| 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"
| mumblemumble wrote:
| 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.
| hamburglar wrote:
| 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; })
| throwGuardian wrote:
| 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
| kyllo wrote:
| 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.
| UweSchmidt wrote:
| 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.
| gregopet wrote:
| 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.
| inetknght wrote:
| > _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.
| xamde wrote:
| Diagrams with PlantUML in AsciiDoc are quite efficient. Faster
| than powerpoint.
| yoz-y wrote:
| PlantUML syntax is also a lot easier to maintain and update
| than an ascii chart which is basically a low res pixel art.
| gregmac wrote:
| 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.
| arminiusreturns wrote:
| An alternative to both I like is the blockdiag programs,
| including seqdiag, netdiag, and rackdiag. Diagrams as text that
| can be properly automated.
| arminiusreturns wrote:
| An alternative to both I like is the blockdiag programs,
| including seqdiag, netdiag, and netdiag. Diagrams as text that
| can be properly automated.
| joshvm wrote:
| 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.
| skybrian wrote:
| 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 wrote:
| As far as I understand, you can convert Markdeep to static HTML
| using rasterizer: https://github.com/romainguy/markdeep-
| rasterizer
| ivanceras wrote:
| See also https://ivanceras.github.io/svgbob-editor/
| Go0the0gophers wrote:
| Why not just use asciidoc? http://asciidoc.org/
|
| asciidoc is perfect.
| nablaoperator wrote:
| Check out Markdown Preview Enhanced
| https://shd101wyy.github.io/markdown-preview-enhanced/#/
|
| This has support for mermaid, slides etc.
| fernly wrote:
| 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 wrote:
| If you can get down with emacs, then org mode had you covered:
| https://orgmode.org/manual/Paragraphs.html
| fernly wrote:
| Thank you! I'd never heard of it. And, it's even one of the
| input formats to PanDoc. Huh.
| Finnucane wrote:
| That doesn't cover you for lines of poetry that are broken
| across lines of dialog.
| Finnucane wrote:
| 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.
| JohnHaugeland wrote:
| Where can I see a screenshot of a correct result
| pmiller2 wrote:
| See the examples in the manual for the LaTeX verse
| environment: https://rcweb.dartmouth.edu/doc/texmf-
| dist/doc/latex/verse/v...
| g8oz wrote:
| For film scripts check out Screenplay Markdown now known as
| Fountain
| databasher wrote:
| Pandoc calls these "Line blocks":
| https://pandoc.org/MANUAL.html#line-blocks
| mzs wrote:
| 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
| Giho wrote:
| 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.
| [deleted]
| tyingq wrote:
| 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.
| gravypod wrote:
| Does this index a file tree and create a document table of
| contents? I'd love to have a public version of g3docs.
| geogra4 wrote:
| This is what stops me. Where I work I need an autogenerated
| table of contents.
| gravypod wrote:
| I need TOC, search, predictable URLs, plain markdown (no
| templates, no complexity, etc), and all the features of this
| thing.
___________________________________________________________________
(page generated 2020-02-17 23:00 UTC)