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 a 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 (table icon) and use the mouse to create a table of the desired size.

intellij table choose size

Create table by size

As above, but select Create Table Dialog…​ to specify the size of the height and width of the table.

intellij table dimensions

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

intellij table paste

Use CSV or other delimited formats

Use an include to create a table from a CSV file. This is ideals 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.

intellij csv editor 1

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.

intellij csv editor 2

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

Further reading

Read more about keyboard shortcuts in Using Hotkeys.

Continue to Collaborate with others using IntelliJ’s Git integration for the next step of this series.