Tables

You can create tables using markdown syntax or HTML syntax. Markdown tables with limited HTML syntax for paragraph breaks (<p>), line breaks (<br>), and basic lists (<ul>, <ol>).

Create native markdown tables

Basic syntax

| Header | Another header | Yet another header |
|--- |--- |--- |
| row 1 | row 1 column 2 | row 1 column 3 |
| row 2 | row 2 column 2 | row 2 column 3 |

Example

Simple tables work adequately in Markdown. However, tables that include multiple paragraphs or lists within a cell are difficult to work with. For such content, we recommend using a different format, such as headings & text.

Markdown table with paragraph breaks and lists

| Header | Another header | Yet another header |
|------------|----------|----------------|
| row 1 | first paragraph in cell (`<p>`) <p>second paragraph in cell (`br`) <br> `<p>` = paragraph break and `<br>` = line break | row 1 column 3 |
| row 2 | bullet list<ul><li>item 1</li><li>item 2</li><li>item 3</li></ul> | row 2 column 3 |

Example

Markdown table with centered and right-aligned rows

| Left Aligned | Centered | Right-aligned |
|---|:---:|---:|
| row 1 | This is centered text | This is right-aligned |
| row 2 | 23 | 923 |
| row 3 | 1234 | 19234 |

Example

Notes for working with Markdown tables

Create Markdown tables with bonus HTML

To facilitate migration, we’ve extended Markdown tables to support HTML paragraph breaks (<p>), line breaks (<br>), and basic HTML lists (<ul> and <ol>) within Markdown tables.

Markdown table with line breaks and lists

| Header 1 | Header 2 | Header 3 |
|--- |--- |--- |
| Normal row | row 1 column 2 | row 1 column 3 |
| Line break | first line in cell with `<br>`<br>second line in cell with `<p>`<p>third line in cell | row 1 column 3 |
| Bullet list | Bullet list:<ul><li>Item 1</li><li>Item 2</li><li>Item 3</li></ul> | row 2 column 3 |
| Bullet list with line break | Bullet list:<ul><li>Item 1</li><li>Item 2</li><li>Item 3</li></ul><br>This is a new line after the bullet list | row 2 column 3 |

Example

Work with HTML tables

You can use HTML syntax to create tables. HTML tables are more difficult to edit for most writers, but they allow more flexibility such as the ability to create tables without a header row or with combined cells. However, not all HTML syntax is is supported. Unsupported HTML syntax is either ignored or results in validation errors.

By default, HTML tables with a header row are rendered using the “auto” format, while HTML tables without a header row are rendered using the “fixed” format. You can change the rendering format. See Changing how HTML tables are rendered.

When to use HTML tables

Sample migrated HTML table

<table>
 <tbody>
  <tr>
   <th>Property</th>
   <th>Type</th>
   <th>Value Description</th>
  </tr>
  <tr>
   <td>badgingPath</td>
   <td>String[]</td>
   <td><p><i>(Required)</i> A multi-value string of badge images up to the number of badgingLevels. The badge image paths must be ordered so the first is awarded to the highest expert. If there are less badges than indicated by badgingLevels, the last badge in the array fills out the rest of the array. Example entry:</p><p> <code>/etc/community/badging/images/expert-badge/jcr:content/expert.png</code></p></td>
  </tr>
  <tr>
   <td>badgingLevels</td>
   <td>Long</td>
   <td><i><p>(Optional)</i> Specifies the levels of expertise to be awarded. For example, if there should be an <code>expert </code>and an <code>almost expert</code> (two badges), then the value should be set to 2. The badgingLevel should correspond with the number of expert-related badge images listed for the badgingPath property. Default is 1.</p></td>
  </tr>
  <tr>
   <td>badgingType</td>
   <td>String</td>
   <td><p><i>(Required)</i> Identifies the scoring engine as either "basic" or "advanced". Set to "advanced" else the default is "basic".</p></td>
  </tr>
 </tbody>
</table>

Rendered

Notes for working with HTML tables

<table>
<tr style="border: 0;">

Specify how tables are rendered table-rendering

You can render tables in two ways:

Change the rendering format

HTML tables

If you want to specify how an HTML table is rendered, use one of these syntax lines in the first line of the table:

<table style="table-layout:fixed">
  <tr>
    <th>Month</th>
    <th>Savings</th>
  </tr>
  <tr>
    <td>January</td>
    <td>$100</td>
  </tr>
</table>

Markdown tables

If you want to specify how a markdown table is rendered, add one of these syntax lines after the table separated by blank lines:

| Name | Age | State | Favorite Color |
|---|---|---|---|
| Maria | 23 | Ohio | Teal |
| Ignacio | 17 | Iowa | Aqua |

{style="table-layout:fixed"}

Next paragraph

When to use Auto or Fixed

Overlapping text

Use auto for tables with long code blocks or text that causes overlapping text when fixed (default) is selected.

Fixed

Auto

HTML tables with balanced images

Use fixed for HTML tables that require balanced images that become unbalanced when auto is selected. In this example, the images have identical sizes, but there is more text in the middle column.

Auto

Fixed

Tools for converting tables

In some cases, you’ll want to convert an HTML table to a Markdown table or to Markdown text. Perhaps you need to improve the appearance, resolve a validation error, or make it easier to edit going forward.

Unfortunately, we haven’t been able to find a single tool that converts HTML tables well. We usually use some combination of tools to cobble together a decent Markdown table.