fix: preserve code blocks in Markdown exports

AF
15h ago
+102-0

Summary

Markdown export currently sends CodeSnippet.text through the ordinary-text fallback. As a result, a code comment beginning with # becomes a heading, Markdown punctuation is interpreted, indentation loses its code-block meaning, and an HTML example becomes real HTML.

Render CodeSnippet elements as fenced code blocks. Choose a fence longer than any backtick run in the code so examples containing Markdown fences remain complete. Preserve the original text, indentation, tabs, and line endings, adding a final newline only when needed to put the closing fence on its own line.

The behavior applies to element_to_md(), elements_to_md(), and Markdown output from create_file_from_elements().

Validation

  • 16 regression/control cases cover normal code, indentation, Markdown punctuation, HTML and entity examples, embedded backtick/tilde fences, blank lines, empty code, neighboring text, consecutive code blocks, tabs/CRLF, serialized inputs, iterators, and file encoding.
  • The tests use the real Python-Markdown renderer with its fenced-code extension. On the base revision, 15 fail and 1 passes; all 16 pass after the change.
  • Together with the existing element serialization tests: 98 passed using normal package imports on Python 3.12.14, Markdown 3.10.1, and BeautifulSoup 4.14.3.
  • The full Markdown partitioning and full repository suites were not run; their partitioner imports require the unavailable local spaCy stack.
  • Ruff 0.17.5 check, format --check, and git diff --check pass.

Checklist

  • The PR title is a user-facing release-note entry with a conventional commit prefix.
  • Apply a category label (enhancement, bug, or an appropriate existing label), or ask a maintainer to apply it. Please apply bug.
  • For breaking changes, use ! in the title and explain impact and migration above. No breaking API change.