adoc-mode

Introduction

AsciiDoc is a text document format for writing short documents, articles, books and UNIX man pages. AsciiDoc files can be translated to HTML and DocBook markups.

adoc-mode is an Emacs major mode for editing AsciiDoc files. It emphasizes the idea that the document is highlighted so it pretty much looks like the final output. What must be bold is bold, what must be italic is italic etc. Meta characters are naturally still visible, but in a faint way, so they can be easily ignored.

adoc-mode aims to be fully compatible with the modern official AsciiDoc language specification developed under the Eclipse AsciiDoc Working Group. You can follow our progress toward that goal in the spec-compliance document.

Features

Here are some of the main features of adoc-mode:

• comprehensive syntax highlighting for all AsciiDoc elements, including backslash-escaped inline formatting (e.g. *not bold*)

• native fontification of source code blocks using language-appropriate major modes

• font-lock support for Asciidoctor inline macros (]+btn:[, menu:[], etc.)

• table highlighting for the PSV (|===), CSV (,===), and DSV (:===) formats - PSV is the most common and flexible, so reach for it unless you’re pasting comma- or colon-separated data

• inline image preview with right-click context menus and remote image support

• ~50 tempo templates for inserting AsciiDoc markup (formatting, titles, blocks, lists, macros, etc.)

• region-aware text-styling commands under C-c C-s (bold, italic, monospace, highlight, super/subscript, link) that wrap the active region or word at point and toggle the markup off when it’s already there

• heading navigation modelled on markdown-mode / org-mode: next / previous heading (C-c C-n / C-c C-p), forward / backward at the same level (C-c C-f / C-c C-b), and up to the parent heading (C-c C-u)

• title management: promote / demote (M-left / M-right), toggle between one-line and two-line styles, adjust underline length

• list editing: M-left / M-right nest the list item at point deeper or shallower, M-RET inserts a sibling item (incrementing the number for explicitly-numbered lists), M-up / M-down move an item (with its sub-items) past its siblings, and M-x adoc-renumber-list renumbers an explicitly-numbered list

• navigate to anchors and sections with completion (C-c C-a), and follow URLs, link: and include:: macros, and xrefs at point (C-c C-o / M-.), or by clicking them with the mouse

• section titles act as cross-reference targets too: their Asciidoctor auto-ids are offered in completion and resolved by navigation, with the id style (Asciidoctor _my_title vs Antora my-title) detected automatically or set via adoc-section-id-style

• Antora awareness: in a component (a directory with an antora.yml), following an xref: to another page (e.g. topic/page.adoc) opens the resolved page under the right module’s pages/ directory and jumps to the section, and completion inside an xref: offers the component’s pages and, after a #, the target page’s sections

• an xref backend over anchors and sections: M-? lists every cross-reference to the id at point, with the usual xref marker stack and completion UI

