Markdown 4 Quarto
Markdown 4 Quarto brings Quarto-oriented scientific authoring features to the native Markdown preview in Visual Studio Code, while keeping .md files as the primary writing surface.
Author in native Markdown. Publish with Quarto.
The core idea is simple: the native Markdown preview in VS Code is extremely fast, fluid, and tightly integrated with the editor. Markdown 4 Quarto preserves that experience instead of replacing it with a custom preview.
You keep all the native behavior you already expect from VS Code Markdown:
- synchronized scrolling between source and preview;
- double-click in the preview to jump back to the corresponding source position;
- editor-selection highlighting in the preview;
- path suggestions;
- Markdown validation;
- the lightweight rendering speed of the built-in preview.
Markdown 4 Quarto adds a focused layer of Quarto/Pandoc-oriented scientific authoring features on top of that native experience.
The model
The extension is designed around a separation between writing and publishing:
section.md
│
┌──────────────┴──────────────┐
▼ ▼
VS Code native preview included in .qmd
│ │
Markdown 4 Quarto Quarto
│ │
▼ ▼
fast authoring UX HTML / PDF / DOCX
A .md file remains lightweight and pleasant to edit. A .qmd file can then embed it for document-level composition, metadata, styling, and final output:
{{< include section.md >}}
This means you can spend most of your time writing in .md, with the native VS Code Markdown experience, and use Quarto only where its publishing system is needed.
Why this approach?
Many scientific and technical documents are mostly prose, citations, figures, tables, equations, notes, and cross-references. They do not need executable code chunks in every section.
For those documents, using the native Markdown preview provides a noticeably more immediate authoring loop than a full document render pipeline.
Markdown 4 Quarto therefore follows one architectural principle:
Keep Markdown optimized for writing; keep Quarto optimized for publishing.
The extension intentionally does not try to reproduce Quarto's computational runtime, notebook execution, or code-chunk engine. Computation belongs in .qmd when it is needed.
Features
Markdown 4 Quarto currently adds support for:
- GitHub-style alerts:
NOTE, TIP, IMPORTANT, WARNING, CAUTION;
- footnotes using
[^id];
- Quarto/Pandoc-style cross-references for sections, figures, tables, and equations;
- BibTeX citations;
- CSL-based citation formatting;
- parenthetical, narrative, and multiple citations;
- automatic bibliography rendering in the native preview;
- Quarto project variables through
_variables.yml and {{< var ... >}};
- Quarto-style equation labels such as
$$ {#eq-linear}.
Whenever Quarto/Pandoc already has an appropriate syntax, the extension prefers to reuse it rather than inventing a preview-only syntax.
Recommended VS Code settings
The repository includes a .vscode/settings.json with settings that complement the extension:
{
"markdownNative.bibliography": "references.bib",
"markdownNative.csl": "sample-author-date.csl",
"markdownNative.locale": "en-US",
"markdownNative.renderBibliography": true,
"markdown.preview.doubleClickToSwitchToEditor": true,
"markdown.preview.markEditorSelection": true,
"markdown.suggest.paths.enabled": true,
"markdown.validate.enabled": true
}
The first four settings belong to Markdown 4 Quarto. The remaining settings are native VS Code Markdown features.
Native source/preview navigation
With:
"markdown.preview.doubleClickToSwitchToEditor": true
you can double-click a location in the preview and VS Code jumps back to the corresponding source position.
With:
"markdown.preview.markEditorSelection": true
the current source selection is reflected in the preview.
Together with VS Code's native synchronized scrolling, this provides a very fluid source/preview writing workflow.
Open the preview
Open a Markdown file and use:
Ctrl+K V
or run:
Markdown: Open Preview to the Side
Markdown 4 Quarto enriches this built-in preview directly.
GitHub-style alerts
> [!NOTE]
> This is a note.
> [!TIP] Custom title
> This alert uses a custom title.
> [!WARNING]
> Pay attention to this point.
The source remains readable as ordinary Markdown even without the extension.
A statement can have a footnote.[^method]
[^method]: Additional methodological explanation.
Cross-references
Sections
## Methods {#sec-methods}
See @sec-methods.
{#fig-map}
See @fig-map.
Tables
| Variable | Value |
|---|---:|
| A | 10 |
: Results summary {#tbl-results}
See @tbl-results.
Equations
Use the same source syntax that Quarto understands:
$$
y = a + bx
$$ {#eq-linear}
See @eq-linear.
Supported prefixes are:
sec-
fig-
tbl-
eq-
Quarto project variables
If a Markdown file belongs to a Quarto project, the extension looks for _variables.yml beside _quarto.yml or _quarto.yaml.
Example:
version: 0.1.1
project:
name: Markdown 4 Quarto
tagline: "*Author fast in Markdown, publish fully with Quarto.*"
links:
quarto: "[Quarto](https://quarto.org)"
Then use the same shortcode syntax as Quarto:
Version: **{{< var version >}}**
Project: {{< var project.name >}}
{{< var project.tagline >}}
See {{< var links.quarto >}}.
Values containing Markdown are resolved before Markdown parsing, so emphasis and links render naturally in the native preview.
Nested keys use dot notation:
{{< var project.name >}}
The Quarto escape form is also supported:
{{{< var version >}}}
Fenced blocks can disable shortcode processing with:
```{shortcodes=false}
{{< var version >}}
```
BibTeX citations and CSL
Configure a bibliography and CSL style:
{
"markdownNative.bibliography": "references.bib",
"markdownNative.csl": "style.csl"
}
Parenthetical citation:
The result has been discussed previously [@silva2024].
Narrative citation:
@silva2024 discusses the same result.
Multiple citations:
[@silva2024; @pereira2022]
When:
"markdownNative.renderBibliography": true
is enabled, cited references are collected and rendered automatically at the end of the native preview.
Embedding .md files in Quarto
This is a central use case of the extension.
A project can keep prose in Markdown files:
paper/
├── index.qmd
├── _introduction.md
├── _methods.md
├── _results.md
├── _discussion.md
├── references.bib
└── figures/
while index.qmd provides publication-level composition and styling:
---
title: "My paper"
format:
html: default
pdf: default
docx: default
---
{{< include _introduction.md >}}
{{< include _methods.md >}}
{{< include _results.md >}}
{{< include _discussion.md >}}
The .md files remain the fast authoring surface. The .qmd wrapper handles document metadata, styling, and output formats.
The same content can therefore be:
written in .md
↓
previewed instantly in VS Code
↓
included in .qmd
↓
published as HTML / PDF / DOCX
Quarto compatibility helper
This repository includes a small Quarto extension/filter used by the sample project to convert GitHub-style alerts into native Quarto callouts during publication.
The VS Code extension itself remains focused on authoring in the native Markdown preview.
Sample files
The repository includes:
sample.md — complete demonstration of the native preview features;sample.qmd — Quarto wrapper that embeds sample.md;_variables.yml — sample Quarto variables;references.bib — sample bibliography;sample-author-date.csl — sample CSL style.
To render the same Markdown content through Quarto:
quarto render sample.qmd --to html
quarto render sample.qmd --to pdf
quarto render sample.qmd --to docx
Development
Clone the repository and install dependencies:
git clone https://github.com/lsbjordao/markdown-4-quarto.git
cd markdown-4-quarto
npm install
code .
Press F5 to open an Extension Development Host window.
Inside it, open sample.md and use Ctrl+K V.
Packaging
Install the official VS Code extension packaging CLI:
npm install -g @vscode/vsce
Then run:
vsce package
For version 0.1.1, this creates:
markdown-4-quarto-0.1.1.vsix
Install it locally with:
code --install-extension ./markdown-4-quarto-0.1.1.vsix --force
License
MIT
