Rendering notebook to docusaurus-md format removes heading

[jackgerrits]

Bug description

When rending a notebook to the docusaurus format the heading is removed. There is also no front matter added.

This is using the latest quarto version: 1.5.23

Steps to reproduce

$ cat repro.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# This is a header\n",
    "\n",
    "Content of page"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "version": "3.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}

quarto render repro.ipynb --to docusaurus-md

pandoc
  to: >-
    markdown_strict+raw_html+all_symbols_escapable+backtick_code_blocks+fenced_code_blocks+space_in_atx_header+intraword_underscores+lists_without_preceding_blankline+shortcut_reference_links+autolink_bare_uris+emoji+footnotes+gfm_auto_identifiers+pipe_tables+strikeout+task_lists+tex_math_dollars+pipe_tables+tex_math_dollars+header_attributes+raw_html+all_symbols_escapable+backtick_code_blocks+fenced_code_blocks+space_in_atx_header+intraword_underscores+lists_without_preceding_blankline+shortcut_reference_links
  output-file: repro.mdx
  standalone: true
  default-image-extension: png
  wrap: none
  html-math-method: webtex

metadata
  quarto-custom-format: docusaurus

Output created: repro.mdx

Renders:

Content of page

Expected behavior

I would expect the header to remain and (I think) the front matter including title to be added.

Actual behavior

Header is removed and no front matter added.

Your environment

MacOS 14.3.1, quarto cli

Quarto check output

Quarto 1.5.23
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.11: OK
      Dart Sass version 1.70.0: OK
      Deno version 1.41.0: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.5.23
      Path: /Applications/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: (not installed)
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Tex:  (not detected)

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.11.7
      Path: /Users/jackgerrits/w/autogen/.venv/bin/python3
      Jupyter: 5.7.1
      Kernels: python3

[✓] Checking Jupyter engine render....OK

[✓] Checking R installation...........(None)

      Unable to locate an installed version of R.
      Install R from https://cloud.r-project.org/

[mcanouil]

Thanks for the report and the reproducible example.
I can reproduce on latest.

Note that this only happens with Jupyter notebook and note with plain text Quarto document such as below.

# This is a header

Content of page

[jackgerrits]

Are you able to provide any pointers about where this bug might be happening? It's blocking my use case so I would love to help unblock if I am able to

[jackgerrits]

I worked out how to mitigate the issue so I'm not blocked now

[cscheid]

@jackgerrits thanks for the report. The issue here is most likely an interaction between the way that titles can be declared in .ipynb, and how that information is getting relayed to the other renderers.

In Ipynb, a level-1 heading is interpreted as the title of the document (because that's often how authors in jupyter denote a document title). In markdown formats, we typically relay that information in a metadata block. Consider this:

$ quarto render repro.ipynb --to markdown -o -
pandoc -o /var/folders/nm/m64n9_z9307305n0xtzpp54m0000gn/T/quarto-sessione7b3fa25999c9fde/b158b745ab27fc54/a050f5c2b7303586.md
  to: markdown
  standalone: true
  default-image-extension: png

---
title: This is a header
toc-title: Table of contents
---

Content of page

Note where the title ended up. To be clear, it's 100% a bug on our side that in docusaurus the H1 title is getting dropped! Let me think about the best way to solve this and I'll follow up.

[cscheid]

I'm more confident that this is indeed the issue. Another way that authors can declare titles in jupyter notebooks is by starting the notebook with a Raw NBconvert block and then use that to write YAML metadata:

$ cat repro-2.ipynb
{
 "cells": [
  {
   "cell_type": "raw",
   "id": "38d955ee",
   "metadata": {},
   "source": [
    "---\n",
    "title: A title\n",
    "---"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a98ba0fc",
   "metadata": {},
   "source": [
    "Some markdown"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}

This style of title declaration reproduces the behavior above in both md and docusaurus-md formats:

$ quarto render repro-2.ipynb --to markdown -o -
pandoc -o /var/folders/nm/m64n9_z9307305n0xtzpp54m0000gn/T/quarto-sessionfea0df00f94d17d/3d7edb513b2295f7/828981d65273e23c.md
  to: markdown
  standalone: true
  default-image-extension: png

---
title: A title
toc-title: Table of contents
---

Some markdown
$ quarto render repro-2.ipynb --to docusaurus-md -o -
pandoc -o /var/folders/nm/m64n9_z9307305n0xtzpp54m0000gn/T/quarto-sessionacb532d7bcc21164/bf56da737388d53f/40a2cbc824d75023.mdx
  to: >-
    markdown_strict+raw_html+all_symbols_escapable+backtick_code_blocks+fenced_code_blocks+space_in_atx_header+intraword_underscores+lists_without_preceding_blankline+shortcut_reference_links+autolink_bare_uris+emoji+footnotes+gfm_auto_identifiers+pipe_tables+strikeout+task_lists+tex_math_dollars+pipe_tables+tex_math_dollars+header_attributes+raw_html+all_symbols_escapable+backtick_code_blocks+fenced_code_blocks+space_in_atx_header+intraword_underscores+lists_without_preceding_blankline+shortcut_reference_links
  standalone: true
  default-image-extension: png
  wrap: none
  html-math-method: webtex

metadata
  quarto-custom-format: docusaurus



Some markdown

I think a different way to characterize this bug is "titles from jupyter documents are not rendered properly in docusaurus".

[jackgerrits]

The weird part is that only became a problem for me when migrating from v1.4.549 -> v1.5.23. When I was using v1.4.549 I was getting titles. I know that is a large range but I wonder what changed?

[cscheid]

I know that is a large range but I wonder what changed?

It's not a large range, and thank you for the bracket. It was easy to bisect from there. The offending commit was d75246d. I'll fix this right away.

[cscheid]

We have a fix on 1.4.551 as well as a fix on main for this now, and regression testing around that part of the code base as well. Thanks for the report!

[jackgerrits]

Thank you so much for quick fix! It is greatly appreciated!