How to Convert Excel to Markdown Tables

Excel spreadsheets are everywhere — project tracking, financial reports, data exports, API references, dependency lists, meeting notes. But the moment you need that data in a GitHub README, documentation site, blog post, knowledge base, or AI workflow, you hit a wall. Excel files are proprietary, heavy, and invisible to version control.

Markdown tables solve this. They're plain text, portable, version-controllable, and render beautifully on GitHub, GitLab, Obsidian, MkDocs, Docusaurus, and every other markdown-aware platform.

This guide covers four methods for converting Excel to markdown — from the simplest (drag and drop) to the most powerful (Python scripting) — so you can choose the right approach for your situation.

---

Why Convert Excel to Markdown?

The Problem with Sharing Spreadsheets

• Proprietary format — Not everyone has Microsoft Office or wants to install it. Google Sheets can open XLSX files but formatting often breaks.
• Can't embed in documentation — You can't put an Excel file inside a README, wiki page, or blog post. You can only link to it, which creates a maintenance burden.
• Version control blind spot — Git can't meaningfully diff Excel files. When someone changes a number in a spreadsheet, git diff shows binary gibberish. Markdown tables produce clean, line-by-line diffs.
• Heavy files — A simple 10-row table in Excel is 8-10 KB. The same table in markdown is 200 bytes.
• Formatting baggage — Cell colors, conditional formatting, and custom styles obscure the actual data. Markdown strips this down to content.

When You Need Markdown Tables

• GitHub README files — Feature comparison tables, project dependencies, configuration references, API endpoint summaries
• Technical documentation — Data specs in MkDocs, Docusaurus, GitBook, Sphinx, or Confluence docs-as-code
• Blog posts — Statistics, benchmarks, comparisons, and results in markdown-based CMS platforms (Ghost, Hugo, Jekyll, Astro, Hashnode)
• Knowledge bases — Structured data in Obsidian, Notion, Logseq, or corporate wikis
• Meeting notes and reports — Action items, status updates, and tracking tables shared via markdown
• AI/LLM context — Structured data fed to ChatGPT, Claude, or RAG systems. Markdown tables are more token-efficient and better understood by LLMs than raw spreadsheet data.

---

Method 1: Craft Markdown (Recommended — Fastest and Most Private)

The simplest approach — drag, drop, and get a clean markdown table. No installation, no account, no spreadsheet knowledge required beyond having the file.

Step by Step

1. Go to Craft Markdown's Excel converter
2. Drag and drop your .xlsx or .xls file onto the page
3. If your workbook has multiple sheets, the converter handles each one
4. Preview the markdown table output
5. Copy to clipboard or download as a .md file

The entire process takes seconds. Your Excel file is processed entirely in your browser — it's never uploaded to any server.

What Gets Converted

Excel Element	Markdown Output
Cell values	Table cell content
Header row (first row)	Markdown table header with separator
Multiple sheets	Separate tables per sheet
Formulas	Calculated values (the result, not the formula)
Merged cells	Expanded to individual cells
Number formatting	Raw numeric values preserved
Empty cells	Empty table cells
Date values	Date strings as displayed

What Doesn't Convert (By Design)

Markdown tables are plain text — they don't support visual formatting. This is a feature, not a limitation:

• Cell colors, fonts, and styles — Markdown tables have no styling. The data is what matters.
• Charts and graphs — Visual elements can't be represented as text. Extract the underlying data instead.
• Conditional formatting — Color-based rules are visual, not data. The cell values are preserved.
• Comments and annotations — These are metadata, not table content.
• Hyperlinks — Link text is preserved but the URL may be lost depending on how the link was created in Excel.

Privacy

Your Excel file is processed entirely in your browser using client-side JavaScript. The spreadsheet is never uploaded to any server. Craft Markdown has zero access to your data — this is architecturally guaranteed, not a policy promise.

This matters because spreadsheets often contain sensitive data — financial figures, employee information, pricing, project plans. Browser-based processing means confidential spreadsheets stay confidential.

---

Method 2: Copy-Paste from Excel (Manual but Quick for Small Tables)

For small tables (under 10 rows), manually formatting is sometimes faster than opening a conversion tool.

Step by Step

1. Select the cell range in Excel
2. Copy (Ctrl+C / Cmd+C)
3. Paste into a text editor
4. Add | between columns
5. Add a header separator row (|---|---|---|)
6. Align columns as needed

Example

Excel data (copied as tab-separated):

Name    Role        Department
Alice   Engineer    Engineering
Bob     Designer    Product
Carol   Manager     Operations

Manually formatted as markdown:

| Name | Role | Department |
|------|------|------------|
| Alice | Engineer | Engineering |
| Bob | Designer | Product |
| Carol | Manager | Operations |

When This Works

• Tables with 3-5 columns and under 10 rows
• Quick one-off conversions where opening a tool feels like overkill
• When you're already in a text editor

