Codebraid Preview

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.
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:
```
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.

haberdashPI / vscode-codebraid-preview