Advanced VS Code Settings for Markdown to PDF

Visual Studio Code is the editor of choice for millions of developers. With the right extension, it is also a powerhouse for writing technical documentation, resumes, and ebooks. However, the default PDF export configurations are often basic, leaving you with suboptimal margins, missing page numbers, or generic styles. By optimizing your vs code markdown to pdf settings, you can turn your editor into an automated, publication-ready document generator.

In this guide, we will configure the popular Markdown PDF extension and write a custom settings.json file to manage styles, page margins, headers, and automatic exports on save.

Installing the Markdown PDF Extension

To begin, you will need the Markdown PDF extension by yzane. Open your VS Code extensions pane (Ctrl+Shift+X or Cmd+Shift+X on macOS) and search for:

Markdown PDF

Click install. This extension uses headless Chromium behind the scenes to export your Markdown files into beautifully formatted PDFs.

Tweaking settings.json for Custom Exports

Once installed, we can configure how the extension formats documents. Open your VS Code workspace settings by opening the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and selecting Preferences: Open Workspace Settings (JSON).

Add these custom configurations to automate output directory routing, apply page margins, and build custom headers:

{
  "markdown-pdf.outputDirectory": "build/pdf",
  "markdown-pdf.outputDirectoryRule": "relative",
  "markdown-pdf.format": "A4",
  "markdown-pdf.orientation": "portrait",
  "markdown-pdf.margin.top": "20mm",
  "markdown-pdf.margin.bottom": "20mm",
  "markdown-pdf.margin.left": "20mm",
  "markdown-pdf.margin.right": "20mm",
  "markdown-pdf.displayHeaderFooter": true,
  "markdown-pdf.headerTemplate": "<div style=\"font-size: 9px; margin: 0 auto; width: 100%; text-align: right; color: #bbb;\"><span class=\"title\"></span></div>",
  "markdown-pdf.footerTemplate": "<div style=\"font-size: 9px; margin: 0 auto; width: 100%; text-align: center; color: #bbb;\">Page <span class=\"pageNumber\"></span> of <span class=\"totalPages\"></span></div>",
  "markdown-pdf.styles": [
    "${workspaceRoot}/styles/pdf-theme.css"
  ],
  "markdown-pdf.convertOnSave": false
}

Explaining Key Settings:

• outputDirectory: Redirects compiled PDFs to a structured folder (build/pdf) instead of cluttering your working source directories.
• displayHeaderFooter: Activates top headers and bottom footers.
• headerTemplate & footerTemplate: Uses browser-supported templates to dynamically show the document title, current page numbers, and total page count.
• styles: References a custom stylesheet within your workspace to override standard default fonts and colors.

Creating a Workspace CSS Stylesheet

To customize colors, tables, and spacing, create a stylesheet inside your project folder at styles/pdf-theme.css. You can add custom styling rules to make headings stand out or to format code blocks cleanly:

body {
  font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
  color: #222;
  line-height: 1.5;
}

h1 {
  color: #0f172a;
  border-bottom: 2px solid #e2e8f0;
  padding-bottom: 0.5rem;
}

/* Style blockquotes for technical summaries */
blockquote {
  border-left: 4px solid #3b82f6;
  background-color: #f8fafc;
  padding: 0.5rem 1rem;
  color: #475569;
}

/* Ensure code blocks don't split awkwardly across page breaks */
pre {
  page-break-inside: avoid;
  border: 1px solid #e2e8f0;
}

Automating Exports on Save

If you are constantly updating a document and want to review the PDF in real-time, you can set "markdown-pdf.convertOnSave": true in your JSON settings. This automatically recompiles the PDF file every time you press save, creating a highly efficient loop for editing documentation.

Conclusion

Optimizing your VS Code workspace settings makes formatting and exporting documents from your local development environment seamless and reliable. By maintaining your styles in a dedicated theme file, you guarantee your output matches your preferences. If you’re working outside of VS Code or need a fast web-based preview of your documents, remember you can always use our free online editor.