The better alternative to Markdown

AsciiDoc (or Adoc) is a tool used to write technical documents. It is far better than the industry standard of Markdown but it is very underrated.

Thank you so much for taking the time to watch.

Timestamps:
0:00 - What is Markdown?
0:11 - The problem with Markdown
0:42 - What is AsciiDoc?
1:00 - Embedded source code
1:30 - Exporting
1:47 - Better tables
1:57 - Diagram plugins
2:17 - More features

[geryz]

In defense of Markdown tables: Markdown - and by extension, its tables - was originally designed to be human-readable in plain-text form (and I think it still does that pretty well, regardless of flavor). ADoc tables are not recognizable as such if you don't already know the syntax.

[SedBuildsThings]

Can't be a markdown replacement if it's not human readable in plain text

[quantumstormgames]

This seems like a classic case of the “15 competing standards” problem lol

[pokefreak]

Lost me at plugins, LaTeX, etc. Like jfc why does everything need to be a framework or abstraction layer now. Why can't people just write a standard that actually solves the problem instead of outsourcing it?

[tryoxiss]

All syntax problems are either personal preference or solvable with simple (and common) extensions. Markdown flavours, while different, are all similar enough it causes no problems unless you are using advanced features.

All the rendering stuff at the end (syntax hiloghting, PDF format, etc) is the job of the renderer, not the format. The only reason it’s “consistent” with ASCIIDoc is because there is only one tool to handle it.

[Amejonah]

I wrote my bachelor thesis in Pandoc Markdown, converted to latex, made changes at 5AM and then sent my thesis-final-final-final to the prof as PDF per e-mail. What a time to be alive.
Looking back, I should've used typst locally using community VS Code plugins and such (I cannot upload my thesis on the typst site, as it contains NDA restricted information).

Btw, the "sane" use of Markdown to create PDFs, sites and such, would be to use Pandoc and write filters for it, which can parse specific tokens to represent tables and other fancy stuff. (i.e. embedded files, the code snippets you mentioned, latex expressions, mermaid js integration (which is possible in some markdown editors!), etc.).
The difference between AsciiDoc and markdown would be that the former has more "built-in", but technically... using pandoc... you get also these features "built-in" using filters (or easier: markdown editors like Typora).

(P.S.: Jetbrains Fleet got recently Markdown Preview and they are working on AsciiDoc support for Writerside)

[enternix]

I've never had such a nice concise video that demonstrated the pros so practically, great job!

[ruslanustiuhov]

It feels that we are comparing apple to oranges here.

[noahcuroe]

point 2 is already solved for markdown by pandoc. consistent markdown export to any format, supports inline latex if you want it, and output format is fully customizable. can even have one source markdown file export to pdf, html, and PowerPoint slides.

[somewhatmay_]

Incredible video! Definitely will look into it!

[okolol]

great, can you please make a detailed tutorial/explanation on how to use it?

[ChrisCarlos]

I just look to using markdown because my goal isn't to make a pretty document. It is merely because the formatting generally leaves a well understood document that you can follow along without being worried if it is being rendered or not by some fancy graphic renderer. The rendering is a bonus not required.

I just feel this goes one step I've over. I mean everyone has different needs so I am not saying it is bad of course. I use the bare bones of MD mainly because I just want to separate sections and have documentation that gives me some clear intent or meaning without becoming superfluous and cumbersome.

I know what is a list and can find and understand it without renderer. I know what headings are and what level usually denoting what layer I am in and so forth.

[YuriAlbuquerque]

Org-mode is the best one, tbh. But you need to use Emacs.

[emmanuelgenga]

I guess I'll have a look, thanks for sharing

[tanishqsingla]

Thanks for bringing this, this looks cool

[simon-off]

This looks awesome! I love markdown but the small inconsistencies does complicate things sometimes (and tables are painful 😅). I don't want more features, just more consistency.

I'm gonna give this a try. Great video!

[odw]

Granted -- They've done a very thorough job documenting the standard, and covering a lot of potential use cases.
But I feel like "complete" is an unreachable goal, because one person really needs LaTex rendering, and the next will ask "why doesn't it natively embed GeoJSON as a map?" (etc, etc).
Markup languages can not really be feature-complete (HTML isn't either), so they will also never be fully consistent (HTML isn't either). Some website full of GIS geeks will offer support for GeoJSON, and before you know it you'll have different adoc flavors.

[Bankoru]

All I need is consistent Latex, so I'm sold

[anzo.]

You mean I need to render it to read it ?
I find it unreasonable as a replacement. I still open a lot of md file in vim or plain text cuz it's convenient. I don't want to go open another source file just to see what function was quoted. The video's great but asciidoc just is not imho.

[rondYT]

Can you sell me on why I should choose this over my beloved org mode?