So, you might be asking why I chose AsciiDoc. I like AsciiDoc because it is a simple markup language that lets me focus on my writing and layout. Markdown can do this too, and is more common than AsciiDoc. However, the fact that there isn’t a standard Markdown
CommonMark?
and I don’t like any of the rendered output. With AsciiDoc, they give a simple and clean default result in HTML with CSS.
Category error — the OP is mixing up the markup syntax (and the code that transforms it to unstyled HTML) with a template/theme system that produces full pages. In other words, they’re not talking about Markdown, they’re talking about Jekyll/Hugo/whatever.
Digging through the scripts, the OP uses an engine called asciidoctor.
(One genuine point in ASCIIdoc’s favor is that it’s got better support for high level structure like TOCs. But I still prefer Markdown because I like the syntax better.)
Yeah, at this point markdown is more standardised than AsciiDoc/Asciidoctor
they give a simple and clean default result in HTML with CSS.
FWIW, one of my gripes with AsciiDoctor is that default html output is pretty horrible. It looks good, but it’s a soup of divs. I am eagerly waiting for something like https://github.com/jirutka/asciidoctor-html5s to be available out of the box.
But I still prefer Markdown because I like the syntax better
This one I don’t quite understand: asciidoctor is more or less superset of markdown at this point. The biggest difference is in the link syntax:
Hm, you’re right about syntax; I went to the asciidoc website and looked at the examples.
My opinion comes from some asciidoc documentation files in a repo I work on, that I sometimes need to edit. Their author used a different syntax for headings, where you put a line of punctuation below the text with the same length, like
Yes, I think this is deprecated. Or, more specifically, I think that’s an older AsciiDoc syntax, and that the new AsciiDoctor dialect added = title, == subtitle syntax and made that a default.
Which is another problem with asciidoctor – it accumulated a bit of cruft on the docbook -> asciidoc -> asciidoctor path. Hopefully the standardization effort would lean in the direction of the cleanup, rather backwards comparability here.
The deployment step has a race condition: A user visiting the webpage while the htdocs directory is moved out of the way will get an error.
I recommend always uploading to a tagged/dated directory and arranging for a symlink to be replaced atomically (e.g. using mv -T) so that clients aren’t disturbed as you hack on your website.
I’m always in favor of AsciiDoc (especially over Markdown) but I have my gripes. My most desired features are an <abbr> syntax and reducing some of the complexity that comes with the styling/themes/icons. The other annoyances like nesting way too many things in <p> and other tags aren’t too difficult to address as an additional step. I recently wrote a Nix flake with some OCaml+Lambdasoup to massage Asciidoctor output so I could use a README.adoc on Sourcehut where Markdown is the only supported syntax.
For the context of a blog or small site Soupault is the perfect post processor if you need to make some tweaks not afforded to with the base Asciidoctor output that can get you 90% of the way there and without introducing noise to you document like front-matter and short-codes.
Isn’t
asciidoctora dependency? Or is it included in OpenBSD these days?It seems to be a package. See: https://openports.pl/path/textproc/asciidoctor
whereis asciidoctor|command -v asciidoctor= 0 result if not install (by default, on v7.1)CommonMark?
Category error — the OP is mixing up the markup syntax (and the code that transforms it to unstyled HTML) with a template/theme system that produces full pages. In other words, they’re not talking about Markdown, they’re talking about Jekyll/Hugo/whatever.
Digging through the scripts, the OP uses an engine called asciidoctor.
(One genuine point in ASCIIdoc’s favor is that it’s got better support for high level structure like TOCs. But I still prefer Markdown because I like the syntax better.)
Yeah, at this point markdown is more standardised than AsciiDoc/Asciidoctor
FWIW, one of my gripes with AsciiDoctor is that default html output is pretty horrible. It looks good, but it’s a soup of divs. I am eagerly waiting for something like https://github.com/jirutka/asciidoctor-html5s to be available out of the box.
This one I don’t quite understand: asciidoctor is more or less superset of markdown at this point. The biggest difference is in the link syntax:
Stuff like lists, headings, fenced blockes, bold/italics/underline is the same.
Does AsciiDoctor have the equivalent of Markdown’s “slug” notation for links?
Sadly, no. There’s a generic substitution mechanism which can be used instead though:
https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#attributes-and-substitutions
But you have to put the links first.
Hm, you’re right about syntax; I went to the asciidoc website and looked at the examples.
My opinion comes from some asciidoc documentation files in a repo I work on, that I sometimes need to edit. Their author used a different syntax for headings, where you put a line of punctuation below the text with the same length, like
I don’t see this used in the asciidoc docs; maybe it’s deprecated?
Yes, I think this is deprecated. Or, more specifically, I think that’s an older AsciiDoc syntax, and that the new AsciiDoctor dialect added
= title,== subtitlesyntax and made that a default.Which is another problem with asciidoctor – it accumulated a bit of cruft on the docbook -> asciidoc -> asciidoctor path. Hopefully the standardization effort would lean in the direction of the cleanup, rather backwards comparability here.
The deployment step has a race condition: A user visiting the webpage while the htdocs directory is moved out of the way will get an error.
I recommend always uploading to a tagged/dated directory and arranging for a symlink to be replaced atomically (e.g. using mv -T) so that clients aren’t disturbed as you hack on your website.
I’m always in favor of AsciiDoc (especially over Markdown) but I have my gripes. My most desired features are an
<abbr>syntax and reducing some of the complexity that comes with the styling/themes/icons. The other annoyances like nesting way too many things in<p>and other tags aren’t too difficult to address as an additional step. I recently wrote a Nix flake with some OCaml+Lambdasoup to massage Asciidoctor output so I could use aREADME.adocon Sourcehut where Markdown is the only supported syntax.For the context of a blog or small site Soupault is the perfect post processor if you need to make some tweaks not afforded to with the base Asciidoctor output that can get you 90% of the way there and without introducing noise to you document like front-matter and short-codes.