miku-md2xlsx

miku-md2xlsx converts Markdown files into practical Excel .xlsx workbooks.

It is a local tool. Your Markdown file is processed on your machine and is not uploaded to a server.

Use it when you have Markdown notes, specifications, tables, or generated Markdown reports that you want to review, distribute, or edit in Excel.

The goal is to preserve practical Markdown structure in a workbook. It is not intended to recreate a pixel-perfect Excel layout.

Quick Start

GitHub Release Asset

Download miku-md2xlsx-0.10.0.mjs from the GitHub Release, then run it directly from the download directory:

node miku-md2xlsx-0.10.0.mjs ./sample.md --out ./sample.xlsx
node miku-md2xlsx-0.10.0.mjs --help

The release asset requires Node.js but does not require a source checkout or npm install.

Repository Checkout

Install dependencies once:

npm install

Create a small Markdown file:

# Sales memo

| Item | Quantity | Note |
| --- | --- | --- |
| Apple | 3 | Checked |
| Orange | 5 | Pending |

## Next steps

- Confirm quantities
- Share with the team

Convert it to an Excel workbook:

npm run cli -- ./sample.md --out ./sample.xlsx

Split sheets by top-level headings:

npm run cli -- ./sample.md --out ./sample.xlsx --sheet-mode heading

Reuse an Excel template:

npm run cli -- ./sample.md --out ./sample.xlsx --template ./template.xlsx

Show help or version:

npm run cli -- --help
npm run cli -- --version

Generated Workbook Behavior

• Generated XLSX package entries use ZIP DEFLATE compression.
• Markdown headings become bold worksheet rows. Heading levels # through ###### use different font sizes.
• Markdown tables become worksheet rows with basic header and border styling.
• Bullet and numbered lists become worksheet rows. Nested list depth shifts the output to later columns.
• Markdown links become Excel hyperlinks when a cell contains a single link.
• Common inline styles such as **bold**, *italic*, ~~strike~~, <ins>underline</ins>, and <br> are converted to Excel rich text runs and cell-internal line breaks.
• Local PNG, JPEG, and GIF images referenced by relative Markdown paths are embedded best-effort when the files exist next to the input Markdown.
• Excel template reuse through --template <xlsx> writes generated sheet values into template sheets and reuses workbook-level style/theme parts.
• Markdown table cell values are written as strings. Numeric-looking, date-like, currency-like, and percentage-like text is not inferred or converted into Excel number/date cells.

What It Converts

Supported Markdown features include:

• headings
• paragraphs
• bullet and numbered lists
• Markdown tables
• fenced and indented code blocks
• horizontal rules
• Markdown links
• common inline styles: bold, italic, strikethrough, underline via <ins>, and <br> line breaks inside cells
• local PNG, JPEG, and GIF images referenced from Markdown

Local images are embedded on a best-effort basis when Markdown image URLs point to relative files next to the input Markdown file, such as ![chart](assets/chart.png). The Markdown image reference is also kept as workbook text so the original semantic reference remains visible. Remote URLs, absolute paths, and missing local files are left as text references.

Markdown table cell values are written as strings. Numeric-looking, date-like, currency-like, and percentage-like text is not inferred or converted into Excel number/date cells, so values such as 0010, 3月13日, and 98.7% remain the text written in Markdown.

miku-xlsx2md merge markers in table cells are converted into Excel merged cell ranges. [←M←] extends a merge to the left, and [↑M↑] extends a merge upward.

