Tables

Tables is one of the drawbacks to using Markdown. Standard Markdown supports only basic tables. For AdobeDocs Markdown, you have the following options:

  • Basic Markdown tables
  • HTML tables
  • Markdown tables with limited HTML extensions for line breaks and basic lists

Converting HTML tables to Markdown 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.

Tool What it does
markdownTables Converts the HTML table to a stripped-down Markdown table. It removes all formatting, links, and images.
Turndown Converts the HTML table to Markdown code in non-table format. This is useful when a table isn’t necessary or when cobbling together a table.
Markdown Tables Generator Good for creating Markdown tables from scratch.

Before you use markdownTables to convert an HTML table, consider replacing the HTML formatting for keywords and uicontrol to the Markdown equivalent (text). See the section about wildcard searching.

Basic Markdown tables

  • Make sure that you add at least three hyphens in the second row that determines the table properties.
  • Tables must have at least one header row and one body row. You cannot create a one-row or one-cell table.
  • Make sure that each row has the same number of pipe ( | ) characters. If you need to include a pipe character within a table cell, escape by preceding it with a backslash (\|) or using the HTML entity code (|).
  • Be careful about using code blocks in tables. Inline code blocks can cause disproportionate column widths.

Creating Markdown tables with HTML extensions

To facilitate migration, we’ve extended Markdown tables to support HTML 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<br>second 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

Header 1 Header 2 Header 3
Normal row row 1 column 2 row 1 column 3
Line break first line in cell
second line in cell
row 1 column 3
Bullet list Bullet list:
  • Item 1
  • Item 2
  • Item 3
row 2 column 3
Bullet list with line break Bullet list:
  • Item 1
  • Item 2
  • Item 3

This is a new line after the bullet list
row 2 column 3
IMPORTANT

If you decide to use HTML in native tables, make sure that you use proper HTML syntax. Mistakes in HTML syntax results in validation errors that are difficult to understand. Double-check your work.

Working with HTML tables

The migration tool tried to preserve as much formatting as possible from the original table. Most of this HTML syntax is ignored, while some of this syntax results in validation errors.

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

Property Type Value Description
badgingPath String[]

(Required) 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:

/etc/community/badging/images/expert-badge/jcr:content/expert.png

badgingLevels Long

(Optional) Specifies the levels of expertise to be awarded. For example, if there should be an expert and an almost expert (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.

badgingType String

(Required) Identifies the scoring engine as either "basic" or "advanced". Set to "advanced" else the default is "basic".

Notes for working with HTML tables

  • Don’t use Markdown syntax in HTML tables. For example, if you add [!NOTE] to an HTML table, it will be rendered as is ([!NOTE]). Instead, use HTML syntax to format a note, add an image, and tag terms for localization.
  • Width, height, alignment, color, and other values are ignored. You can leave these values in unless they result in a validation errors.
  • HTML tables cannot include nested tables or column spans.
  • Convert class="value" as needed. With the exception of localization classes such as “wintitle” and “uicontrol”, we ignore class. For example, <span class="codeph">term</span> is ignored. However, if you convert these classes to simple HTML code elements, such as <code>term</code>, the content will render properly.

On this page