Show HN: Codebraid Preview for VS Code: Pandoc Preview with Jupyter Kernels

Show HN: Codebraid Preview for VS Code: Pandoc Preview with Jupyter Kernels

Codebraid Preview provides a Markdown preview for
Pandoc documents within VS
. 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.

VS Code editor with Codebraid Preview


  • 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
    automatically refreshes.

  • Full bidirectional scroll sync. This requires processing the document
    as commonmark_x, which is CommonMark plus
    Pandoc extensions.
    commonmark_x has 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 $$ for
    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 and, both in the same directory. Simple create a file named
    _codebraid_preview.yaml with this contents:


    Now, when you launch a preview in either or,
    both files will be combined in the preview. When you scroll the preview,
    the editor will automatically switch between and depending 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 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.

Extension settings

  • codebraid.preview.minBuildInterval [1000]: Minimum interval between
    document builds in milliseconds. Builds only occur when there are changes.

  • codebraid.preview.pandoc.fromFormat [commonmark_x]: Pandoc source
    format (--from=FORMAT). Currently, only commonmark_x supports scroll

  • codebraid.preview.pandoc.options [none]: Pandoc command-line options in
    array form (for example, ["--filter", "FILTER"]).

  • codebraid.preview.pandoc.previewDefaultsFile [_codebraid_preview.yaml]:
    Special Pandoc defaults file in document directory. If it exists and
    defines input-files, the preview will automatically work with all files
    in a multi-file document. Currently, input-files and from are 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.

Read More

Charlie Layers

Charlie Layers

Fill your life with experiences so you always have a great story to tell