Using tables with AsciiDoc in IntelliJ

How to use tables in AsciiDoc documents efficiently when working with IntelliJ. Tables help technical writers to structure content for their readers.

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.

Creating a new table

There are multiple ways to create an AsciiDoc table in IntelliJ. See the following sections for an overview.

For large tables, consider the CSV format.

Live template

Type on the keyboard ad-table and use a live-template to create a table. To find out more about live templates, see the Live Templates page.

Draw the size of the table

Use the menu icon for tables () and use the mouse to create a table of the desired size.

Create table by size

As above, but select Create Table Dialog… to specify the table’s height and width.

Paste a table from a spreadsheet

As above, but select Paste Table… to paste a table which has been copied, for example, from a spreadsheet program to the clipboard. For this to work usually tab separator works best. Independent of the format the user selects, it is converted to the standard AsciiDoc table when pasted.

Use CSV or other delimited formats

Use an include directive to create a table from a CSV file. This is ideal for large, uniform tables.

IntelliJ includes CSV file support, see the screenshots at the end of this section. It allows adding and moving rows and columns more efficiently than the standard AsciiDoc format. Therefore, the CSV contents should be included from a separate file and not edited in the AsciiDoc file directly.

Such a CSV file can even be edited in a spreadsheet program if required.

A table that reads data from a CSV file reads as follows:

[%header,format=csv]
|===
include::tracks.csv[]
|===

When opening the CSV file in IntelliJ for the first time, it will show in a standard editor.

To configure the CSV format, click on the table icon in the upper right of the editor. To switch to the table view click on the Data tab at the bottom.

See the AsciiDoc manual about tables in CSV, TSV and DSV data format for details what data formats are supported.

Future ideas

For future ideas about editing tables, follow this GitHub issue asciidoctor/asciidoctor-intellij-plugin#1256