Tables

Using tables to simplify content and data provides a comprehensive way to arrange design, structure, outlines, pattern, or order. It is a great tool for comparisons, breakdowns, lists, functions, and descriptions.

Here are some tips when creating tables:

Label column headers.
Label row headers if appropriate.
Avoid merged cells. When cells are merged, it impacts how a screen reader navigates the page.
Avoid too much text.
Aim for parallelism within the column.
Keep tables as simple and as small as possible.
Sort rows in a logical order. If no logical order exists, use alphabetical order.
Introduce tables with a complete sentence that describes the purpose of the table because not all screen readers preannounce tables. The introductory sentence can end with a colon or a period; usually a colon if it immediately precedes the table, and usually a period if there's more material (such as a note paragraph) between the introduction and the table.

Introductory sentences

Introduce tables with a complete sentence that describes the purpose of the table because not all screen readers preannounce tables. The introductory sentence can end with a colon or a period; usually a colon if it immediately precedes the table, and usually a period if there's more material (such as a note paragraph) between the introduction and the table.

When referring to a table, use a phrase like "the following table" or "the preceding table." Do not place a table in the middle of a sentence.

Column headings

Use sentence case.
Write concise headings that clearly describe the column content.
Do not end column headings with punctuation, including periods, ellipses, or colons.
Use the th element for column headings in HTML tables. Include the scope attribute for accessibility.

<thead>
  <tr>
    <th scope="col">Name</th>
    <th scope="col">Description</th>
  </tr>
</thead>

Table placement

Place each table directly after the sentence that introduces it.
Do not place a table in the middle of a numbered procedure. Place the table immediately after the relevant step.
If a table has footnotes, place them immediately after the table.

Table captions

If a page contains only one table, it does not need a caption. Place the table adjacent to the text that refers to it.

If a page contains more than one table in close proximity, add a caption to each table. Start the caption with a number in the form Table NUMBER. followed by a brief description. Use sentence case. Do not place a period at the end of the caption.

When referring to a captioned table from text, refer to it by number — for example, "as shown in table 2." Do not capitalize "table" unless it starts a sentence.

In Markdown, place the caption as a bold line immediately before the table:

**Table 1.** Supported DNS record types

| Type | Description |
| --- | --- |
| A | Maps a domain to an IPv4 address |
| AAAA | Maps a domain to an IPv6 address |

In HTML, use the caption element as the first child of the table element:

<table>
  <caption><b>Table 1.</b> Supported DNS record types</caption>
  <thead>
    <tr>
      <th scope="col">Type</th>
      <th scope="col">Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>A</td>
      <td>Maps a domain to an IPv4 address</td>
    </tr>
  </tbody>
</table>

When to use tables

Tables display pieces of information that have some sort of relationship.

Example:

Dates and descriptions, like a changelog
A list of products with attributes

When not to use tables

Do not use tables to format a page.

Markdown examples

Add a table

To add a table, use three or more hyphens (---) to create each column’s header, and use pipes (|) to separate each column. For compatibility, you should also add a pipe on either end of the row.

| Syntax      | Description |
| ----------- | ----------- |
| Header      | Title       |
| Paragraph   | Text        |

The rendered output looks like this:

Syntax	Description
Header	Title
Paragraph	Text

Tip: Creating tables with hyphens and pipes can be tedious. To speed up the process, try using the Markdown Tables Generator ↗.

Alignment

You can align text in the columns to the left, right, or center by adding a colon (:) to the left, right, or on both side of the hyphens within the header row.

| Syntax      | Description | Test Text     |
| :---        |    :----:   |          ---: |
| Header      | Title       | Here is this  |
| Paragraph   | Text        | And more      |

The rendered output looks like this:

Syntax	Description	Test Text
Header	Title	Here is this
Paragraph	Text	And more

Formatting text in tables

You can format the text within tables. For example, you can add links, code, and emphasis.

You can’t add headings, blockquotes, lists, horizontal rules, images, or HTML tags.

Escaping pipe characters in tables

You can display a pipe (|) character in a table by using its HTML character code ("|").

HTML examples

For complex tables, consider using HTML. The following example is created with HTML:

Field Description

Field	Description
`http.cookie` `String`	Represents the entire cookie as a string. Example value: `session=8521F670545D7865F79C3D7BEDC29CCE;-background=light`
`http.host` `String`	Represents the hostname used in the full request URI. Example value: `www.example.org ↗`

http.cookie
String

Represents the entire cookie as a string.

Example value:
session=8521F670545D7865F79C3D7BEDC29CCE;-background=light

http.host
String

Represents the hostname used in the full request URI.

Example value:
www.example.org ↗