Setup for technical writing

This article guides users new to IntelliJ IDEA through the necessary steps to set up their environment for technical writing with AsciiDoc.

It describes best practices and shows an opinionated approach to make it simple for users new to IntelliJ.

For users already familiar with JetBrains IntelliJ, there’s a Quick Start documentation. For advanced installation options, see the page Installing the plugin.

Why to use IntelliJ for technical writing

The AsciiDoc plugin provides an as-you-type preview, syntax highlighting, auto-completion and content validation in one plugin. The IntelliJ IDE offers a great integration with Git and also plugins for spell and grammar checking.

To get a full overview of all features of the plugin, see Features of the IntelliJ AsciiDoc plugin.

Steps to set up a writer’s environment

Follow these steps to set up IntelliJ IDEA as the tool for technical writing. Each page gives a brief overview to get started and links to other pages in this guide for additional information.

udemy course There is an online course at Udemy that contains approx. 60 minutes of video content covering several chapters of this guide. By clicking on this affiliate link, you ensure that almost all the money you pay is forwarded to the maintainer of this plugin.

If the information in the following pages is missing an aspect and leaves questions unanswered, visit the Getting help from docs and other users page to find more documentation resources and learn where to contact other users of the plugin to collaborate and to get answers to questions.

  1. Installing IntelliJ IDEA as the workplace for technical writing.

  2. Starting IntelliJ IDEA for the first time and installing the AsciiDoc plugin.

  3. Opening the first project in IntelliJ IDEA.

  4. Adding a file to a project and editing AsciiDoc content in an existing project.

  5. Navigating from one file to other referenced files in a project.

  6. Searching AsciiDoc content in a project.

  7. Learning the AsciiDoc syntax.

  8. Using tables with AsciiDoc an IntelliJ.

  9. Collaborate with others using IntelliJ IDEA’s Git integration.

  10. Preparing a Git repository for AsciiDoc and IntelliJ to work with a team of technical writers.

  11. Using IntelliJ with Antora, the static site generator for AsciiDoc content.

  12. Enhance a writer’s productivity with plugins for IntelliJ.

Improving this guide

Each of the pages in the guide has an “Edit this page” link in the upper right corner. Use this to edit the content on GitHub. As an alternative, all content to this guide is hosted in the Git repository of the AsciiDoc plugin in the doc folder, so it can be edited in an IDE like any other AsciiDoc content.

If there are missing features, contact the maintainer via email or create an issue on GitHub.

Further reading

To read more about structuring a project for Antora, see Decisions around Antora for the discussion of different aspects.

To get a full overview of all features of the plugin, see Features of the IntelliJ AsciiDoc plugin.

To customize the plugin’s settings, see Configuring the plugin for recommended settings.