4 ms·

Certainly not holding me back. I can go from crappy notes on a notepad to a polished and branded PDF release including TOC, tables, images and formulas, info/wa

by tedggh 11mo ago

Certainly not holding me back. I can go from crappy notes on a notepad to a polished and branded PDF release including TOC, tables, images and formulas, info/warning boxes, lists, code snippets with syntax highlighting, header/footer, etc in literally minutes. What else do you need?

Mikhail_Edoshin 11mo ago
Example: I want to explain the role of various files in the development directory. I start with a couple files; then I describe a command that creates a third file. And then I do this several more times, filling up the directory. It wold be nice to show the starting list of files, a command, and the resulting list of files. It would also be nice to maybe color-code source and target files for each step, both in the command and in the listing. It may also help to typographically distinquish base files that are written by hand and generated ones. A few pictograms to tell apart files and directories would also be useful. And it would be nice to somehow keep this a single process so that a command references a source state and produces the target state and the list of files is computed automatically. (Doing this right now with XML and XSLT, targeting PDF via XSL-FO. Drew pictograms in SVG right in the XSLT. Haven't got to the automatic part yet, just got an idea that this is a natural way to go.)
josephg 11mo ago
What else? I want figures. I want linked references. I want custom styling for images, and for blocks of text (eg warnings, notes, etc). I want a TOC and numbered chapters and sections. Sometimes I want a bibliography. Or a table generated from data within a JSON file. You don't need this stuff for a readme file. But IMO markdown isn't powerful enough for blog posts, documentation or longer form content.
- sallveburrpi 11mo ago
  I use docusaurus as markdown renderer which adds most of what you need. Mermaid.js for figures. Never needed a data table from JSON but would be easy to add a custom component for this. So yes for me markdown is definitely powerful enough for blogging and complex technical writing - has been for the last 6 years- with a few small extensions and I’ll eat my hat before I use anything xml based or reinvent html…
  - josephg 11mo ago
    I hear you, but to be clear - you're not using markdown any more. A quick look at the docusaurus website suggests it uses MDX, which explicitly does not support commonmark. MDX documents cannot be rendered with other markdown renderers. And normal markdown text can also be incompatible with mdx. If markdown were actually good enough, you wouldn't be reaching for bespoke extensions to markdown to make it more capable.
- MrWB 11mo ago
  Have you looked at Quarto?
  - josephg 11mo ago
    No. Should I? It looks like a markdown renderer with a huge pile of custom extensions. It looks like they've added support for some of the things I need (eg references). But not other stuff. It has hardcoded block support for Note and Warning. But it looks like I can't program my own? It supports front matter, but only in a few predefined styles? And it looks like I can't define my own rendering / styling for image blocks? Like, if I want to make images clickable and be shown full screen, I can't do it using quarto? Like I said in another comment, if you're writing a markdown-like document that can only be rendered properly in one bespoke tool, you're not writing in actual markdown any more. Like if I had my own C compiler with a bunch of custom extensions, code written which uses all of those extensions isn't really C code. With actual markdown, you can send people the markdown content itself and they can render it locally using whatever tool they like. Use a tool like quarto if you want. But the need for something like this proves the point that markdown on its own isn't sufficient. If you're reaching for a markdown-incompatible document format, why stick with markdown at all, and not React, or ascii doctor, or typst?

by tedggh 11mo ago

Mikhail_Edoshin 11mo ago

Example: I want to explain the role of various files in the development directory. I start with a couple files; then I describe a command that creates a third file. And then I do this several more times, filling up the directory. It wold be nice to show the starting list of files, a command, and the resulting list of files. It would also be nice to maybe color-code source and target files for each step, both in the command and in the listing. It may also help to typographically distinquish base files that are written by hand and generated ones. A few pictograms to tell apart files and directories would also be useful. And it would be nice to somehow keep this a single process so that a command references a source state and produces the target state and the list of files is computed automatically. (Doing this right now with XML and XSLT, targeting PDF via XSL-FO. Drew pictograms in SVG right in the XSLT. Haven't got to the automatic part yet, just got an idea that this is a natural way to go.)

josephg 11mo ago

What else? I want figures. I want linked references. I want custom styling for images, and for blocks of text (eg warnings, notes, etc). I want a TOC and numbered chapters and sections. Sometimes I want a bibliography. Or a table generated from data within a JSON file. You don't need this stuff for a readme file. But IMO markdown isn't powerful enough for blog posts, documentation or longer form content.

sallveburrpi 11mo ago
I use docusaurus as markdown renderer which adds most of what you need. Mermaid.js for figures. Never needed a data table from JSON but would be easy to add a custom component for this. So yes for me markdown is definitely powerful enough for blogging and complex technical writing - has been for the last 6 years- with a few small extensions and I’ll eat my hat before I use anything xml based or reinvent html…
- josephg 11mo ago
  I hear you, but to be clear - you're not using markdown any more. A quick look at the docusaurus website suggests it uses MDX, which explicitly does not support commonmark. MDX documents cannot be rendered with other markdown renderers. And normal markdown text can also be incompatible with mdx. If markdown were actually good enough, you wouldn't be reaching for bespoke extensions to markdown to make it more capable.
MrWB 11mo ago
Have you looked at Quarto?
- josephg 11mo ago
  No. Should I? It looks like a markdown renderer with a huge pile of custom extensions. It looks like they've added support for some of the things I need (eg references). But not other stuff. It has hardcoded block support for Note and Warning. But it looks like I can't program my own? It supports front matter, but only in a few predefined styles? And it looks like I can't define my own rendering / styling for image blocks? Like, if I want to make images clickable and be shown full screen, I can't do it using quarto? Like I said in another comment, if you're writing a markdown-like document that can only be rendered properly in one bespoke tool, you're not writing in actual markdown any more. Like if I had my own C compiler with a bunch of custom extensions, code written which uses all of those extensions isn't really C code. With actual markdown, you can send people the markdown content itself and they can render it locally using whatever tool they like. Use a tool like quarto if you want. But the need for something like this proves the point that markdown on its own isn't sufficient. If you're reaching for a markdown-incompatible document format, why stick with markdown at all, and not React, or ascii doctor, or typst?