Customize tables

Styling the tables used in your technical writing can improve the readability and overall aesthetic of your documentation. This guide will show you how to customize the styling of Markdown and Markdoc tables using CSS.

Redocly supports tables written in both Markdown and Markdoc syntax.

Before you begin

These are useful to have before you begin:

• Basic CSS knowledge
• A Realm, Reef, or Revel project with a @theme/styles.css file set up

Table styling basics

In Redocly projects, you can create global styles that apply to all tables or style tables individually. Most table styling requires custom CSS.

• Global table styles use CSS variables defined in global scopes.
• Individual table styles rely on the creative use of CSS selectors.

Many table styling needs are met with only CSS variables. However, more advanced styling requires working with CSS selectors to reference specific table elements.

HTML table structure

Tables written in Markdown or Markdoc resolve to HTML when they render. The table's HTML tags are used in the CSS selectors to apply more granular styling. Understanding the tags and structure of HTML tables will help you customize styles more effectively.

  <table>
    <thead>
      <tr>
        <th>Heading 1</th>
        <th>Heading 1</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>Cell 1</td>
        <td>Cell 2</td>
      </tr>
      <tr>
        <td>Cell 4</td>
        <td>Cell 5</td>
      </tr>
    </tbody>
  </table>

Add global table styles

To customize the styling of all tables by adding global styles:

1. Ensure the @theme/styles.css file has a :root selector. Add one if not.

   • Also add :root.dark if using color modes.

2. Style tables by setting the table CSS variables inside :root and :root.dark.

   • If needed, use browser dev tools to identify CSS variables for tables.

3. (Optional) Use the table's HTML tags as selectors to style elements not covered by CSS variables.

The following example adds global table styles that change with the color mode:

:root {
  --md-table-cell-padding: 8px;
  --md-table-border-color: black;
  --md-table-header-bg-color: #EDEDF2;

  & table {
    border-collapse: collapse;
  }
}
:root.dark {
  --md-table-border-color: white;
  --md-table-header-bg-color: #3B3D44;
}

Style Markdown tables

Customize the style of individual Markdown tables or table elements using CSS. This approach uses CSS selectors based on the table's header content to apply styling. Markdown tables that share matching headers will both receive the same styling.

Use the data-label

When a Markdown table renders, each header value is automatically added as a data-label attribute on the th tag. Use that attribute to apply custom styling to a specific column or table.

The following example sets the width of the "Favorite veggie" column in the Markdown table:

:root th[data-label="Favorite vegetable"] {
  width: 80%;
  background-color: lightyellow;
}

Combine CSS selectors

Combine the data-label with other CSS selectors for more advanced table styling capabilities, as in the following example:

:root table:has(th[data-label="Favorite animal"]) {
  --md-table-border-color: black;
  --md-table-header-bg-color: gold;

  & tr:nth-child(even) {
    background-color: cornsilk;
  }
}

:root.dark table:has(th[data-label="Favorite animal"]) {
  --md-table-border-color: white;
  --md-table-header-bg-color: indigo;

  & tr:nth-child(even) {
    background-color: mediumpurple;
  }
}

This example sets the table border color, header background color, and adds alternating stripes.

Style Markdoc tables

Customize a Markdoc table by adding attributes or custom classes to the table's Markdoc tag. Attributes offer streamlined control of the table layout while classes offer complete control over styling. They can be combined.

Use built-in attributes

Customize the layout of Markdoc tables using attributes built into the table tag. Three Markdoc attributes (width, align, colspan) control the layout of a table without any CSS changes.

The following example shows a Markdoc table customized using attributes:

{% table %}
  * Person
  * Favorite food {% width="80%" %}
---
  * Pizza {% colspan=2 align="center" %}
---
  * Annabelle
  * Bacon
---
  * Oliver
  * Popsicle
---
  * Daisy {% align="right" %}
  * Dog treats
{% /table %}

Create custom classes

Create custom CSS classes for more advanced styling of Markdoc tables. The classes can be added to the Markdoc tag, as in the following example:

:root .striped-table-rows {
  --md-table-border-color: black;
  --md-table-header-bg-color: royalblue;

  & tr:nth-child(even) {
    background-color: lightskyblue;
  }
}

:root.dark .striped-table-rows {
  --md-table-border-color: white;
  --md-table-header-bg-color: darkgreen;

  & tr:nth-child(even) {
    background-color: mediumseagreen;
  }
}

{% table .striped-table-rows .md %}
  * Person
  * Favorite activity
---
  * Taylor
  * Snowboarding
---
  * Annabelle
  * Roblox
---
  * Oliver
  * Swings
---
  * Daisy
  * Dog park
{% /table %}

Related How tos

• Customize styles - Learn to customize the styles of your Redocly projects.
• Customize color modes - Add unique styling for each color mode.

Resources

• Styling - Learn how styling works in Realm.
• Color mode - Learn how color modes work in Realm.
• CSS variables dictionary - See a list of available CSS variables.