Customize tables

Styling tables in your technical documentation improves readability and aesthetics. This guide shows you how to customize Markdown and Markdoc tables using CSS.

Redocly supports tables written in both Markdown and Markdoc syntax.

Make sure you have the following:

• a basic understanding of CSS
• a @theme/styles.css file in your project

In Redocly projects, you can create global styles for all tables or style individual tables. Most table styling requires custom CSS.

• Define global table styles with CSS variables.
• Create individual table styles using CSS selectors.

CSS variables handle many table styling needs. For more advanced styling, use CSS selectors to target specific table elements.

Markdown and Markdoc tables convert to HTML when displayed. Understanding HTML table structure helps you write more precise CSS selectors for targeted styling.

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

Apply consistent styling across all tables by:

1. Ensuring your @theme/styles.css file has a :root selector.

   • Add :root.dark if using color modes.

2. Setting table CSS variables in your root selectors.

3. (Optional) Using HTML table selectors for elements not covered by CSS variables.

This example adds global table styles with color mode variants:

:root {
  --md-table-cell-padding: 8px;
  --md-table-cell-vertical-align: middle;
  --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;
}

Target specific tables and elements with CSS selectors based on table headers. Tables with matching headers will share styling.

Each header value automatically becomes a data-label attribute on th tags when rendered. Use this attribute to style specific columns or tables.

This example sets the width of the "Favorite vegetable" column and the background color of its header cell:

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

:root.dark th[data-label="Favorite vegetable"] {
  background-color: #5C5300;
}

Create more advanced styles by combining data-label with other CSS selectors:

: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;
    --md-table-cell-text-color: black;
  }
}

Control Markdoc table appearance with attributes or custom classes. Attributes provide quick layout control while classes offer complete styling flexibility.

Shape your table layout with these built-in attributes - no CSS required:

• width - controls column width
• align - sets horizontal text alignment
• valign - sets vertical text alignment (top, middle, or bottom)
• colspan - spans cells across columns
• rowspan - spans cells across rows

Example table customized with attributes:

{% table %}

- Person
- Favorite food {% width="80%" %}

---

- Pizza {% colspan=2 align="center" %}

---

- Annabelle
- Bacon

---

- Oliver
- Popsicle

---

- Daisy {% align="right" valign="middle" %}
- - Dog treats
  - Belly rubs

{% /table %}

For advanced styling, create CSS classes and add them to your Markdoc table tag:

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

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

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

  & tr:nth-child(even) {
    background-color: mediumseagreen;
    --md-table-cell-text-color: black;
  }
}

Add the class to the table tag together with the .md class. A custom class replaces the default .md class. Without .md, the table loses the default theme styling.

{% table .example-striped-table-rows .md %}

- Person
- Favorite activity

---

- Taylor
- Snowboarding

---

- Annabelle
- Roblox

---

- Oliver
- Swings

---

- Daisy
- Dog park

{% /table %}

Highlight important information by styling specific rows in your tables. Add a CSS class directly to a row in your Markdoc table, then target that class in your CSS.

/* Style all cells in rows containing the class */
:root tr:has(.highclick) > * {
  background-color: yellow;
  --md-table-cell-text-color: black;
}

:root tr:has(.medclick) > * {
  background-color: lightyellow;
  --md-table-cell-text-color: black;
}

:root.dark tr:has(.highclick) > * {
  background-color: gold;
  --md-table-cell-text-color: black;
}

:root.dark tr:has(.medclick) > * {
  background-color: khaki;
  --md-table-cell-text-color: black;
}

Here's how to apply these classes to specific rows:

{% table .md %}

- Task
- Clicks required
- Notes

---

- Change your logo {% .highclick %}
- 10
- Only found details on Getting started page

---

- Change the color of a heading
- 2
-

---

- Revert changes {% .medclick %}
- 8
- Could be highlighted more in the sidebar

---

- Add admonition
- 3
-

{% /table %}

This example shows how to highlight high-click tasks in yellow and medium-click tasks in light yellow, with appropriate dark mode alternatives.

• Customize styles - Customize your project's appearance using CSS variables and custom stylesheets for comprehensive styling control
• Customize color modes - Apply different table styling for light and dark modes with mode-specific color schemes and CSS rules
• Style your site - Available branding and customization approaches from basic configuration to advanced component styling
• Color mode - Color mode feature and its CSS variable-based implementation for table styling
• CSS variables - Complete dictionary of table-specific CSS variables and global styling variables for advanced customization