How to Convert an Excel Table to Markdown for GitHub

To convert an Excel table to Markdown for GitHub, copy a rectangular range with one header row, paste it into the Excel to Markdown table converter, and copy the generated Markdown into your README. Preview the result on GitHub before saving it. This transfers the table’s readable values into text that can be reviewed in a commit or pull request.

The same tool accepts spreadsheet files, including .xlsx and .xls, as well as CSV and TSV input. A workbook import reads the first worksheet, so copying a specific range is often the clearest option when a workbook contains several sheets, notes above the table, or unrelated calculations. Start with a small representative selection instead of exporting the entire workbook immediately.

Prepare one rectangular range

A Markdown table needs a consistent number of columns. In Excel, select the column labels and the records beneath them. Leave out the report title, empty spacer rows, separate totals panels, and explanatory notes outside the table. Put those details in ordinary Markdown paragraphs above or below the generated table.

Give each column a meaningful name. A heading such as “Response time (ms)” is more useful than “Value,” especially when someone reads the README without the spreadsheet beside it. Include units and define any abbreviation that is specific to your team.

Merged cells need particular attention. A merged heading can communicate a relationship visually in Excel, but a basic Markdown table has individual cells in a flat grid. Replace a two-level merged heading with explicit labels such as “Actual revenue” and “Forecast revenue.” If that produces an unwieldy table, split it into smaller tables with clear section headings.

Decide which values belong in the README

Markdown stores text, not a working calculation model. A cell containing a formula becomes a representation of its result or source text, depending on what you copy or import. It does not keep a dependency on the original workbook.

Before exporting formula results, recalculate and save the workbook in Excel. The browser converter reads stored workbook data; it does not act as Excel’s calculation engine. An old cached result can therefore remain old after conversion. Check a few calculated cells against the open workbook, including totals and any cells whose inputs recently changed.

Also inspect identifiers, dates, and percentages. An account code such as 0042 should remain an identifier, not silently become 42. A date should be understandable to readers in different regions. Where ambiguity matters, choose an explicit representation such as 2026-09-01 and explain whether a percentage is stored as 15% or a decimal value.

Convert the selection and inspect the source

Copying an Excel range normally provides rows separated by line breaks and columns separated by tabs. Paste that data into the converter’s input. The output updates automatically, and the first row becomes the Markdown header.

For example, a three-column range can become:

| Scenario      | Samples | Status   |
| ------------- | ------- | -------- |
| Baseline      | 120     | Reviewed |
| Updated model | 150     | Pending  |

The line of hyphens separates the header from the data. It is required table syntax, not another record. Keep it immediately beneath the header and preserve the same column count throughout the table.

The site’s converter escapes literal pipe characters so a value containing North | South does not accidentally create another column. It also escapes angle brackets as text and normalizes tabs or line breaks inside a cell into spaces. That normalization is useful for a compact README table, but it means an Excel cell containing a carefully arranged multiline address will not retain the same internal layout.

If a table contains substantial paragraphs, consider moving those descriptions into a list or a section below the table. A technically valid grid can still be difficult to read on a narrow screen.

Check the result in GitHub’s preview

Paste the generated source into the intended Markdown file, with a blank line before the table. Use GitHub’s preview to verify the actual destination renderer. GitHub documents the separator row, alignment markers, and pipe escaping in its guide to organizing information with tables.

Check the header and the last record first. Missing the first row can turn a data record into a heading; missing the last row can hide a truncated selection. Then compare the number of data rows and columns with the original range. Spot-check a blank cell, a long value, a percentage, an identifier with leading zeros, and any cell containing punctuation used by Markdown.

You can also inspect the generated source with the Markdown to HTML converter. That is useful for finding structural mistakes, while the GitHub preview remains the final check for a GitHub README. Different Markdown renderers can handle extensions differently.

Keep the spreadsheet and documentation synchronized

Treat the published table as a snapshot. If the workbook changes, the README will not update by itself. Choose which file owns the data and record a date or version near the table when readers need to know how current it is.

For a repeated workflow, keep a small export range on the first worksheet or copy the same named range each time. Use stable column order and consistent labels so a pull request highlights changed values instead of noisy formatting changes. Review the diff before merging, particularly when rows have been sorted or filtered.

If a colleague later needs the Markdown table in a spreadsheet again, the Markdown table to Excel converter can provide a new workbook from its text values. That reverse conversion does not reconstruct the original formulas, formatting, or workbook history. Keep the original Excel file whenever those features matter.

The final deliverable should be a table readers can understand without opening Excel: clear labels, useful values, intact rows, and an explicit relationship to the maintained source. Once those checks pass, the Markdown is ready to become part of the repository’s documentation.