Handle headers in code-cell generated Markdown

[chrisjsewell]

This has essentially been reported in #309, #315 and executablebooks/jupyter-book#1299. Its a known issue that I'll explain here:

So the heart of the problem, as I have recently explained in https://github.com/executablebooks/MyST-Parser/issues/351#issuecomment-823987564, is that in Sphinx you cannot nest headers in other elements. So currently if you do include headers in generated markdown, you'll end up with something like:

<section h1 in main text>
  <code_input>
    ...
  <code_output>
    <section h2 generated from code>
      <elements>
        ...
  <section h3 in main text>
     ...

and everything will be messed up, because the section hierarchy will be misinterpreted.

What you actually need is a special option, to inject markdown output directly into the AST, without enclosing it, like:

<section h1 in main text>
  <code_input>
    ...
  <section h2 generated from code>
    <elements>
      ...
      <section h3 in main text>
        ...

I will fix executablebooks/jupyter-book#1299 ~now, which should make the warning clearer.

But actually fixing the AST "structural" issue, its something that I'm already working on but will require a bit more time as I'm basically re-writting myst-nb 😬 (to holistically improve a number of outstnding issues, including this)

[sanjaynagi]

Did this get anywhere? would be a really useful enhancement!