How to Convert Markdown to PDF: Four Methods Compared

Knowing how to turn Markdown into a PDF is a practical skill for developers, technical writers and documentation teams. Maybe you're sharing a report, submitting a resume, or publishing documentation. PDF is still the most widely accepted format. This guide walks through four different methods, with details on image handling and platform-specific steps that most guides skip.

Why Converting Markdown to PDF Matters

Markdown (MD) is a lightweight markup language built for readability in plain text. It powers README files on GitHub, documentation in static site generators and note-taking in apps like Obsidian. But clients, recruiters and stakeholders rarely want a raw .md file.

Portable Document Format (PDF) preserves your layout, fonts and images no matter what device or operating system the recipient uses. The catch? Converting between these two formats isn't always simple, especially when your document includes images, tables or custom styling.

The four methods covered here are: Pandoc command line, VS Code extension, online converter tools and desktop applications like Typora and Okular. Each comes with a different skill ceiling, cost profile and output quality.

Method 1: Using Pandoc on the Command Line

Pandoc is widely considered the gold standard for command line Markdown to PDF conversion. It's a free, open-source document converter that supports dozens of input and output formats. If you want precise control over the output, Pandoc is your best path to convert Markdown with minimal compromises.

Installing Pandoc on Windows, Mac and Linux

Installation varies by operating system. On Mac, run brew install pandoc via Homebrew. On Ubuntu or Debian Linux, use sudo apt-get install pandoc. On Windows, download the installer directly from pandoc.org or use winget install pandoc from PowerShell.

Pandoc needs a LaTeX engine to produce PDF output. Install TeX Live on Linux, MacTeX on Mac or MiKTeX on Windows. Without LaTeX, Pandoc will throw an error when you target PDF output.

Running the Conversion Command

The basic command is straightforward:

pandoc input.md -o output.pdf

You can add styling with a custom CSS file using the --css flag when exporting via HTML intermediary, or pass LaTeX variables directly. For example, to set margins and font size:

pandoc input.md -o output.pdf -V geometry:margin=1in -V fontsize=12pt

For Markdown to PDF with images, make sure all image paths in your .md file are relative to the file location. Pandoc resolves local image paths correctly when you run the command from the same directory as your Markdown file.

Aspect

Rating

Output quality

Excellent

Image support

Full (local and remote)

Learning curve

Moderate

Cost

Free

Platform support

Windows, Mac, Linux

Method 2: VS Code Extension Workflow

Visual Studio Code (VSCode) has become the editor of choice for millions of developers. The Markdown PDF extension by yzane brings Markdown to PDF conversion directly into your editor, with no terminal commands needed. This makes it a good fit for those who spend most of their day inside VSCode.

Installing and Configuring the Extension

Open VSCode, go to the Extensions panel (Ctrl+Shift+X or Cmd+Shift+X on Mac) and search for "Markdown PDF". Install the extension published by yzane. It uses Chromium under the hood, so it renders your document exactly as a browser would. That's a real advantage for CSS-heavy documents.

Once installed, right-click inside any open .md file and select Markdown PDF: Export (pdf). The PDF appears in the same directory as your Markdown file within seconds.

Custom CSS and Theme Options

The VSCode Markdown PDF extension supports custom stylesheets. In your settings.json, add the path to a CSS file:

"markdown-pdf.styles": ["./custom-style.css"]

This lets you control fonts, heading colours, table borders and page margins directly through CSS. Most competing tools do not support this at this level of ease. You can also configure header and footer templates using HTML strings in the settings.

• Install via the VSCode Extensions Marketplace in under 60 seconds
• Export to PDF, PNG, JPEG or HTML from a single right-click menu
• Custom CSS support for complete visual control
• Images render correctly when paths are relative to the project root
• No LaTeX dependency required, unlike Pandoc

Image handling note: Remote images (URLs) render correctly in most cases. Local images require paths relative to the workspace root. If images appear blank in your PDF output, switch from absolute paths to relative paths in your Markdown source. Learn more about fixing image rendering issues in PDF exports.

Method 3: Online Converter Tools

Online Markdown converters need no installation and work on any device. Tools like APITemplate's free Markdown to PDF converter, Dillinger.io and Markdown2PDF.com let you paste or upload your Markdown and download a PDF in three steps or fewer.

Step-by-Step Guide Using an Online Converter

1. Open your chosen online converter in a browser (APITemplate offers a real-time preview editor)
2. Paste your Markdown text into the editor or upload your .md file
3. Review the live preview on the right-hand panel to check formatting
4. Click the Download or Export button to save the PDF to your device

Most free online converters handle basic Markdown formatting well: headings, bold/italic text, lists, code blocks and tables. The gap appears with images. Free md to pdf tools often strip local image references because they cannot access files on your computer. If your document contains images, you must either host them at a public URL or use a different method.

Paid online tools, such as APITemplate's API-based PDF generation, do support image injection through base64 encoding or hosted asset URLs. Pricing typically starts at around $9 per month for API access, which is worthwhile for teams producing PDFs programmatically at scale. Compare free vs paid PDF tools for Markdown workflows.

Method 4: Desktop Applications (Typora and Okular)

Desktop applications offer the most visual, beginner-friendly approach to Markdown to PDF conversion. Two tools stand out: Typora and Okular.

Typora is a premium Markdown editor (one-time licence of approximately $14.99 USD) available on Windows, Mac and Linux. It renders Markdown in real time and exports to PDF via File > Export > PDF. Typora supports custom CSS themes, making it one of the most polished options for producing publication-quality PDFs without touching the command line.

