Start with the simpler option

Most one-off conversions do not need an installed tool. If you have one ordinary file and want one result, a browser converter is usually faster. Open the file, review the Markdown, and download it.

An Agent Skill earns its setup when conversion is already part of a Codex or Claude Code task. The agent can extract a report, edit the Markdown, create a new deliverable, and verify that output without moving the file through a separate conversion service.

Both ilovemd and the installed Skill process supported files locally. The practical difference is where the workflow lives: in a browser tab or inside the agent task.

SituationBetter starting point
One straightforward fileBrowser converter
Quick Markdown cleanup or previewBrowser tool
Repeated conversions inside Codex or Claude CodeAgent Skill
PDF → Markdown → another outputAgent Skill
The agent must verify the generated artifactAgent Skill
Exact reproduction of a complex layoutManual or format-specific workflow
Open the browser toolsConvert, edit, and preview Markdown without installing anything

Why Markdown works as the middle layer

Markdown preserves the parts an agent can edit reliably: headings, paragraphs, lists, links, code, and many simple tables. That makes it a useful working format between a source file and a new deliverable.

The intermediate step also sets the fidelity boundary. A PowerPoint deck becomes readable slide content, not its original design. A newly generated PPTX is built from that Markdown structure; it cannot recreate positions, animations, fonts, or media that disappeared during extraction.

Use this route when the content matters more than a pixel-perfect round trip.

Install the Markdown Converter Agent Skill

The public Skill works with Codex, Claude Code, and other clients that support the Agent Skills format. It requires Node.js 20 or newer. Its conversion runtime, OCR worker and language data, fonts, renderer, and verifier are bundled in the repository.

After installation, the agent can use the Skill instructions for supported conversion tasks. You can also call the bundled runtime directly. Set MARKDOWN_CONVERTER_DIR to the directory containing the installed SKILL.md instead of assuming that the current working directory is the Skill directory.

Install the Skill
npx skills add agent-tools-lab/markdown-converter --skill markdown-converter
Portable runtime pattern
node "$MARKDOWN_CONVERTER_DIR/scripts/runtime/convert.mjs" INPUT --to FORMAT -o OUTPUT

Convert a text PDF to Markdown

Use ordinary extraction when the PDF already has a usable text layer. A quick check is to open the file in a PDF reader and try to select a sentence.

Expect readable content and likely structural cues such as paragraphs, headings, and bullets. PDF stores positioned page content rather than a semantic document outline, so columns, complex tables, equations, footnotes, and unusual typography still need review.

Text PDF → Markdown
node "$MARKDOWN_CONVERTER_DIR/scripts/runtime/convert.mjs" report.pdf --to markdown -o report.md

Use OCR for image-only PDF pages

A scanned page can look readable while containing no machine-readable text. For those pages, the Skill can run bundled local OCR. It extracts native text where available and applies OCR only to pages without a usable text layer.

The current OCR models cover English, Spanish, German, Japanese, and Simplified Chinese. The PDF limits are 30 MB, 100 total pages, and 20 OCR pages per file.

Proofread OCR output against the scan. Names, dates, amounts, punctuation, headings, and tables deserve particular attention. Handwriting, low-resolution scans, dense columns, and exact table reconstruction are outside the promised boundary.

Scanned PDF → Markdown with English OCR
node "$MARKDOWN_CONVERTER_DIR/scripts/runtime/convert.mjs" scan.pdf --to markdown --ocr-language eng -o scan.md
OCR languageCode
Englisheng
Spanishspa
Germandeu
Japanesejpn
Simplified Chinesechi_sim

Convert DOCX to editable Markdown

Text-first Word documents are good candidates. Paragraphs, headings, lists, links, and simple tables map naturally into Markdown, which makes the result easier for an agent to revise or publish elsewhere.

Word-specific features do not have equivalent Markdown syntax. Do not expect exact page layout, embedded media, comments, tracked changes, macros, floating elements, fonts, or spacing to survive faithfully.

DOCX → Markdown
node "$MARKDOWN_CONVERTER_DIR/scripts/runtime/convert.mjs" report.docx --to markdown -o report.md
Check the Markdown syntaxReview headings, tables, lists, links, and code before the next export

Create a searchable PDF from Markdown

Markdown can be the source as well as the destination. The Skill generates an A4 PDF with real text objects rather than turning every page into a screenshot. Supported text can therefore be searched, selected, copied, and extracted.

The PDF is a new document rendered from the Markdown. If the workflow began with another PDF, its original page design does not return automatically.

Markdown → searchable PDF
node "$MARKDOWN_CONVERTER_DIR/scripts/runtime/convert.mjs" notes.md --to pdf -o notes.pdf
Try Markdown to PDF in the browserEdit the source, inspect the preview, and download a searchable PDF

Know what the format list means

The Skill accepts documents, presentations, web content, plain text, structured data, and PDFs. Every non-Markdown input first becomes editable Markdown. A second requested output is generated from that intermediate.

The output list is broader than a typical one-way converter, but the target name does not promise application-specific behavior. JSON is a Markdown token tree, Confluence is legacy Wiki Markup, and Notion output is import-oriented Markdown rather than a Notion API operation.

FamilyCurrent examplesMain boundary
InputsPDF, DOCX, XLSX/XLS, PPTX, HTML, TXT, CSV, JSON, XMLContent and structure become Markdown; layout and application behavior can be lost
DocumentsPDF, DOCX, XLSX, PPTX, EPUBNew files are generated from Markdown rather than reconstructed from an earlier source
Publishing and textHTML, plain text, LaTeX, AsciiDoc, RTF, RST, Confluence, Notion, Reveal, WeChatEach target has renderer- or platform-specific limits
Data and imagesCSV, Markdown-token JSON, mind-map JSON, PNG, JPG, CardTable/data targets need suitable source structure; Card is a designed summary

