6 ms·

No! Markdown is made to be simple. Don’t use it for complex projects. Use properly thought out markup languages for that, like Asciidoc.

pbronez 2y ago
Thanks for the reminder about Asciidoc! A few years ago I dug into various markup languages looking for a better way to draft legal documents. Asciidoc was the best balance of power & simplicity. Unfortunately the ecosystem was pretty weak. In subsequent years there has been an effort to standardize the spec, which should unlock better tooling. I need to check in on that…
- pbronez 2y ago
  They’re still working on the spec. Last release was five months ago. So, slow progress continues. https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-la https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-la... Here are the minutes from the last working group meeting, back in Feb. looks like they’ll meet again in September https://docs.google.com/document/u/0/d/1eqB2w5pungP2vxiF_DeM4hlOmklor9h_WL_sfmd6L0U/mobilebasic https://docs.google.com/document/u/0/d/1eqB2w5pungP2vxiF_DeM...
- tcfhgj 2y ago
  Have you checked out Typst? I have tried ASCII doc and haven't really enjoyed it. Typst on the other hand is simple, fast, powerful and ergonomic at the same time.
  - KingMob 2y ago
    At a glance, Typst looks more like a competitor to Latex, not Markdown/Asciidoc/rST.
    - setopt 2y ago
      Typst is trying to take on LaTeX: high-quality PDF output, equation typesetting, citation and reference systems, programmability, etc. But if you look closer, the actual syntax of Typst is clearly a mix of MarkDown and AsciiDoc (e.g. code blocks and lists work like MarkDown, while headers work like AsciiDoc, and I think the math syntax is to some degree inspired by AsciiMath from the AsciiDoc ecosystem). As someone who mainly uses MarkDown to author PDFs, I find Typst to be a clear competitor to Markdown/AsciiDoc/Org as well as TeX. I think they're working on basic Typst support for Pandoc, in which case you might soon be able to generate HTML with it too.
      - stephenr 2y ago
        What's your markdown to pdf tool(s) of choice?
        setopt 2y ago
        The king in this space is Pandoc. It supports most things you might need in "serious" documents: figures, tables, equations, references, citations, etc. You can even customize the TeX export template if you need more control over the output. And if you need to later, you can easily re-export the same document to TeX, DOCX, or HTML. Lately, I've also been using Quarto a bit. The default export is HTML but it also supports PDF. It's nice if you're into "literate programming", where you write code blocks (e.g. Python snippets) in a MarkDown file, and those code blocks are automatically used to generate figures, tables, etc. in your MarkDown file on export. If you want something that "just works" and are not averse to commercial apps, I can recommend giving "iA Writer" a shot. It has a built-in preview and export solution that is lightning fast and has good support for equations. But I wouldn't use its export for anything important, as the output is clearly draft quality, and the MarkDown support lacks features like citations. (Though it supports footnotes, so for informal documents you can abuse that for citations.)
  - pbronez 2y ago
    Yes, but it's probably worth another look as my use cases have shifted around. I'm 1000% not interested in signing up for their SaaS (corporate data security concerns) but I see that they have an open source CLI [0] so maybe I'll try that. Also, looks like they offer a self-hosted enterprise offering now, which is intriguing. My use cases include: - Drafting, reviewing and iterating over legal documents, especially contracts - Technical and business process documentation - Long-form, print-friendly report generation, including data visualization, tables and images [0] https://github.com/typst/typst https://github.com/typst/typst
    - setopt 2y ago
      The open-source CLI is indeed all you need. On Mac, I could just do `brew install typst` to get the compiler, and then run it on a local `*.typ` file. I'm sure there are packages available for most Linux distributions as well by now.
hoosieree 2y ago
I wonder about the other direction - how much can you remove from Markdown until it's no longer useful enough for wide adoption? How about: one heading level only no nesting (of lists or styles) tables can only contain plain text (not even links!) either indented or fenced code blocks, but not both But keep the html escape hatch. If anyone needs one of the missing features, they can drop down to html. Just a bit more friction.
- WA 2y ago
  Remove img support. Its severely lacking anyways. Most images need more meta data such as sizes, but also modern images are responsive with different resolutions etc.
