mkdn

Convert files to Markdown using Cloudflare Workers AI.

Works as a CLI and as a Node.js library — zero runtime dependencies.

Install

npm install -g @oele_dev/mkdn

Or use directly with npx:

npx @oele_dev/mkdn file.pdf

Setup

mkdn uses the Cloudflare Workers AI API. You need a free Cloudflare account.

1. Get your Account ID from the Cloudflare dashboard
2. Create an API Token at https://dash.cloudflare.com/profile/api-tokens
3. Run:

mkdn auth

For CI/scripts, use non-interactive mode:

mkdn auth --account-id YOUR_ID --token YOUR_TOKEN

Or set environment variables (useful for CI/Docker):

export CLOUDFLARE_ACCOUNT_ID=your-account-id
export CLOUDFLARE_API_TOKEN=your-api-token
mkdn file.pdf

Environment variables take priority over saved credentials.

CLI Usage

# Convert a file (output to stdout)
mkdn file.pdf

# Save to file
mkdn file.pdf -o output.md

# Multiple files
mkdn file.pdf document.docx spreadsheet.xlsx

# Pipe to clipboard (macOS)
mkdn file.pdf | pbcopy

# JSON output (includes token count)
mkdn file.pdf --json

# Read from stdin
cat file.pdf | mkdn - --type pdf

# List supported formats
mkdn formats

Library Usage

import { convert, createClient } from 'mkdn'

// Uses saved credentials (~/.config/mkdn/config.json)
const results = await convert('document.pdf')
console.log(results[0].data)    // markdown string
console.log(results[0].tokens)  // estimated token count

// Multiple files
const results = await convert(['file.pdf', 'doc.docx'])

// With explicit credentials
const client = createClient({
  accountId: 'your-account-id',
  apiToken: 'your-api-token'
})
const results = await client.convert(['file.pdf'])

// From buffer
const buffer = fs.readFileSync('file.pdf')
const result = await client.convertBuffer(buffer, 'file.pdf')

Supported Formats

| Format | Extensions | |--------|-----------| | PDF | .pdf | | Word | .docx | | Excel | .xlsx, .xlsm, .xlsb, .xls, .et | | OpenDocument | .ods, .odt | | CSV | .csv | | HTML | .html, .htm | | XML | .xml | | SVG | .svg | | Images | .jpeg, .jpg, .png, .webp | | Apple Numbers | .numbers |

How It Works

mkdn sends files directly to the Cloudflare Workers AI toMarkdown API. Conversion is free for most formats. Image conversion uses AI models for object detection and may use your Workers AI free tier allocation.

Your files are processed on Cloudflare's edge network and are not stored.

Auth Management

mkdn auth            # Set up credentials (interactive)
mkdn auth status     # Show current credentials
mkdn auth logout     # Remove stored credentials

Credentials are stored in ~/.config/mkdn/config.json (or $XDG_CONFIG_HOME/mkdn/config.json).

Why mkdn?

| | mkdn | Pandoc | Markitdown | Docling | |---|---|---|---|---| | Install | npx mkdn | System package | pip install | pip install | | Dependencies | Zero | Haskell runtime | Python + extras | Python + ML models | | Image OCR | Yes (AI) | No | Limited | Yes (heavy) | | Setup | 1 min | Varies | Varies | Complex | | Runs on | Cloudflare edge | Local | Local | Local |

mkdn is the fastest path from "I have a file" to "I have Markdown". No Python, no system packages, no ML models to download.

Requirements

• Node.js 18+
• Cloudflare account (free tier works)

License

MIT