Verify the generated artifact

A zero exit code does not prove that a document is usable. Run the bundled verifier for every generated artifact, then inspect representative content in the application where the file will be read.

Treat a failed verifier as a failed conversion. Keep the original input as well; conversion should create a derivative rather than overwrite the only source copy.

  • Confirm that the output exists, is non-empty, and opens in the target application.
  • Compare representative headings, paragraphs, lists, tables, links, and code with the source.
  • Check that non-English text displays correctly.
  • For PDF output, confirm that representative text can be selected or extracted.
  • For OCR input, compare names, numbers, headings, and at least one paragraph with the visible scan.
  • Record any fidelity loss that matters to the next step.
Verify a generated PDF
python3 "$MARKDOWN_CONVERTER_DIR/scripts/verify_output.py" notes.pdf --format pdf

What local conversion does and does not promise

The Skill runs its conversion process locally and does not send source text, filenames, or output content to ilovemd.net or another conversion API. Generated artifacts do not receive a product logo, watermark, promotional footer, attribution link, or hidden product metadata.

Local execution does not make a lossy format translation lossless. Preserve the original file, review the result, and use a format-specific workflow when page design, formulas, comments, tracked changes, animation, presenter notes, embedded media, equations, or exact complex tables are the asset.

Keep moving

Related converters, Markdown tools, and guides

Popular converters

Markdown to PDFConvert Markdown to a searchable A4 PDF in your browser.Markdown to WordConvert Markdown to editable Word documents (.docx) online for free.Markdown to HTMLConvert Markdown to clean, standalone HTML instantly.Markdown to Plain TextStrip Markdown formatting to clean plain text.
More converters (25)
Markdown to PNG ImageRender supported Markdown structure as a high-resolution PNG image.Markdown to JPG ImageConvert Markdown to JPG images online.Markdown to PowerPoint (PPTX)Convert Markdown to PowerPoint (.pptx) presentations.Markdown to SlidesConvert Markdown into a Reveal.js HTML slide deck.Markdown Table to CSVConvert Markdown tables to CSV format.Markdown to Excel (XLSX)Convert Markdown tables directly to Excel (.xlsx) spreadsheets.Markdown to JSON ASTParse Markdown into a structured JSON AST (abstract syntax tree).Markdown to RTF (Rich Text)Convert Markdown to RTF format for cross-platform rich text editing.Markdown to EPUB EbookConvert Markdown to EPUB ebook format.Markdown to LaTeXConvert Markdown to LaTeX source code for academic papers and scientific documents.Markdown to AsciiDocConvert Markdown to AsciiDoc source.Markdown to reStructuredTextConvert Markdown to reStructuredText (RST) for Python documentation, Sphinx, and docutils.Markdown to Confluence Wiki MarkupConvert Markdown to legacy Confluence Wiki Markup online for compatible Confluence Data Center workflows and markup fields.Markdown to NotionClean and normalize Markdown for Notion's Text & Markdown import workflow.Markdown to Mind MapRender Markdown headings as an interactive mind map.Markdown to Social Card ImageRender Markdown as a styled social media card image (PNG).Markdown to WeChat ArticleConvert Markdown to inline-styled HTML for the WeChat editor.HTML to MarkdownTurn HTML into clean, editable Markdown.CSV to MarkdownTurn CSV rows into a Markdown table.Word to MarkdownOpen a DOCX file as editable Markdown.Excel to MarkdownTurn XLSX workbook sheets into editable Markdown tables.PowerPoint to MarkdownExtract slide titles and text from a PPTX file.JSON to MarkdownTurn objects and arrays into Markdown tables and lists.XML to MarkdownMap elements, attributes, and text into readable Markdown.Text to MarkdownNormalize plain-text lists and continue editing in Markdown.

Markdown tools

Markdown EditorWrite and revise Markdown with a rich preview.Markdown PreviewOpen an MD file and inspect the rendered result.Table GeneratorBuild a table visually or import CSV and TSV.Markdown FormatterNormalize headings, lists, spacing, and syntax.Markdown Cheat SheetLook up syntax with copy-ready examples.Learn MarkdownPractice with 24 interactive questions.
Frequently asked questions

Agent workflows FAQs

Can Codex convert PDF to Markdown with this Agent Skill?

Yes. Text PDFs use local text extraction. Image-only pages can use bundled OCR when they fit the documented language, size, and page limits.

Can Claude Code use the same Markdown Converter Skill?

Yes. The repository uses the product-neutral Agent Skills format for Codex, Claude Code, and compatible clients.

Does every PDF need OCR?

No. PDFs with a usable text layer should use ordinary extraction. OCR is reserved for image-only pages without readable native text.

Can it convert Word, Excel, and PowerPoint files to Markdown?

Yes. DOCX, XLSX/XLS, and PPTX are supported inputs. The result preserves readable content and structure rather than office layout, formulas, styling, animation, or media.

Can Markdown be converted back to Word or PowerPoint?

Yes. DOCX and PPTX are supported outputs, but they are newly generated from Markdown and are not exact reconstructions of an earlier source file.

Is the generated PDF searchable?

Yes for supported characters. The PDF writer creates real text objects, and the verification step checks for a non-empty extractable text layer.

When should I use ilovemd.net instead?

Use the browser tools for a quick one-off conversion, edit, or preview. Use the installed Skill when conversion belongs inside a repeated or multi-step agent workflow.

Where can I install the Markdown Converter Agent Skill?

Install it from github.com/agent-tools-lab/markdown-converter with npx skills add agent-tools-lab/markdown-converter --skill markdown-converter.