Navigating in an IntelliJ Project

How to follow references and navigate within in an IntelliJ Project.

Navigation is used to describe how to get from one AsciiDoc file to a referenced image or another AsciiDoc file. Searching content is used here to filter content, for example, with a keyword. Read more about searching in Searching in an IntelliJ Project.

This is part of the step-by-step series to set up a technical writing environment with IntelliJ and the AsciiDoc plugin. See the page Setup for technical writing for an overview of all steps.

Prerequisites

This assumes that IntelliJ IDEA is open with a project with some existing content. See Opening a project in IntelliJ IDEA and Editing an AsciiDoc file in IntelliJ on how to do this.

This section describes how to get from one AsciiDoc document to related documents Use the menu item Navigate for a full list of options, or use Help  Find Action…​ to search all action available in the IDE.

While all other sections describe how to navigate forward, these are the most common ways to return to files opened previously:

  • To return to a previous file, use Ctrl+E ⌘ E and select the file to return to.

  • Use Alt+Shift+Left Alt+Ctrl+Left ⌘ ⌥ ← and Alt+Shift+Right Alt+Ctrl+Right ⌘ ⌥ → to move backwards and forwards in the latest cursor positions.

  • To return to the previous editing position, use Ctrl+Shift+Backspace ⇧ ⌘ ⌫.

Moving the cursor within a file

The editor shows the content. After placing the cursor in the editor pane, the user can use the cursor keys to move up, down left and right, use the mouse and the scroll bar to move up and down, and also place the cursor. Use Alt+Up ⌃ ⇧ ↑ and Alt+Down and ⌃ ⇧ ↓ to move the keyboard cursor by paragraph. Use Ctrl+Left ⌥ ← and Ctrl+Right ⌥ → to move the keyboard cursor by one word.

Navigation to referenced resource

After pressing the Ctrl ⌥, all elements that allow navigation show as underlined when the mouse cursor hovers over them. This works file names and references in macros like xref:[], images:[] and include::[]. When the user clicks the element while the Ctrl ⌥ key is still pressed, the IDE opens the referenced resource in an editor. If there are multiple possible targets, the IDE shows a list of targets for the user to choose the one to navigate to.

The same functionality works when placing the editing cursor with the keyboard on such a reference, and pressing Ctrl+B ⌘ B.

Finding other usages of an element

For each named element like an included file or a reference, the user can find its usages. With the mouse, this is available from the context menu which opens when right-clicking on the element. It is also available as a shortcut via Alt+F7 Alt+Shift+7 ⌥ F7.

Jump to a line/column in a file

To jump within the current file, press Ctrl+G ⌘ L and enter the line, optionally followed by a colon and the column to where to jump to.

To jump to a different file, press Ctrl+Shift+N ⌘ ⇧ O and enter the file name, optionally followed by a colon with the line and optionally followed with a colon with the column.

By default, the plugin shows a split view for each AsciiDoc file showing both the editor and the preview. Users can choose to show only the preview or only the editor via the icons in the menu bar or via the plugin’s settings via File  Settings…​  Languages & Frameworks  AsciiDoc.

Once the user places the cursor in the editor, the preview scrolls so that it shows the paragraph where the cursor is placed.

  • Clicking on an external link opens it in a new window of the system’s browser.

  • Clicking on an internal link opens the target in the editor.

  • Clicking on text content places the cursor in the editor in that paragraph. If the content is from an included AsciiDoc file, the editor opens that file in a new editor tab.

The structure view is usually hidden. The user opens and hides it by clicking on Structure in the tool border of the IDE’s window in the lower left corner.

intellij structure view

It always shows the structure of the current editor. Use the icons in front of the structure view to expand and collapse parts of the tree. Click on an item to open the referenced file in the editor and place the cursor on that item.

Using the keyboard, the same view is available via Ctrl+F12 ⌘ F12. Users can then use the keyboard to narrow it down to entries containing the typed text.

When the current file contains several levels of section headings, there is a hierarchical view of the current levels at the bottom of the editor. Clicking on any of the levels shown there places the cursor on the element named there.

The user opens and hides the project view by clicking on Project in the tool border of the IDE’s window.

intellij project view

In the upper right corner there are different view variants. For technical writing, the style Project should be used.

In the upper right corner is a crosshair icon: Clicking it selects the file that is opened in active editor in the tree view which allows locating a file in the project’s hierarchy.

For each file, the user can find its usages, for example, where an AsciiDoc file is used as in an include::[] preprocessor macro. With the mouse, this is available from the context menu which opens when right-clicking on the element. It is also available as a shortcut via Alt+F7 Alt+Shift+7 ⌥ F7.

Even when the project tool window is closed, the user can use the navigation bar to navigate the file tree using the current editor’s file path.

Further reading

Read more about keyboard shortcuts in Using Hotkeys and IntelliJ’s docs about Navigating through the source code.

Continue to Searching in an IntelliJ Project for the next step of this series.