8 ms·

I think so-called ASCII-art is more in the spirit of Markdown. The nice thing about the original Markdown (modulo bugs) is that things are written the way one

I think so-called ASCII-art is more in the spirit of Markdown. The nice thing about the original Markdown (modulo bugs) is that things are written the way one would write plaintext documents which are supposed to be easily read in a text editor. So you don’t write bullet lists like this: - Bullet 1 - Bullet 2 - Bullet 3 And hope that some post-processing will add linebreaks for you. You write it like this: - Bullet 1 - Bullet 2 - Bullet 3 Similarily there have been many tools that let you add so-called ASCII-art diagrams to Markdown documents. The spirit behind the kind of thing in the OP, on the other hand, is that one should get nicely formatted HTML from Markdown for the purpose of online consumption. Which is a very different goal. So if I were to judge the syntax itself (since that is what matters most to the original spirit of Markdown.pl) I would say that it seems pretty decent. Not as “declarative” (!) as ASCII-art, but most probably much easier to edit.

jasonlotito 5y ago
ASCII-art is generally difficult to write as denoted by the numerous tools that have been created to generate ASCII-art for markdown. ASCII-art is also much more difficult to edit after the fact. The spirit of Markdown is succinctly described on DF's Markdown project website. "Markdown allows you to write using an easy-to-read, easy-to-write plain text format." Mermaid makes it easy-to-read and easy-to-write. ASCII is easy-to-read, but hardly easy-to-write. While Mermaid isn't as nice-to-read, it's still easy-to-read. It's also much easier to modify than ASCII art. Finally, Markdown itself was designed that while the text is easy to read, Markdown itself is a conversion tool. It literally takes the text and changes it into something that is more readable. This can be seen with how Markdown handles tables. It's literally HTML table tags rather than ASCII designed tables. This is very much in the spirit of Markdown, and things like this have already been done in the original implementation.
- avgcorrection 5y ago
  > The spirit of Markdown is succinctly described on DF's Markdown project website. > "Markdown allows you to write using an easy-to-read, easy-to-write plain text format." The third/fourth person to quote the original article while failing to acknowledge this paragraph from the same article: > The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. Your quote brings up two things that might be in conflict sometimes: 1. Being easy to write 2. Being easy to read Given that the “overriding design goal” (my emphasis) is to be as “readable as possible”, it immediately follows that (2) takes precedence over (1). Which is why you assertion here: > While Mermaid isn't as nice-to-read, it's still easy-to-read. It's also much easier to modify than ASCII art. Misses the point—the original spirit is to be easy to read, and that does (by implication) take precedence over being easy to write.
dan-robertson 5y ago
I’ve had reasonable success with ditaa. If you use it in orgmode, then editing the source dumps you into artist-mode, emacs can display the image result, and you don’t need to rely on a special export process as you generate an image to be used like any other
8note 5y ago
i tend to find that asci art usually looks like a broken mess. if i was to have a graph view thats equally readable when not rendered, id want the barebones bits of graph viz's dot syntax
PinguTS 5y ago
We should not forget, that the "spirit of Markdown" is: > Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML). Inventor of Markdown https://daringfireball.net/projects/markdown/ https://daringfireball.net/projects/markdown/
- avgcorrection 5y ago
  You’re at least the third person to point to that paragraph while failing to acknowledge an important paragraph further into the article. :) > The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. So a text-to-HTML conversion to with the overriding design goal of being readable as-is… that’s the Gruberian spirit, and the basis for my original post.
Zababa 5y ago
A good example of ASCII diagrams: https://github.com/fpereiro/backendlore https://github.com/fpereiro/backendlore
rektide 5y ago
> Similarily there have been many tools that let you add so-called ASCII-art diagrams to Markdown documents. here-in is the nub. these are self contained(/embeddable?) editors of what is essentially non-textual content. there's a concealed inner data-model which is rendered/transpiled into text. i far far far far prefer a text mark up, which is easy to directly edit, which is fairly readable on it's own (imo mermaid reads very nicely). maaking the inner data model both explicit directly workable like this is ascendant beyond compare. mermaid also has predictable rendering rules, where-as there's much more author's opinion/whim about crafting ascii-diagrams, which are open ended. this makes it more predictable as a reader, with diagrams following common layout & flow patterns that one can come to expect. the other boom to mermaid is it's not that hard to parse. i have investigated how available the mermaid team makes the parser but having a relatively-simple well-specified machine readable format opens so so many doors. absolutely the right choice using human editable text markup inside human editable markdown.
- birdyrooster 5y ago
  the nub
