Editing AsciiDoc Content

The user can fold sections and blocks using the small +/- symbols on the left of the editor. Folded sections and blocks show their first line except when this is block id (like [[id]]).

As an experimental feature, predefined attributes for character replacements like {plus} or {quot} and attributes are foldable as well. Attributes need to resolve to a single declared value to be folded. Folding is also available for HTML entities (like &) and unicode characters (like †). As an experimental feature, the user needs to enable it in the settings of the plugin.

Clicking on a folded attribute unfolds it. The hotkey to unfold one element is Ctrl+NumPad+, the hotkey to fold one element is Shift+NumPad- The hotkey to unfold all elements is Ctrl+Shift+NumPad+, the hotkey to fold all elements is Ctrl+Shift+NumPad-.

The structure of the file Alt+7 shows the hierarchy of sections and blocks with titles. This contains (if available) the first block attribute element (like [source], [quote] or [verse]) and the title of the block or section. If an element like an image::[] references another file, it shows the icon and the name of the file. If an include::[] references an AsciiDoc file, it includes the file as a subtree in the structure view. Clicking on either a referenced file or an element of a subtree opens the referenced file.

The search all view ShiftShift shows section titles and IDs of blocks.

The breadcrumbs-view (bottom of the editor) shows the hierarchy leading to the current sections and blocks. It contains the same elements as in the structure view for the cursor position.

AsciiDoc recommends the one-sentence-per-line style. To avoid scrolling horizontally, the user should enable soft-wrap in the IDE. Go to Settings  Editor  General, scroll to Soft Wrap, add the AsciiDoc file extension (if not already pre-populated) and activate the checkbox “Soft-wrap files”.

The user can toggle soft-wrap for a single file via the editor toolbar. If the user hasn’t enabled soft wrap per default, an editor notification appears and suggests enabling soft wrap per default in the IDE settings.

Soft wrapping adds an indent on each wrapped line. To disable this, users can set a custom IDEA property via Help  Edit Custom Properties. Adding these two properties and restarting the IDE will change the soft wrap arrow to a zero-width space.

For include::[] and image::[] block macros the keys Ctrl+Click and Ctrl+B navigate to the referenced file.

For references (like <<id>>) the keys Ctrl+Click and Ctrl+B navigate to the reference (like [[id]]). This works similarly for attributes ({attrib} and :attrib:). “Find Usages” (Alt+F7) finds usages of references and attributes and allows navigation.

The user can navigate using Ctrl+Click and Ctrl+B from a file name or Java class name in backticks (as monospaced text like `filename.txt` or `JavaClassName`) or in underscores (as italic text like _filename.txt_ or _JavaClassName_) or asterisks (as bold text like *filename.txt* or *JavaClassName*). The plugin tries to rename occurrences of files and Java classes in the AsciiDoc file when the user renames the file or the class.

The user can show a quick documentation for the element at the cursor’s position using Ctrl+Q. At the moments this works for attributes ({attrib} and :attrib:) both in the editor and when using autocomplete.

The plugin highlights matching braces including symmetric formatting for bold, italic and monospace. When the user selects some text and types a formatting character like _ or *, the plugin formats selected text by adding the formatting at the beginning and end of the selected text. The plugin uses constrained/unconstrained formatting as necessary. If the selected text already has the chosen formatting, the plugin removes the formatting from the selected text.

When the user adds a source code block with information about the language, the plugin will highlight the code block if IntelliJ supports the language. A source block like the following will receive JSON highlighting:

In the settings the user can enable and disable this feature, including fine-tuning on a per-language level, and if errors should be highlighted or not.

The plugin expands the current selection when the user presses Ctrl+W and contracts the current selection when the user presses Ctrl+Shift+W.

IntelliJ’s built-in spell checker verifies all text areas of the document. It underlines unknown words with a green wavy line. With the context menu the user can change the spelling or to add the word to the project’s dictionary. To enable spell-checking support for other languages, the user can add a language via File  Settings…​  Editor  Proofreading. The IDE downloads the dictionaries for the selected languages once the user adds the language in the settings.

Starting with IntelliJ 2020.1, the bundled Grazie plugin highlights possible grammar and spelling mistakes in the editor. As of plugin version 0.36.2, every heading and paragraph of the text will be checked. It supports multiple languages: Once the user configured the languages in IDE’s proofreading settings, the plugin detects the language of a section automatically. As it performs all checks locally with the help of libraries from https://languagetool.org/, it doesn’t submit text written in the IDE to a third party cloud service.

Starting with IntelliJ 2021.3, there is the Grazie Professional plugin that adds additional grammar checks and auto-completion when writing text using a neural network. All the processing is still running locally in the IDE. There is an optional invitation-only cloud service for additional checks. This additional plugin can add a significant CPU load when writing and committing texts. It allows integration for project specific rules using the Vale syntax to warn about the usage of specific words or phrases.

During rendering, Asciidoctor might indicate problems in the file including a line number. The editor shows them as red and yellow annotations. Hover over the annotations to see the full warning or error message. The user can disable this feature in the settings. If it is disabled in the settings, errors show up in the event log.

