Excel to Markdown Table Converter
Get a sheet into a README, an issue or a wiki page. Pipes inside your data are escaped, in-cell line breaks survive, and the numeric columns are the ones that get right-aligned.
To convert Excel to Markdown, drop your .xlsx above. The chosen sheet becomes a GitHub-flavored Markdown table with the header row as the header, numeric columns right-aligned so the digits line up, pipes inside values escaped so they do not split cells, and in-cell line breaks written as br. Copy the text straight into GitHub.
Want to cut it down to the useful columns? Open the app
The table that has to live in the repository
There is a category of table that starts in a spreadsheet and belongs in a repository: the supported-versions matrix, the environment variable reference, the list of error codes and what they mean, the pricing tiers a README has to state.
Keeping it in a spreadsheet means it drifts, because nobody reviews a spreadsheet in a pull request. Moving it into Markdown means the change shows up in the diff next to the code that depends on it.
The obstacle is always the same: doing the conversion by hand is twenty minutes of typing pipes, and doing it badly produces a table that renders broken in the one place everybody looks.
Worked example
A sheet with the two things that break a Markdown table:
Service Version Replicas Notes
billing-api 2.4.1 6 rollout paused
resumed 09 Jan
web-frontend 5.0.0 4 canary 10% | full 14 JanWhere the notes cell for billing-api holds two lines. The Markdown:
| Service | Version | Replicas | Notes |
| --- | --- | ---: | --- |
| billing-api | 2.4.1 | 6 | rollout paused<br>resumed 09 Jan |
| web-frontend | 5.0.0 | 4 | canary 10% \| full 14 Jan |The pipe in the second notes cell is escaped, so that row still has four columns. The two-line cell became one cell with a <br> in it. Only Replicas is right-aligned, because Version holds 2.4.1 and 5.0.0, which are not numbers however much they look like them.
The three failure modes, and what happens instead
A pipe inside a value ends the cell. Spreadsheets are full of them, in notes columns and in anything somebody typed as a makeshift list. Every one is escaped as \|, and backslashes are escaped first so a value ending in one cannot consume the escape that follows it.
An in-cell line break, typed with alt and enter, ends the row, and Markdown has no continuation. It becomes <br>, which GitHub renders as a line break and other readers show as literal text. A competing converter deletes the break and joins the lines with a space, which looks tidy and changes your data.
A column that looks numeric but is not, a padded code or a version string, is left-aligned, because auto alignment follows the type the column actually has. The same competing converter right-aligns a ZIP code column it typed as text one pane earlier.
What Excel formatting does and does not survive
- Bold, colours and borders do not come through. Markdown has no way to express most of them, and the ones it can express are decisions about presentation that belong to the document, not the sheet.
- Number formatting does not come through either. A cell displaying
1,840.50writes1840.5, because the comma and the trailing zero are the format rather than the value. Format the column as text in Excel if the display string is what you need. - Dates come through as ISO strings, which sort correctly as text and are unambiguous to every reader.
- Formulas come through as their computed values.
- Merged cells put their value in the top-left position. A merged header is the usual cause of a column called
column_3in the output.
Alignment, and how long is too long
Auto is the default: a column whose every value is a real number gets a right-aligned marker so the decimal points line up, and nothing else does. All left, all centered and all right are there for the cases where the data does not decide well, such as a short status column that reads better centered.
Columns are not padded to a common width in the source. It costs a great many characters on a wide sheet, no renderer looks at it, and it makes the next diff on that file unreadable.
Above about ten thousand rows you get a note. A Markdown table that long renders slowly on GitHub and nobody scrolls it. Nothing is blocked, but at that size a linked spreadsheet or a dashboard is usually the better artefact.
Frequently Asked Questions
What happens to a cell with two lines in it?
It becomes one cell containing a br. Markdown has no way to continue a table row, so the alternative is losing the break. GitHub renders it; other readers show the tag as text, which is still better than two lines silently becoming one.
Does it escape pipes in my data?
Every one, and backslashes are escaped first so a value ending in a backslash cannot eat the escape on the pipe after it. An unescaped pipe is the most common reason a generated Markdown table arrives broken.
Why is my version column not right-aligned?
Because 2.4.1 and 5.0.0 are not numbers. Auto alignment follows the type the column actually holds, decided from all of its values, rather than the shape of the characters. Right-aligning an identifier presents it as a quantity.
Does bold or cell colour come through?
No. Markdown cannot express most spreadsheet formatting, and the parts it could express are presentation choices that belong to the document rather than the sheet. Structure and values come through.
Why does 1,840.50 become 1840.5?
The comma and the trailing zero were the cell's number format, not the number. Excel stores one and paints the other. Format the column as text in Excel before exporting if the display string is what you need in the table.
Is there a size where this stops being sensible?
Around ten thousand rows you get a note. Nothing is blocked, but a Markdown table that long renders slowly on GitHub and nobody reads past the first screen. At that size a link to a spreadsheet or a dashboard does the job better.
Move the table into the repository
Escaped pipes, kept line breaks, numeric columns aligned. Copy and paste.
Back to the converter