Org tutorial for tables

Table of Contents

{Back to Worg's index}

This tutorial briefly describes the use of tables with Org. You can freely improve this tutorial by editing Worg.

Creating a table

While typing

The easiest way to create a table is to directly type the "|" character at the beginning of a line, or after any amount of white space. This will put you in the first field of an atomic table.

| This is the content of the first cell

Once you've finished editing this cell, you can jump to the next one by pressing TAB. Since the row you just started only contains one cell, the next cell is really the first cell of the next row.

| This is the content of the first cell |
| < Here I am after pressing TAB        |

By creating the structure and filling it

You can also create a table from scratch with C-c |. You will be asked for the structure of the table, the default being 5x2 (see org-table-default-size), five columns and two rows:

|   |   |   |   |   |
|---+---+---+---+---|
|   |   |   |   |   |

Then you can jump from one field to another with the TAB key (jump to the next cell) or S-<TAB> (jump to the previous cell). RET will jump to the to the next cell in the same colum, and create a new column if there is no such cell (or if the next row is beyond a separator line.)

By converting a region into a table

Org provides useful ways of converting a region into a table. For this, select a region and press C-c |. For example, press C-c | on this:

some, comma, separated, values

will automagically produce this:

| some | comma | separated | values |

Usually, this command should be smart enough to guess what is the field separator for the region. If each line of the active region contains a TAB or a comma, it will assume this is the separator.

  • If you want to force the comma as a field separator, press C-u C-c |.
  • If you want to force TAB as a field separator, press C-u C-u C-c |.
  • If you want to force a specific number of spaces – say 3 – use C-u 3 C-c |.

Editing the structure of a table

Editing table with Org is pure magic.

Moving rows/columns

Let's say for example that you have this basic table:

| A | B | C |
| 1 | 2 | 3 |
| a | b | c |

With the cursor in the A field, pressing M-<right> will move the A column to the right:

| B | A | C |
| 2 | 1 | 3 |
| b | a | c |

With the cursor in the first row, pressing M-<down> will move the first row down:

| 1 | 2 | 3 |
| A | B | C |
| a | b | c |

Inserting rows/columns

Prefixed with the Shift key, these command will insert a new column or a new row, instead of moving it. For example, with the cursor initially in the B cell, S-M-<right> will insert a new column between A and B

| A |   | B | C |
| 1 |   | 2 | 3 |
| a |   | b | c |

… leaving the cursor in the newly created column.

And S-M-<down> when cursor is in the first row will insert a new row at the beginning of the table:

|   |   |   |
| A | B | C |
| 1 | 2 | 3 |
| a | b | c |

Narrowing the visible part of a column

Sometimes cells can get really wide. If you want to restrict the width visible width of a cell, you need to add a new row to your table.

| <10>             | <15>                        |
| A very wide cell | Another very very wide cell |

Pressing C-c C-c on this table will update the display so that the first and second columns are respectively narrowed to 10 and 15 characters:

| <10>     | <15>            |
| A very=> | Another very => |

When columns are narrowed, it might be useful to temporarily see the content of a cell with C-u <TAB> (or C-u C-c `) or to edit the content in a separate window with C-c `.

Preparing tables for export

This table :

| A | B |
| 1 | 2 |

will be exported like this:

A B
1 2

Adding a table header

This table :

| A | B |
|---+---|
| 1 | 2 |

will be exported like this:

A B
1 2

The horizontal line separating the two rows tells the exporter to consider the first line is the table header.

Grouping columns

You can group columns like this:

|   |  N | N^2 | N^3 | N^4 | sqrt(n) | sqrt[4](N) |
|---+----+-----+-----+-----+---------+------------|
| / | <> |   < |     |   > |       < |          > |
| # |  1 |   1 |   1 |   1 |       1 |          1 |
| # |  2 |   4 |   8 |  16 |  1.4142 |     1.1892 |
| # |  3 |   9 |  27 |  81 |  1.7321 |     1.3161 |
|---+----+-----+-----+-----+---------+------------|

Here is the output:

N N2 N3 N4 sqrt(n) sqrt(N)
1 1 1 1 1 1
2 4 8 16 1.4142 1.1892
3 9 27 81 1.7321 1.3161

Documentation from the http://orgmode.org/worg/ website (either in its HTML format or in its Org format) is licensed under the GNU Free Documentation License version 1.3 or later. The code examples and css stylesheets are licensed under the GNU General Public License v3 or later.