HTML export and TOC

[fmilanese-1]

I'm author of another extension, that provides these features together with HTML export via jupyter nbconvert commands.

Do you think this can be a feature of jupytext-sync?. I know that jupytext's idea doesn´t contains html exports, but really what is the difference between exporting to markdown or html?.

Maybe that when exporting to html via nbconvert you export the execution outputs together. Not just the plain "text".

If this feature were to be built in within this new extension I will be happy to collaborate and also suggest users of DSUtils to move to this new extension.

What do you think?

[caenrigen]

Do you think this can be a feature of jupytext-sync?

I do not have a very strong opinions on this yet. Personally this is not a feature that I ever needed. I used your extension for several months mainly for the jupytext features.

That said, let's look a bit deeper into the topic. Sorry if what follows is a bit unorganised.

---

To get a bit clear on the use case that you would like to be supported:

I suppose what you miss the most in the TOC in the exported HTML (perhaps a main reason for your built DSUtils). Correct me if I am wrong about this.

Are you interested in simply having something along the lines of a "Jupyter: Export to HTML with TOC" command that exports .ipynb to .html i.e. a one-way conversion?

For future readers, please note that Jupyter in VS Code already ships with a "Jupyter: Export to HTML" (jupyter.exportToHTML) (as well as to PDF/Python Script) using nbconvert under the hood. The command can be used to assign a keyboard shortcut or perhaps can be combined with notebook.codeActionsOnSave

---

From another perspective it seems that the "TOC in HTML export" feature is something that belongs in the nbconvert repository itself, seems an old issue in the repo:

• Export in html_toc - produces buggy html output jupyter/nbconvert#1835
• command line argument for table of content. jupyter/nbconvert#1690

also with ongoing open PR: jupyter/nbconvert#2178

---

I know that jupytext's idea doesn´t contains html exports, but really what is the difference between exporting to markdown or html?

I am not aware of the details, I mainly use .ipynb and .py(percent).

One main difference might be that markdown is a "two-way" format from which you can recover the .ipynb notebook (the input code cells, of course) using jupytext commands. I don't know if there is any equivalent .html format that allows for two-way conversions.

---

From a quick look at https://pypi.org/project/nbconvert/ nbconvert covers many other features and formats. As a preliminary thought, perhaps it would make more sense to use my extension as a "template" for implementing an equivalent one that fully supports the nbconvert itself within VS Code. E.g. we keep jupytext features in my extension and nbconvert features in DSUtils.

From one side I do not want to bloat the code of this extension with features that can get a bit tricky to maintain and that require extra dependencies. But from another side, if this is something that the Jupyter community uses a lot, then it would be nice to support these workflows for smoother transition to VS Code.

Since this extension is being considered for being "officially" endorsed in the jupytext docs, might make sense to ask @mwouts for opinion on this topic.

---

While I was thinking and researching the topic, I came across a few projects that might be of your interest to cover the HTML export functionality:

• https://docs.marimo.io/guides/exporting/, https://marketplace.visualstudio.com/items?itemName=marimo-team.vscode-marimo
• https://quarto.org/docs/output-formats/html-basics.html, https://marketplace.visualstudio.com/items?itemName=quarto.quarto

Disclaimer I did not use much either of them, but both seemed impressive and mature with significant documentation.

[fmilanese-1]

Thanks for the thoughtful reply! After reflecting on this, I think you're absolutely right. My team and I rely heavily on having a TOC in the HTML exports because of how we deliver notebook-based reports. That said, I now see this is clearly outside the intended scope of this extension.

I really appreciate your openness and the suggestions you shared. We'll explore those other tools you mentioned to better support our workflow. Thanks again!