daptaq 5y ago
The "spirit of markdown" has long been abandoned by GitHub, more often than not the offline readability of a README is absolutely ignored in exchange for a safe-HTML subset to create kind-of websites below the directory listing of a repository. It should really be called RENDERME.
- glennvtx 5y ago
  README.HTML
- PinguTS 5y ago
  Markdown has always been about "renderme". From the beginning. If you want a simple README, then do a README and not a README.md.
- Someone 5y ago
  The first paragraph of https://daringfireball.net/projects/markdown/ https://daringfireball.net/projects/markdown/: “Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).” ⇒ I think “easy to read and write” is an important, but secondary goal. The goal is to render to (X)HTML. That’s similar to how SwiftUI’s struct ContentView: View { var body: some View { Text("Hello World") } } is deemed an improvement over, for example, Java Swing’s JFrame frame = … JLabel label = new JLabel("Hello World"); frame.getContentPane().add(label); but in both cases, it’s the result that counts.
  - deleted 5y ago
    [deleted]
  - zamadatix 5y ago
    From your same link it does not say un-rendered readability was a secondary goal, it says the exact opposite: > The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. This also fits with the ordering from the second paragraph: > Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML. Markdown has always included rendering capability as a goal but I think GP is right, Markdown was never intended to be an always render first format just because it included the capability to render.
throw0101a 5y ago
> I think so-called ASCII-art is more in the spirit of Markdown. If you're simply doing a less on a file, then sure. But if you want to do a 'render' on the Markdown and convert it to another format (HTML, PDF) then having a mechanism that can translate ASCII to something graphical could be useful. In some ways this is what the DOT language does in Graphviz: * https://graphviz.org/gallery/ https://graphviz.org/gallery/ > The spirit behind the kind of thing in the OP, on the other hand, is that one should get nicely formatted HTML from Markdown for the purpose of online consumption. Which is a very different goal. I'm not sure if there's a way to have both ASCII art and it be renderable to graphics. Closest that I could find: * https://github.com/martinthomson/aasvg https://github.com/martinthomson/aasvg
- actually_a_dog 5y ago
  I saw several things that looked promising on Github: * https://github.com/ivanceras/svgbob https://github.com/ivanceras/svgbob * https://github.com/ggerganov/dot-to-ascii https://github.com/ggerganov/dot-to-ascii (renders DOT to ascii. Combine this with an SVG renderer, maybe?) * https://github.com/ivanceras/spongedown https://github.com/ivanceras/spongedown Also, this SO question: https://stackoverflow.com/questions/3211801/graphviz-and-ascii-output https://stackoverflow.com/questions/3211801/graphviz-and-asc... I'm sure there are more out there.
raman162 5y ago
I agree that ASCII-art definitely is more cenetered around the original markdown spirit but I personally struggle making my ASCII-art diagrams in Vim. Looking at the mermaid, syntax it looks like I can whip up something equivalent really quick. As a developer I also don't mind that the mermaid syntax reads like pseudocode so it's probably easy for me to digest.
- dan-robertson 5y ago
  Not a great answer: if you use evil-mode for emacs (eg with doom-emacs or spacemacs) you get picture-mode which can make ascii art a bit easier, and artist-mode which gives you point-and-click (or move-and-press-enter) ascii art drawing.
- tasty_freeze 5y ago
  One thing that might help is using ":set virtualedit=all". This makes all lines act as if there are unlimited spaces at the end of line. That means you can move anywhere on the screen by cursor or by clicking with your mouse, etc, and not have to worry about typing in all the padding yourself. Once you place a character at column N, it will insert spaces up to column N-1 then place the new character.
  - raman162 5y ago
    This is cool, didn't know about that, will try that out next time.
moolcool 5y ago
To that point, ASCIIFlow is an amazing tool which I use constantly when working on markdown files https://asciiflow.com/#/ https://asciiflow.com/#/
- llimllib 5y ago
  I used it yesterday and really wished it supported dashed lines!
