5 ms·

I’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

• asiachick 5y ago
  Yes, it sucks. This is why we can't have nice things. Because a million different programmers always choose some random incompatible interpretation and then we're all stuck with it. Another similar example, all of VSCode's configuration files are called filename.json but they aren't actually json (any spec compliant json parser would barf on them). They could just have easily named them filename.jsonc (or whatever they actually are) but they didn't so we're stuck with all these .json files that json parsers won't actually parse and special hacks to validate them differently based on like if they're in a .vscode folder or if their name is some specific filename. Unfortunately there's no way to wrangle millions of programmers so we're stuck with whatever bad decisions become popular. IF that's not clear above, for example, trailing commas and comments are not allowed in JSON but they are in JSONC. You'd like your editor to highlight errors. Typically this is done by filename extension. .json = comments show as errors, .jsonc = comments OK. But VSCode named it's .jsonc files as .json so every editor that wants to be able to show if there are errors in your file now needs some random heuristic to decide how to interpret the file..... all because of a bad decision by 1 or 2 programmers that ended up being popular and now their too entrenched to fix it. The same thing is true here. ``` is supposed to mark a codeblock as in show the text as is, whitespace as is, line breaks as is. If you want to write a tutorial on how to use mermaid in markdown you'd want ``` to show the mermaid source. Use some other tag for rendering. But now where stuck with an exception and more will be added. And before you go say "there's no official spec", so what!? It's called being consistent and interpreting the contents of a ``` block is inconsistent.
  • anchpop 5y ago
    If I could have one wish, I'd replace file extensions with a hash of the spec and have someone maintain a lookup table from spec hash -> extension for rendering
    • account42 5y ago
      That prevents any possibility for progressive enhancement though as your old renderer won't know the hashes for new but still mostly compatible spec versions.
• dan-robertson 5y ago
  FWIW, you also sometimes see ```math -b \pm \sqrt{b^2 - 4ac} \over {2a} ``` So to some extent the rendering is advanced syntax highlighting. I wonder where you would draw the monospace text vs rendered line on this spectrum? JavaScript ; poem ; ’90s email ; OP ; latex math ; ditaa I guess you’d put it at the end with nothing being rendered?
• alaroldai 5y ago
  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) ``` I wish they’d adopted something like that instead - I have no idea how you’d include highlighted Mermaid source in a GH markdown file.
• qbasic_forever 5y ago
  Only the mermaid identifier is supported for triple backticks blocks, you can't put js and have it spit out script that executes in the browser.
  • tehbeard 5y ago
    You missed the point, that being; isn't triple backticks meant for whitespace preserving, highlighted in certain cases source code? And not embedding other file types.
    • qbasic_forever 5y ago
      No there's not a formal requirement or spec for how markdown blocks are rendered. Even things like syntax highlighting are optional choices different renderers make (and even the whole idea of highlighting is not specified or defined, how do you define the grammer, etc?). Some tools in the computational notebook space use markdown with fenced code blocks as blocks of executable code, see for example jupytext: https://github.com/mwouts/jupytext/blob/main/docs/formats.md https://github.com/mwouts/jupytext/blob/main/docs/formats.md or myst markdown: https://myst-parser.readthedocs.io/en/latest/syntax/syntax.html https://myst-parser.readthedocs.io/en/latest/syntax/syntax.h... or nbconvert: https://nbconvert.readthedocs.io/en/latest/ https://nbconvert.readthedocs.io/en/latest/
      • dijit 5y ago
        There is a formal spec (from github themselves) for how it’s rendered. What’s debatable is what the spec does with the “info” section. https://github.github.com/gfm/#fenced-code-blocks https://github.github.com/gfm/#fenced-code-blocks
        • qbasic_forever 5y ago
          Sure but there's no markdown spec. Markdown is purely a series of blog posts by John Gruber and a collection of different implementations. CommonMark is as close to as it's gotten to a formal spec, and even it says there is no requirement the info string (i.e. text like mermaid after backticks) be interpreted for specific rendering (or not rendering) of the content: https://spec.commonmark.org/0.28/#fenced-code-blocks https://spec.commonmark.org/0.28/#fenced-code-blocks
• mminer237 5y ago
  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}
  • sitkack 5y ago
    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?
    • rch 5y ago
      Lack of high-quality free editors was a massive problem with xml, particularly when xsd was involved.
      • sitkack 5y ago
        Yaml is now worse than the thing it was designed to replace. Rather than solve the real problem (ungood editors), we prop up and extend a janky solution.
• Ajedi32 5y ago
  Agreed; this is an annoying inconsistency. If you want to embed and render a non-Markdown file in Markdown, there's already another, far better syntax for that which is more in-line with the spirit of Markdown's "just text" philosophy: 
  • Arnavion 5y ago
    It's nice to have the diagram source in the same file that uses it, instead of a separate file that needs to be kept in sync.
    • dijit 5y ago
      Since it’s sufficiently different to how it’s rendered its really more like an SVG than a table. So, the question is would you rather have SVGs inline? Personally I think the reference to another file is a perfectly fine compromise, as the content is sufficiently different to no longer be markdown.
      • Arnavion 5y ago
        It's subjective, in my opinion. I might be fine with inline SVGs if they were "smaller", ie didn't have the doctype and root element and general XML verbosity on all nodes. PlantUML / Mermaid have a much more to-the-point syntax. Also, I personally hate markdown tables since editing even a single cell means that I likely have to then resize either the entire row or the entire column, or both. So when I do need tables I use HTML tables anyway. At any rate, a middle-ground might be to have the diagram source as references at the end of the document, and reference those from the use site, like `![Chart][#chart]` or something. So you don't have to see the diagram source inline if you don't like it, but it's still there in the same file.
      • brainfish 5y ago
        I think this is a false equivalence. The content of SVGs is non-semantic; to get from SVG code to Meaning one needs to do some sort of rendering and re-interpreting of the resulting image. Even if for some simple images that could be done in-brain, that is not usually the case. Whereas something like Mermaid is intended to be meaningful both as code and as rendered output, just like Markdown itself. Having that additional meaning inline can be very helpful to faster understanding of the content, which is not usually going to be the case for inline'd SVG.