• context-aware completion via completion-at-point: cross-reference ids inside << / xref:, attribute names inside {, file paths after include::, and source-block languages inside [source,

• nested imenu index with hierarchical heading structure

• outline folding built on outline-minor-mode (enabled out of the box): TAB cycles the subtree at point, S-TAB cycles the whole buffer (overview / contents / show all), one-line title style only

• preview and export via Asciidoctor (C-c C-c): live HTML preview in an xwidget or eww side pane, plus export to HTML, DocBook, PDF, and EPUB with navigable warnings and errors

• on-the-fly diagnostics through a built-in Flymake backend (and out-of-the-box support for Flycheck’s asciidoctor checker)

• integration with flyspell-mode (skips non-prose regions) and comment commands (M-;)

• filling that respects AsciiDoc hard line breaks (a line ending in ` +`) and section titles

Demo

The highlighting emphasizes how the output will look. All characters are visible, however meta characters are displayed in a faint way. An exception are image links. You can toggle between the display of the link text and the linked image.

See Also

If you’re looking for a lighter-weight alternative, check out asciidoc-mode — a tree-sitter-based AsciiDoc mode focused on the essentials (highlighting, navigation, folding). It requires Emacs 30.1+ and trades `adoc-mode’s richer feature set for simplicity and the performance benefits of tree-sitter. Both modes are maintained by the same author.

Installation

adoc-mode is available on NonGNU ELPA (Emacs 28+), MELPA Stable and MELPA.

NonGNU ELPA is enabled by default in Emacs 28+, so adoc-mode can be installed without any additional package archive configuration. MELPA Stable carries the latest stable version, while MELPA has a development snapshot for users who don’t mind breakage but don’t want to run adoc-mode from a git checkout.

You can install adoc-mode using the following command:

M-x package-install RET adoc-mode RET

If the installation doesn’t work try refreshing the package list:

M-x package-refresh-contents

Alternatively, you can add something like this to your Emacs config:

(unless (package-installed-p 'adoc-mode)
  (package-refresh-contents)
  (package-install 'adoc-mode))

or if you’re into use-package:

(use-package adoc-mode
  :ensure t)

Usage

Adoc-mode is designed for intuitive use. Most features are available from the AsciiDoc menu in the menu bar.

This section only describes some not so obvious features.

Completion

adoc-mode registers a completion-at-point function, so M-TAB (or a completion UI like Corfu or Company) offers candidates based on the construct at point:

• inside << or xref: - cross-reference ids: explicit anchors (, [id], []) and section auto-ids. In an Antora component an xref: also completes the component’s pages as targets and, after a , the sections of the target page

• inside { - attribute names, both the ones defined with :name: in the buffer and a set of common built-in attributes

• after include:: - file paths, relative to the document

• inside [source, - source-block language names

In plain prose the completion function yields to whatever else you have on completion-at-point-functions.

Cross-references and navigation

Put point on a reference and follow it with C-c C-o (or M-.), or just click it with the mouse - references highlight on hover. This follows URLs, link: and include:: macros, and cross-references:

• an [id] or [id] jumps to the matching anchor or section in the buffer (section auto-ids work as targets, so you can point at a section even without an explicit anchor)

• in an Antora component, an xref: to another page (e.g. topic/page.adoc) opens the resolved page under the right module’s pages/ directory and jumps to the #fragment. Resolution stays within the current component

C-c C-a jumps to an anchor or section by name, completing over the buffer’s ids.

adoc-mode also registers an xref backend, so the standard cross-reference keys work for AsciiDoc ids: M-? (xref-find-references) lists every [id] / [id] that points at the id under point, and M-, (xref-go-back) returns after a jump. In an Antora component M-? searches the whole component, so cross-page references (this/page.adoc from other pages) are included.

Preview and Export

adoc-mode can render and export documents by shelling out to the Asciidoctor command-line tool, so you need asciidoctor on your PATH for these commands to work. PDF and EPUB export additionally need the asciidoctor-pdf and asciidoctor-epub3 converters.

Press C-c C-c to open the Asciidoctor transient menu, or use the AsciiDoc → Preview / Export menu. From there you can:

• adoc-preview - render the current buffer and show the HTML in a side pane.

• adoc-live-preview-mode - a minor mode that re-renders the preview every time you save the buffer.

• adoc-export-html / adoc-export-docbook / adoc-export-pdf / adoc-export-epub - export the file next to the source. These run through compile, so you can jump to any warnings or errors with M-g M-n.

The preview feeds the buffer to Asciidoctor through its standard input, so it reflects unsaved edits and resolves relative include:: and image paths.

The preview pane is chosen by adoc-preview-backend. By default (auto) it uses an embedded WebKit widget when your Emacs was built with xwidget support, and falls back to eww otherwise. You can force a specific backend:

;; one of: auto (default), xwidget, eww, browser
(setq adoc-preview-backend 'eww)

Pass extra arguments to every Asciidoctor invocation via adoc-asciidoctor-extra-args, e.g. to enable section numbers:

(setq adoc-asciidoctor-extra-args '("-a" "sectnums"))

Syntax Checking

adoc-mode ships a Flymake backend that runs the buffer through Asciidoctor and reports its parser errors and warnings inline. It’s registered automatically, so you just turn on flymake-mode (and make sure asciidoctor is on your PATH):

(add-hook 'adoc-mode-hook #'flymake-mode)

The check feeds the buffer to Asciidoctor over its standard input, so it runs on unsaved edits, and it jumps with the usual flymake-goto-next-error / flymake-goto-prev-error.

Prefer Flycheck? It ships its own built-in asciidoctor checker that also works in adoc-mode out of the box - just enable flycheck-mode instead.

Image Preview

If you click mouse-3 on an image link like image⁣:path/to/image[] the Image context menu pops up.

This context menu allows you to generate or remove the preview for the linked image.

The menu item AsciiDoc → Toggle display of images runs the command adoc-toggle-images. It removes all image previews from the buffer if there are any. If there are no image previews in the buffer it generates them for all image links.

This may be confusing if all image previews are outside the visible region of the buffer. In this case, you might expect adoc-toggle-images to generate the previews for the image links in the visible area on the first run. But it does not, since it first removes all the previews, even if you have not seen them.

Just run adoc-toggle-images again if it does not do what you expect on the first run.

Configuration

General

The .adoc and .asciidoc file extensions are associated with adoc-mode automatically.

Note	An old AsciiDoc manual lists .txt as the standard extension. If you want adoc-mode for .txt files as well, add this to your init file:

(add-to-list 'auto-mode-alist (cons "\\.txt\\'" 'adoc-mode))

You can see a list of all configuration options offered by adoc-mode by running the following command - M-x customize-group adoc.

Native Syntax Highlighting of Source Code Blocks

Out-of-the-box adoc-mode will try to apply native font-locking to source code blocks (e.g. the same font-locking that ruby-mode would use for Ruby code blocks). This can be tweaked by several configuration options:

• Native fontification of source blocks can be switched off by setting adoc-fontify-code-blocks-natively to nil. The default value is 5000, meaning only code blocks of 5000 characters or fewer are fontified natively.

• Native fontification of lengthy code blocks can cause performance problems. If the value of adoc-fontify-code-blocks-natively is an integer only those code blocks are fontified natively whose length is less or equal to that value. Set it to t to fontify all code blocks regardless of size.

• To avoid performance problems with code block beginnings that do not have a matching end yet the scanning for the code block end is delimited by adoc-font-lock-extend-after-change-max.

• All programming languages XYZ that have an Emacs major mode XYZ-mode and use font-lock are automatically supported. Some other languages not fitting into that name scheme are supported through the alist adoc-code-lang-modes. You can add your own languages and modes there if they work based on font-lock and are not automatically supported. A value may be either a single major mode or a list of candidate modes tried in order, with the first available one winning (e.g. OCaml blocks try neocaml-mode, then tuareg-mode, then caml-mode).

• The fall-back language mode is prog-mode without any fontification. You can set your own default by adoc-fontify-code-block-default-mode.

Display of Image Previews

Images are shown as preview by default when you open an AsciiDoc file. You can avoid this by deactivating the option adoc-display-images.

(setq adoc-display-images nil)

By default, images are displayed at their actual size. You can limit the maximum dimensions by setting adoc-max-image-size to a cons cell of (MAX-WIDTH . MAX-HEIGHT) in pixels:

(setq adoc-max-image-size '(640 . 480))

Note	Image resizing requires Emacs to be built with ImageMagick support.

An image link can also be given as url to a remote image. The display of remote images is switched off by default. You can activate it by the option adoc-display-remote-images.

(setq adoc-display-remote-images t)

Images are only downloaded if the protocol of the url matches one of those in the list adoc-remote-image-protocols. This list can be customized. By default, it only contains the entry https.

Syntax Highlighting Customization

It is possible to customize the way adoc-mode renders different text elements (faces) like section titles, text or punctuation styles. For example, if you would like a level 1 section title to have a different text color or height you can achieve this by using standard Emacs functionality.

First of all, list all available faces by running

M-x list-faces-display

and searching for lines with the adoc- prefix.

Alternatively, you can get information about the face under point by calling

M-x describe-face

One possible solution to change the look of a face is to use the built-in use-package feature :custom-face.

Example:

(use-package adoc-mode
  :ensure t
  :custom-face
  (adoc-title-0-face ((t (:height 1.0 :weight bold)))))

Of course, this is only one way to do it. Emacs has a few ways to customize faces. Simply, pick the one you prefer.

If your default face is a fixed pitch (monospace) face, but in AsciiDoc files you’d like to have normal text with a variable pitch face, variable-pitch-mode is a good option:

(add-hook 'adoc-mode-hook #'variable-pitch-mode)

History

adoc-mode was created by Florian Kaufmann in 2009. Eventually the development was halted in 2016 and the mode was dormant for the next 6 years. In 2022 Tobias Zawada encouraged the Emacs community to revive the development and after a brief period under the Emacs Orphanage org, Bozhidar Batsov assumed the project’s maintenance.

These days all upstream packages (e.g. on MELPA) are built from Bozhidar’s fork.

Roadmap

Here are some features that we’re considering to add in the future:

• Table editing and alignment

• Verifying and improving compliance with the latest AsciiDoc language specification

Check out the issue tracker for more details.

Hacking

adoc-mode uses Eldev for development, so you should install the tool first.

The easiest and "purest" way to run adoc-mode is to execute:

$ eldev emacs

This will start a separate Emacs process with adoc-mode and its dependencies available, but without your normal packages installed. However, you can use Eldev-local to add some packages with (eldev-add-extra-dependencies 'emacs …​) forms. See Eldev documentation for details.

Alternatively, if you want to load adoc-mode from source code in the Emacs you use for editing:

• Generate autoloads file (that’s done automatically when installing via package.el but you’ll have to do it manually in this case):

$ eldev build :autoloads

• Add to your .emacs:

;; load adoc-mode from its source code
(add-to-list 'load-path "~/projects/adoc-mode")
(load "adoc-mode-autoloads" t t)

Changing the code

It’s perfectly fine to load adoc-mode from package.el and then to start making experiments by changing existing code and adding new code.

A very good workflow is to just open the source code you’ve cloned and start evaluating the code you’ve altered/added with commands like C-M-x, eval-buffer and so on.

Once you’ve evaluated the new code, you can invoke some interactive command that uses it internally or open an Emacs Lisp REPL and experiment with it there. You can open an Emacs Lisp REPL with M-x ielm.

You can also quickly evaluate some Emacs Lisp code in the minibuffer with M-:.

Running the tests

Run all tests with:

$ eldev test

Note	Tests may not run correctly inside Emacs' shell-mode buffers. Running them in a terminal is recommended.

You can also check for compliance with a variety of coding standards in batch mode (including docstrings):

$ eldev lint

To check for byte-compilation warnings you can just compile the project with Eldev:

$ eldev compile

License

Copyright © 2009-2016 Florian Kaufmann

Copyright © 2022-2026 Bozhidar Batsov and adoc-mode contributors

Distributed under the GNU General Public License; type C-h C-c to view it.