Jupyter-book: Margin tag not working in Jupyter notebooks

[kyleniemeyer]

Hi there,

With the newest version of Jupyter Book available via pip, I'm finding that adding the margin tag to cells in Jupyter notebook has no effect.

For example, in one cell of this notebook, where I have the margin tag, the cell just displays like every other Markdown cell.

Output:

Rendered version from here: https://kyleniemeyer.github.io/computational-thermo/content/combustion/adiabatic-flame-temperature.html

[choldgraf]

Ah - that's because there are two different ways to put content in the margin in Jupyter Book. If you're using code cells, then adding a margin tag is the way to go. However if you are writing markdown, then you should add things to the margin with this pattern:

````
Some markdown content

{margin} my margin content

some other markdown content
````

I know it's an annoying difference - can you think of a way to make this clearer in the docs?

[kyleniemeyer]

Ah! I thought I had tried that, and got a build error. But, when I tried it again just now, it worked properly. 🤷‍♂️

My original read of the docs was that the directive was only for pure Markdown files, but I guess that was just my misunderstanding.

Since a number of folks may still be writing Jupyter notebook files that mix code cells and Markdown cells, maybe it would be helpful to allow the margin tag to work for both, if possible?

[choldgraf]

unfortunately it's not possible otherwise I agree that would definitely be preferable :-/ there's a difference in how code cells and markdown content get parsed

if you can think of an improvement in the docs to clarify this I'd be happy to review a PR!

[drfeinberg]

Maybe this will help some other people:
I had markdown inside the margin text, and it did not render, but html did.
For example, this renders:

````{margin}
<H3>Black</H3>
Black is a package that will automatically format your code. ````

This does not render:

````{margin}
### Black
Black is a package that will automatically format your code. ````

[choldgraf]

@drfeinberg - just a note that markdown in general will render, but headers specifically will not work. Instead of headers we recommend you just use ** to bold things. The reason is because headers define the structure of the book itself, and so having this in a margin would confuse the linear structure of the book

[drfeinberg]

Ha! There's always a good reason behind these decisions. Thanks @choldgraf