md2kindle

Turn Markdown, HTML, a web page or an arXiv paper into a clean, Kindle-ready EPUB — entirely in your browser. Diagrams, equations and images included. Nothing is ever uploaded.

→ Try it live at md2kindle.arahim.dev

Why this exists

A lot of what's worth reading now begins life as a Markdown or HTML file. You ask an AI to explain a topic, draft a guide, or walk you through a paper, and what comes back is genuinely good — but it's stuck in a chat window or a .md on your laptop, in front of the same bright screen you've been staring at all day.

If you love reading on a Kindle — the matte e-ink, no notifications, the way a long piece finally settles down and feels like a book — there's no tidy way to get that text onto the device. So you end up emailing yourself a wall of plain text, or fighting a converter that mangles the diagrams and equations.

md2kindle is for exactly that moment. Hand it the Markdown (or a link, or the raw HTML) and it gives back a clean EPUB — images, diagrams and math intact — ready to send to your Kindle and read the way you'd read a book.

Why EPUB only? Amazon's Send to Kindle stopped accepting MOBI on 18 March 2025. Modern Kindles take a DRM-free EPUB and convert it on-device. EPUB is also the only format that can be produced 100% client-side — which is what keeps your documents private.

---

Features

• 100% on-device. All conversion runs in your browser. Your text and images never leave the tab — no server, no upload.
• Markdown or HTML. Upload or paste either. For HTML, an optional Readability pass strips nav, ads and footers down to just the article (great for saved blog posts).
• Import a blog by URL. Paste a link; the page (and its images) are fetched, cleaned with Readability, and bound. See URL fetching for how this works across hosts.
• arXiv papers. Paste an id (2410.01383), a DOI, or any /abs/, /pdf/ or /html/ link into the URL box. The paper's HTML edition is fetched and bound with its figures, tables and equations, one chapter per section. See arXiv papers.
• Images, kept intact — embedded (data:) images, remote URLs, and local files supplied alongside the Markdown.
• Mermaid diagrams — ```mermaid code blocks are rendered and embedded as crisp images.
• Math — $inline$, $$display$$, and \(...\) / \[...\], typeset with MathJax. Equations are sized in em so they scale with the reader's font. Pages that ship MathML with its LaTeX source (arXiv, Pandoc, KaTeX) are typeset the same way, rather than left to the Kindle's patchy MathML support.
• Raw SVG — inline <svg> figures are rasterised and embedded too.
• Reader-friendly defaults — a clean reading stylesheet: hyphenation off so words don't break mid-line, and code wraps instead of running off the screen.
• Real chapters & table of contents — auto-split on headings (configurable), with a navigable EPUB TOC and an NCX fallback.
• Auto cover — a clean typographic cover is generated for you (or upload your own).
• Front matter aware — title, author, language are read from YAML front matter when present.

Bringing in your content

Pick a format (Markdown or HTML), then one of five ways to supply it:

Mode	Use it for
URL / arXiv	Fetch a web page or a paper by link — images and all. HTML only.
Single file	One .md or .html.
File + images	Pick the document together with its image files (matched by name).
Folder	Drop a whole folder; relative image paths (images/fig.png) resolve automatically.
Paste	Quick notes, or a copied HTML page.

URL fetching

Browsers block cross-origin fetch() (CORS), so importing an arbitrary URL needs a tiny server-side helper that fetches the page (and proxies its images). That helper ships with the app and the client feature-detects it, giving three tiers:

Host	URL import
Local (npm run dev / npm run preview)	Full — built into the dev/preview server.
Vercel	Full — the included api/fetch.ts Edge function.
GitHub Pages (static)	Limited — direct browser fetch only, so just CORS-enabled sites. Everything else still works.

Upload & paste are always 100% on-device. The URL helper only ever sees the public link you give it; the public Vercel function additionally refuses private/loopback hosts (basic SSRF guard).

On analytics. The hosted site counts anonymous page views via Vercel Web Analytics — cookieless, served from its own origin, and it never sees the document you're converting. It's a build-time dependency only: self-host or run locally and no analytics call is made at all.

Webfonts are self-hosted too, so the page makes no third-party requests at all — and works offline once loaded.

arXiv papers

Drop any of these into the URL box and the paper is fetched for you:

2410.01383                              arXiv:2410.01383v2
https://arxiv.org/abs/2410.01383        https://arxiv.org/pdf/2410.01383v1
10.48550/arXiv.2410.01383               hep-th/9901001

The paper's HTML edition (arxiv.org/html/…) is used, not the PDF — so the text reflows properly on a Kindle instead of being stuck in two fixed columns. Figures, tables, footnotes and the bibliography are kept; each section becomes a chapter, and every equation is typeset as an image so it looks right on any Kindle generation. arXiv allows cross-origin requests, so this works on every host tier above, including static GitHub Pages.

One caveat: arXiv only generates HTML for LaTeX submissions from December 2023 onward, and some conversions fail. When there's no HTML the app says so — those papers are PDF-only, and Amazon's Send to Kindle takes PDFs directly.

Getting the book onto your Kindle

1. Convert and download the .epub.
2. Email it to your personal @kindle.com address, or use the Send to Kindle app / web page. Amazon converts it for your device automatically.

---

Development

npm install
npm run dev        # start the dev server
npm run build      # type-check + production build to dist/
npm run preview    # preview the production build on :4173

Tests

npm run test:deps  # smoke-test external dependency contracts (Node)

# End-to-end (drives a real browser, generates an EPUB, validates it):
npm run build && npm run preview &   # serve the build on :4173
npm run test:e2e                     # requires: npx playwright install chromium

Tech

markdown-it · mermaid · MathJax · DOMPurify · JSZip · React + Vite + TypeScript.

The heavy conversion engine (MathJax, mermaid, JSZip) is lazy-loaded on first use, so the page itself loads fast. Because mermaid and canvas rasterisation need the DOM, conversion runs on the main thread with progress reporting between stages.

How it works

Markdown                          HTML / URL
  └─ front matter                   └─ arXiv paper?  → take the LaTeXML article
       → title/author/language      └─ otherwise     → Readability (optional)
  └─ markdown-it                    └─ MathML + its LaTeX → math placeholder
       (+ footnotes, task lists, math plugin)
       └─ DOMPurify → safe DOM
            ├─ resolve <img> (data: / remote / local files) → embed
            ├─ raw <svg>           → rasterise → PNG
            ├─ mermaid code blocks → render → PNG
            └─ $math$ / $$math$$   → MathJax → SVG → PNG
       └─ split into chapters + rewrite in-document anchors
       └─ assemble EPUB 3 (JSZip): OPF · nav.xhtml · NCX · stylesheet · images
EPUB ⬇

Deploy

• GitHub Pages — push to main; the included workflow (.github/workflows/deploy.yml) builds and publishes automatically. Enable Pages → "GitHub Actions" in the repo settings. vite.config.ts uses base: './', so it works from a project sub-path.
• Vercel — import the repo; the Vite preset works out of the box (build command npm run build, output dist).

Notes & limits

• Remote images require permissive CORS to be fetched from the browser.
• Math and diagrams are embedded as raster PNGs (rendered at 2× for sharpness on 300 ppi screens) so they look identical on every Kindle generation.
• The output targets EPUB 3 with an NCX fallback; it was validated for structure and XHTML well-formedness, but not run through epubcheck here (no JRE in the build environment).

License

MIT