Markdown Columns: Side-by-Side Layout Methods

Quick Answer

Markdown has no column syntax. To put content side by side, use an HTML table (works everywhere) or a div with CSS flexbox or grid (works in local apps only).

Method 1: HTML Table (Works on GitHub)

The most portable method. Use an HTML table without borders to create columns that work on GitHub, GitLab, Bitbucket, and local apps:

Two-column text

<table>
<tr>
<td>

**Feature A**

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor.

</td>
<td>

**Feature B**

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi.

</td>
</tr>
</table>

Key detail: leave a blank line after <td> and before </td> so GitHub renders Markdown formatting (bold, links, code) inside the cells.

Images side by side

<table>
<tr>
<td><img src="before.png" alt="Before" width="400"></td>
<td><img src="after.png" alt="After" width="400"></td>
</tr>
<tr>
<td align="center">Before</td>
<td align="center">After</td>
</tr>
</table>

This pattern is common in README files for before/after screenshots, comparison images, and feature showcases.

Three or more columns

<table>
<tr>
<td width="33%">

### Plan A
- 5 GB storage
- Email support

</td>
<td width="33%">

### Plan B
- 50 GB storage
- Priority support

</td>
<td width="33%">

### Plan C
- Unlimited storage
- Dedicated support

</td>
</tr>
</table>

Method 2: Div + Flexbox

For local Markdown apps that support CSS (MDViewer, Typora, Obsidian), use a flex container for responsive columns:

<div style="display: flex; gap: 16px;">
<div style="flex: 1;">

**Left Column**

Content flows naturally and wraps within each column.

</div>
<div style="flex: 1;">

**Right Column**

Columns resize equally and stay side by side.

</div>
</div>

Does not work on GitHub. GitHub strips all style attributes, so the divs stack vertically. Use an HTML table for GitHub.

Unequal column widths

<div style="display: flex; gap: 16px;">
<div style="flex: 2;">

Main content (2/3 width)

</div>
<div style="flex: 1;">

Sidebar (1/3 width)

</div>
</div>

Method 3: Div + CSS Grid

CSS grid gives the most control over complex layouts:

<div style="display: grid; grid-template-columns: 1fr 1fr; gap: 16px;">
<div>

Column 1 content

</div>
<div>

Column 2 content

</div>
</div>

Change grid-template-columns to create any layout: 1fr 1fr 1fr for three equal columns, 2fr 1fr for 2/3 + 1/3, or 200px 1fr for a fixed sidebar.

Platform support: same as flexbox — works in local apps, stripped on GitHub and GitLab.

Method 4: CSS Columns (Text Flow)

For newspaper-style text that flows from one column to the next, use the CSS column-count property:

<div style="column-count: 2; column-gap: 24px;">

Long text content here. It will automatically flow from the first column into the second column when the first one is full. This is useful for reference lists, glossaries, and dense text.

</div>

Unlike flexbox/grid, CSS columns flow text continuously — you do not assign specific content to each column. Useful for reference lists and glossaries.

Platform Support

Rule of thumb: if the file will be viewed on GitHub, use an HTML table. If it is only for local viewing or a documentation site, use flexbox or grid for cleaner markup.

Common Mistakes

Forgetting blank lines inside table cells

On GitHub, Markdown inside <td> tags only renders when there is a blank line between the HTML tag and the Markdown content:

<!-- ❌ Won't render bold on GitHub -->
<td>**Bold text**</td>

<!-- ✅ Will render bold on GitHub -->
<td>

**Bold text**

</td>

Using style attributes on GitHub

GitHub strips all style attributes from HTML. Flexbox, grid, and inline CSS do nothing. Use the width and align HTML attributes instead (GitHub allows these).

Not testing on mobile

HTML tables do not wrap on narrow screens — they scroll horizontally. For responsive layouts, prefer flexbox with flex-wrap: wrap or test your tables on a phone before publishing.

FAQ

Can you create columns in Markdown?

Markdown has no column syntax. The most portable method is an HTML table without visible borders — it works on GitHub, GitLab, and all major renderers. For local apps that support CSS, use display: flex or display: grid for proper responsive columns.

How do I put text side by side in Markdown?

Use an HTML table with two <td> cells in one <tr> row. On GitHub, leave a blank line after <td> so Markdown formatting renders inside the cells. For images, place two <img> tags in adjacent cells.

Do Markdown columns work on GitHub?

Only via HTML tables. GitHub strips CSS properties like display: flex and display: grid, so div-based column layouts collapse into a single column. An HTML table is the only reliable method.

Preview Your Markdown with MDViewer

MDViewer is a native macOS app that renders Markdown with full CSS support — flexbox columns, grid layouts, and HTML tables all render correctly. Open any .md file from Finder and see your column layouts exactly as intended. Lite is free; Pro adds editing, Git history, and PDF export.

Requires macOS 13.0 or later. Intel and Apple Silicon.