Okular is a free document viewer developed by the KDE project, primarily for Linux. It supports Markdown rendering and PDF export natively, which makes it a solid free option for Linux users who do not want to configure Pandoc or install Node.js dependencies.

Tool

Platform

Cost

Image Support

Custom CSS

Pandoc

Win/Mac/Linux

Free

Full

Via flags

VSCode + Extension

Win/Mac/Linux

Free

Relative paths

Full

Online (APITemplate)

Browser

Free/Paid

Remote URLs only

Limited

Typora

Win/Mac/Linux

$14.99

Full

Full

Okular

Linux

Free

Full

No

Handling Images and Formatting in PDF Output

Image handling is where most guides fall short, so it deserves dedicated attention. When you convert Markdown to PDF with images, the converter must locate and embed those image files. Each method handles this differently.

With Pandoc, images are embedded at conversion time. Run the command from the directory containing both your .md file and your image assets. If you reference ![Chart](./images/chart.png), Pandoc will find and embed that file correctly.

With the VSCode Markdown PDF extension, images work best when stored inside the workspace folder. Avoid absolute paths like C:\Users\Name\Pictures\chart.png on Windows. Instead, place images in a subfolder relative to your project, such as ./assets/chart.png.

For online converters, the safest approach is to host images on a public server (GitHub, a CDN or an S3 bucket) and reference them by URL in your Markdown. This bypasses the local file access restriction entirely. See our guide to embedding images in technical documentation PDFs.

Platform-Specific Notes for Windows, Mac and Linux

The experience of converting Markdown to PDF differs meaningfully across operating systems. Here is a concise breakdown for each platform.

Windows

Windows users often face PATH configuration issues after installing Pandoc or MiKTeX. After installation, restart your terminal and run pandoc --version to confirm it is accessible. The VSCode Markdown PDF extension works on Windows without any additional configuration and is generally the easiest starting point.

Mac

Mac users benefit from Homebrew, which makes installing Pandoc and MacTeX straightforward. Run brew install pandoc followed by downloading MacTeX from tug.org. Typora also performs exceptionally well on macOS and integrates with macOS's native font rendering for crisp PDF output.

Linux

On Linux, both Pandoc and Okular are available through standard package managers. Debian/Ubuntu users can install both with a single apt command. Linux users also have the most flexibility for scripting batch conversions using shell scripts combined with Pandoc or Node.js-based tools like md-to-pdf.

Frequently Asked Questions

What is the best format to convert to PDF?

For document-focused content, Markdown and HTML are the two most reliable source formats for PDF conversion. Markdown is ideal when you write in plain text and want a simple, repeatable export process. HTML gives you more layout control. For highly designed documents, starting in a word processor like LibreOffice Writer and exporting to PDF may produce better results than converting from Markdown.

Can I convert Markdown to PDF without installing anything?

Yes. Online converters like APITemplate, Dillinger.io and Markdown2PDF.com need no installation. You paste your Markdown content, preview the result and download the PDF directly from your browser. The trade-off is limited image support and reduced control over styling compared to local tools.

Why do my images not show up in the PDF?

The most common cause is an incorrect image path. Local image paths must be relative to the Markdown file, not absolute system paths. For online converters, local images cannot be accessed at all. Use publicly hosted image URLs instead. With Pandoc on Windows, also check that you are running the command from the correct working directory.

Is Pandoc free to use commercially?

Yes. Pandoc is released under the GPL-2.0 licence and is completely free to use for personal and commercial projects. There are no usage limits or paid tiers. The LaTeX engines it depends on (TeX Live, MacTeX, MiKTeX) are also free and open-source.

How do I add custom fonts or styles to my Markdown PDF?

The approach depends on the tool. In VSCode with the Markdown PDF extension, point the extension to a custom CSS file in your settings. In Pandoc, use the --css flag when converting via HTML-to-PDF, or pass LaTeX font variables for direct PDF output. In Typora, apply a custom CSS theme from the Themes settings panel.

Final Thoughts

To convert Markdown to PDF effectively, the right method depends on your workflow, technical comfort and output requirements. For developers who work in the terminal, Pandoc delivers the most control and the highest quality output, particularly for documents with complex formatting or LaTeX-based equations. For everyday writers who live inside VSCode, the Markdown PDF extension is fast, reliable and requires no additional configuration beyond a simple install.

Online tools serve occasional users or teams that need a quick export without any local setup. They are a practical free option for text-heavy documents but fall short on image-heavy content. Typora fills a genuine gap for users who want a visual, polished experience and do not mind a one-time licence fee. If you are on Linux and want something free with a graphical interface, Okular is worth testing as well.

Your next step is to pick one method and run a test conversion with a real document from your workflow. Pay close attention to how images render and whether your code blocks and tables appear correctly. Once you find the method that meets your quality bar, consider writing a small script or keyboard shortcut so that converting Markdown to PDF becomes a one-click operation rather than a recurring manual task.

---

Try the ToolsVela tools mentioned in this guide

All of these run in your browser — no signup, no uploads, completely free.

• Markdown Previewer — Live-render Markdown with GFM tables and syntax highlighting.
• Markdown to PDF Converter — Try our browser-based exporter with live preview.
• PDF Converter — Convert text, images, or Word documents into a PDF.
• HTML/CSS/JS Compressor — Minify generated HTML before exporting.

Browse all 4 free tools →