It is obviously a nice system but over time our frustration with it grew. Every other piece of software we have uses Markdown: GitHub, work chat, chats of open source projects we work with, things like StackOverflow, HackMD, personal note taking apps, the list goes on and on. Every new person joining our team had to adjust to AsciiDoc just for some of the work they would be doing while staying with Markdown for everything else.
We pulled the plug last year and migrated everything we had to Markdown, and while sometimes I need to use HTML tags to do something advanced I don’t mind it as much as I thought I would.
If you need complex things, you already have enough skills to figure that out. Also there's almost always a help button around that lists what it supports.
Doesn’t seem fair to call that a frustration with AsciiDoc. The frustration is around it, caused by everything else.
> GitHub
Supports and renders AsciiDoc for documentation. But granted, preference is given to markdown in things like comments.
Markdown + html or simply Hugo is way better.
Personally I like the ubiquity and simplicity of Markdown, but I can also see the benefits of the features AsciiDoc has to offer.
Why does there need to be something else? That’s a powerful reason.
Markdown is subpar and has an awful steward—as evidenced by all the different “flavours” and degrees of support in existence—but we somehow made it work in a jumble of hacks and that’s what we have now. It’s crummy but gets the job done.
Even if AsciiDoc is technically superior, which it probably is, is it superior enough to justify the big players implementing and pushing for in more in places regular users have access too?
Note that markdown's whole value proposition is that it is a nice looking plaintext format, it stinks at adding any sort of semantic value to a document. realistically if you care about your documentation you will use something better than markdown. The problem is adding better structure always makes the plain text ugly and hard to read, violating the whole point of markdown. that is to say, the many efforts to add better semantics to markdown don't appear to understand the point of markdown.
ASCII, by way of that character encoding standard, implies that dark age before writing and transmitting 'café' or 'Warschauer Straße' or '€10' or '¡olé!' just worked. Not a great marketing point.
So the first thing you are wondering when you read 'AsciiDoc' is, “Wait, does this mean it doesn't support anything but ASCII characters?”, regardless of whether or not that is true.
MyST, for example, lets you do
:::{makeup-highlight}
:lang: elixir
defmodule A do
def b, do: :ok
end
:::
:::{pygments-highlight}
:lang: python
class B:
pass
:::
And of course you can write some pages in this ecosystem in Markdown if you want using MyST [2]
So you get a result that is Word-quality, but separates presentation and content, and is easy to keep under version control.
No, I'm afraid it's the format I know I don't need. At least not for the kind of things I usually use markdown for.
Readme files, technical documentation, moderately complex websites with templating and rendering engines - markdown works just fine. Sometimes with a custom `|||warning\n...\n|||\n` thrown in to render something in a box with a red border.
I get that there's a market in the space occupied by TeX, Typst (underrated IMHO), and possibly MS Word or Quark Express (for non-techies). Libreoffice is great in theory but, again IMHO, "eh" in practice. That market is generating book-length documents with all the cross-references and other features that needs.
That said, Robert Nystrom of "Crafting Interpreters" managed this just fine with markdown and a few custom scripts: https://journal.stuffwithstuff.com/2020/04/05/crafting-craft... , https://github.com/munificent/craftinginterpreters/tree/mast... . This is how those famous 10x writers/programmers work, I guess.
Asciidoc is Markdown's big brother? I'll carry on playing with the little brother, thank you very much.
Also the whole page is an ad for their own editor tool. $9.99 per month so you don't need to use your own editor and unintuitive tools like (gasp!) the terminal.
You don't need any paid tools if you don't want them, I used a text editor and the terminal and source control.
I don't understand the hostility toward someone offering a product. It's fine that you don't need it, that doesn't mean someone else won't.
I can't think of many scenarios where someone does care about the backing format or explicitly wants to write raw asciidoc, but doesn't want to just use asciidoctor or other free CLI tools.
The asciidoc developers don't seem to consider this an important issue: https://github.com/asciidoctor/asciidoctor/issues/1121
While asciidoc has some nice constructs, this made it a no go the last time I was looking for a documentation language.
[0] https://oxide-and-friends.transistor.fm/episodes/rfds-the-ba...
I tried to rewrite it to AsciiDoc, but there was some unexpected ugly ess. Iirc e.g. lists. It bothered me so much, I switched back to markdown.
Today I reach for Typst when I need more than Markdown. Biggest caviar there is that html export is still wip.
Pandoc seems to support converting from and to Typst. That might be an option for you.
That would be obvious, except for the name.
There is so much you can't put in Markdown because it doesn't work without rendering.
I'd rather pair markdown with an independent template language, if I need programmability. (Or script tags, though that's only useful in contexts where you'll view it rendered and script tags aren't blocked.)
I read the 2003 book The art of Unix programming where the author praises plain text config and says hand editing xml is a human rights violation, since Notepad was the most powerful ubiquitous editor then. Markdown was best then.
https://commerce.nearform.com/open-source/spectacle/docs/api...
- JetBrains Plugin - VSCode Plugin
I wanted to like it, but doing anything was a bit of a pain. If I need that level of structure, I'd rather work with something like Typst. Otherwise Markdown works fine.