Codebraid Preview provides a Markdown preview for
Pandoc documents within VS
Code. Most Markdown previews don’t support
all of Pandoc’s extensions to Markdown syntax. Codebraid Preview supports
100% of Pandoc features—because the preview is generated by Pandoc itself!
There is also full bidirectional scroll sync and document export.
Codebraid Preview provides optional support for executing code blocks and
inline code to embed their output in the preview and in exported documents.
Code execution is performed by
Codebraid using Jupyter kernels or its
own built-in code execution system.
HTML preview of Pandoc documents. Open the preview by running the “Open
Codebraid Preview” command (
Ctrl+Shift+P, then type command). Or, for
Markdown documents, just click on the “Codebraid Preview” button in the
status bar (bottom right). When changes are detected, the preview
Full bidirectional scroll sync. This requires processing the document
commonmark_x, which is CommonMark plus
commonmark_xhas most features of normal Pandoc Markdown and continues to
gain new features.
Math support with KaTeX. Surround LaTeX math with
single dollars signs
$for inline math or double dollar signs
block math, following standard Pandoc conventions.
Adjustable scroll sync directions. Once a preview window is open, click
on the “Scroll” button in the status bar (bottom right) to toggle scroll
Double-click to jump to source. Double-click in the preview, and jump
to the start of the corresponding line in the document.
Export documents with Pandoc (including Codebraid output). Simply click
the “Pandoc” button in the status bar (bottom right), or use the “Export
document with Pandoc” command (
Ctrl+Shift+P, then type command).
Scroll-sync support for multi-file documents. Pandoc allows you to
divide a document into multiple files. It can combine multiple files into a
single output document at build time. Codebraid Preview can display such
documents as long as all document files are in the same directory (folder)
if you create a YAML file that lists the documents to be combined. For
example, suppose your document is divided into
chapter_2.md, both in the same directory. Simple create a file named
_codebraid_preview.yamlwith this contents:
input-files: - chapter_1.md - chapter_2.md
Now, when you launch a preview in either
both files will be combined in the preview. When you scroll the preview,
the editor will automatically switch between
chapter_2.mddepending on which part of the document you are viewing.
That is, scroll sync works across multiple input files!
Execute code. Codebraid allows
code blocks or inline code in Pandoc Markdown documents to be executed, with
output embedded in the document. Simply add a Codebraid class to your code,
then click the “Codebraid” button in the status bar (bottom right) or use
the “Run code with Codebraid” command (
Ctrl+Shift+P, then type command).
Note that the document will take longer to build when using Codebraid, and
the preview will not automatically refresh when you make changes, like it
does when you are just using Pandoc. An upcoming version of Codebraid is
expected to allow automatic refresh with performance nearly the same as
using Pandoc by itself.
Install Pandoc. Version 126.96.36.199 or later is strongly
recommended. Earlier versions may work but will have reduced functionality,
including scroll sync issues with YAML metadata.
For code execution, install Codebraid
version 0.6.0 or later.
1000]: Minimum interval between
document builds in milliseconds. Builds only occur when there are changes.
commonmark_x]: Pandoc source
--from=FORMAT). Currently, only
codebraid.preview.pandoc.options[none]: Pandoc command-line options in
array form (for example,
Special Pandoc defaults file in document directory. If it exists and
input-files, the preview will automatically work with all files
in a multi-file document. Currently,
fromare the only
options that are supported; the full range of Pandoc defaults options is not
The HTML preview is displayed using a webview. A content security policy is
used to restrict what is possible in the webview. Inline scripts and styles
are allowed to support features like KaTeX math. Loading external resources
not associated with the extension is disabled.
Code is never automatically executed with Codebraid. Code is only ever
executed when a Codebraid class is added to a code block or inline code, and
then the “Codebraid” button is clicked (or the “Run code with Codebraid”
command is invoked). This is why documents using Codebraid currently do not
automatically refresh when changed. The core of Codebraid has just been
completely reimplemented. As a result, an upcoming version of Codebraid is
expected to decouple code execution from document update. This should allow
automatic document refresh without code execution.
Supporting this project
Codebraid Preview is open-source software released under the BSD 3-Clause
License. If you use it regularly, please consider supporting further
development through GitHub Sponsors.