1. 9
  1.  

  2. 5

    Isn’t asciidoctor a dependency? Or is it included in OpenBSD these days?

    1. 2

      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)

    2. 3

      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.)

      1. 2

        CommonMark?

        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:

        [markdow](https://example.com)
        
        https://example.com[AsciiDoctor]
        

        Stuff like lists, headings, fenced blockes, bold/italics/underline is the same.

        1. 1

          Does AsciiDoctor have the equivalent of Markdown’s “slug” notation for links?

          [Example site][example-site]
          
          [example-site]: https://example.com
          
          1. 2

            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

            :url-home: https://asciidoctor.org
            
            Check out {url-home}[Asciidoctor]!
            

            But you have to put the links first.

          2. 1

            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

            [[message-types]]
            3. Message Types
            ~~~~~~~~~~~~~~~~
            

            I don’t see this used in the asciidoc docs; maybe it’s deprecated?

            1. 2

              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.

        2. 3

          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.

          1. 2

            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.