How to export an excel spreadsheet as markdown for github readme files
- Step 1Build the table on the first sheet — The converter reads only the first sheet. If your workbook has separate tabs for
roadmap,deps, andconfig, copy the one you want to convert to the first tab — there is no sheet picker. - Step 2Headers on row 1 — Row 1 becomes the GFM header row. For a README feature matrix, that's usually
Feature | Free | Pro | Enterprise. Remove any title rows above it so the column names sit on row 1. - Step 3Open the tool and drop the workbook — Drop your
.xlsxonto the dropzone. SheetJS parses it in the browser — nothing about your private repo touches a server. - Step 4Choose alignment for the table — For a feature matrix, Centre (
:---:) usually reads best because most cells are short flags. For a config reference with long descriptions, Left (:---) is cleaner. Remember the choice applies to every column. - Step 5Convert and review the preview — Click Convert to Markdown. Check the row/column count matches your sheet. The preview truncates at 5,000 characters but copy and download include the full table.
- Step 6Paste into your README or wiki — Click Copy and paste into
README.md, a wiki page, or a PR description. Commit and GitHub renders it. For mixed per-column alignment, edit the separator row in the README after pasting.
GitHub Markdown alignment syntax this tool writes
The alignment control maps directly to GFM separator-row syntax, applied uniformly to all columns. Verified against lib/json-to-markdown.ts (alignSep).
| Alignment selected | Separator row written | GitHub rendering |
|---|---|---|
| Left (default) | | :--- | :--- | | All text/numbers left-aligned |
| Centre | | :---: | :---: | | All cells centred |
| Right | | ---: | ---: | | All cells right-aligned (good for numeric columns) |
| Per-column mix | Not supported by the tool | Edit the separator row by hand after pasting |
Common GitHub README table problems and the fix
What breaks GitHub tables and how this tool's behaviour helps. All behaviours grounded in the converter implementation.
| Problem | Cause | How the tool helps |
|---|---|---|
| Table renders as plain text | Missing or misaligned pipes / no separator row | Tool always writes leading/trailing pipes plus the separator row |
| A cell starts a new column | Unescaped | in the cell (e.g. feat | fix) | Tool escapes inner | to \| |
| Row count looks wrong | In-cell line break treated as a new row | Tool collapses in-cell \n to a space |
| Wrong header text | Title banner on row 1 instead of column names | Put real column names on row 1 (tool reads row 1 as header) |
| Numbers reformatted | SheetJS reads numbers as numbers | Format the column as Text in Excel before converting |
Cookbook
Conversions tuned to the tables that show up in GitHub READMEs, wikis, and PR descriptions. Left block is the sheet; right block is the emitted Markdown.
Feature comparison matrix for a README
The classic README table. Centre alignment reads best because the body cells are short flags.
Excel first sheet: Feature Free Pro Enterprise API access no yes yes SSO no no yes Markdown output (alignment: centre): | Feature | Free | Pro | Enterprise | | :---: | :---: | :---: | :---: | | API access | no | yes | yes | | SSO | no | no | yes |
Changelog entry with a pipe in the cell
A release-notes table where a cell lists feat | fix. The inner pipe is escaped so the table stays three columns wide.
Excel cell value: feat | fix Markdown output: | Version | Type | Summary | | :--- | :--- | :--- | | 2.1.0 | feat \| fix | OAuth + retry fix |
Right-aligned numeric column
A dependency size table. Right alignment makes the numeric columns line up under each other in GitHub's render.
Markdown output (alignment: right): | Package | Size kB | Gzipped | | ---: | ---: | ---: | | react | 142 | 44 | | lodash | 531 | 71 | Note: alignment is uniform; the Package column is right-aligned too.
Environment-variable reference table
A config-reference table for the README. Left alignment keeps long descriptions readable.
Markdown output (alignment: left): | Variable | Default | Description | | :--- | :--- | :--- | | PORT | 3000 | HTTP listen port | | LOG_LEVEL | info | One of debug, info, warn, error |
Mixed alignment after manual edit
The tool emits a uniform separator row; if you want labels left and numbers right, edit the separator row in the README after pasting.
Tool output (alignment: left): | Metric | Value | | :--- | :--- | | Requests | 12000 | After manual edit in README (right-align the value column): | Metric | Value | | :--- | ---: | | Requests | 12000 |
Edge cases and what actually happens
Table renders as plain text on GitHub
Usually fixedThe most common GitHub failure is a missing separator row or unbalanced pipes. The tool always writes leading/trailing pipes and a separator row, so a copy-paste of its output renders correctly. If it still shows as text, you likely pasted into a code fence or an indented block — un-indent it.
Per-column alignment not supported
Manual stepGitHub supports a different alignment per column, but the tool writes one alignment for the whole table. To left-align labels and right-align numbers in the same README table, edit the separator row by hand after pasting.
Only the first sheet is read
By designIf your workbook has roadmap, deps, and config tabs, only the first is converted. Copy the target table to the first tab, or save a single-sheet copy, before converting.
Title row mistaken for the header
Header misreadGitHub will render whatever the tool put on the header line. If row 1 is Q3 Roadmap instead of your column names, that one phrase becomes the entire header. Put the real column names on row 1.
Pipe in a changelog cell
EscapedA cell like feat | fix would split into two columns in raw Markdown. The tool escapes the inner | to \| so GitHub renders it as one cell. This is automatic and not toggleable.
Multi-line release notes in one cell
CollapsedA cell with several lines of notes collapses to a single space-joined line, because GFM rows are one line. For multi-line content, use a <br> in the source cell (it survives as text and GitHub renders it) or move the prose outside the table.
HTML in a cell renders on GitHub
Rendered as HTMLCell HTML such as <sub>beta</sub> is not escaped — it passes through and GitHub renders it. That can be handy (badges, <br>, <sub>) but means a literal < you wanted as text will be interpreted. Neutralise it in the sheet if needed.
Long IDs reformatted in the dependency table
Number coercionA version or hash column read as a number can lose leading zeros or show scientific notation. Format such columns as Text in Excel before converting so the exact string survives into the README.
Very wide tables overflow GitHub's column
Renders but scrollsGitHub renders wide tables but they may need horizontal scroll on narrow screens and in the mobile app. Keep README tables to the columns that matter; move detail to a linked page.
Raw CSV dropped instead of a workbook
May failA plain .csv is read as text and JSON-parsed, which throws. For a README from CSV data, save the CSV as .xlsx first, then convert. Spreadsheet files are the reliable input.
Frequently asked questions
Does GitHub-Flavoured Markdown support aligned columns?
Yes — :--- for left, :---: for centre, and ---: for right. The tool's alignment control writes one of these for the whole table. GitHub renders all three, but the tool applies a single alignment to every column; mixed per-column alignment is a manual edit after pasting.
What happens to empty cells in the table?
An empty or blank cell produces an empty Markdown cell (| |). The table structure and column count are preserved, so the README table never loses a column because a cell was blank.
Is there a row limit for the Markdown output?
GitHub renders tables with any number of rows, though very large tables (500+ rows) are slow and hard to read inline. The tool's own limits are the Excel-family tiers: 10,000 rows on Free, 100,000 on Pro, 500,000 on Pro-media, unlimited on Developer. For big datasets, link to the file instead of inlining it.
Can I paste the output directly into a PR description?
Yes. GitHub PR and issue descriptions use the same GFM as READMEs, so the copied table renders there too. Just paste it on its own lines (not inside a code fence) and it renders on save.
Will the first sheet's row 1 always be the header?
Yes. SheetJS reads the first row of the first sheet as the column keys, and the tool writes those as the Markdown header row. If your column names are on row 2 because of a title banner, delete the banner first.
Does it convert multiple sheets into multiple tables?
No. Only the first sheet is converted. To document several sheets, convert each one separately (copy each to the first tab in turn) and paste the resulting tables into your README under their own headings.
Can I keep a `<br>` line break inside a cell for GitHub?
Yes. A literal <br> typed in the source cell is not escaped, so it survives into the Markdown and GitHub renders it as a line break inside the cell. Real (Alt+Enter) line breaks, by contrast, collapse to a space.
Is my private-repo data uploaded?
No. The spreadsheet is parsed in your browser with SheetJS; nothing is sent to a server. Only an anonymous run counter (no content) is recorded for signed-in users, and you can opt out.
Why are my version numbers showing in scientific notation?
Long numeric strings read as numbers can round or switch to exponential form. Format the column as Text in Excel (or prefix with an apostrophe) before converting so the exact string lands in the README.
Does it produce HTML tables instead of Markdown?
No — this tool outputs Markdown pipe tables. If you want a styled HTML table for a GitHub Pages site, use excel-tailwind-export, which emits an HTML table with Tailwind classes.
Can I generate code from the same data?
Yes — sibling tools take the same workbook and emit other artefacts: json-to-sql for INSERT statements, excel-python-gen for a Python data structure, and excel-trpc-router for a tRPC router scaffold.
Which tier do I need?
Excel-to-Markdown is a Pro-tier tool in the registry. Free covers small files (5 MB / 10,000 rows); Pro and above raise the limits to 50 MB / 100,000 rows and beyond.
Privacy first
Every JAD Excel tool runs entirely in your browser using SheetJS and ExcelJS. Your spreadsheets, formulas, and data never leave your device — verified by zero outbound network requests during processing.