- Steltek 5y ago
  Behaves like it's Chrome only? Gonna have to pass on that one. Or maybe MacOS only? I dunno. Definitely doesn't feel snappy and certain things just don't work.
- mafro 5y ago
  Nice tip! I use Monodraw which is macOS only
- enzanki_ars 5y ago
  ASCIIFlow is less accessible than Mermaid though for folks that use screen readers. Mermaid can be read as is from the source, or be transformed into a readable format for screen readers, but ASCIIFlow has no such mechanism to translate it into a format that can be accessible.
corysama 5y ago
http://casual-effects.com/markdeep/ http://casual-effects.com/markdeep/ has had ASCII-art-as-vector-image features for quite some time now. It's in need of a good editor, though.
berkes 5y ago
While I agree, formatting languages like Mermaid or PlantUML are human readable enough to grasp them and their meaning from reading the textual form. And, as others below point out, editability is another great treat of Markdown. ASCII charts are very hard to format; you'll really need tools or editor plugins for that. So I think that Mermaid (and PlantUML) strike a very pragmatic and human-friendly balance. Which, IMO is the actual spirit of Markdown.
- Steltek 5y ago
  > ASCII charts are very hard to format; you'll really need tools or editor plugins for that. Even with tools and plugins, creating tables in Markdown (in any flavor) is painful enough that I just don't even try. No one really expects to edit an image with a text editor but tables are tantalizing close. I'd sooner have ASCII inspired tables that are easier to edit than images and diagrams.
  - IggleSniggle 5y ago
    I do tables, but I will admit to having them auto-formatted on save. That is, I type a pipe separated list manually, and auto-space it on save.
    - anchpop 5y ago
      IIRC vscode does this by default, definitely a really handy feature
runarberg 5y ago
Shameless plug. I wrote a math authoring tool Mathup[1] with that purpose in mind. That you could author math really easily which would also be easy to read in plaintext. You could write things like 1+2 / 3+4 which you would be rendered as you would expect, or you could write your matrices like A = [a, b; c, d]. My main reason for writing it was for inclusion in markdown documents. https://runarberg.github.io/mathup/ https://runarberg.github.io/mathup/
yu-carm-kror 5y ago
If I need something to look good as text without any rendering I write text (a .txt file). Even the most basic features of markdown (inline code, italics, etc) look pretty nasty without post rendering.
- OJFord 5y ago
  I strongly disagree with that, they're about as clear and unintrusive as I can imagine, what else would you do? Personally _I_ even sometimes use them when markdown isn't available, as in won't be rendered.
prpl 5y ago
There is also https://github.com/asciitosvg/asciitosvg https://github.com/asciitosvg/asciitosvg Used in zeromq docs.

jasonlotito 5y ago

ASCII-art is generally difficult to write as denoted by the numerous tools that have been created to generate ASCII-art for markdown. ASCII-art is also much more difficult to edit after the fact. The spirit of Markdown is succinctly described on DF's Markdown project website. "Markdown allows you to write using an easy-to-read, easy-to-write plain text format." Mermaid makes it easy-to-read and easy-to-write. ASCII is easy-to-read, but hardly easy-to-write. While Mermaid isn't as nice-to-read, it's still easy-to-read. It's also much easier to modify than ASCII art. Finally, Markdown itself was designed that while the text is easy to read, Markdown itself is a conversion tool. It literally takes the text and changes it into something that is more readable. This can be seen with how Markdown handles tables. It's literally HTML table tags rather than ASCII designed tables. This is very much in the spirit of Markdown, and things like this have already been done in the original implementation.

avgcorrection 5y ago
> The spirit of Markdown is succinctly described on DF's Markdown project website. > "Markdown allows you to write using an easy-to-read, easy-to-write plain text format." The third/fourth person to quote the original article while failing to acknowledge this paragraph from the same article: > The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. Your quote brings up two things that might be in conflict sometimes: 1. Being easy to write 2. Being easy to read Given that the “overriding design goal” (my emphasis) is to be as “readable as possible”, it immediately follows that (2) takes precedence over (1). Which is why you assertion here: > While Mermaid isn't as nice-to-read, it's still easy-to-read. It's also much easier to modify than ASCII art. Misses the point—the original spirit is to be easy to read, and that does (by implication) take precedence over being easy to write.

dan-robertson 5y ago

