Clone this wiki locally
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.
Installation is as usual, so if you are proficient with Emacs you don't need to read this.
Install the traditional way
- Download the file adoc-mode.el from
store it to a directory in your load-path, e.g. ~/.emacs.d. To add a
specific directory to the load path, add the following to your
initialization file (probably ~/.emacs):
(add-to-list 'load-path "mypath")
- You will also need to install the library markup-faces.
- Add either of the two following lines to your initialization file. The
first only loads adoc mode when necessary, the 2nd always during startup
(autoload 'adoc-mode "adoc-mode" nil t)
- Optionally byte compile adoc-mode.el for faster startup:
- To use adoc mode, call adoc-mode after you opened an AsciiDoc file:
Install via Emacs Lisp Packages (on Marmalade)
M-x package-install RET adoc-mode RET.
Possible steps after installation
Each of the following is optional
- According to 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))
- 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 for you:
(add-hook 'adoc-mode-hook (lambda() (buffer-face-mode t)))
- sophisticated highlighting
- promote / denote 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)
The next features I plan to implement
- Denote / promote for list items
- Outline support also for two line titles
- Correctly highlighting backslash escapes
The highlighting emphasizes on how the output will look like. All characters are visible, however meta characters are displayed in a faint way.