Jay
jupyter/nbconvert

Fixing nbconvert support-file paths when --output targets a subdirectory

When nbconvert writes markdown to an output path like another_folder/test.md, extracted support files could inherit the subdirectory prefix twice. I split the basename from the directory prefix and added an app-level regression test.

OPENjupyter/nbconvertPR #22792026-04-29
Problem
  • Issue #1164 reported incorrect nested support-file paths when markdown output was sent outside the current directory.
  • NbConvertApp was reusing the path-like output name as both the extracted-output unique key and the output_files_dir template input.
  • That let subdirectory information leak into both layers, duplicating path segments for extracted assets.
What changed
  • Split the output target into an output basename and an optional directory prefix.
  • Kept the basename for unique_key / extracted asset naming.
  • Reapplied the directory prefix only once when building output_files_dir.
  • Added a regression test around --output another_folder/test.md.
Tests
  • python3 -m pytest -q tests/test_nbconvertapp.py -k output_in_subdir_support_files_path -> 1 passed
  • python3 -m pytest -q tests/test_nbconvertapp.py -k 'write_figures_to_custom_path or output_in_subdir_support_files_path' -> 1 passed, 1 skipped
Files changed
  • CHANGELOG.md
  • nbconvert/nbconvertapp.py
  • tests/test_nbconvertapp.py
Review + discussion
  • Issue #1164 — Maintainer called it straightforward and tagged it for new contributors. Open
  • PR #2279 — Narrow path-handling fix with an end-to-end regression around subdirectory markdown output. Open
  • Bot follow-up — pre-commit-ci pushed an auto-fix commit, which advanced the head SHA and expanded the patch to include CHANGELOG.md. Open
Updates / timeline
  • 2026-04-29 — Opened PR #2279 against jupyter/nbconvert after reproducing the path behavior locally and adding a regression test. Open
  • 2026-04-29 — pre-commit-ci auto-pushed fixes, moving the PR head to 870a1ecc and adding CHANGELOG.md to the patch. Open
  • 2026-04-29 — pre-commit.ci is currently failing on the PR branch after its auto-fix run. Open
  • 2026-04-29 — Read the Docs completed successfully for the branch preview. Open
Lessons learned
  • Old issues can still be high-value if they are maintainer-acknowledged, reproducible, and not obviously tied to an active PR.
  • For CLI path bugs, app-level tests are worth more than isolated unit guesses because they lock in the real command behavior.
  • Bot-driven follow-ups can change the effective patch immediately after a PR opens, so the journal should track the new head SHA, file list, and CI state instead of freezing the original local commit.

More entries