{"id":4641,"library":"myst-nb","title":"MyST-NB","description":"MyST-NB is a Sphinx extension that enables direct parsing and execution of Jupyter Notebooks (.ipynb) within Sphinx documentation. It builds upon the MyST Markdown parser, allowing users to write rich technical documentation that seamlessly integrates executable code, outputs, and MyST Markdown syntax. The library maintains an active development cycle, with new versions released regularly to enhance features and ensure compatibility with the latest Python and Sphinx versions.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/executablebooks/myst-nb","tags":["sphinx","jupyter","markdown","notebook","documentation","executable books"],"install":[{"cmd":"pip install myst-nb","lang":"bash","label":"Install MyST-NB"}],"dependencies":[{"reason":"Core dependency as MyST-NB is a Sphinx extension.","package":"sphinx","optional":false},{"reason":"MyST-NB is built on top of MyST-Parser and automatically includes it.","package":"myst-parser","optional":false},{"reason":"Removed as a direct dependency in v1.0.0. Install separately if needed for interactive widgets.","package":"ipywidgets","optional":true}],"imports":[{"note":"MyST-NB is primarily used as a Sphinx extension by adding 'myst_nb' to the `extensions` list in `conf.py`.","wrong":"import myst_nb # Not typically imported directly in Python code for Sphinx extension usage","symbol":"myst_nb","correct":"extensions = ['myst_nb'] # in conf.py"},{"note":"Used for 'gluing' variables from code cells into the narrative text.","symbol":"glue","correct":"from myst_nb import glue"}],"quickstart":{"code":"import os\n\n# --- conf.py (Sphinx configuration file) ---\n# project = 'MyST-NB Quickstart'\n# copyright = '2026, Your Name'\n# extensions = [\n#     'myst_nb',\n#     'sphinx.ext.autodoc', # Example standard Sphinx extension\n# ]\n# # Optional: Configure notebook execution\n# # nb_execution_mode = \"auto\" # 'auto', 'off', 'force', 'cache'\n# # nb_execution_timeout = 60\n\n# --- example.md (MyST Markdown file with code cells) ---\nexample_md_content = '''\n# MyST-NB Example Document\n\nThis is a MyST Markdown file demonstrating executable code cells.\n\n```{code-cell} python\nimport datetime\nprint(\"Hello from MyST-NB!\")\nprint(f\"Current time: {datetime.datetime.now()}\")\n```\n\nYou can also use the `glue` functionality to embed variables from executed cells.\n\n```{code-cell} python\nfrom myst_nb import glue\nmy_result = \"This value was 'glued' from a Python cell.\"\nglue(\"my_embedded_string\", my_result)\n```\n\nThe result embedded from the code cell is: {glue:text}`my_embedded_string`.\n'''\n\n# To run this, you would typically:\n# 1. Create a Sphinx project (e.g., `sphinx-quickstart`)\n# 2. Modify `conf.py` as commented above\n# 3. Create `example.md` with the content above\n# 4. Build with `sphinx-build -b html . _build`\n\n# This snippet simulates saving the content to files for demonstration.\n# In a real Sphinx project, these files would exist in your source directory.\n# (Not actually running sphinx-build here, just showing file content)\nprint(\"--- Simulated conf.py content ---\")\nprint(\"# See comments in code for full conf.py example\")\nprint(\"extensions = ['myst_nb']\")\n\nprint(\"\\n--- Simulated example.md content ---\")\nprint(example_md_content)\n","lang":"python","description":"To quickly get started, install MyST-NB and add 'myst_nb' to the `extensions` list in your Sphinx `conf.py`. You can then create MyST Markdown files (`.md`) or Jupyter Notebooks (`.ipynb`) containing code cells, which MyST-NB will parse and execute during the Sphinx build process. The `glue` function allows embedding variables directly into your narrative text."},"warnings":[{"fix":"Review the MyST-NB v1.0.0 changelog and documentation for updated configuration options. Update your `conf.py` to use the new `nb_` prefixed options and explicitly enable `dollarmath` if needed: `myst_enable_extensions = [\"dollarmath\"]`. For cell-level configuration, the top-level key `render` has been deprecated in favor of `mystnb`.","message":"Breaking changes were introduced in v1.0.0, including significant changes to configuration option names. Many options that previously did not have a prefix now use `nb_` (e.g., `jupyter_execute_notebooks` became `nb_execution_mode`). `nb_render_priority` was removed and replaced by `nb_mime_priority_overrides` with a different format. The `dollarmath` MyST extension is no longer enabled by default.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"If your project uses `ipywidgets`, ensure it is explicitly added to your project's `requirements.txt` or installed separately: `pip install ipywidgets`.","message":"The `ipywidgets` package was removed as a direct dependency in v1.0.0. If your documentation relies on interactive ipywidgets, they will no longer function unless `ipywidgets` is explicitly installed in your environment.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Custom renderers will need to be rewritten to align with the new plugin system (`myst_nb.renderers` and `myst_nb.mime_renderers` entry points). Consult the API documentation for the updated structure and plugin system.","message":"The internal AST structure and rendering plugin system were completely rewritten in v1.0.0 for compatibility with new Docutils functionality. Any custom renderers or direct manipulation of MyST-NB's internal Docutils AST nodes will likely break.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Only include `'myst_nb'` in your `conf.py` `extensions` list. Do not add `'myst_parser'`. All configuration options for `myst_parser` will still be processed when `myst_nb` is active.","message":"MyST-NB automatically activates the `myst_parser` extension. Explicitly including `myst_parser` in your `extensions` list alongside `myst_nb` will cause conflicts or redundant processing.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When debugging errors in `.ipynb` files, interpret `LINE_NUMBER` by taking `error_line_number % 10000`. The `CELL_INDEX` can be derived from `floor(error_line_number / 10000)`.","message":"When MyST-NB processes Jupyter Notebooks (.ipynb), Sphinx error reporting for these files uses a special line number format: `<CELL_INDEX> * 10000 + LINE_NUMBER`. This can make pinpointing the exact line in a notebook cell challenging without understanding the format.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}