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
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 ([!UICONTROL 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.

Specifying how tables are rendered

We can render tables in two ways:

  • Fixed (currently the default) - Includes custom rules for rendering tables, including HTML tables with images. Tables are rendered as full-width with no scrolling, which sometimes causes overlapping text.
  • Auto - Similar to Git-flavored Markdown (GFM). Tables are allowed to scroll, so text does not overlap.

In most cases, the tables are rendered with the same appearance. However, if your table includes overlapping text, you’ll want to apply the auto tag. Or, if your HTML table with image cards isn’t rendering properly, you might want to apply the fixed tag.

We’re considering changing the default from fixed to auto.

Editing Markdown tables

If you want to specify how a native markdown table is rendered, add one of these syntax lines AFTER the table, with blank lines before and after:

  • {style="table-layout:auto"}
  • {style="table-layout:fixed"}

table-rendering

Editing 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:auto">
  • <table style="table-layout:fixed">
<table style="table-layout:fixed">
  <tr>
    <th>Month</th>
    <th>Savings</th>
  </tr>
  <tr>
    <td>January</td>
    <td>$100</td>
  </tr>
</table>

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 (Default)

Insights metric Description ID query parameter
timeseries.data.collection.validation.category.type.count Total number of invalid “type” messages for one dataset or for all datasets. Dataset ID
timeseries.data.collection.validation.category.range.count Total number of invalid “range” messages for one dataset or for all datasets. Dataset ID
timeseries.data.collection.validation.category.format.count Total number of invalid “format” messages for one dataset or for all datasets. Dataset ID
timeseries.data.collection.validation.category.pattern.count Total number of invalid “pattern” messages for one dataset or for all datasets. Dataset ID
timeseries.data.collection.validation.category.presence.count Total number of invalid “presence” messages for one dataset or for all datasets. Dataset ID
timeseries.data.collection.validation.category.enum.count Total number of invalid “enum” messages for one dataset or for all datasets. Dataset ID

Auto

Insights metric Description ID query parameter
timeseries.data.collection.validation.category.type.count Total number of invalid “type” messages for one dataset or for all datasets. Dataset ID
timeseries.data.collection.validation.category.range.count Total number of invalid “range” messages for one dataset or for all datasets. Dataset ID
timeseries.data.collection.validation.category.format.count Total number of invalid “format” messages for one dataset or for all datasets. Dataset ID
timeseries.data.collection.validation.category.pattern.count Total number of invalid “pattern” messages for one dataset or for all datasets. Dataset ID
timeseries.data.collection.validation.category.presence.count Total number of invalid “presence” messages for one dataset or for all datasets. Dataset ID
timeseries.data.collection.validation.category.enum.count Total number of invalid “enum” messages for one dataset or for all datasets. Dataset ID

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

Lead Main editing workflow for lead writers.
Infrequent Not a lead writer? Learn the easiest ways to make contributions. Not a lead writer? Learn the easiest ways to make contributions. Not a lead writer? Learn the easiest ways to make contributions. Not a lead writer? Learn the easiest ways to make contributions. Not a lead writer? Learn the easiest ways to make contributions. Not a lead writer? Learn the easiest ways to make contributions.
Validation Learn to resolve validation errors.

Fixed (in more ways than one)

Lead Main editing workflow for lead writers.
Infrequent Not a lead writer? Learn the easiest ways to make contributions. Not a lead writer? Learn the easiest ways to make contributions. Not a lead writer? Learn the easiest ways to make contributions. Not a lead writer? Learn the easiest ways to make contributions. Not a lead writer? Learn the easiest ways to make contributions. Not a lead writer? Learn the easiest ways to make contributions.
Validation Learn to resolve validation errors.

On this page

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now