Features of the Editor

Summary of the features of the editor for navigation, writing and reformatting.

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 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 to unfold it. The hotkey to unfold one element is Shift+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 sub-tree in the structure view. Clicking on either a referenced file or an element of a sub-tree 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 check box “Soft-wrap files”.

There is also the option to enable soft-wrap for a single file in the editor toolbar. If the user enables soft wrap per file multiple times, an editor notification appears and suggests enabling soft wrap in the IDE settings.

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 mono spaced text like `filename.txt` or `JavaClassName`) or in underscores (as italic 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 selected 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:

[source,json]
----
{ "key": "value" }
----

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 dictionary file via File  Settings…​  Editor  Spelling. Dictionaries are available online for example at http://www.winedt.org/dict.html. Word lists need to be in the UTF-8 format to work.

Once the user installed the Grazie plugin the editor highlights possible grammar and spelling mistakes. For now text must be included in a section or block to be checked. A minimal file would therefore contain at least a heading and some text. The user needs to enable spell checking in the Grazie settings. Grazie supports multiple languages: Once the user configured the languages in Grazie’s plugin 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.

The API of Grazie changed recently, therefore use the following minimum versions: IntelliJ (2019.3), Grazie plugin (2019.3-6.2.stable) and AsciiDoc plugin (0.30.20).

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

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

Writing

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

  1. a snippet [source,java receives a closing bracket and two listing separator lines.

  2. a snippet include::text.adoc receives an opening bracket, a leveloffset= if it can be derived from the current file’s context and the context of the included file, and a closing bracket.

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

For references, attributes and images, and several macros like include, image and diagrams it provides auto-completion using Ctrl+Space. References and attributes support renaming within a project.

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 tries to find a declaration of the imagesDir attribute either in any of the AsciiDoc files of the project.

There are several live templates included. Once the user starts typing ad, a list of templates appears. Continued typing of any character of the template name restricts the list. A Tab selects and entry. Users can add their own live templates to avoid repetitive typing and to ensure consistency.

The user can copy images from the clipboard into the document. To do that 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 just 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.

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

The editor runs inspections on the content. Once it finds for example Markdown-styled headings, Markdown-styled horizontal rules or Markdown-styled listings it highlights this as a warning. The user can use Ctrl+Enter to select a quick-fix to 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:

// suppress inspection "AsciiDocReferencePattern"
[[invalid!]]

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

// suppress inspection "AsciiDocLinkResolve" for whole file
// ...
<<ref>>

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

The user can extract and inline includes. This is available from the “Refactor” context menu and via context-sensitive intentions via Alt+Enter (“Inline Include Directive” and “Extract Include Directive”). Extract extracts either the selected text, the current block or the current section including subsections. Inline inlines the referenced file at the current include; optionally it can provide a preview, inline all occurrences of the file and delete the included file afterwards.

Available from release 0.31.35:

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 section about reformatting on how to configure this.

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

Reformatting

The user can reformat the source in the editor using “Reformat Code” (Ctrl+Alt+L).

The user can disable formatting completely or configure parameters using Settings…​  Editor  Code Style  AsciiDoc. Currently it adjusts empty lines around headings, lists and blocks. It also adjusts spaces around list items.

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