How to Merge Cells in Markdown Tables

Merging cells horizontally across columns (colspan) or vertically across rows (rowspan) is one of the most requested features in Markdown documentation. Because standard GitHub Flavored Markdown (GFM) pipe syntax does not provide native cell-spanning operators, developers use three practical strategies to format multi-column headers, irregular matrices, and complex schedules.

Quick Reference: 3 Methods for Merging Table Cells

Approach	Syntax Technique	Best For	GFM Support
1. HTML Fallback	<td colspan="2"> & <td rowspan="2">	Pixel-perfect rendering, screen reader accessibility	100% Supported
2. Visual Pseudo-Merge	\| Category \| → \| or \| \|	Staying in pure Markdown; lightweight READMEs	Visual only
3. Pandoc Grid Tables	+---+---+ (omitting internal pipes)	Academic papers, PDF/LaTeX generation	Pandoc only

Method 1: The Standard HTML Hybrid Solution (Recommended)

When you need true cell merging on GitHub, GitLab, or Obsidian, raw HTML is the industry-standard solution. All major Markdown engines allow raw HTML blocks. Use colspan="N" to span multiple columns horizontally, and rowspan="N" to span multiple rows vertically:

HTML Table with Colspan & Rowspan (Pasteable into Markdown)

<table>
  <thead>
    <tr>
      <th rowspan="2">Region</th>
      <th colspan="2">2026 Performance</th>
      <th rowspan="2">Target Met</th>
    </tr>
    <tr>
      <th>Q1 Revenue</th>
      <th>Q2 Revenue</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td rowspan="2">North America</td>
      <td>$1,420,000</td>
      <td>$1,650,000</td>
      <td>Yes</td>
    </tr>
    <tr>
      <td colspan="2">Consolidated NA Bonus: $50,000</td>
      <td>Yes</td>
    </tr>
    <tr>
      <td>Europe</td>
      <td>$980,000</td>
      <td>$1,100,000</td>
      <td>Yes</td>
    </tr>
  </tbody>
</table>

Rendered Browser Simulation

Region	2026 Performance		Target Met
Region	Q1 Revenue	Q2 Revenue	Target Met
North America	$1,420,000	$1,650,000	Yes
North America	Consolidated NA Bonus: $50,000		Yes
Europe	$980,000	$1,100,000	Yes

Method 2: Pure Markdown Visual Pseudo-Merging

If project constraints prohibit raw HTML (e.g. strict Markdown linters or security policies that sanitize HTML), you can simulate merged cells visually using directional Unicode arrows (→, ↓, ↔) or empty string placeholders:

Visual Colspan Simulation with Unicode Arrows

| Component | Dev Environment | Staging | Production |
| :-------- | :-------------: | :-----: | :--------: |
| Database  | PostgreSQL 16   |    →    |     →      |
| Cache     | Redis 7.2       |    →    |     →      |
| API Gateway | Localhost:8080| Kong 3.4| Kong 3.4   |

💡 In this pattern, the right arrow → clearly indicates to human readers that the same configuration spans across Dev, Staging, and Production.

Visual Rowspan Simulation with Empty Cells (Indented Hierarchy)

| Category | Sub-Category | Metric |
| :------- | :----------- | :----: |
| Frontend | React 19     | 98.4%  |
| ^        | Tailwind CSS | 99.1%  |
| ^        | TypeScript   | 100%   |
| Backend  | Node.js 22   | 97.5%  |
| ^        | PostgreSQL   | 99.8%  |

Using the caret ^ or quotation mark " represents a "ditto" mark signifying that the cell inherits the value from the row above.

Method 3: Pandoc Grid Tables (Academic & PDF Publishing)

In technical documentation compiled with Pandoc (such as academic whitepapers, book publishing with Quarto, or automated PDF reports), Grid Tables natively support multi-column cells without using HTML:

+---------------------+-----------------------+
| Item Name           | Value Details         |
+=====================+=======================+
| Consolidated Header (spans both columns)    |
+---------------------+-----------------------+
| Sub-item A          | 14.5 ms               |
+---------------------+-----------------------+

