Easy Markdown Tables with Table to Markdown

A beginner's guide to Markdown

In the original Markdown spec, John Gruber describes Markdown as "a text-to-HTML conversion tool for web writers." It was designed to be easy to read and easy to write, and it certainly meets those requirements. Compare writing a bold link in HTML:

<a href="https://tabletomarkdown.com"><strong>Table to Markdown</strong></a>

with Markdown:

[**Table to Markdown**](https://tabletomarkdown.com)

The Markdown version has almost 1/3 fewer characters without losing any information.

This ability to generate HTML without writing HTML hasn't gone unnoticed. Since 2004, Markdown has continued to climb in popularity. The Google Trends data for 'markdown' shows impressive growth, especially since 2010:

Markdown tooling has also exploded since 2004, with Markdown parsers in many languages (e.g., Python-Markdown for Python; Marked, Showdown, and markdown-it for JavaScript). At the same time, developers wrote extensions to extend Markdown's original feature set, including an extension to represent HTML tables with Markdown's characteristic user-friendliness.

Markdown Tables

The syntax for describing tables in Markdown was popularized by GitHub in the The GitHub Flavored Markdown (GFM) Spec. The GFM spec describes tables in Markdown like this:

A table is an arrangement of data with rows and columns, consisting of a single header row, a delimiter row separating the header from the data, and zero or more data rows.

In other words—or in other Markdown—this is what a table looks like following the GFM table spec:

| Format   | Grooviness | <-- Header
| -------- | ---------- | <-- Delimiter
| HTML     | Medium     | <-- Data
| Markdown | High       | <-- Data

This table is formatted to be easy on the eyes, but not all Markdown tables are. Take a look at the formatting of this table, which is equally compliant but less readable:

|Format|Grooviness|
|-|-|
|HTML|Medium|
|Markdown|High|

This readability issue gets even worse when adding rich content into table data cells:

|Format|Grooviness|
|-|-|
|[HTML](https://developer.mozilla.org/en-US/docs/Web/HTML)|Medium|
|[Markdown](https://daringfireball.net/projects/markdown/)|High|

Composing and editing Markdown tables while keeping them readable is no picnic. Thank goodness there's Table to Markdown!

Features

Converts cell contents to Markdown

Table to markdown uses Turndown with custom rules to convert table data cell contents to Markdown.

These custom-written rules ensure that cells containing line breaks don't break the table layout and that certain tags without Markdown handling, like <sup> and <sub>, have their contents converted to Markdown, too.

Gives column cells consistent widths

Markdown tables without consistent column widths are hard on the eyes. Table to Markdown ensures that cells in the same column are the same width your table looks tubular and tabular.

Converts first row to header

Tables copied from spreadsheet applications lack proper header rows. If a table is missing a header row, Table to Markdown converts the first row in a table to a header row to ensure that the table is valid Markdown.

Handles partially-selected tables

When copying a table from a website, even though a table may look selected, often times some elements remain unselected, like <thead>. Table to Markdown repairs partially-selected tables to save you the trouble.