When the text contains Markdown style headings (starting with #) or old style AsciiDoc headings (titles underlined with string or characters matching the length or the heading), the editor highlights this in yellow and offers a quick fix to convert these to a new style AsciiDoc heading.

The editor supports a default and dark theme. The user can change the colors of the theme in the IDE settings.

When using listings with [source,lang], the plugin triggers language injection to the following code block when the IDE supports the language (either by default, or by a language plugin). This allows syntax highlighting and code completion specific to the language of the code block. The user can disable this feature in the settings completely or for selected languages. For the user to re-format the code block, use “Edit Fragment” (Alt+Enter) and “Reformat Code” (Ctrl+Shift+L). Language injection is disabled if the block contains an AsciiDoc pre-processor macro like include::[], as in these cases the code block with pre-processor macros doesn’t represent compilable code.

All comments containing a TODO and FIXME and are indexed in the Todo-View (Alt+6). The user can configure the keywords in the IDE settings.

In the editor, the user can select from a list of browsers that are shown in the upper right corner of the editor to preview the document. The user can also trigger this action from the context menu. To update the preview in the browser, the user needs to refresh the contents by pressing F5 in the browser.

The user can open an AsciiDoc file in an external tool (like for example, Google Chrome with the Asciidoctor Extension installed). To do this, add Chrome as an external Tool in the settings. Provide $FilePath$ as the argument so that Chrome knows where to find the file. The user can assign a shortcut to the external tool using Help  Find action…​  (type the name of external tool)  Alt+Enter  (type the shortcut of choice)  OK.

Sometimes a user wants to run the examples in a document. For source code blocks or inline monospace quoted text, the plugin tries to identify executable commands. If it does, it will show a line marker with a green play button at the left of the editor to execute the command in a local shell. The current project needs to be a trusted project. This is available from plugin version 0.37.14 onwards.

Currently, the following snippets are available to run:

The editor has a toolbar with the most common actions like make bold, adding a link, etc. The toolbar hides when entering the presentation mode to remove distractions for the audience.

When adding block attributes, the plugin supports statement completion (also known as “Smart Enter”) using the shortcut Shift+Ctrl+Enter. For example:

When the user opens a quote or a bracket, the plugin automatically adds a closing quote if it is followed by spaces or a closing bracket.

For references, attributes and images, and several macros like include, image and diagrams it provides auto-completion using Ctrl+Space. Both references and attributes support renaming within a project. Typing characters like {, <, or : as part of a macro or attribute definition will open the auto-completion dialog as well.

When auto-completing folder and file names in macros, the plugin tries to resolve attributes using their values specified in the current file or other files. For image macros it also tries to find a declaration of the imagesDir-attribute in any of the AsciiDoc files in the project.

There are several live templates included. See Live Templates for more information.

The user can copy images from the clipboard into the document. To do that, the user selects “Paste image from clipboard” from the editor’s icon menu or from the context menu. If the clipboard contains a reference to an existing file, the user can choose to copy the file to the project or to create a reference to the image in the AsciiDoc document. If the clipboard contains an image, the user can choose to create a JPEG or PNG file from the clipboard and add the reference to the document. In both cases, the user has the option to configure the image with additional attributes (width and alt text).

As a shortcut the user can also use Ctrl+C and Ctrl+V to add a reference to the image from within the project to the current document. This shortcut doesn’t work yet for copying contents from outside the project.

The user can copy formatted text from the clipboard into the document. To do that, the user selects “Paste formatted text” from the editor’s icon menu or from the context menu. The plugin downloads Pandoc to convert the clipboard’s contents from HTML to AsciiDoc. (This is available from plugin version 0.37.51 onwards.)

The user can enable in the plugin settings that converting contents on paste, then and Ctrl+V will do the conversion automatically.

The editor runs inspections on the content. It finds and highlights Markdown-styled headings, horizontal rules or listings as a warning. The user can use Ctrl+Enter to quickly convert these to AsciiDoc syntax.

To suppress an inspection for a given line, use the quick-fix to add a comment on the line before:

To suppress an inspection for a file, use the quick-fix to add a comment at the beginning of the file:

Use multiple lines to suppress multiple inspections, or separate multiple inspections with commas.

Extract and Inline include directives are available to the user. Include directives can be accessed from the “Refactor” context menu and via context-sensitive intentions via Alt+Enter (“Inline Include Directive” and “Extract Include Directive”). Extract directive can take the selected text, current block or the current section including subsections and extract it as a separate document. Inline directive can take the file referenced via the selected include and put its content in the current document; optionally it can provide a preview, inline all occurrences of the file and delete the included file after inlining it.

The user can change single-line admonition to a block-style admonition. This is available from the “Refactor"` context menu and as a context-sensitive intention "`Refactor to block admonition” via Alt+Enter. It is available when user places the cursor on the start of single-line admonition (like for example NOTE:).

All of these changes can be undone (Ctrl+Z). Refactorings will re-format the refactored block. See the page about Reformatting Content on how to configure this.

The user can disable and enable intentions in Settings…​  Editor  Intentions  AsciiDoc.