Mastering HTML Tables in GitHub Markdown: Multi-Column Grids & Card Layouts

1. Standard Pipe Tables vs. HTML Tables

Standard GitHub Flavored Markdown (GFM) pipe tables (| Header | Header |) were designed for simple data charts. They have severe limitations:

• No multi-line paragraphs or structured bullet lists inside cells.
• No vertical alignment control (cells always align to the baseline).
• No cell merging via colspan or rowspan.
• No precise column width allocation (like width="50%").

By switching to raw HTML <table> syntax, you gain complete layout control to build modern cards, side-by-side showcases, and feature comparisons.

2. GitHub’s Strict HTML Sanitization Rules

GitHub uses an aggressive HTML sanitizer to prevent malicious script injection. Understanding what is allowed—and what is stripped—is essential:

3. The 2-Column Responsive Card Pattern

To build a 2-column project showcase with cards that align perfectly at the top, use width="50%" and valign="top":

<table width="100%">
  <tr>
    <td width="50%" valign="top">
      <h3 align="center">⚡ Project Alpha</h3>
      <p align="center">
        <img src="https://via.placeholder.com/400x200" width="100%" alt="Preview" />
      </p>
      <p>A distributed key-value cache engine built with Go and Raft consensus.</p>
      <p align="center">
        <a href="https://github.com/username/project-alpha">
          <img src="https://img.shields.io/badge/Repository-Go-blue?style=flat-square" alt="Repo" />
        </a>
      </p>
    </td>
    <td width="50%" valign="top">
      <h3 align="center">🎨 Studio Canvas</h3>
      <p align="center">
        <img src="https://via.placeholder.com/400x200" width="100%" alt="Preview" />
      </p>
      <p>Collaborative drawing application powered by WebGL, Zustand, and WebSockets.</p>
      <p align="center">
        <a href="https://github.com/username/studio-canvas">
          <img src="https://img.shields.io/badge/Live_Demo-Vercel-success?style=flat-square" alt="Demo" />
        </a>
      </p>
    </td>
  </tr>
</table>

4. Mobile Responsiveness & Avoiding Horizontal Scroll

The number one mistake developers make with HTML tables is specifying absolute pixel dimensions (e.g. <table width="800"> or <td width="450">). On an iPhone or Android screen (375px–412px wide), this forces GitHub’s mobile web app to display an awkward horizontal scroll bar.

• Always set table width to a relative percentage: <table width="100%">.
• For 2-column grids, assign width="50%" to each cell so GitHub’s browser engine scales columns fluidly.
• Use width="100%" on embedded images inside table cells so they never overflow cell boundaries.

5. Expandable Accordion Tables

You can combine <details> tags inside HTML tables to create interactive, collapsible project deep dives:

<table>
  <tr>
    <td>
      <details>
        <summary><b>🔍 Click to expand Architecture Diagram & Benchmarks</b></summary>
        <br />
        <p>Achieved 48,000 requests per second under P99 latency of 3.2ms.</p>
        <pre>Client -> Cloudflare -> API Gateway -> Go Worker</pre>
      </details>
    </td>
  </tr>
</table>