Codebraid Preview provides a Markdown preview for Pandoc documents within VS Code.

Overview

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.

VS Code editor with Codebraid Preview

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.

Comments
  • Codebraid doesn't recognise and doesn't render Markdown plugins

    Codebraid doesn't recognise and doesn't render Markdown plugins

    Hello!

    For example, I have @qjebbs's Markdown Extended extension that comes with admonition plugin.

    Test and preview:

    !!! danger Atenção
        Por favor, sempre utilize Git Bash. Não recomendamos Prompt do Comando (`cmd`). 
    

    @yzhang-gh's Markdown All in One extension recognises Markdown plugins and renders them very well. Microsoft's native Markdown Preview also recognises and renders them perfectly.

    enhancement pandoc 
    opened by gusbemacbe 30
  • Min. codebraid version check failing

    Min. codebraid version check failing

    I'm using the newest version of this extension as well as the newest version of codebraid on a windows machine through WSL. Since updating to the latest version of the preview, the codebraid version check keeps failing, and thus it is not applied.

    A notification appears saying:

    Codebraid is not installed or is out of date (need v0.7.0+). Install or upgrade (https://pypi.org/project/codebraid/), then reload the extension. Code execution and loading output from cache is disabled.

    However running codebraid --version in the terminal yields Codebraid 0.7.0 as required. It seems the check_codebraid.ts has not worked.

    `

    bug enhancement 
    opened by lcnhb 13
  • You overwrote our syntax highlighting CSS

    You overwrote our syntax highlighting CSS

    Hello,

    We have own syntax highlighting CSS. We use Prism.js or Highlight.js.

    Using VSCode's native Markdown Preview, our syntax highlighting CSS is used and not overwritten.

    But with your extension, our syntax highlighting isn't used and is overwritten.

    opened by gusbemacbe 8
  • Support syntax highlighting for julia

    Support syntax highlighting for julia

    This adds support for highlighting julia code in Markdown files intended for codebraid.

    I'm guessing this might also be useful for other langauges, but I know at least python already works, and I haven't tested the other options.

    enhancement 
    opened by haberdashPI 5
  • LaTeX macros do not execute in preview

    LaTeX macros do not execute in preview

    LaTeX macros defined within my markdown file do not execute when the preview is displayed. However they behave correctly when using a different pandoc-based preview extension for VSCode, namely Pandoc Markdown. Can you show a simple example where this works correctly?

    Screenshot 2022-07-25 094458

    documentation 
    opened by i-thot-u-wanted2dance 3
  • matplotlib plots are not rendering

    matplotlib plots are not rendering

    I'm using codebraid-preview 0.5.1 with codebraid 0.8. When I run the short file below in a conda environment that includes matplotlib I do not get a plot in the output.

    • Tested on M1 Mac, macOS 12.4
    • Python and codebraid installed in a conda environment.
    • Pandoc installed via homebrew

    Screenshot of result:

    no-plot_md

    Input file is attached:

    no-plot.md

    discussion 
    opened by mwcraig 2
  • KaTeX math failing to render

    KaTeX math failing to render

    The math equations aren't being rendered out of the box for me, while they work with another Markdown preview. Here's a recording:

    https://user-images.githubusercontent.com/31820255/156712109-fa83f9cf-07e8-474f-8efd-546d5068e4fe.mp4

    bug 
    opened by UtkarshVerma 2
  • Please publish to [open-vsx.org](https://open-vsx.org/) in addition to the VS Code Marketplace

    Please publish to [open-vsx.org](https://open-vsx.org/) in addition to the VS Code Marketplace

    VSCodium is the open-source build of VSCode, with less/no telemetry sent to MS etc.

    Would it be possible to publish this great extension also on the open-vsx.org marketplace in addition to the VS Code Marketplace?

    The publishing process is documented in the Open VSX Wiki.

    Thanks!

    enhancement 
    opened by mfhepp 1
  • how to add pandoc arguments

    how to add pandoc arguments

    From the readme, it says one should add pandoc arguments as follows:

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

    I've tried several ways but it won't take my options, tried it in different ways (settings.json):

    {
      "codebraid.preview.pandoc.options": [
          "`[\"--filter\", \"pandoc-crossref\"]`",
          "[\"--filter\", \"pandoc-crossref\"]",
          "[--filter, pandoc-crossref]",
          "\"--filter=pandoc-crossref\"",
          "--filter=pandoc-crossref",
       ],
    }
    

    But none of them seems to work. Could you assist how to add them correctly?

    bug 
    opened by dswbx 1
  • Previewing Local Images

    Previewing Local Images

    Hi, I couldn't get local images to render using your extension.

    I reviewed issue #13 including this comment which mentions "you may be using a different directory structure or something else may be interfering". I am not sure what would be interfering.

    The file for which I want to insert an image is located in a directory structure like this: ~\Documentation\resources\file.md. The image I am linking is located here: ~\Documentation\images\image.jpg. In the markdown, I reference the image like this: ![alt](../images/image.jpg.

    I am not sure what to change in order to get this to work. I am unfamiliar with the Webview API - any direction you could provide would be greatly appreciated!

    opened by jdc136 1
  • Change font using my own stylesheet

    Change font using my own stylesheet

    I am trying to set the previewer to show a font different to the font i am using in vscode?

    Is this possible? Maybe Im missing something..

    1 - adding pandoc arg --css in vscode settings.json

    "codebraid.preview.pandoc.options": [
            "--css assets/css/theme.css"
        ]
    

    2 - Adding css: to _codebrain_preview.yml

    #  _codebrain_preview.yml
    css: assets/css/theme.css
    

    CSS:

    body {
      font-family: 'Liberation Serif';
    }
    

    I know its working using only pandoc with this test:

    pandoc --defaults _codebraid_preview.yml -o market-research.html market-research.md
    # this outputs an html with font as 'Liberation Serif'
    

    Removing --css flags from this.pandocPreviewArgs does enable my custom font from the stylesheet.

    bug 
    opened by fhill2 2
  • Add previewing images support

    Add previewing images support

    Hello, I couldn't get images to load using your extension.

    After searching the Webview Content Security Policy instructions, I found that adding the img-src ${webview.cspSource} https:; snippet to this line works well.

    Is this a feature you wish to add? Or is there a security risk I missed?

    Thanks.

    opened by mateibarbu19 2
  • Codebraid doesn't understand @tarleb's Lua filter `list-table` because of container without point (even if with point)

    Codebraid doesn't understand @tarleb's Lua filter `list-table` because of container without point (even if with point)

    Hello!

    You can check the Lua file at @tarleb's list-table. Codebraid doesn't understand that Lua filter because Codebraid accepts only the container with point.

    Observe that I modified the Lua filter, adding a point for list-table as Codebraid, but it gave the same error too.

    Here is the screenshot:

    image

    I tested with the command pandoc -s "List of supported languages in three syntax highlighters.md" -o result.html -f commonmark_x -t html5 -L filters/lua/list-table.lua on terminal. Pandoc understood the Lua filter and generated without error:

    image

    opened by gusbemacbe 2
  • Numbering and cross-references

    Numbering and cross-references

    opened by i-thot-u-wanted2dance 1
  • Feature request: Add option for filters in

    Feature request: Add option for filters in "_codebraid_preview.yaml"

    I usually like to keep my reports consolidated in a single folder, with the filters also stored. The folder organization may vary for different reports, therefore I wish there was an option to specify the filters used for generating the preview.

    include-code-files is one of my personal favourites when it comes to filters.

    Currently, I did this for the builds using pandocomatic using the following in the document frontmatter.

    ---
    title: 'Exp 4: Stepper motor control with systick timer'
    author: Utkarsh Verma
    date: \today
    
    pandocomatic_:
      pandoc:
        from: markdown
        to: pdf
        template: ../template.tex
        lua-filter:
          - ../../.filters/include-code-files.lua
    ---
    

    I also like the fact that pandocomatic can be configured directly inside the frontmatter. Could we have something for codebraid preview as well?

    opened by UtkarshVerma 4
Releases(v0.10.0)
  • v0.10.0(Dec 4, 2022)

    • Added new settings codebraid.preview.css.useDefault and codebraid.preview.css.overrideDefault for controlling whether the default preview CSS is loaded and whether it is overridden by document CSS. Document CSS now has precedence by default (#14).

    • A Codebraid Preview defaults file now has precedence over the extension's Pandoc settings.

    • Updated KaTeX to v0.16.3.

    Source code(tar.gz)
    Source code(zip)
    codebraid-preview-0.10.0.vsix(1.01 MB)
  • v0.9.0(Jul 29, 2022)

    • The preview Pandoc AST is now preprocessed before any user filters are applied. Adjacent Str nodes that are wrapped in data-pos spans as a result of the sourcepos extension are now merged. sourcepos splits text that normally would have been in a single Str node into multiple Str nodes, and then wraps each in a data-pos span. The preprocessing makes user filters behave as closely as possible to the non-sourcepos case (#9).

    • Added details about commonmark_x, including LaTeX macro expansion, to README (#10).

    • When the Codebraid process fails and there is stderr output, the full details are now written to the Output log.

    Source code(tar.gz)
    Source code(zip)
    codebraid-preview-0.9.0.vsix(1.00 MB)
  • v0.8.0(Jul 11, 2022)

    • _codebraid_preview.yaml now supports essentially all Pandoc defaults options and no longer limits the characters allowed in filter file names (#2). Previously, only input-files, input-file, from, and filters were supported.

    • The "Codebraid Preview" button in the status bar now only appears when a Markdown document is open and visible, and does not yet have a preview. Previously, after the extension loaded, the button was visible for non-Markdown files and was also visible if the info panel was open.

    • Fixed a bug that prevented YAML metadata from working with Codebraid.

    • Fixed a bug that prevented identification of inherited languages (for example, with .cb-paste).

    Source code(tar.gz)
    Source code(zip)
    codebraid-preview-0.8.0.vsix(1.00 MB)
  • v0.7.0(Jun 29, 2022)

  • v0.6.0(Jun 25, 2022)

    • Minimum supported Codebraid is now v0.9.0. The preview now shows correct file names and line numbers for errors/warnings related to the Markdown source, rather than using file names like <string> and line numbers that are incorrect when multiple Markdown sources are concatenated. The preview now shares cache files with normal Codebraid processing, rather than creating a separate cache entry. All of this is based on the new Codebraid option --stdin-json-header.

    • Fixed a bug that prevented codebraid executable from being located in Python installations with the python executable under bin/ or Scripts/ rather than at the root of the environment (#5).

    • Improved and optimized process for finding codebraid executable.

    • Updated KaTeX to v0.16.0.

    • Improved display of Codebraid output in the preview. Code chunks that have not yet been processed/executed by Codebraid and thus do not have output are indicated by placeholder boxes. Output from modified code chunks or from stale cache is more clearly indicated.

    • Improved responsiveness of progress animations for "Codebraid" button and preview. There is no longer a significant, noticeable time delay between clicking the button and the start of button and preview progress animations.

    • Added logging in VS Code's Output tab, under "Codebraid Preview".

    Source code(tar.gz)
    Source code(zip)
  • v0.5.1(Jun 12, 2022)

    • Fixed scroll sync bug that could cause the editor to jump to the beginning of a document when the preview is scrolled to the very end of the document.
    Source code(tar.gz)
    Source code(zip)
  • v0.5.0(Jun 11, 2022)

    • Minimum supported Codebraid is now v0.8.0.

    • Improved process for locating codebraid executable. If a Python interpreter is set in VS Code, then that Python installation is now checked for a codebraid executable. If no executable is found, then PATH is checked for a codebraid executable. A warning message is displayed when the Python installation set in VS Code lacks an executable and the extension falls back to an executable on PATH. Previously, only PATH was checked for an executable (#5).

    • If the codebraid executable is part of an Anaconda installation, it is now launched via conda run so that the relevant environment will be activated.

    • Fixed a bug that prevented Codebraid output from being displayed for code chunks with a named session or source.

    Source code(tar.gz)
    Source code(zip)
  • v0.4.0(Jun 4, 2022)

    • Added support for --only-code-output from Codebraid v0.7.0. The preview now refreshes automatically for Codebraid documents, displaying all code output that is currently available. The build process is now nearly as fast as plain Pandoc. Code execution still requires clicking the "Codebraid" button or using the "Run code with Codebraid" command.

    • Added basic support for filters in _codebraid_preview.yaml (#2). Spaces and some other characters are not currently supported in filter names.

    • When the extension loads, it now checks whether Codebraid is installed and determines the Codebraid version. Loading a Codebraid-compatible document now results in an error message if Codebraid is not installed or if the version available is not compatible with Codebraid Preview. Plain preview without code execution still works automatically in these cases.

    • Added Codicons for displaying messages in the preview webview.

    • Fixed a bug that prevented error messages from stderr from being correctly converted to literal text in HTML.

    • Scroll sync is now supported for all CommonMark-based formats (commonmark, commonmark_x, gfm), not just commonmark_x.

    Source code(tar.gz)
    Source code(zip)
  • v0.3.0(May 15, 2022)

    • Extension setting codebraid.preview.pandoc.options now works (#3).

    • Under Windows, Pandoc option values in codebraid.preview.pandoc.options that begin with unquoted ~/ or ~\ have the ~ expanded to the user home directory via os.homedir().

    • Document export now works with file names containing spaces.

    • Added temporary support for syntax highlighting in Julia code blocks, until VS Code Markdown grammar is updated to support this (#4).

    • Updated KaTeX to 0.15.3.

    Source code(tar.gz)
    Source code(zip)
  • v0.2.0(Mar 5, 2022)

  • v0.1.0(Mar 5, 2022)

Owner
Geoffrey Poore
Geoffrey Poore
Alfred Workflow for selecting citations in Pandoc Syntax from a BibTeX File.

Supercharged Citation Picker A citation picker for academics that write in markdown. Using Alfred, this citation picker inserts Pandoc citations from

pseudometa 69 Dec 29, 2022
A Hackable Markdown Note Application for Programmers. Version control, AI completion, mind map, documents encryption, code snippet running, integrated terminal, chart embedding, HTML applets, plug-in, and macro replacement.

Yank Note A hackable markdown note application for programmers Download | Try it Online >>> Not ecommended English | 中文说明 [toc]{level: [2]} Highlights

洋子 4.3k Dec 31, 2022
Grupprojekt för kurserna 'Javascript med Ramverk' och 'Agil Utveckling'

JavaScript-med-Ramverk-Laboration-3 Grupprojektet för kurserna Javascript med Ramverk och Agil Utveckling. Utvecklingsguide För information om hur utv

Svante Jonsson IT-Högskolan 3 May 18, 2022
Hemsida för personer i Sverige som kan och vill erbjuda boende till människor på flykt

Getting Started with Create React App This project was bootstrapped with Create React App. Available Scripts In the project directory, you can run: np

null 4 May 3, 2022
Kurs-repo för kursen Webbserver och Databaser

Webbserver och databaser This repository is meant for CME students to access exercises and codealongs that happen throughout the course. I hope you wi

null 14 Jan 3, 2023
Preview and reply to your messages from within Alfred. Keep your hands on that keyboard!

Mouseless Messenger Mouseless Messenger offers you rapid keyboard-driven access to send and read conversations in the macOS Messages app via Alfred —

Stephan Casas 37 Dec 30, 2022
Contented is a Markdown-based authoring workflow that encourage developer authoring within its contextual Git repository.

Contented is a Markdown-based authoring workflow that encourage developer authoring within its contextual Git repository. npm i @birthdayresearch/cont

Birthday Research 44 Jan 7, 2023
The iofod SDK provides developers with the ability to interact with the main iofod interface within the Web worker, enabling rapid development of iofod extensions through the SDK.

iofod-sdk English | 简体中文 The iofod SDK provides developers with the ability to interact with the main iofod interface within the Web worker, enabling

iofod, Inc. 47 Oct 17, 2022
A JavaScript plugin that provides snapping functionality to a set of panels within your interface.

PanelSnap A JavaScript library that provides snapping functionality to a set of panels within your interface. Introduction PanelSnap is a framework ag

Guido Bouman 616 Dec 16, 2022
Get an isolated preview database for every Netlify Preview Deployment

Netlify Preview Database Plugin Create an isolated preview database for each preview deployment in Netlify Quickstart • Website • Docs • Discord • Twi

Snaplet 10 Nov 16, 2022
Preview document wrtting in YOUR markdown.

Glance Vim Do you know the number of Markdown flavours in the world? Everyone has an own flavour. It's hard to find the suitable Markdown previewer fo

TANIGUCHI Masaya 31 Dec 6, 2022
Provides intellisense, search and preview of emoji

Features Suggest emoji names after typing : or / (can be changed) Browse emojis by category Fuzzy search emojis Intellisense emojiIntellSense.language

Xiaoqian Zhang 5 Oct 15, 2022
A markdown-it plugin that process images through the eleventy-img plugin. Can be used in any projects that uses markdown-it.

markdown-it-eleventy-img A markdown-it plugin that process images through the eleventy-img plugin. Can be used in any projects that use markdown-it. F

null 25 Dec 20, 2022
An obsidian plugin for uploading local images embedded in markdown to remote store and export markdown for publishing to static site.

Obsidian Publish This plugin cloud upload all local images embedded in markdown to specified remote image store (support imgur only, currently) and ex

Addo.Zhang 7 Dec 13, 2022
Markdown Transformer. Transform markdown files to different formats

Mdtx Inspired by generative programming and weed :). So I was learning Elm language at home usually in the evening and now I am missing all this gener

Aexol 13 Jan 2, 2023
MySQL meets Jupyter notebooks. Grasp provides a new way to learn and write SQL, by providing a coding-notebook style with runnable blocks, markdown documentation, and shareable notebooks. ✨

A New Way to Write & Learn SQL Report Bug · Request Feature Table of Contents About The Project Built With Getting Started Prerequisites Installation

Lakshya 7 Sep 1, 2022
Apinto document project, which includes the use tutorials, development documents and other related contents of apinto.

apinto-docs Apinto document project, which includes the use tutorials, development documents and other related contents of apinto. README 本文档由 VuePres

Eolink 5 Dec 1, 2022
JSON Struct is a vocabulary that allows you to annotate and validate JSON documents.

JSON-Struct JSON Struct is a vocabulary that allows you to annotate and validate JSON documents. Examples Basic This is a simple example of vocabulary

Saman 3 May 8, 2022
Clojure inside your Obsidian documents!

Obsidian Wielder Clojure inside your Obsidian documents! This Obsidian plugin allows you to use the full power of Clojure directly inside of your docu

Victor Bjelkholm 53 Dec 18, 2022