71–80 of 124 posts
My work adopted ReStructured Text and Sphinx for large volume of technical documentation, similar system to AsciiDoc .
I was reviewing a command-line MD reader today. I think it was the nth time I've looked it over. It's called glow : https://github.com/charmbracelet/glow
I always come to the same conclusion. I don't need it. I don't need to remember to use (yet) another command line program to read MD or perform a very specific (and non-vital) function.
The reason is that MD and AD are so very easy to read. They are too effective at their jobs. They aren't like HTML tags that get in the way of the text. You barely even notice MD/AD in most(?) cases. Text plus MD/AD are incredibly easy to read without a 3rd-party program "rendering" the results.
Having said that... the only time I got really excited about MD/AD was when there was a post about Textual Markdown : https://news.ycombinator.com/item?id=34028765
It wasn't that the "rendered" text looked great (it looked beautiful, btw) but I could see 'Textual Markdown' turning into a command-line, online browser just for MD text! Think about that...
I even thought about how great it would be if the GeminiSpace folks : https://en.wikipedia.org/wiki/Gemini_(protocol)?useskin=vect... : embraced MD/AsciiDOC instead of their limited markup language.
It's exciting to think of MD/AD making themselves an alternative lightweight tagging system on the web. Exciting to think about a lightweight web in general - no tracking, adware, tons of JS, etc...
Exciting to think about a bunch of browsers growing out of this (ie; you don't need billions/yr to support MD/AD browsers) - from full-blown GUIs to, well... "Textual-Markdown".
Anyway... MD/AD would be great if it grew beyond offline use. For offline use only... you really don't need rendering. Maybe it helps a bit with really long files but otherwise...
Earlier quoted context omitted.
Not having includes in markdown is a real bummer, though.
You get links, if you need more than that you're probably overcomplicating your documentation. Transclusion might sound nice, but now your docs have depedencies and they become harder to send, harder to host, and harder to edit (is this edit in this transcluded file going to work for every other file that includes it?). Then someone goes "I use it for templating" and now you have a CMS. It's a slippery slop that mark…
I think the bigger downside is that the include directive doesn't really help you when you're reading the source file, but markdown was explicitly designed to also be pleasant to read "raw". Realistically however, you will render you docs into HTML (or pdf) so that doesn't really matter.
I also find includes neat to include code snippets from separate files, so I can run linting and other checks on them independently (and sometimes even run scripts as independent files).
Everything in that article is why I don't like asciidoc. I think a lot of documentation should be absolute dead simple - no macros and complex behavior. It should just work. Markdown is great for that.
AsciiDoc is so close to being good. It slam dunks Markdown, but they just have a few nagging issues that they refuse to fix, for 9 years now: https://github.com/asciidoctor/asciidoctor/issues/1087
I think this is actually a great example of how dedicated Dan Allen is to the project! He has been following up on the ticket for over 6 years!
I have interacted with him briefly on the Antora Zulip Chat a couple of times and he is always very helpful, it's a pleasure.
AsciiDoc is so close to being good. It slam dunks Markdown, but they just have a few nagging issues that they refuse to fix, for 9 years now: https://github.com/asciidoctor/asciidoctor/issues/1087
I read the thread, and it is said that by now the implementation cannot be changed without breaking a lot. But there are multiple workarounds and fixes you can apply depending on your situtation. There also seems to be a new HTML renderer where the problem is already fixed. I think this is actually a great example of how dedicated Dan Allen is to the project! He has been following up on the ticket for over 6 years! I…
I am not sure what the worry is with backward compat. The only difference with the resultant HTML, is extraneous "p" elements would be removed from "li" elements. Anyone who has been relying on that behavior, has been relying on non-idiomatic HTML and should be inconvenienced.
I see a lot of comments in this thread mentioning that it is only Ruby, but there is asciidoctor.js [1], a JS implementation. I'm using it at my company for the docs, together with Antora. It's the only docs system I have used extensively, but so far I didn't miss anything! We have quite a complex system with different components versioned independently, but it just works! [1] https://docs.asciidoctor.org/asciidoctor…
We adopted Asciidoc at work (migrated from Word and Markdown), and it has been a stellar tool for editing and reviewing our technical documentation, as it fits well into our code review process. We also use Mermaid and PlantUML for our diagrams, which the asciidoctor extension has handled well.
It's not accurate to say AsciiDoc only has a single implementation, there is the original AsciiDoc written in Python, and also there is AsciiDoctor written in Ruby. Unfortunately, AsciiDoctor is merely _mostly_ compatible and deliberately opted to not support some features. (And being Ruby, GitHub will use AsciiDoctor to render AsciiDoc files; whether you should conform your documents to this environment depends on w…