Such a pity to have a hodgepodge of markdown plus custom extensions.
Include diagrams in your Markdown files with Mermaid
171–180 of 272 posts
Re: Include diagrams in your Markdown files with Mermaid
#172Earlier quoted context omitted.
I agree. R Markdown has R code execution as part of it's Markdown flavor and it distinguishes code block vs code execution as ```R vs ```{R}
It feels like Markdown and Jupyter notebooks in on the path to merging, and markdown is like the dumbed (need a different word for this, simplicated (though that that word is cumbersome)) down yaml which is a simplicated xml. Why don't we just go back to xml and provide decent structured editors?
Lack of high-quality free editors was a massive problem with xml, particularly when xsd was involved.
Re: Include diagrams in your Markdown files with Mermaid
#173I’m super excited for this! One thought though, on the syntax. Wouldn’t it be a bit odd if suddenly this line in a README.md: ```js const foo = 1 + 1 ``` Rendered as: `2` ? Isn’t that kind of what we’re doing here with the mermaid source tag? That tag is for showing source code, no? Feels like there should be another tag for rendering it.
FWIW, you also sometimes see
```math
-b \pm \sqrt{b^2 - 4ac} \over {2a}
```
JavaScript ; poem ; ’90s email ; OP ; latex math ; ditaa
Re: Include diagrams in your Markdown files with Mermaid
#174Earlier quoted context omitted.
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, I…
> 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 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.
Re: Include diagrams in your Markdown files with Mermaid
#175I 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…
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.
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.
Re: Include diagrams in your Markdown files with Mermaid
#176I’m super excited for this! One thought though, on the syntax. Wouldn’t it be a bit odd if suddenly this line in a README.md: ```js const foo = 1 + 1 ``` Rendered as: `2` ? Isn’t that kind of what we’re doing here with the mermaid source tag? That tag is for showing source code, no? Feels like there should be another tag for rendering it.
I’ve actually been using an almost identical filter for GraphViz markup in my university papers for the last year, except I added a leading exclamation point to the language tag to distinguish between included source and included markup:
```!dot
(Markup)
```
Re: Include diagrams in your Markdown files with Mermaid
#177I 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…
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
Re: Include diagrams in your Markdown files with Mermaid
#178Earlier quoted context omitted.
> 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 mark up 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…
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]
[1] https://daringfireball.net/projects/markdown/syntax#html
Re: Include diagrams in your Markdown files with Mermaid
#179Honestly, Friday deploys are the best deploys. You’re extra motivated to get things out, fewer people will be around to complain if things are going wrong (at least if you mostly make money in the week) and you want to go home so you’re motivated to just do it efficiently instead of hesitating. There is a risk of rolling bugs on the weekend but there’s also a risk of having to spend your Mondays fixing twice as many (on average) bugs from bad rolls as well as other issues that may have been discovered on the weekend. The best trick for deploying on Fridays is to not write bugs, write software that is easy to roll back, and/or spend your weekend away from any kind of mobile signal.
Re: Include diagrams in your Markdown files with Mermaid
#180Earlier quoted context omitted.
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.
We need to go back to something like Word documents. We’ve come full circle
README.docx