- christophilus 2y ago
  I recently made a markdown parser that is essentially this. It runs my blog. My table parser is non-standard, though, as I hate typing up markdown tables. Instead, I’m using a special code block “gen:table” and I just type up a whitespace-aligned table. The raw markdown table ends up looking like a table even with standard markdown processors since it just renders as an unknown code block.
  - hoosieree 2y ago
    Tables can be very nice to work with in a text editor with some convenience features like automatic alignment and tab-to-next-cell. At least that's my experience using tables in emacs with org-mode files. But I imagine there's quite a lot going on behind the scenes to make that work, plus there's some inflexible syntax used to recognize when your cursor is in a table. But I like your approach of leveraging monospace fonts to work as informal tables.
- woodrowbarlow 2y ago
  gemtext (the native presentation format for gemini capsules) is a markdown-like language which only uses the first three characters of each line to determine the presentation mode for that line. it's designed so that it's trivial to create a renderer, even on retro 8-bit computers (determine presentation mode, set up the font, then just dump the buffer until you hit a newline). it supports paragraphs, headings (3 levels), links (not inline with text, must be on its own line), lists (unordered), blockquotes, and preformatted text. there is zero inline formatting (not even a way to emphasize words in a paragraph). https://gemini.flounder.online/docs/gemtext.gmi https://gemini.flounder.online/docs/gemtext.gmi
deleted 2y ago
[deleted]
amelius 2y ago
I wonder if we can replace Markdown by an LLM entirely. Just tell it what you want and how it should look in natural English, and then use that as your source file.
- deleted 2y ago
  [deleted]
- xienze 2y ago
  You would need LLM output to be deterministic first (i.e., given the same set of English instructions, you get the exact same output every time). And that’s not even getting into the inherent problems with the nuances of natural language. For something like this you really do need a tailor-made language suited to the task.
  - amelius 2y ago
    DL libraries like pytorch are completely deterministic.
- v3ss0n 2y ago
  Now you need high end nvidia GPU just to render text ...

pbronez 2y ago

Thanks for the reminder about Asciidoc! A few years ago I dug into various markup languages looking for a better way to draft legal documents. Asciidoc was the best balance of power & simplicity. Unfortunately the ecosystem was pretty weak. In subsequent years there has been an effort to standardize the spec, which should unlock better tooling. I need to check in on that…

pbronez 2y ago
They’re still working on the spec. Last release was five months ago. So, slow progress continues. https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-la https://gitlab.eclipse.org/eclipse/asciidoc-lang/asciidoc-la... Here are the minutes from the last working group meeting, back in Feb. looks like they’ll meet again in September https://docs.google.com/document/u/0/d/1eqB2w5pungP2vxiF_DeM4hlOmklor9h_WL_sfmd6L0U/mobilebasic https://docs.google.com/document/u/0/d/1eqB2w5pungP2vxiF_DeM...
tcfhgj 2y ago
Have you checked out Typst? I have tried ASCII doc and haven't really enjoyed it. Typst on the other hand is simple, fast, powerful and ergonomic at the same time.
- KingMob 2y ago
  At a glance, Typst looks more like a competitor to Latex, not Markdown/Asciidoc/rST.
  - setopt 2y ago
    Typst is trying to take on LaTeX: high-quality PDF output, equation typesetting, citation and reference systems, programmability, etc. But if you look closer, the actual syntax of Typst is clearly a mix of MarkDown and AsciiDoc (e.g. code blocks and lists work like MarkDown, while headers work like AsciiDoc, and I think the math syntax is to some degree inspired by AsciiMath from the AsciiDoc ecosystem). As someone who mainly uses MarkDown to author PDFs, I find Typst to be a clear competitor to Markdown/AsciiDoc/Org as well as TeX. I think they're working on basic Typst support for Pandoc, in which case you might soon be able to generate HTML with it too.
    - stephenr 2y ago
      What's your markdown to pdf tool(s) of choice?
      - setopt 2y ago
        The king in this space is Pandoc. It supports most things you might need in "serious" documents: figures, tables, equations, references, citations, etc. You can even customize the TeX export template if you need more control over the output. And if you need to later, you can easily re-export the same document to TeX, DOCX, or HTML. Lately, I've also been using Quarto a bit. The default export is HTML but it also supports PDF. It's nice if you're into "literate programming", where you write code blocks (e.g. Python snippets) in a MarkDown file, and those code blocks are automatically used to generate figures, tables, etc. in your MarkDown file on export. If you want something that "just works" and are not averse to commercial apps, I can recommend giving "iA Writer" a shot. It has a built-in preview and export solution that is lightning fast and has good support for equations. But I wouldn't use its export for anything important, as the output is clearly draft quality, and the MarkDown support lacks features like citations. (Though it supports footnotes, so for informal documents you can abuse that for citations.)
