Reformatting Content

The user can reformat AsciiDoc contents in the editor and on the command line using “Reformat Code”.


The user can reformat AsciiDoc in the editor using “Reformat Code” (Ctrl+Alt+L ⌘ ⌥ L ). They can disable formatting completely or configure parameters using Settings…​  Editor  Code Style  AsciiDoc.

Project-specific settings can be checked-in together with the code as either XML or .editorconfig files to share the settings across all contributors to a project.

Users can reformat a single AsciiDoc file when placing the cursor in an editor, or folders with all files and subdirectories when selecting a folder in the project’s tree view.

Using the command line for reformatting

The IntelliJ IDEA formatter is available form the command line. It allows both reformatting of files and checking that the formatting of the files correct using the “dry run” option.

Styling of the reformatting

Currently, reformatting adjusts empty lines around headings, lists, and blocks. It also adjusts spaces around list items.

By default, it re-formats blocks to the one-sentence-per-line style. The user can disable this in the code style settings.

By default, the IDE will remove leading blanks when pasting content to an AsciiDoc document. This does not change the rendering of the content as those blanks are optional for AsciiDoc. See Indent missing when pasting from clipboard for details on how to disable this.

IDE vs. Project specific settings

Settings can be stored in the IDE instance or within the project. Users can switch change them in the menu Settings…​  Editor  Code Style  AsciiDoc.

Project-specific settings can be stored in two different ways: an XML file in the folder .idea/codeStyles, and in an .editorconfig file.

Settings per IDE instance

When storing settings in the IDE instance, they are active across projects opened with this IDE. If a user has multiple IDE instances installed on a single machine, each IDE instance will use its own configuration.

Settings per project as an XML file

The XML file is specific to IntelliJ. Depending on the project’s version control system configuration, the folder .idea/codeStyle might be ignored. When using Git as a version control system, users should check their .gitignore file if the folder or its contents are ignored, and amend the configuration to allow files to be committed there. Once the file has been committed, the formatting settings are available to other users as well.

Settings per project as an .editorconfig file

The .editorconfig file is an open standard that allows for several configuration options that will be applied across IDEs of different vendors. For some IDEs, an additional plugin might be necessary to support the features.

The JetBrains family of IDEs supports the .editorconfig files out of the box. It also allows custom properties starting with ij_. The AsciiDoc plugin for IntelliJ uses custom properties starting with ij_, therefore, those settings are only effective for IntelliJ.

The settings in an .editorconfig file become effective in IntelliJ once the user saves and closes the editor of the file.

An example AsciiDoc configuration for the AsciiDoc plugin for IntelliJ in an .editorconfig file looks as follows:

An example .editorconfig file with the default settings
root = true

# Common AsciiDoc settings that work across IDEs
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

# Custom settings for the IntelliJ AsciiDoc plugin
ij_asciidoc_blank_lines_after_header = 1
ij_asciidoc_blank_lines_keep_after_header = 1
ij_asciidoc_formatting_enabled = true
ij_asciidoc_one_sentence_per_line = true

The file with root = true should be placed in the root folder of the project. Files without this attribute in sub folders override the settings in that folder.

When editing the .editorconfig files in the IDE, IntelliJ offers auto-completion and validation.