When This Doesn't Work

• Tables with many columns or rows — tedious and error-prone
• Data with special characters (pipes |, backticks) that need escaping
• Regular conversions — the manual process adds up quickly
• When accuracy matters — easy to misalign columns or miss cells

---

Method 3: Excel Macros (For Excel Power Users)

If you work in Excel regularly and want a built-in conversion option, a VBA macro can convert selected cells to a markdown table on your clipboard.

The Macro

Sub SelectionToMarkdownTable()
    Dim rng As Range
    Dim row As Range
    Dim cell As Range
    Dim md As String
    Dim sep As String
    Dim isHeader As Boolean
    Dim cellValue As String

    Set rng = Selection
    isHeader = True

    For Each row In rng.Rows
        md = md & "|"
        For Each cell In row.Cells
            cellValue = CStr(cell.Value)
            cellValue = Replace(cellValue, "|", "\|")
            md = md & " " & cellValue & " |"
        Next cell
        md = md & vbCrLf

        If isHeader Then
            md = md & "|"
            For Each cell In row.Cells
                md = md & " --- |"
            Next cell
            md = md & vbCrLf
            isHeader = False
        End If
    Next row

    Dim cb As MSForms.DataObject
    Set cb = New MSForms.DataObject
    cb.SetText md
    cb.PutInClipboard
    MsgBox "Markdown table copied to clipboard!"
End Sub

How to Use

1. Open the VBA editor (Alt+F11 in Excel)
2. Insert → Module
3. Paste the macro code
4. Close the VBA editor
5. Select your table data in Excel
6. Run the macro (Alt+F8 → SelectionToMarkdownTable → Run)
7. Paste the clipboard contents into your markdown file

Pros: Works inside Excel, no external tools needed, reusable across workbooks.

Cons: Requires VBA knowledge to set up, no preview, basic formatting only, Windows-centric (Mac Excel VBA support is limited).

---

Method 4: Command Line and Python (For Developers and Automation)

When you need to convert spreadsheets programmatically — as part of a CI/CD pipeline, documentation build process, or data workflow — command-line tools are the right approach.

Using Pandoc

Pandoc can convert Excel files to markdown:

pandoc spreadsheet.xlsx -t markdown -o output.md

For specific sheets or formatting options, Pandoc's XLSX reader provides additional flags.

Using Python (openpyxl)

A Python script for converting Excel to markdown with full control:

import openpyxl

def xlsx_to_markdown(filepath, sheet_name=None):
    wb = openpyxl.load_workbook(filepath, data_only=True)
    ws = wb[sheet_name] if sheet_name else wb.active

    rows = list(ws.iter_rows(values_only=True))
    if not rows:
        return ""

    # Calculate column widths for alignment
    col_count = len(rows[0])

    # Header row
    header = "| " + " | ".join(
        str(c) if c is not None else "" for c in rows[0]
    ) + " |"

    # Separator row
    separator = "| " + " | ".join("---" for _ in range(col_count)) + " |"

    # Data rows
    data_rows = []
    for row in rows[1:]:
        cells = [str(c) if c is not None else "" for c in row]
        data_rows.append("| " + " | ".join(cells) + " |")

    return "\n".join([header, separator] + data_rows)

# Usage
markdown = xlsx_to_markdown("data.xlsx")
print(markdown)

Using Python (pandas)

If you're already using pandas, the conversion is a one-liner:

import pandas as pd

df = pd.read_excel("data.xlsx")
markdown = df.to_markdown(index=False)
print(markdown)

Note: pandas.to_markdown() requires the tabulate package (pip install tabulate).

---

Markdown Table Formatting Tips

Once you have your markdown table, these tips help you produce the cleanest output.

Column Alignment

Control alignment with the separator row:

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:--------------:|--------------:|
| text         |     text       |          text |

• :--- or --- — left-aligned (default)
• :---: — center-aligned
• ---: — right-aligned

Right-alignment is especially useful for numeric columns (prices, counts, percentages).

Escaping Special Characters

Characters that have special meaning in markdown tables:

• Pipe | — Use \| to display a literal pipe inside a cell
• Backtick ` — Use \`` `` to escape backticks
• Leading/trailing whitespace — May be trimmed by some renderers

Handling Large Tables

Markdown tables work best for small to medium datasets:

• Under 10 columns — Reads well on most screens
• Under 100 rows — Manageable in a document
• Over 20 columns — Consider whether all columns are necessary, or split into multiple tables
• Over 500 rows — Consider linking to a downloadable CSV or Excel file instead
• Very wide cells — Keep cell content concise; long text in cells makes tables hard to read

Table Formatting Best Practices

