Paragraphs (and other block elements) within tables

Avoid using block elements within normal tables. Only when a table cell contains more than one idea, fact or point should child block elements be used. Do not use block elements in simple tables.

In DITA, the cells of a table normally contain plain text (technically, string data). However, table cells may also contain paragraphs, lists, and other block elements (block data). This characteristic of table cells results in a choice for authors of whether to enter plain text or paragraphs in cells.

For example, a simple table cell could be coded as string data <stentry>2.5 litre engine</stentry> or block data <stentry><p>2.5 litre engine</p></stentry>. It is also technically valid to have a mix of string and block data, where one cell has plain text and another has paragraphs.

The best practice mark-up is the simplest mark-up.

If there is just one block of text in the cell, then the cell should be left as string data. This stores the minimum of mark-up, and simplifies the processed output. If there are multiple blocks in the cell, then paragraphs (or other block items) should be used. String data should not be used in the same cell as block data.

If there is a need for one cell to include block elements, then all cells should be consistently treated. Using mixed mark-up methods (blocks in some cells and string-only in others) are likely to result in inconsistent rendering of the output.

In particular, simple tables (simpletable elements) should be kept as simple as possible. If a table requires block elements in cells, it should be coded as a normal table rather than a simple table.