Integration with VS Code using a VS Code extension about codebraid

[gpoore]

I'm now working on an extension for VS Code. This will provide a preview window with scroll sync. At least at first, the preview may not update until all code has executed, However, I'm trying to finish a redesign of the Codebraid internals that should allow the preview to update nearly instantly during code execution with the latest output. I'm currently in the process of finishing scroll sync and am just about to start on integrating Codebraid. I'm hoping to release an initial version of the extension and ideally a new version of Codebraid as well within 2-4 weeks.

Question for those who are interested in a VS Code extension: What features do you consider most important or useful in an extension, besides preview with scroll sync and fast updates? I may not have time or interest to do much more than that, but I'm interested in getting ideas in case some design decisions now can provide more options (for me or others) in the future.

[amichuda]

I think just that feature would be great! Thank you for working on this!

[gpoore]

The VS Code extension is now available: https://marketplace.visualstudio.com/items?itemName=gpoore.codebraid-preview.

This requires the absolute latest Pandoc and Codebraid versions for best results.

This should be quite usable. There may be a few aspects of scroll sync that need to be polished in the future to provide a slightly smoother experience. Eventually there may also need to be some document templates to make the default exported documents a little less plain.

Currently, the preview refreshes automatically when you are just using Pandoc, but it requires manual refresh for Codebraid. I've just finished completely reimplementing the internals as async to support better --live-output. I'm hoping that building on this will eventually allow the preview to refresh automatically, even during code execution, and be significantly faster.

[gpoore]

I've thought about an extension in the past, but haven't tried anything. I agree that an alternative way to run codebraid would be nice...unfortunately, my time is very limited and I don't have much experience with programming JavaScript/TypeScript and graphical user interfaces.

Depending on what features you want, it seems like a Markdown extension with Pandoc support would be a good starting point. The last time I looked, I didn't find anything, but I just looked again, and how there's https://github.com/kzvi/vsc-pandoc-markdown-preview. I installed it and made a few changes to preview_panel.js (diff below) and was able to get a live preview pane working with codebraid.

diff ./preview_panel.js ./codebraid_preview_panel.js
20a21
>         this.katexPath = katexPath;
22a24
>         this.cssPath = cssPath;
68,69c70,71
<         pandocOptions.push(`--katex=${this.katexUri}/`);
<         pandocOptions.push(`--css=${this.cssUri}`);
---
>         //pandocOptions.push(`--katex ${this.katexUri}/`);
>         pandocOptions.push(`--css ${this.cssPath}`);
71,72c73,74
<             pandocOptions.push('--metadata=header-includes:{{pmp-base-tag}}');
<         this.subprocess = child_process_1.exec(`pandoc ${pandocOptions.join(' ')}`, execOptions, (err, stdout, stderr) => {
---
>             pandocOptions.push('--metadata header-includes:{{pmp-base-tag}}');
>         this.subprocess = child_process_1.exec(`codebraid pandoc -f markdown -t html ${pandocOptions.join(' ')}`, execOption s, (err, stdout, stderr) => {

This requires the dev version of codebraid that can read from stdin. I disabled --katex since I was getting Pandoc errors. There were some issues like matplotlib plots from Jupyter kernels not updating and perhaps overly aggressive code execution (code is run too often, before it can be completed...only run on save might be better). But this seems to have potential and could be a good starting point, depending on the desired features.

This extension doesn't have scroll sync. However, I've already designed and partially implemented a way to get codebraid working with SyncTeX (jump back and forth between Markdown and LaTeX PDF output). So if I knew what data was needed to get scroll sync working with HTML, I expect this could be solved.

[aeturrell]

Wow, this looks amazing! Will have a play and come back with any issues but definitely clears the initial ask (and then some).

[amichuda]

There's an issue open with the VS code python extension to allow sending code to the interactive window from a markdown file if it's within code cells. All you would have to do then would be to set it reading codebraid cells as python cells.

microsoft/vscode-python#13568

[MatrixRanger98]

Any updates? It appears that there is still not an extension available on VS Code's market space for Codebraid.

[gpoore]

@matrix-ranger For the moment, I still don't have any better suggestions than taking an existing VS Code extension like https://github.com/kzvi/vsc-pandoc-markdown-preview and customizing the subprocess command to use codebraid instead of pandoc.

I'm currently working on improving error handling to simplify debugging. Once that is done, I will be implementing a mapping between Markdown input line numbers and LaTeX/HTML output line numbers/locations. This will make possible SyncTeX for LaTeX and scroll sync for HTML. Once that is done, I will see what I can do about a VS Code extension, if no one else has tried first. At least to start with, I'll be trying to create a Markdown preview pane that uses codebraid to generate the HTML and has scroll sync. This appears to be relatively straightforward by combining a VS Code webview with sync triggered by window.onDidChangeTextEditorVisibleRanges.

My impression from browsing through the VS Code issues is that there is a lot of work being done to extend VS Code's current interface for working with Python Jupyter notebooks to support a wider range of notebooks/markdown+code tools. If something like that becomes possible for a format like MyST Markdown or R Markdown, then it should be possible to extend the same approach for Codebraid.

[MatrixRanger98]

Thanks for the reply. Indeed a Markdown preview pane that uses Codebraid to generate the HTML sounds like the best solution here. Up to now, I can't find an extension that can preview R/MyST Markdown well though I am using Markdown Preview Enhanced as a temporary workaround. MPE has the option of extending Markdown parser by user-defined JS scripts and customizing CSS, and I use this to help it recognize the code blocks and containers in R/Codebraid Markdown.