Almost 3 years after the rebirth of adoc-mode I’m happy to announce that adoc-mode 0.8 is finally out! This is a massive release that has been cooking for way too long, but I think it was worth the wait.

Let me walk you through the highlights.

Native Code Block Highlighting

This was the flagship feature I teased at the end of my 0.7 announcement, and it’s easily the most impactful change in this release. Source code blocks now get fontified using the appropriate language major mode – Ruby code looks like it does in ruby-mode, Python code looks like python-mode, and so on.

The feature is enabled out-of-the-box with a sensible default – only code blocks of 5000 characters or fewer are fontified natively, to avoid performance issues with very large blocks. You can set adoc-fontify-code-blocks-natively to t if you want unlimited fontification, or to nil to disable it entirely.

Inline Image Preview

You can now see images directly in your buffer instead of just staring at image::path/to/screenshot.png[]. Image previews are displayed automatically when you open a file (controlled by adoc-display-images), and you can toggle them on and off with adoc-toggle-images.

Right-clicking on an image link gives you a context menu to generate or remove the preview for that specific image. Remote images are supported too – set adoc-display-remote-images to t if you want to fetch and display images from URLs.

A couple of welcome additions here:

  • adoc-follow-thing-at-point (bound to C-c C-o and M-.) lets you follow URLs (opens in browser), include:: macros (opens the referenced file), and cross-references (jumps to the anchor). It’s one of those features that once you have it, you can’t imagine living without.
  • adoc-goto-ref-label (C-c C-a) jumps to an anchor by ID, with a smart default pulled from the xref at point.
  • The imenu index is now hierarchical – headings are nested under their parent sections, which makes navigating large documents much more pleasant.

Asciidoctor Inline Macros

adoc-mode now highlights Asciidoctor-specific inline macros like kbd:[], btn:[], menu:[], pass:[], stem:[], latexmath:[], and asciimath:[]. These were previously ignored by font-lock and would just blend in with regular text.

I’m a heavy user of Antora, and I really appreciate this one.

Bug Fixes Galore

This release squashes a lot of long-standing bugs:

  • Fixed a noticeable lag when typing in code blocks (this one was particularly annoying).
  • Fixed an Emacs hang caused by escaped curly braces in attribute references.
  • Fixed multiline font-lock for inline formatting (bold, italic, etc. spanning multiple lines).
  • Prevented auto-fill-mode from breaking section title lines.
  • Prevented Flyspell from generating overlays for links and other non-prose regions.
  • Fixed table delimiter highlighting (was limited to 4 columns).
  • Fixed unconstrained monospace delimiters.
  • And quite a few more – check the release notes for the full list.

Internal Improvements

I’ve also spent some time cleaning up the internals:

  • The minimum Emacs version is now 28.1 (up from 26).
  • Deprecated AsciiDoc backtick-apostrophe quote styles (not supported by Asciidoctor) have been removed.
  • Two-line (Setext) titles are now disabled by default, since Asciidoctor has deprecated them.
  • Image display and tempo templates have been extracted into separate files (adoc-mode-image.el and adoc-mode-tempo.el), making the main file more manageable.

The codebase is in much better shape than it was 3 years ago, but there’s still some room for improvement.

One More Thing: asciidoc-mode

I did eventually act on that idea I mentioned in my 0.7 post – I created asciidoc-mode, a tree-sitter-based AsciiDoc major mode for Emacs 30.1+. It’s a very different beast from adoc-mode – focused on the essentials (highlighting, navigation, folding) and leveraging tree-sitter for accurate and performant parsing.

If you’re on Emacs 30+ and prefer a lighter-weight editing experience, asciidoc-mode might be a good fit. If you want the full kitchen sink – image previews, tempo templates, native code block highlighting – adoc-mode is still the way to go. Both packages are maintained by me and they complement each other nicely.

Epilogue

adoc-mode 0.8 is available on NonGNU ELPA, MELPA Stable, and MELPA. Upgrading is just a M-x package-install away.

I’d like to thank everyone who contributed bug reports, pull requests, and feedback over the past 3 years. Open-source is a team sport and this release wouldn’t have happened without you. You rock!

That’s all I have for you today. Keep hacking! And keep writing… in AsciiDoc, of course!