The paper makes the point that people keep extending Markdown, badly and incompatibly.
Markdown is holding you back
21–30 of 194 posts
Re: Markdown is holding you back
#22This is a timely topic for me. I'm just beginning the writing of a technical book. I plan to target epub/mobi. My research thus far has pointed to markdown -> html -> epub/mobi. If you were going to write a technical ebook would you use markdown or an alternative?
What about markdown do you feel limits you in your writing process? The beauty of markdown is that it’s standardized. If you find your self midway through the book and feel a need to change formats, it’s easy enough to parse and reformat.
Nothing! I was asking from the point of you that you don't know what you don't know.
Re: Markdown is holding you back
#23I would like to point out that asciidork provides ability to get AST representation of asciidoc. It’s very nice package. Not the author but have used it.
Re: Markdown is holding you back
#24Org is pretty good.
Re: Markdown is holding you back
#25Markdown is the minimum viable product. It’s easy to learn and still readable if not rendered in an alternate format. It’s great. For making PDFs, I’ve recently moved from AsciiDoc to Typst. I couldn’t find a good way to get AsciiDoc to make accessible PDFs, and I found myself struggling to control the output. Typst solves all of AsciiDoc’s problems for me. But in the end, no markup language will make you write bette…
typst looks interesting -- but how are you writing it? from what I looked at, it looks like theres an official web editor and a vscode plugin with limited support. this feels pretty limited, as someone who came in expecting something like obsidian.
I'm not aware of any limitations in the Tinymist plugin.
And you can just write it in the plain text editor of your choice, and keep an eye on the PDF with typst watch.
Re: Markdown is holding you back
#26The other options look like garbage tho
Re: Markdown is holding you back
#27Feels like a great argument...for, I don't know, a bunch of moderately technical high-schoolers who were somehow raised on markdown instead of Microsoft Word and want more power?
No, seriously, who is this for?
Re: Markdown is holding you back
#28This is a timely topic for me. I'm just beginning the writing of a technical book. I plan to target epub/mobi. My research thus far has pointed to markdown -> html -> epub/mobi. If you were going to write a technical ebook would you use markdown or an alternative?
You might look at DocBook. I haven't used it in ~25 years, and then only for short documents, and it is XML hence quite verbose.
But it's explicitly targeted at technical documentation. If nothing else, searching for DocBook alternatives might give you some ideas.
Re: Markdown is holding you back
#29You can include arbitrary HTML tags in Markdown at any place you need them.[0] I am not aware of any Markdown tooling that does not support this. So, no, Markdown is not holding me back. It is perfectly capable of what the author claims it isn't. [0]: https://daringfireball.net/projects/markdown/syntax#html
There are real limitations to this: You can't arbitrarily mix and match HTML and Markdown. As soon as you introduce an HTML block, you're locked out of Markdown syntax.
AsciiDoc lets you mix and match however you want. Or, put differently: AsciiDoc's superiority over Markdown extends even to being better at shelling out to HTML.
Re: Markdown is holding you back
#30The author seems to forget that markdown is just an extension of html. If markdown doesn't provide something that html does, you just write it in html and it will be rendered correctly. I'd also argue that the limitations of markdown allow me to focus on actual content and less on the presentation. I have little use of all the features of a markup language if I can't remember how to use them.
It is not features but structure and undetstanding that is missing.
That said I am not sure what the solution is to that since your docs may need structure my docs dont need. Therefore you cant solve the "semantic" outside of a "namespace" of what you agree in your organization.
E.g. you may decide architecture diagrams are in Mermaid but that is by no means a stanfard and my org uses embeded svg.
So to go full circle... you are right just use HTML. After all it's semantic isn't it ;-)