formatferry-markdown
Converts local HTML, DOCX, PDF, XLSX, CSV, JSON, XML and PPTX files (or stdin) to Markdown in 8 flavours (GitHub, CommonMark, Slack, Discord, Reddit, Confluence, Google Docs, R Markdown). Local conversion runs in-process and, with --offline, makes no network calls. Two optional features use the network: --url sends the URL to the FormatFerry API for server-side fetching (needs FORMATFERRY_API_KEY and the user's explicit go-ahead), and a stored license key triggers an entitlement check against formatferry.vibingfun.com unless --offline is passed.
FormatFerry Markdown Converter
Document-to-Markdown converter. Local files and stdin are converted in-process and never uploaded. Supports 8 input formats and 8 output flavours, with optional network-backed URL extraction and premium batch mode.
Network use at a glance
| Mode | Network | What is sent |
|---|---|---|
Local file / stdin with --offline | None | Nothing |
Local file / stdin without --offline, license key stored | formatferry.vibingfun.com | License key for an entitlement check (cached 24h) |
--url <url> | FormatFerry API | The URL and API key; the page is fetched and processed server-side |
Key differentiator vs alternatives: Output flavours tailor Markdown to specific platforms (Slack *bold* vs GitHub **bold**, Confluence wiki markup, R Markdown, etc.). No other converter offers this.
Prerequisites
- Node.js 18+ and npm must be installed
- Install the CLI globally:
npm install -g formatferry@1.0.51
The skill is tested against CLI 1.0.51; install that exact version rather than the latest.
Supported File Types
| Format | Extension | Notes |
|---|---|---|
| HTML | .html, .htm | Web pages, snippets |
| Word | .docx | Microsoft Word documents |
.pdf | Including OCR for scanned documents | |
| Excel | .xlsx | Spreadsheets with tables |
| CSV | .csv | Comma-separated data |
| JSON | .json | Structured data |
| XML | .xml | Markup and data feeds |
| PowerPoint | .pptx | Slide content |
Supported Markdown Flavours
Use the -f / --flavour flag to select output format:
github(default) — GitHub Flavored Markdowncommonmark— Standard CommonMarkslack— Slack-compatible markdowndiscord— Discord-compatible markdownreddit— Reddit-compatible markdownconfluence— Confluence wiki markuprmarkdown— R Markdowncustom— Custom format
Usage Examples
# Convert a file
formatferry -i document.docx -o output.md
# Pipe HTML from stdin
echo '<h1>Hello</h1>' | formatferry --offline
# Choose a flavour
formatferry -i notes.html -f slack -o notes.md
# Convert a PDF (includes OCR for scanned documents)
formatferry -i paper.pdf -o paper.md
# URL extraction (requires FORMATFERRY_API_KEY)
formatferry --url https://example.com/article -o article.md
# Batch convert (requires FORMATFERRY_LICENSE_KEY)
formatferry --batch "docs/**/*.docx" --output-dir ./markdown/
Environment Variables
Both environment variables are optional. The CLI works for local file conversion with zero credentials.
| Variable | Required | Purpose |
|---|---|---|
FORMATFERRY_API_KEY | No | Needed only for --url flag (URL extraction). Not needed for local file conversion. |
FORMATFERRY_LICENSE_KEY | No | Needed only for --batch mode (premium feature). |
Set them via your shell profile or pass inline:
FORMATFERRY_API_KEY=ff_xxxxx formatferry --url https://example.com/article
Privacy
- Local file conversion is fully in-process — file content is never uploaded or sent to any server
- Optional license validation ping — if a license key is stored, the CLI may contact
formatferry.vibingfun.comto check entitlement (cached for 24h).--offlineskips this check - URL extraction (
--url) sends the URL to the FormatFerry API, which fetches and processes the page server-side.--offlinedoes not change this. Never use--urlfor internal, private or signed URLs - Credentials —
formatferry authstores API and license keys in the CLI's local config. Prefer theFORMATFERRY_API_KEY/FORMATFERRY_LICENSE_KEYenvironment variables for one-off use, and runformatferry auth --logoutto remove stored keys
Procedure
-
Determine input type:
- Text/pasted content → pipe to stdin or save to temp file
- File path → use
-i <path> - URL → only when the user explicitly asks to convert a web page and agrees that the URL is sent to FormatFerry's server; then use
--url <url>(requiresFORMATFERRY_API_KEY). Otherwise ask the user for the file - Multiple files → use
--batch(requiresFORMATFERRY_LICENSE_KEY)
-
Execute conversion:
bash # Stdin (most common for agent use): always offline echo "$INPUT" | formatferry --offline # File: always offline formatferry --offline -i "$FILE_PATH" -o "$OUTPUT_PATH" # URL: only after the user has agreed to server-side fetching formatferry --url "$URL" -o output.md -
Capture output:
- stdout is Markdown by default
- Use
-o <file>to write directly to file
-
Return clean Markdown to user
-
Clean up temp files if created
Pitfalls & Recovery
| Issue | Solution |
|---|---|
formatferry: command not found | Install via npm install -g formatferry@1.0.51 |
node: command not found | Install Node.js 18+ first |
| API rate limit hit | Wait 60s or use local file input instead of URL |
| Large file (>20MB PDF) | Consider splitting before conversion |
| Invalid URL | Verify URL starts with http:// or https:// |
| Empty output | Verify input has content; check for HTML entity encoding issues |
Verification
# Test basic conversion
echo '<h1>Test</h1><p>Content</p>' | formatferry --offline
# Verify no HTML tags remain
echo '<div>test</div>' | formatferry --offline | grep -c '<.*>' || echo "Clean: 0 HTML tags"
# Test file conversion
TMP_DIR=$(mktemp -d)
echo '<p>File test</p>' > "$TMP_DIR/test.html"
formatferry --offline -i "$TMP_DIR/test.html"
rm -rf "$TMP_DIR"
Related skills
- Downloads
- 1.4kAll time
- Security audit
- Pass
- Last updated
- 19h ago
- Current version
- v1.1.6
- License
- MIT-0