Markdown links are converted into Excel hyperlinks when a cell contains a single link. External links such as [Open example](https://example.com/) become external hyperlinks. miku-xlsx2md-style internal links such as [Jump to Other](#other) (Other!A1) become workbook hyperlinks to the generated sheet/cell target.

Common inline Markdown styles are written as Excel rich text runs. **bold**, *italic*, ~~strike~~, <ins>underline</ins>, and <br> are converted to cell formatting and cell-internal line breaks.

Markdown heading levels use different font sizes in the generated workbook, so # through ###### are visually distinguishable.

miku-xlsx2md Compatibility

This project is not a complete inverse converter for miku-xlsx2md. It supports practical compatibility for Markdown generated by miku-xlsx2md, while still prioritizing readable generated workbooks over exact restoration of the original Excel layout.

For Markdown generated by miku-xlsx2md, an early access input dialect is available:

npm run cli -- ./sample.md --out ./sample.xlsx --input-dialect miku-xlsx2md

This early access mode consumes # Book: as a structural marker without writing it to a cell, restores the text after ## Sheet: as the Excel sheet name subject to Excel naming restrictions and duplicate-name adjustment, and places the immediately following Markdown table at the cell range declared by ### Table: 001 (B12-F16). It provides a semantic round trip for sheet names, table structure, and supported merge markers; it does not aim to reproduce the original workbook pixel for pixel. The dialect and its restoration behavior may change while the feature is in early access.

miku-xlsx2md merge markers in table cells are converted into Excel merged cell ranges. [←M←] extends a merge to the left, and [↑M↑] extends a merge upward.

Known limitations:

• cell addresses outside declared table ranges, column widths, row heights, and detailed styles are not reconstructed
• formulas, charts, drawings, SmartArt, and conditional formatting are not generated
• image anchor positions, sizes, and drawing geometry are not restored exactly

CLI Options

Basic conversion:

npm run cli -- ./sample.md --out ./sample.xlsx

Split sheets by top-level headings:

npm run cli -- ./sample.md --out ./sample.xlsx --sheet-mode heading

Use the early access semantic restoration mode for Markdown generated by miku-xlsx2md:

npm run cli -- ./sample.md --out ./sample.xlsx --input-dialect miku-xlsx2md

The generic --sheet-mode heading --sheet-heading-depth 2 behavior remains available when second-level headings should split arbitrary Markdown without interpreting the Book:, Sheet:, and Table: metadata dialect. Do not combine --sheet-mode or --sheet-heading-depth with the dedicated miku-xlsx2md input dialect; the CLI rejects those combinations. In early access mode, malformed Sheet: or Table: markers and a Table: marker not immediately followed by its Markdown table cause conversion to fail instead of being interpreted heuristically. --title supplies a fallback sheet name only when the input contains no ## Sheet: marker.

Disable Markdown table header-row styling:

npm run cli -- ./sample.md --out ./sample.xlsx --no-header-row

Use plain table styling:

npm run cli -- ./sample.md --out ./sample.xlsx --table-style plain

Use an Excel template:

npm run cli -- ./sample.md --out ./sample.xlsx --template ./template.xlsx

--template treats the template workbook as a sheet-format source. The first generated sheet is written over the first template sheet, the second generated sheet over the second template sheet, and so on. When generated sheets exceed the number of template sheets, the rightmost template sheet is reused as the base for additional sheets.

Generated Markdown cell values replace the template sheet data. Template workbook styles, theme parts, and worksheet-level settings are reused where the current generator can preserve them. Template formulas, charts, drawings, tables, pivot data, shared strings, and existing cell values are not preserved as workbook content in the generated output.

Use template mode when the workbook needs a predefined visual frame, column or row settings, or sheet-level setup. Do not use it when existing workbook formulas, charts, drawings, or table objects must remain live after generation.

Current Status

This repository is in active development. It creates .xlsx files from Markdown document blocks, tables, links, common inline styles, local image references, and selected miku-xlsx2md compatibility markers.

See TODO.md for follow-up work.

Developer handoff notes are in docs/handoff-from-xlsx2md.md. Shared miku-soft reference information is in docs/miku-soft-reference.md.

Development Notes

Build and smoke-test the release bundles:

npm run build:bundle
npm run smoke:bundle
npm run smoke:runtime

build:bundle generates the executable CLI bundle, the importable runtime bundle, and the source bundle under bundle/.

The XLSX package helper is vendored under src/vendor/ as miku-ms-office-core. When updating it, replace the versioned vendor files and update the import in src/ts/xlsx-writer.ts.

workplace/ is a local scratch area for sister repository checkouts, generated verification files, and temporary artifacts. Only workplace/.gitkeep is tracked.

Generated build outputs under dist/, bundle/, and coverage/ are ignored.