Jupyter-book: Full-width doesn't seem to work on Markdown cells

[dlukes]

I can't seem to get full-width to work on Markdown cells, be it in regular .ipynb notebooks or MyST-based notebooks with the +++ {"tags": ["full-width"]} syntax.

What seems to be happening is that the MyST +++ syntax generates the correct .ipynb source (presumably via JupyText?), with Markdown content split into cells with properly applied tags, but when that gets converted into HTML, the cells are merged and the tag information gets lost. At least when inspecting the generated HTML, there's no div that would group the content between a pair of +++ lines, to which the tags could be applied as classes.

Steps to reproduce the behavior:

1. jb create test-book
2. Edit notebooks.ipynb, adding "tags": ["full-width"] to the metadata field of the first Markdown cell.
3. jb build test-book
4. Open the book in the browser.

As per the description of the +++ feature in the docs, I would expect the content in the page to be full-width, but it's not.

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! :tada:

[dlukes]

The jupyter-book docs themselves look like they make use of this feature here:

https://github.com/executablebooks/jupyter-book/blame/master/docs/content/layout.md#L205-L213

(Rendered here)

And it seemingly works, except I think what actually makes the content full-width is not the cell tag (i.e. the +++ {"tags": ["full-width"]} part), but the directive keywords under the admonition directive (:class: full-width).

[chrisjsewell]

No I'm afraid metadata is not applied to Markdown cells since this is not compatible with the section headings hierarchy, i.e.

+++ {"tags": ["tag1"]}
# Heading 1a
## Heading 2a
+++ {"tags": ["tag2"]}
## Heading 2b
# Heading 1b

goes to:

<heading 1a>
  <heading 2a>
  <heading 2b>
<heading 1b>

which would cause an incompatible hierarchy, if you also tried to also wrap markdown cells:

<cell 1 tags=[tag1]>
  <heading 1a>
    <heading 2a>
       <cell 2 tags=[tag2]>
          <heading 2b>
       <heading 1b>

Therefore, I believe @choldgraf's documentation is wrong here

[chrisjsewell]

You can set full width for a particular section of Markdown though, in an admonition, or with:

` {div}
:class: full-width

Markdown that does not contain headers...
```
````

[choldgraf]

Well it's not my documentation, it's the project's documentation :-P

but good point - I think that's a carry-over from the old Jupyter Book docs. I'll make a PR to fix 👍

[chrisjsewell]

They don't call it "blame" for nothing lol: https://github.com/executablebooks/jupyter-book/blame/master/docs/content/layout.md#L205-L213

I've should check again at some point what actually happens if you try to put a heading inside an admonition. I'm sure it breaks, but I can't remember exactly how

[dlukes]

which would cause an incompatible hierarchy

Oh right, that makes sense. So there's just no way cell-level metadata can be preserved for Markdown cells in general.

@choldgraf's documentation is wrong here

To be fair, the cell breaks and metadata do carry over into the generated .ipynb, it's only during the HTML conversion that they get lost :) So this section is technically correct. Still, this is a potentially subtle and confusing point that could use some clarification in the docs. As in, "the +++ syntax is relevant for conversion to .ipynb and back, but it's meaningless for the HTML conversion".

As for full-width working equally well for Markdown cells, as stated here, that is indeed not the case.

You can set full width for a particular section of Markdown though, in an admonition, or with:

That looks neat! Unfortunately, it results in:

/home/david/src/v4py.github.io/src/outro.md:162: WARNING: Directive 'div': Unknown option: class

:class: full-width

Maybe the feature hasn't made it into a release yet? Once it does, it would be great to document it here instead of the full-width tag :)

[dlukes]

And thank you both for the quick response! :)

[choldgraf]

Indeed and "blame" is a problematic word for open source communities that I wish GitHub would change, as blameless cultures are IMO more productive / positive cultures for distributed communities - but that's a conversation for another time.

I've got a PR here to try and clarify this language a bit: https://github.com/executablebooks/jupyter-book/pull/1042

in particular see this change for the full-width markdown: https://deploy-preview-1042--jupyter-book.netlify.app/content/layout.html#full-width-markdown-content

@dlukes wanna give the new full-width section a shot and let me know if this works for you?

[chrisjsewell]

Nope, I definitely blame you 😝

[chrisjsewell]

That looks neat! Unfortunately, it results in

Ah my bad its:

```{div} full-width content ```

Note this comes from https://github.com/executablebooks/sphinx-panels/blob/30a28b7acbd19fcccdba5417fa883cf3c0fdd2b4/sphinx_panels/__init__.py#L105
The reason not to use the built-in docutils container directive, is that it sets also a class named container, which clashes with the bootstrap classes from the sphinx-book-theme

[dlukes]

@choldgraf Thank you very much, #1042 looks great as far as documenting full-width capabilities!

I added #1045 as a sketch of how the scope of the +++ Markdown cell break feature could be clarified. Feel free to iterate on that :)

@chrisjsewell Thanks for digging up the correct directive!

[choldgraf]

great - thanks @dlukes !!