I’ve had reasonable success with ditaa. If you use it in orgmode, then editing the source dumps you into artist-mode, emacs can display the image result, and you don’t need to rely on a special export process as you generate an image to be used like any other

8note 5y ago

i tend to find that asci art usually looks like a broken mess. if i was to have a graph view thats equally readable when not rendered, id want the barebones bits of graph viz's dot syntax

PinguTS 5y ago

We should not forget, that the "spirit of Markdown" is: > Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML). Inventor of Markdown https://daringfireball.net/projects/markdown/ https://daringfireball.net/projects/markdown/

avgcorrection 5y ago
You’re at least the third person to point to that paragraph while failing to acknowledge an important paragraph further into the article. :) > The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. So a text-to-HTML conversion to with the overriding design goal of being readable as-is… that’s the Gruberian spirit, and the basis for my original post.

Zababa 5y ago

A good example of ASCII diagrams: https://github.com/fpereiro/backendlore https://github.com/fpereiro/backendlore

rektide 5y ago

> Similarily there have been many tools that let you add so-called ASCII-art diagrams to Markdown documents. here-in is the nub. these are self contained(/embeddable?) editors of what is essentially non-textual content. there's a concealed inner data-model which is rendered/transpiled into text. i far far far far prefer a text mark up, which is easy to directly edit, which is fairly readable on it's own (imo mermaid reads very nicely). maaking the inner data model both explicit directly workable like this is ascendant beyond compare. mermaid also has predictable rendering rules, where-as there's much more author's opinion/whim about crafting ascii-diagrams, which are open ended. this makes it more predictable as a reader, with diagrams following common layout & flow patterns that one can come to expect. the other boom to mermaid is it's not that hard to parse. i have investigated how available the mermaid team makes the parser but having a relatively-simple well-specified machine readable format opens so so many doors. absolutely the right choice using human editable text markup inside human editable markdown.

birdyrooster 5y ago
the nub

daptaq 5y ago

The "spirit of markdown" has long been abandoned by GitHub, more often than not the offline readability of a README is absolutely ignored in exchange for a safe-HTML subset to create kind-of websites below the directory listing of a repository. It should really be called RENDERME.

glennvtx 5y ago
README.HTML
PinguTS 5y ago
Markdown has always been about "renderme". From the beginning. If you want a simple README, then do a README and not a README.md.
Someone 5y ago
The first paragraph of https://daringfireball.net/projects/markdown/ https://daringfireball.net/projects/markdown/: “Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML).” ⇒ I think “easy to read and write” is an important, but secondary goal. The goal is to render to (X)HTML. That’s similar to how SwiftUI’s struct ContentView: View { var body: some View { Text("Hello World") } } is deemed an improvement over, for example, Java Swing’s JFrame frame = … JLabel label = new JLabel("Hello World"); frame.getContentPane().add(label); but in both cases, it’s the result that counts.
- deleted 5y ago
  [deleted]
- zamadatix 5y ago
  From your same link it does not say un-rendered readability was a secondary goal, it says the exact opposite: > The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. This also fits with the ordering from the second paragraph: > Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, written in Perl, that converts the plain text formatting to HTML. Markdown has always included rendering capability as a goal but I think GP is right, Markdown was never intended to be an always render first format just because it included the capability to render.

throw0101a 5y ago

> I think so-called ASCII-art is more in the spirit of Markdown. If you're simply doing a less on a file, then sure. But if you want to do a 'render' on the Markdown and convert it to another format (HTML, PDF) then having a mechanism that can translate ASCII to something graphical could be useful. In some ways this is what the DOT language does in Graphviz: * https://graphviz.org/gallery/ https://graphviz.org/gallery/ > The spirit behind the kind of thing in the OP, on the other hand, is that one should get nicely formatted HTML from Markdown for the purpose of online consumption. Which is a very different goal. I'm not sure if there's a way to have both ASCII art and it be renderable to graphics. Closest that I could find: * https://github.com/martinthomson/aasvg https://github.com/martinthomson/aasvg