Notice how the separator line between the two columns is completely removed on row 4, telling Pandoc to generate a LaTeX \multicolumn{2}{l}{...}.

Common Pitfalls & Broken vs Fixed Examples

Pitfall 1: Omitting Pipe Characters to "Merge" Cells in Pipe Tables

❌ Broken (Omitted Pipe in GFM)| Col 1 | Col 2 | Col 3 | | :--- | :--- | :--- | | Merged across two cols | Data |Result: Parser detects 2 cells instead of 3; the third column renders as empty/broken!

✅ Fixed (HTML Colspan or Placeholder)<table> <tr> <td colspan="2">Merged across two cols</td> <td>Data</td> </tr> </table>Result: Renders an authentic merged cell spanning exactly 2 columns.

Pitfall 2: Trying to Use Markdown Asterisks (bold) Inside Raw HTML <td>

❌ Broken (**text** in <td>)<td>**Bold Value**</td>Result: Most CommonMark parsers do NOT parse markdown inside HTML; displays literal "**Bold Value**".

✅ Fixed (HTML <b> or <strong>)<td><strong>Bold Value</strong></td>Result: Consistently renders bold text across all Markdown platforms.

Platform Compatibility Matrix

Environment	Support Level	Technical Behavior & Workaround
GitHub (GFM)	HTML Only	Pipe tables cannot merge cells. HTML <table> with colspan/rowspan is fully supported in READMEs, PRs, and Issues.
GitLab (GLFM)	HTML Only	Accepts raw HTML <table> with colspan/rowspan in MRs, issues, and wiki docs.
Obsidian	HTML Only	Renders raw HTML tables with merged cells in Live Preview and Reading View.
Pandoc	Native Support	Supports merged cells natively via Grid Table syntax (+---+---+) and HTML fallback.
Notion	Not Supported	Simple tables in Notion cannot merge cells; database views do not support irregular cell spans.
VS Code	HTML Only	Markdown preview renders HTML colspan/rowspan seamlessly.

Frequently Asked Questions

Does standard GitHub Flavored Markdown (GFM) support colspan or rowspan?

No. The GitHub Flavored Markdown (GFM) and CommonMark specifications strictly require a fixed, symmetrical grid where every row has an identical number of pipe-separated cells. Native syntax for spanning cells across multiple columns or rows does not exist in standard pipe tables.

Can I use raw HTML <table> with colspan and rowspan in GitHub READMEs?

Yes! GitHub, GitLab, and Obsidian fully support raw HTML5 <table>, <tr>, <th>, and <td> tags with standard colspan and rowspan attributes. This is the official, standard workaround when your data requires merged cells on GitHub.

Can I use Markdown formatting (like bold or links) inside an HTML <td> cell?

By default in standard CommonMark, Markdown inside raw HTML blocks is not parsed as Markdown unless your parser supports markdown="1" (like PHP Markdown Extra) or you use inline HTML tags (<b>, <a>, <code>) instead of Markdown asterisks and brackets.

How do Pandoc Grid Tables handle merged cells?

Pandoc grid tables (+---+---+) allow multi-column cells by omitting the interior vertical divider pipe within a row. Pandoc automatically computes the cell span and converts it to LaTeX \multicolumn or HTML colspan when compiling to PDF or web pages.

How do screen readers read visually pseudo-merged Markdown table cells?

If you use empty string cells (| |) or directional arrows (→, ↓) to visually simulate merged cells in a pipe table, screen readers will announce the cell as empty or read the literal arrow character. For full accessibility (WCAG 2.1 compliance), use semantic HTML <table> with proper headers, colspan, and rowspan.

Related Markdown Table Syntax Guides

Column Width Control

Control wrapping, min-width, and padding.

Line Breaks (<br>)

Insert multi-line text inside individual cells.

Collapsible Tables

Wrap large tables inside HTML <details>.

Need to Convert Complex HTML Tables to Markdown?

Paste any Excel, CSV, or HTML table into our editor to instantly normalize irregular cells.

Open Table Generator