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

Features

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

sophisticated highlighting
native fontification of code blocks
toggle between the display of image links and the display of the corresponding images
promote / demote title
toggle title type between one line title and two line title
adjust underline length of a two line title to match title text’s length
goto anchor defining a given id, default reading from xref at point
support for outline (however only with the one-line title style)

Demo

The highlighting emphasizes on how the output will look like. 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.

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.

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 what you expect on the first run.

Installation

adoc-mode is available on the community-maintained MELPA Stable and MELPA repos.

Using MELPA Stable is recommended as it has the latest stable version. 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

Alternative, 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)

Configuration

General

According to an old AsciiDoc manual, .txt is the standard file extension of AsciiDoc files. Add the following to your initialization file to open all .txt files with adoc-mode as major mode automatically:

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

Modern conventions for AsciiDoc file extensions favor .adoc and .asciidoc and they are associated with adoc-mode automatically.

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

The maximal size (a cons cell with the format (width . height)) for the preview of images can be set with adoc-max-image-size:

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

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 liked to have normal text with a variable pitch face, buffer-face-mode is one good options for you:

(defun my-buffer-face-mode-variable ()
   "Set font to a variable width (proportional) fonts in current buffer."
   (interactive)
   (setq buffer-face-mode-face '(:family "DejaVu Sans" :height 100 :width semi-condensed))
   (buffer-face-mode))

(add-hook 'adoc-mode-hook (lambda() (buffer-face-mode t)))

Roadmap

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

Demote / promote for list items
Outline support also for two line titles
Correctly highlighting backslash escapes

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 a 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

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 build from Bozhidar’s fork.

License

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

bbatsov/adoc-mode