actually_a_dog 5y ago
I saw several things that looked promising on Github: * https://github.com/ivanceras/svgbob https://github.com/ivanceras/svgbob * https://github.com/ggerganov/dot-to-ascii https://github.com/ggerganov/dot-to-ascii (renders DOT to ascii. Combine this with an SVG renderer, maybe?) * https://github.com/ivanceras/spongedown https://github.com/ivanceras/spongedown Also, this SO question: https://stackoverflow.com/questions/3211801/graphviz-and-ascii-output https://stackoverflow.com/questions/3211801/graphviz-and-asc... I'm sure there are more out there.

raman162 5y ago

I agree that ASCII-art definitely is more cenetered around the original markdown spirit but I personally struggle making my ASCII-art diagrams in Vim. Looking at the mermaid, syntax it looks like I can whip up something equivalent really quick. As a developer I also don't mind that the mermaid syntax reads like pseudocode so it's probably easy for me to digest.

dan-robertson 5y ago
Not a great answer: if you use evil-mode for emacs (eg with doom-emacs or spacemacs) you get picture-mode which can make ascii art a bit easier, and artist-mode which gives you point-and-click (or move-and-press-enter) ascii art drawing.
tasty_freeze 5y ago
One thing that might help is using ":set virtualedit=all". This makes all lines act as if there are unlimited spaces at the end of line. That means you can move anywhere on the screen by cursor or by clicking with your mouse, etc, and not have to worry about typing in all the padding yourself. Once you place a character at column N, it will insert spaces up to column N-1 then place the new character.
- raman162 5y ago
  This is cool, didn't know about that, will try that out next time.

moolcool 5y ago

To that point, ASCIIFlow is an amazing tool which I use constantly when working on markdown files https://asciiflow.com/#/ https://asciiflow.com/#/

llimllib 5y ago
I used it yesterday and really wished it supported dashed lines!
Steltek 5y ago
Behaves like it's Chrome only? Gonna have to pass on that one. Or maybe MacOS only? I dunno. Definitely doesn't feel snappy and certain things just don't work.
mafro 5y ago
Nice tip! I use Monodraw which is macOS only
enzanki_ars 5y ago
ASCIIFlow is less accessible than Mermaid though for folks that use screen readers. Mermaid can be read as is from the source, or be transformed into a readable format for screen readers, but ASCIIFlow has no such mechanism to translate it into a format that can be accessible.

corysama 5y ago

http://casual-effects.com/markdeep/ http://casual-effects.com/markdeep/ has had ASCII-art-as-vector-image features for quite some time now. It's in need of a good editor, though.

berkes 5y ago

While I agree, formatting languages like Mermaid or PlantUML are human readable enough to grasp them and their meaning from reading the textual form. And, as others below point out, editability is another great treat of Markdown. ASCII charts are very hard to format; you'll really need tools or editor plugins for that. So I think that Mermaid (and PlantUML) strike a very pragmatic and human-friendly balance. Which, IMO is the actual spirit of Markdown.

Steltek 5y ago
> ASCII charts are very hard to format; you'll really need tools or editor plugins for that. Even with tools and plugins, creating tables in Markdown (in any flavor) is painful enough that I just don't even try. No one really expects to edit an image with a text editor but tables are tantalizing close. I'd sooner have ASCII inspired tables that are easier to edit than images and diagrams.
- IggleSniggle 5y ago
  I do tables, but I will admit to having them auto-formatted on save. That is, I type a pipe separated list manually, and auto-space it on save.
  - anchpop 5y ago
    IIRC vscode does this by default, definitely a really handy feature

runarberg 5y ago

Shameless plug. I wrote a math authoring tool Mathup[1] with that purpose in mind. That you could author math really easily which would also be easy to read in plaintext. You could write things like 1+2 / 3+4 which you would be rendered as you would expect, or you could write your matrices like A = [a, b; c, d]. My main reason for writing it was for inclusion in markdown documents. https://runarberg.github.io/mathup/ https://runarberg.github.io/mathup/

yu-carm-kror 5y ago

If I need something to look good as text without any rendering I write text (a .txt file). Even the most basic features of markdown (inline code, italics, etc) look pretty nasty without post rendering.

OJFord 5y ago
I strongly disagree with that, they're about as clear and unintrusive as I can imagine, what else would you do? Personally _I_ even sometimes use them when markdown isn't available, as in won't be rendered.

prpl 5y ago

There is also https://github.com/asciitosvg/asciitosvg https://github.com/asciitosvg/asciitosvg Used in zeromq docs.