MarkNest

A Markdown workspace analyzer and PDF converter. Upload a ZIP, point to a folder, or pass a single .md file — MarkNest resolves local images, renders Mermaid diagrams and math, and produces print-ready PDFs.

Try it online: dontsendfile.com/md2pdf

https://github.com/user-attachments/assets/489b1b61-a840-4374-8eb5-d90d5fa1f4db

Features

• Workspace-aware — analyzes folders, ZIP archives, and GitHub URLs; resolves relative image paths automatically
• Mermaid & Math — renders fenced Mermaid diagrams to SVG and LaTeX math via MathJax, with configurable off/auto/on modes
• Themes & styling — built-in presets (default, github, docs, plain), custom CSS, header/footer templates, per-side margins
• Batch conversion — convert all Markdown files in a workspace at once, preserving directory structure
• Browser & CLI — WASM-powered browser preview with no server upload, plus a native CLI for local and CI workflows
• PDF quality controls — page size, orientation, table of contents, PDF metadata, print-layout page breaks
• Security built in — Zip Slip prevention, path traversal blocking, HTML sanitization on by default, archive size limits
• Offline rendering — Mermaid, MathJax, and html2pdf.js assets are vendored locally; no external CDN required
• Remote images — best-effort fetch and inline of HTTP images across CLI, browser, and fallback flows
• Local fallback server — Playwright-driven Chromium PDF generation for high-quality output when browser export isn't enough
• Docker image — single image bundles CLI, fallback server, Chromium, and fonts for reproducible builds

Quick Start

# Install
cargo install marknest

# Install a headless browser for PDF rendering
npx playwright install chromium

# Convert a Markdown file to PDF
marknest convert README.md -o README.pdf

Installation

Cargo (from crates.io)

cargo install marknest

npm / npx

# Run without installing
npx marknest convert README.md -o output.pdf

# Or install globally
npm install -g marknest
marknest convert README.md -o output.pdf

From source

git clone https://github.com/developer0hye/marknest.git
cd marknest
cargo install --path crates/marknest

Docker

docker build -t marknest .

# CLI usage
docker run --rm -v "$PWD":/work -w /work marknest marknest convert README.md -o README.pdf

# Fallback server (default CMD)
docker run --rm -p 3476:3476 marknest

Browser prerequisite

PDF rendering requires a local Chromium-based browser. If none is installed:

npx playwright install chromium
# or for headless-only environments:
npx playwright install --with-deps chromium

Browser discovery order: MARKNEST_BROWSER_PATH env var > Playwright headless shell > system Chrome/Edge/Chromium.

Usage

Validate

Check workspace structure, image links, and Mermaid/Math blocks without generating a PDF.

marknest validate README.md
marknest validate ./docs.zip --entry docs/README.md
marknest validate ./docs --all --report report.json
marknest validate ./docs --all --strict

Convert — single file

marknest convert README.md -o README.pdf
marknest convert README.md --theme github --landscape -o README.pdf
marknest convert README.md --toc --mermaid auto --math auto -o README.pdf
marknest convert README.md --css custom.css --header-template header.html -o README.pdf
marknest convert README.md --page-size letter --margin-top 24 --margin-bottom 24 -o README.pdf
marknest convert README.md --title "Guide" --author "Team" --subject "Arch" -o README.pdf

Convert — ZIP or folder (batch)

marknest convert ./docs --out-dir ./pdf
marknest convert ./docs.zip --all --out-dir ./pdf
marknest convert ./docs.zip --entry docs/README.md -o out.pdf

Convert — GitHub URL

marknest convert https://github.com/user/repo -o output.pdf
marknest convert https://github.com/user/repo/blob/main/docs/guide.md -o guide.pdf
marknest convert https://github.com/user/repo/tree/v2.0 --all --out-dir ./pdf

Set GITHUB_TOKEN or GH_TOKEN for private repositories or to avoid API rate limits.

Debug artifacts

marknest convert README.md \
  --debug-html ./out/debug.html \
  --asset-manifest ./out/assets.json \
  --render-report ./out/report.json \
  -o README.pdf

Configuration

Settings can be provided through CLI flags, a config file, or environment variables.

Precedence: CLI args > config file > environment variables > built-in defaults

# Use a config file
marknest convert README.md --config .marknest.toml -o README.pdf

Config files are auto-discovered from .marknest.toml or marknest.toml in the working directory.

Exit codes

Web App

The browser app provides ZIP upload, entry selection, HTML preview, and PDF download — all client-side via WASM.

trunk serve

Export modes:

• Browser Fast — client-only PDF generation, no data leaves the browser
• High Quality Fallback — sends ZIP to the local fallback server for Playwright/Chromium rendering

The web app also supports theme/CSS/margin/TOC/metadata controls, Mermaid/Math preview, debug bundle download, and batch ZIP export.

Fallback Server

cargo run -p marknest-server

Listens on http://127.0.0.1:3476 by default (override with MARKNEST_SERVER_ADDR). Accepts multipart ZIP uploads with output options and returns PDF or batch ZIP.

Project Structure

Development

# Format
cargo fmt --all

# Test
cargo test

# Check WASM target
cargo check -p marknest-wasm --target wasm32-unknown-unknown

# Install Playwright runtime for native PDF
npm ci --prefix crates/marknest/playwright-runtime

# Install validation dependencies
npm ci --prefix validation

License

MIT