How to Set Column Width in a Markdown Table

Ways to control column width

| Option                   | Default | Description |
| :--- | :---: | :--- |
| `timeout` | 30 | Seconds before the request is aborted |
| `retries` | 3 | Attempts after the first failure |

Why columns size themselves

A pipe table becomes a plain HTML <table> with no width information. Browsers then use automatic table layout: each column gets the width its content needs, and long text wraps once the table hits the width of the page. Spaces you add in the source to line up the pipes are collapsed by the browser, so they never affect the rendered width; they only make the source readable (which is what the table formatter does).

Every workaround therefore does one of two things: it puts wider content in the column (non-breaking spaces, a spacer image), or it adds CSS that overrides automatic layout.

How do I widen a column on GitHub?

GitHub strips style attributes and doesn't let you add CSS, so content is the only lever. Its stylesheet makes tables display: block; width: max-content; max-width: 100%: a table is exactly as wide as its content and scrolls horizontally when it is wider than the page.

Pad the header with  

Non-breaking spaces are real characters that don't collapse or wrap, so ten of them add roughly ten characters of width. Put them in the header cell only. This is the simplest fix and works on GitHub, GitLab, Obsidian and VS Code.

Add a spacer image

For a width in pixels, put an image with a width attribute in the header. Point it at a transparent 1×1 image committed to your repository and give it height="1" so it stays invisible.

| Name<br><img width="240" height="1" src="docs/spacer.png" alt=""> | Notes |
| :--- | :--- |
| `timeout` | Seconds before the request is aborted |

HTML tables with width attributes

In an HTML table you can set width on <th> or <td> in pixels or percent. Renderers that keep the attribute treat it as the column's preferred width. On GitHub, the attribute is kept but the content-sized table stylesheet makes the result inconsistent, so check the rendered page.

<table>
  <tr>
    <th width="100">Method</th>
    <th width="220">Endpoint</th>
    <th width="380">Description</th>
  </tr>
  <tr>
    <td><code>GET</code></td>
    <td><code>/api/v1/users</code></td>
    <td>Lists active users with their roles</td>
  </tr>
  <tr>
    <td><code>POST</code></td>
    <td><code>/api/v1/users</code></td>
    <td>Creates a user and sends an activation email</td>
  </tr>
</table>

Don't put <th width="…"> inside a pipe-table header cell: that nests a header cell inside another one. Convert the whole table with Markdown table to HTML first.

Setting widths with CSS on your own site

Where you control the stylesheet, CSS gives real control. With the default table-layout: auto, widths are suggestions the content can override. With table-layout: fixed and a table width, the widths you set are applied exactly and the content wraps to fit.

/* Fixed layout: the widths you set win over the content */
article table {
  table-layout: fixed;
  width: 100%;
}
article table th:nth-child(1) { width: 20%; }
article table th:nth-child(2) { width: 15%; }
/* the remaining column gets the rest */

article table td {
  overflow-wrap: anywhere; /* long URLs and identifiers wrap instead of overflowing */
}

/* Auto layout, but never narrower than this */
article table th:first-child {
  min-width: 12rem;
}

Pipe tables don't take classes or ids in GFM, so CSS targets columns by position with :nth-child(). If only some tables need it, wrap them in a <div class="…"> (with blank lines around the table so it is still parsed as Markdown) and scope the selector to that class.

How do I make a table full width?

A table that stops halfway across the page is usually the theme, not your Markdown. Many themes deliberately size tables to their content and make them scroll horizontally when they are too wide, which works well on phones. To stretch them, override the table's display and width:

• GitHub: not possible; width="100%" on an HTML table is overridden by the stylesheet. A long header row or a wide spacer image is the only way to make a table wider.
• Your own site: table { display: table; width: 100%; }. Keep an overflow-x: auto wrapper for tables that may be wider than a phone screen.
• Obsidian: also turn off Settings → Editor → “Readable line length”, which caps the width of the whole note.

MkDocs, Docusaurus and Obsidian recipes

MkDocs (Material theme)

Material wraps each table in a scroll container and sizes it to its content. These rules stretch tables to the full content width and set the first column:

/* docs/stylesheets/extra.css
   mkdocs.yml:
     extra_css:
       - stylesheets/extra.css */

/* Material for MkDocs: stretch tables to the content width */
.md-typeset__table {
  min-width: 100%;
}
.md-typeset table:not([class]) {
  display: table;
}

/* First column 30% wide */
.md-typeset table:not([class]) th:first-child {
  width: 30%;
}

Docusaurus

/* src/css/custom.css */
.markdown table {
  display: table;   /* Infima renders tables as display:block */
  width: 100%;
}
.markdown table th:first-child {
  width: 30%;
}

display: table removes Infima's built-in horizontal scrolling, so wide tables will overflow on small screens. Scope the rule to a wrapper class if only some tables should stretch.

Obsidian

/* .obsidian/snippets/tables.css
   Enable it in Settings → Appearance → CSS snippets */
.markdown-rendered table {
  width: 100%;
}
.markdown-rendered table th:first-child {
  width: 30%;
}

.markdown-rendered targets Reading view. Live Preview uses different elements; open the developer tools (Ctrl+Shift+I, or Cmd+Option+I on macOS) to find the selector for your Obsidian version and theme.

Pandoc and Quarto: relative widths

Pandoc is the only common Markdown processor where the delimiter row affects width. According to the Pandoc manual, if any line of a pipe table is longer than the column limit (--columns, 72 by default), the table spans the full text width and each column's share is proportional to its number of dashes. Shorter tables keep their natural widths. Here the separator has 7 and 79 dashes, so the first column gets about 8% of the width.

| Term  | Definition                                                                    |
|-------|-------------------------------------------------------------------------------|
| Width | Relative widths come from the dash counts once a row is longer than 72 chars  |

Quarto, which uses Pandoc, also accepts explicit percentages in the table caption:

| Term  | Definition                       |
|-------|----------------------------------|
| Width | Set explicitly with tbl-colwidths |

: Glossary {tbl-colwidths="[25,75]"}

More in the Pandoc tables guide.

Column width support by platform

Common mistakes (broken vs. fixed)

Padding the source with spaces

| Name                              | Value |
| --------------------------------- | ----- |
| retries                           | 3     |

Putting   in the delimiter row

| Name | Value |
| ---     | ----- |
| retries | 3 |

A bare URL stretching the column

| Package | Source |
| :--- | :--- |
| table-engine | https://github.com/example-org/markdown-table-engine/blob/main/packages/core/README.md |

| Package | Source |
| :--- | :--- |
| table-engine | [README](https://github.com/example-org/markdown-table-engine/blob/main/packages/core/README.md) |

Using style attributes on GitHub

<td style="width: 200px"> works in some renderers, but GitHub removes the style attribute entirely, so the width silently disappears. Use the attribute form or a spacer image there.

When to switch to HTML or restructure

Width fights are often a sign the table has the wrong shape. Before reaching for HTML, consider:

• Too many columns: transpose the table so the columns become rows, or split it in two.
• One long text column: move the prose out of the table, or break it with <br> line breaks.
• Cramped headers: shorten them, or put units on a second line.

Switch to an HTML table when you need fixed widths on a renderer that allows attributes but no CSS, or when the table also needs merged cells. To place the table rather than size its columns, see centering a table, and for the rest of the syntax the Markdown table syntax guide.

Frequently asked questions