LaTeX in Markdown for Pandoc

Features | Installation | Quickstart | Usage | Showcase

Visual Studio Code extension that brings LaTeX syntax highlighting to Markdown documents processed with Pandoc.

Features

LaTeX code in the Pandoc-flavoured Markdown frontmatter is highlighted with this extension. You can keep using your favorite theme.

Features are as follows:

• Highlight LaTeX code in Pandoc-flavoured Markdown
  • [x] LaTeX code in Markdown frontmatter written in YAML
  • [ ] [WIP] LaTeX code in Markdown body

Frontmatter highlight

Frontmatter highlight in dark theme (Atom One Dark):

Frontmatter highlight in light theme (Bold Light (rainglow)):

Installation

This extension is available for free in the Visual Studio Code Marketplace.

If you're a Cursor user, you cannot install this extension from the marketplace now (planned to be supported in the future). However, you can install it from a .vsix file. See the section Install locally for details.

Quickstart

1. Install this extension from the Visual Studio Code Marketplace.
2. Create a new Markdown file.
3. Copy the contents of quickstart example into your Markdown file.
4. LaTeX code in the Markdown frontmatter will be highlighted.

Usage

Frontmatter highlight

To highlight LaTeX code in the frontmatter, e.g. Frontmatter highlight, you need to add two YAML comments shown below to the frontmatter:

• # ----- pandoc-latex-begin -----
• # ----- pandoc-latex-end -----

After adding them, the range between them in frontmatter is highlighted as LaTeX code. This is a necessary step to enable LaTeX syntax highlight in the frontmatter. We provide utility snippets to easily add these comments.

If correctly set up, LaTeX code like \usepackage{graphicx} is highlighted. For example, your Markdown's frontmatter should look like:

---
# ----- pandoc-latex-begin -----

# The code below is treated as normal YAML
documentclass: extarticle
papersize: a4
pagestyle: empty
geometry:
  - top=17.5mm
  - bottom=20mm
  - left=20mm
  - right=20mm

# The code below is highlighted as LaTeX code in your editor!
header-includes:
  - \usepackage{xcolor}
  - \usepackage{graphicx}
  - \usepackage{titlesec}
  - \usepackage{setspace}

# ----- pandoc-latex-end -----
--- # <- punctuation to end frontmatter

Utility snippets

Use the following snippets to insert comments mentioned above quickly.

for new empty Markdown file

You can add frontmatter template by typing pandoc template like below:

for existing frontmatter

You can add frontmatter comments that trigger the highlighting by typing pandoc begin and pandoc end. You must type these inside the frontmatter block.

[!WARNING] You might think LaTeX code will still be highlighted even if you skip adding the end comment # ----- pandoc-latex-end ----- to the frontmatter.

However, this extension depends on those comments to delimit the scope it highlights, so omitting them can lead to unexpected errors. Make sure you add the # ----- pandoc-latex-end ----- comment to the end of the frontmatter correctly.

Showcase

In this section, we show some examples of LaTeX in Markdown for Pandoc. As an appendix, we also show how to build PDF and LaTeX files from Markdown files with Pandoc.

Overview

Each example contains a list of files as follows:

• main.md: The main Markdown file
• main.tex: The output LaTeX file (intermediate file)
• main.pdf: The output PDF file (final output)

Examples

• Resume with single column layout
  • This example shows how to write a resume with a single column layout
• Statistics - basics of the normal distribution
  • This example shows how to write a statistics topic in Japanese

Appendix: How to build examples in showcase

This appendix shows how to build PDF and LaTeX files from a Markdown file with Pandoc for the example "Resume with single column layout".

[!NOTE] This section is specifically for macOS users.

While it may be possible to build on other platforms, please be aware of potential differences.

Environment

• macOS Sonoma 14.7
• Pandoc 3.8
• MacTeX 2025.0308
  • XeLaTeX 3.141592653-2.6-0.999997 (TeX Live 2025)

Install dependencies

Install pandoc and MacTeX:

# Install pandoc
brew install pandoc

# Install MacTeX (this takes 10-20 minutes on slow internet)
brew install --cask mactex

Check versions:

pandoc --version
# pandoc 3.8
xelatex --version
# XeTeX 3.141592653-2.6-0.999997 (TeX Live 2025)

In this example, xelatex is used as PDF engine.

Clone repository

git clone git@github.com:nukopy/latex-in-markdown-for-pandoc.git

Build PDF and LaTeX files from Pandoc-flavoured Markdown

cd latex-in-markdown-for-pandoc/examples/showcase/resume_single_column

# build PDF file
pandoc main.md --pdf-engine=xelatex -o main.pdf
file main.pdf

# build LaTeX file
pandoc main.md -s -t latex -o main.tex
file main.tex

Open main.pdf in a viewer and main.tex in your editor to see the result.

Roadmap

• [x] Highlight LaTeX code in Pandoc-flavoured Markdown
  • [x] LaTeX in Markdown frontmatter written in YAML
  • [ ] LaTeX in Markdown body
• [ ] Extend LSP support to LaTeX code in Markdown (hover documentation and go-to-definition) or LaTeX Workshop integration.
  • [ ] LaTeX in Markdown frontmatter written in YAML
  • [ ] LaTeX in Markdown body

Motivation

I built this extension while writing my resume with Pandoc.

I needed proper LaTeX syntax highlighting inside Markdown, both in YAML frontmatter and the body.

Development

Requirements

• Node.js v22.16.x
• Visual Studio Code v1.99.x or later
• (optional) Cursor 1.7.x or later

Setup

git clone git@github.com:nukopy/latex-in-markdown-for-pandoc.git
cd latex-in-markdown-for-pandoc
pnpm i

Now, you can start developing the extension.

Build

pnpm run vsce:build

If successful, the extension package dist/latex-in-markdown-for-pandoc-<version>.vsix is created.

Install locally

Execute command Extensions: Install from VSIX... in VS Code (or Cursor) and select the file dist/latex-in-markdown-for-pandoc-<version>.vsix.

Prepare for publishing

1. Create Azure DevOps organization
2. Create Personal Access Token
   • Copy the Personal Access Token for next step
3. Create a publisher

ref: Publishing Extensions | Visual Studio Code

Publish to VS Code Marketplace

• Login to VS Code Marketplace

pnpm run vsce:login -- <publisher ID>
# input Personal Access Token

• Edit version in package.json

{
-  "version": "0.1.0"
+  "version": "0.1.1"
}

• Release

pnpm run vsce:publish

• Unpublish

pnpm run vsce:unpublish

References

Thanks to the following references for inspiration:

• Pandoc User's Guide — YAML metadata blocks and header-includes
• Pandoc User's Guide — Variables
• Pandoc User's Guide — raw attribute extension ({=latex})
• Visual Studio Code Extension API — Syntax Highlight Guide (Injection Grammars)
• vscode-latex-basics/markdown-latex-combined.tmLanguage.json

License

LaTeX in Markdown for Pandoc is under the MIT License: See LICENSE file.