• Use clear, concise column headers
• Keep cell content short — if cells contain paragraphs, a table isn't the right format
• Right-align numeric columns for readability
• Use consistent formatting within columns (don't mix "$100" and "100 dollars")
• Include units in the header, not in every cell ("Price (USD)" not "100 USD" in each row)

---

Common Use Cases with Examples

GitHub README — Project Dependencies

| Package | Version | License | Purpose |
|---------|---------|---------|---------|
| React | 19.0.0 | MIT | UI framework |
| Next.js | 15.1.0 | MIT | Server framework |
| Tailwind CSS | 4.0.0 | MIT | Utility CSS |
| Prisma | 6.2.0 | Apache-2.0 | Database ORM |

Documentation — API Endpoints

| Endpoint | Method | Auth | Description |
|----------|--------|------|-------------|
| `/api/users` | GET | Bearer token | List all users |
| `/api/users/:id` | GET | Bearer token | Get user by ID |
| `/api/users` | POST | Bearer token | Create new user |
| `/api/users/:id` | DELETE | Admin only | Delete user |

Project Management — Sprint Status

| Task | Status | Owner | Due | Notes |
|------|--------|-------|-----|-------|
| Auth system | Complete | Alice | Feb 15 | Deployed to staging |
| Dashboard UI | In Progress | Bob | Feb 22 | Blocked on design review |
| API docs | Not Started | Carol | Mar 1 | Waiting for API freeze |
| Load testing | In Progress | Dave | Feb 28 | 80% complete |

Data Analysis — Benchmark Results

| Model | Accuracy | Latency (ms) | Cost (per 1M tokens) |
|-------|:--------:|---------:|-------:|
| GPT-4o | 94.2% | 850 | $5.00 |
| Claude 3.5 Sonnet | 93.8% | 620 | $3.00 |
| Gemini 1.5 Pro | 92.1% | 740 | $3.50 |
| Llama 3.1 70B | 89.5% | 420 | $0.80 |

---

Converting Google Sheets to Markdown

Google Sheets doesn't export to markdown directly, but the conversion is straightforward:

Method 1: Export as CSV, then convert

1. In Google Sheets: File → Download → Comma-separated values (.csv)
2. Convert the CSV to markdown using Craft Markdown's CSV converter

Method 2: Export as XLSX, then convert

1. In Google Sheets: File → Download → Microsoft Excel (.xlsx)
2. Convert the XLSX to markdown using Craft Markdown's Excel converter

Method 3: Copy and paste

1. Select cells in Google Sheets
2. Copy (Ctrl+C)
3. Paste into Craft Markdown's CSV converter — tab-separated data from the clipboard converts cleanly

---

Key Takeaways

1. Craft Markdown is the fastest path for most users — drag and drop, instant conversion, complete privacy. No installation, no account, no learning curve.

2. Manual formatting works for tiny tables — under 10 rows and 5 columns, but it doesn't scale and is error-prone.

3. VBA macros are useful for Excel power users who want conversion built into their existing workflow without leaving the application.

4. Python and Pandoc are the right tools for automation — CI/CD pipelines, documentation builds, data processing workflows, and batch conversion of multiple workbooks.

5. Markdown tables have practical limits — they work best for small to medium datasets. For very large data, link to a downloadable file instead.

6. Privacy matters for spreadsheets — financial data, employee info, and project plans belong in a tool that processes locally, not one that uploads to a server.

Convert your Excel spreadsheets to markdown — free and private →

---

Frequently Asked Questions

Can I preserve Excel formatting in markdown?

No, and that's by design. Markdown tables are plain text — they don't support cell colors, fonts, borders, or conditional formatting. Only the data values and table structure are converted. This makes markdown tables portable, lightweight, and version-control friendly. The trade-off is worth it for most use cases.

What happens to formulas?

Formulas are converted to their calculated values. If cell B2 contains =SUM(A1:A10) and the result is 4,250, the markdown table shows 4250. The formula logic itself is not included — you get the data, not Excel-specific instructions.

Can I convert Google Sheets to markdown?

Yes. Export your Google Sheet as CSV (File → Download → CSV) or XLSX (File → Download → Excel), then convert using Craft Markdown. You can also copy cells and paste directly into the CSV converter.

How do I handle merged cells?

Merged cells are expanded to individual cells. The value from the merged cell appears in the top-left cell of the merge range, and remaining cells are empty. You may need to manually adjust the table after conversion — duplicate the value into the empty cells or restructure the table.

Can I convert multiple sheets at once?

Craft Markdown handles workbooks with multiple sheets — each sheet becomes a separate markdown table with the sheet name as a heading. For batch conversion of many workbooks, Python with openpyxl or Pandoc is more efficient.

What's the maximum file size?

Browser-based processing handles typical Excel files (up to several MB) without issues. For very large workbooks (50MB+), consider exporting the specific sheets you need as CSV first — CSV files are smaller and convert faster.

Is there a way to auto-update the markdown when the Excel file changes?

Not with browser-based tools. For automated sync, set up a Python script or CI/CD step that re-converts the Excel file to markdown on each change. This is common in documentation workflows where spreadsheet data feeds into a docs-as-code pipeline.