I've moved my blog to Djot

[matklad]

So yeah, I've moved my blog at https://matklad.github.io from AsciiDoctor to Djot (and from Jekyll to hand-written Deno build script):

matklad/matklad.github.io@58b876f

I will probably regret doing this before djot hit official 1.0 and stability promise, but, in my defense, it was fun :-)

Things that went well:

• maintainability: although Djot is super-new, I am now much more confident about long-term maintainability: with AsciiDoctor, I am beholden to a somewhat large upstream impl, with Djot the parser itself is small, and the code to render HTML I wrote myself.
• control: djot has a well-defined AST, so it's very easy too convert that into exact HTML you want (my impl). One of my main gripes with adoc was that its default html output is html4 mess of divs and tables, with djot I can have minimal modern semantic output without tying myself to a particular implementaion's filter API
• syntax: djot's rules for curly quotes, emph, bold and verbatim are significantly more readbale and robust than those of asciidoctor. as an example, in AscdiiDoctor C++ is spelled {cpp} because double plus has semantic meaning. Curtly quotes are just ❤️ , in asciidoctor those need to be spelled explicitly as "`my quote`" and that's super annoying
• extensibility, AsciiDoctor has dedicated syntax for shortcuts kbd:[Ctrl+Alt+Del] and menu items menu:Edit[Transform > Rotate]. It was very easy to replicate that with djot's attributes. Some examples in this post.
• perf: not sure how much credit here is due to djot, but my new setup is more than 2x faster to generate (and I shell out to djot, so that's a process-per-post...)

Things that went less well:

• AsciiDoctor allows to add titles/captions to everything, which I used a lot (eg, bullet lists with titles). djot doesn't have syntax for this, so I used ad-hoc {cap="Title of my list"} attribute sytnax. The problem with that is that there's no inlines without recursive djot invocations which I was too lazy to implement.

• Inlines in verbatim blocks: with asciidoctor, it's easy to bloden/highlight parts of code blocks. With djot, I think that'll be easy to do by doing a recursive djot invocation, but I didn't do that because djot doesn't have a CLI flag to parse only inlines, and because I am too lazy :)

• "block" images are wrapped in p, so I had to write custom code to pattern-match on single-child ps to turn them into figures.

• Hierarchical sections in the AST #86 headers are flat, so, if you want to create a nested sections structure you have too write some custom code, which I was too lazy to do

• Italics _ got in a way a couple of times requiring escapes:

  • sometimes I use file_names_with_undersco.rs (eg, as link texts)
  • I tend to write long numbers like 1_000_000

• Tables. I think I only have two tables, and both are actually just examples of asciidoctor syntax, but even in the small wyswyg pipe tables feels inferior to "cell-per-line" tables.

• definition syntax feels a bit cluncy, as it always requires a blank line and an indent:

  : term
  
    def
  

  asciidoctor allows term:: def which is quite a bit more succinct

[waldyrious]

• Italics _ got in a way a couple of times requiring escapes:

  • sometimes I use file_names_with_undersco.rs (eg, as link texts)
  • I tend to write long numbers like 1_000_000

For reference, Textile requires wrapper brackets for intra-word bold and italics, e.g. 1[_000_]000 to italicize the "000".

In Djot, this would be e.g. 1{_000_}000 if the emphasis is actually intended, which is compatible with what was written in Beyond Markdown:

For intraword emphasis, we’d require a special syntax:

fan~_tas_~tic

[jgm]

Living dangerously! Well, this will be a good way to find potential issues. I think that with the pandoc djot reader, you can be confident that you'll be able to export your content to another format when you want to -- which should help give confidence to continue the experiment.

Feel free to raise any of these points as separate issues; that makes them easier to track.

I think that requiring {} for intraword emphasis is a reasonable idea to explore.

[jgm]

I think that requiring {} for intraword emphasis is a reasonable idea to explore.

I remembered why I did not require this. The problem lies in determining which _ or * characters are "intraword," without having access to full unicode tables. I can easily check to see if _ is between two ASCII alphanumerics, but that isn't general enough. We could alternatively require start emphasis to have whitespace to the left, and end emphasis to have whitespace to the right, but this seems too restrictive (*for example*), or *for example*, or for example`. So I didn't really know how to implement a feature like this, consistent with the constraint of making parsing uncomplicated.

[bpj]

As a compromise instead of requiring specific kinds of chars to the left/right ASCII alphanumerics may be forbidden i.e. "require" %W/SOS/EOS (assuming the parser can "peek") before the opening _ and after the closing _ only, or simply forbid ASCII alphanumerics on both sides of a delimiter, i.e. skip over %w_%w. Since strings containing literal underscores probably are file names or identifiers, so this would require {} in most reasonably ambiguous cases. Personally I think `file_name.ext`, `some_identifier` in the source and all-ASCII file names are good practice, and hopefully someone who uses underscores in file names also prefers all-ASCII file names.

[jgm]

Sure -- that is possible, but to me the differentiation between ascii and non-ascii alphanumerics seems unintuitive -- your typical end user won't understand this distinction, and may well have file names with non-ascii alphanumerics.

I agree that filenames should be in verbatim backticks, which solves the problem completely.