- pbronez 2y ago
  Yes, but it's probably worth another look as my use cases have shifted around. I'm 1000% not interested in signing up for their SaaS (corporate data security concerns) but I see that they have an open source CLI [0] so maybe I'll try that. Also, looks like they offer a self-hosted enterprise offering now, which is intriguing. My use cases include: - Drafting, reviewing and iterating over legal documents, especially contracts - Technical and business process documentation - Long-form, print-friendly report generation, including data visualization, tables and images [0] https://github.com/typst/typst https://github.com/typst/typst
  - setopt 2y ago
    The open-source CLI is indeed all you need. On Mac, I could just do `brew install typst` to get the compiler, and then run it on a local `*.typ` file. I'm sure there are packages available for most Linux distributions as well by now.

hoosieree 2y ago

I wonder about the other direction - how much can you remove from Markdown until it's no longer useful enough for wide adoption? How about: one heading level only no nesting (of lists or styles) tables can only contain plain text (not even links!) either indented or fenced code blocks, but not both But keep the html escape hatch. If anyone needs one of the missing features, they can drop down to html. Just a bit more friction.

WA 2y ago
Remove img support. Its severely lacking anyways. Most images need more meta data such as sizes, but also modern images are responsive with different resolutions etc.
christophilus 2y ago
I recently made a markdown parser that is essentially this. It runs my blog. My table parser is non-standard, though, as I hate typing up markdown tables. Instead, I’m using a special code block “gen:table” and I just type up a whitespace-aligned table. The raw markdown table ends up looking like a table even with standard markdown processors since it just renders as an unknown code block.
- hoosieree 2y ago
  Tables can be very nice to work with in a text editor with some convenience features like automatic alignment and tab-to-next-cell. At least that's my experience using tables in emacs with org-mode files. But I imagine there's quite a lot going on behind the scenes to make that work, plus there's some inflexible syntax used to recognize when your cursor is in a table. But I like your approach of leveraging monospace fonts to work as informal tables.
woodrowbarlow 2y ago
gemtext (the native presentation format for gemini capsules) is a markdown-like language which only uses the first three characters of each line to determine the presentation mode for that line. it's designed so that it's trivial to create a renderer, even on retro 8-bit computers (determine presentation mode, set up the font, then just dump the buffer until you hit a newline). it supports paragraphs, headings (3 levels), links (not inline with text, must be on its own line), lists (unordered), blockquotes, and preformatted text. there is zero inline formatting (not even a way to emphasize words in a paragraph). https://gemini.flounder.online/docs/gemtext.gmi https://gemini.flounder.online/docs/gemtext.gmi

deleted 2y ago

[deleted]

amelius 2y ago

I wonder if we can replace Markdown by an LLM entirely. Just tell it what you want and how it should look in natural English, and then use that as your source file.

deleted 2y ago
[deleted]
xienze 2y ago
You would need LLM output to be deterministic first (i.e., given the same set of English instructions, you get the exact same output every time). And that’s not even getting into the inherent problems with the nuances of natural language. For something like this you really do need a tailor-made language suited to the task.
- amelius 2y ago
  DL libraries like pytorch are completely deterministic.
v3ss0n 2y ago
Now you need high end nvidia GPU just to render text ...