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.
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.
“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
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.
To be fair, I'm not sure "offline readability" is an actual problem anymore. VS Code and (presumably) other IDEs offer a very simple live-preview window for viewing and editing markdown files.
While it is true, these features seem to me to be added because Markdown is (ab)used the way it is. The issue is if you are working in an environment where it isn't possible, e.g. on a server where you only have vi/nano, and not even a TUI browser (or if you don't want to use an editor based on electron).
My issue is that you can still have a nice readme (often even giving a better, brief overview) by sticking to HTML-free Markdown.
Gitlab seems to be slightly better than Github, by allowing things like badges to be listed outside of the README, in the header of the repository page.
This always irked me as I can't read the image when trying to look at raw text and the, say build status, isn't actually relevant to understanding the project. Sourcehut has an interesting approach where you can POST any HTML to an endpoint at it becomes the homepage. You can tag on extra markup if you want in the build step and that markup doesn't have to live in the README (say badges, other images, abbreviation tags, summary/details, etc.)
To you it does but manifestly your use case doesn’t matter to the people writing these pieces of software and these readme files. They care about their audience which want different things than you. At some point you can’t expect the world to cater for you. You have to deal with the annoyances which come with doing things differently or move on with your time.
* reading documents in the terminal (like man pages)
* note taking
In both those instances the less auto-formatting that the editor does the easier it is for me to use the use the file format.
I’m sure you can say that editor auto-formatting isn’t an issue because people manage fine on MS Word. But the point is I want as little distractions as possible when not taking but I also want to be able to add headings and code snippets. So wrestling with an editor when it gets its formatting rules in a mess is the exact opposite of productively. Eg take a look at the number of authors that still use DOS editors for similar reasons.
How so? Word Documents are not made to be edited by hand. They are meant to be edited in Word. Markdown even with Mermaid is still readable and editable by hand. While I can agree Mermaid isn't my ideal markup, there are alternatives and you can even propose your own.
The examples shown in the fine article are Hello, world. The information contained within would be just as clear in vulgar prose. However the Mermaid code to create complex flowcharts that are not easily described in words, would be just as opaque as the Netscape 5 codebase.
I agree that it is no ideal, at least for my tastes, but I think what you are stating is an exaggeration. If you are using reference points like someone that knows little to nothing about technology, then just about anything different that what they are used is probably as readable as C++. For example, trying to read HTML would be the same to my grandma as trying to read C++.
Readable by humans is relative. Mermaid does not make it unreadable to some humans. Again, you are free to create an alternative that makes it more readable. Some could say that adding tables to markdown makes it unreadable. There are lot of extensions for markdown that adds features, but you have to know what they are to read them and use them. Grandma doesn't have to use Mermaid if she doesn't want to.
Which specific github flavored features violate the original spirit of markdown? I only use the basic syntax, but I don’t think I’ve run across a readme edit that hasn’t adhered to that original spirit.
I don't think GP was suggesting that there's anything specific wrong with GFM, but more that the way github encourages READMEs to be used (by auto-rendering all READMEs to HTML) creates an abstraction that shadows the readable-as-text goals of markdown.
Markdown was meant to be rendered, not left as plaintext (for viewing, at least as a primary use-case). It's name is a punny joke, but it's a lightweight markup language that was meant to be a lightweight way to write formatted text that would be rendered as formatted HTML. GFM seems in keeping with this for the most part.
> Markdown was meant to be rendered, not left as plaintext (for viewing, at least as a primary use-case). [...] meant to be a lightweight way […]
No, that was not the primary design goal.
> 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. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email.
But Mermaid code is much more readable in plaintext than a link to an image elsewhere?
I wish they wouldn't have used code blocks though - I commented on this recently about some other plugin that was doing it: usually ``` gets syntax highlighted and 'pre' formatting, but otherwise its contents is unchanged; it's unusual to execute the contents.
```python
print(42)
```
Renders
print(42)
Not
42
!
In my opinion it would've been better to use $$ as often used for mathjax, $$mermaid or something. Since it is expected that an interpretation of
$$
\code\here
$$
is rendered, rather than it itself. And if we want the code itself, we have:
```tex
\code\here
```
! How do you give an example of Mermaid code in a Readme? I'm sure they've thought of it, it can be escaped, but why? Why is it different?
The purpose of the implementation of the language may be readability, but surely the purpose of the existence of the language is to be rendered not to perpetuate its own existence...
> Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web. [1]
> 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).
Literally the first paragraph from your link. I'm having trouble reconciling that first paragraph with the idea that it wasn't meant to be rendered as HTML.
I think you're talking past each other a little. Markdown was designed to let you "write HTML using an easy-to-read, easy-to-write plain text format", and to "be publishable as-is, as plain text". Those are both explicitly stated design goals.
The argument that GitHub is abandoning the "spirit of Markdown", I surmise, is that a README file written in Markdown should be equally readable whether you're reading it as rendered HTML or not. It may be a minor quibble in some respects, but I think it's a valid minor quibble. If I open your README file in my editor, I shouldn't have to run it through external software to make it comprehensible. I mean, maybe your project has an awesome logo, but would you just drop SVG code in the middle of the README file and tell me that if I was using the proper rendering engine it wouldn't be profoundly annoying? No, of course you wouldn't, because you're not a jerk. :)
Personally, I try to use only the "reference" style of links in README files so they look like "footnotes" when read as plain text, try not to include images unless they're both supplemental and really helpful when rendered on GitHub (e.g., screenshots for editor themes), etc. Mermaid seems like it would be awesome for generating diagrams for finished pages, but it doesn't seem at all like a good fit for READMEs.
It is still readable, though. It's not like there's a base 64 encoded blob in the middle. Mermaid is reasonably comprehensible (as reasonable as any other code block, at least) without any rendering.
“A text-to-HTML conversion tool” with the “overriding design goal” of “[making] it as readable as possible”.
You wrote:
> Markdown was meant to be rendered, not left as plaintext
Then the overriding design goal would not be to make it “as readable as possible” in its “raw” form (because what would be the point of that?). So this is clearly a falsehood.
Markdown was meant to be readable as-is. Meaning that you could read it as-is or render it. At your leisure.
Also literally your words:
> was meant to be a lightweight way
With the overriding goal of making it “as readable as possible”. Keyword “override”. Which means that it takes precedence over being “lightweight”.
Then you literally wrote:
> that it wasn't meant to be rendered as HTML.
Clearly a falsehood or a strawman as I only emphasized the “overriding design goal”. Markdown was supposed to be able to be rendered as HTML… and to be readable as-is.
The part that you were wrong about was this:
> Markdown was meant to be rendered, not left as plaintext
It was designed to be readable as plaintext as well… so this assertion of yours is false since it implies that plaintext readability was not a consideration. But it was in fact the primary design goal when making the syntax.
The "easy-to-read [...] plain text format" indicates to me that the idea was that markdown should be readable in plaintext form too. The ability to convert it to HTML is a different goal?
Maybe? My point, though, is that from day 1 it was meant to be rendered as HTML. So what Github does with it (rendering README.md files) is perfectly compatible with that original intent. Just like everyone who used md->html renderers for their blogs or whatever other content.
If you just want plaintext, then you don't need markdown or any other markup. Just a plaintext file, like, I don't know, a README file. Don't throw .md (or .org in my case) on it, and it won't get rendered.
> Maybe? My point, though, is that from day 1 it was meant to be rendered as HTML.
No, from day 1 it was meant to be readable as plain text and optionally rendered as HTML
Nobody is disputing that a key requirement of MD is to be machine parseable. What you’re missing is that another key requirement is for it to be human readable in plain text because it needs to be readable even when it hasn’t been rendered. Ie the rendering is an optional step but the format has to support one’s choice whether to render.
Rendering has HTML isn't really the issue, imo. The question is rather how readable the source remains, when you foget to fold lines, insert too many images without alt texts, intersperse regular HTML, etc.
> Markdown was meant to be rendered, not left as plaintext
Now it’s not. Markdown was intend to be legible in plain text but visually emulate rendered text. The rendering stuff came later but even then it still had an emphasis on plain text readability.
There is a reason it was chosen for README, INSTALL etc documents in project repositories that are (or, at least until relatively recently in computing history, were) traditionally read in the command line.
> For months I’ve been working with John Gruber on a new project. The idea was to make writing simple web pages, and especially weblog entries, as easy as writing an email, by allowing you to use much the same syntax and converting it automatically into HTML.
Markdown is based on a really old nerd convention of stylising plain text. Things like /italics/ and *bold* predate MD by great many years. I was using some of markdown’s semantics even in the 90s.
This is what Aaron meant when he said:
> as easy as writing an email, by allowing you to use much the same syntax
…in that link you’ve posted.
Heck, even that quote token I used above (the greater than prefix) is a really old convention used in emails since probably before Aaron was even born.
It’s also worth noting that when markdown was released there were plenty of other plain text mark ups around (there’s some not even mentioned in that blog post too) but both Greg and Aaron point out that markdown is more readable in plain text and that’s a key decision behind it.
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.
> 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.
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.
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.
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.
> 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:
> 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:
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.
> 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.
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.
> 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.
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.
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
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).
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.
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.
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.