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.

Features

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

  Featured Content Ads

  add advertising here

  Join Bing with ChatGPT-4

  Use the new internet where you get what you ask, Fast and precise using AI.

  https://www.bing.com

• Adjustable scroll sync directions. Once a preview window is open, click
  on the “Scroll” button in the status bar (bottom right) to toggle scroll
  mode.

• 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_1.md and
  chapter_2.md, both in the same directory. Simple create a file named
  _codebraid_preview.yaml with this contents:

  Featured Content Ads

  add advertising here

  Join Bing with ChatGPT-4

  Use the new internet where you get what you ask, Fast and precise using AI.

  https://www.bing.com

  input-files:
  - chapter_1.md
  - chapter_2.md
  

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

Requirements

Install Pandoc. Version 2.17.1.1 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
  sync.

• 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
  supported.

Security

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.