md2star.preprocessing.pipeline module

Orchestrator: runs the preprocessing phases in order.

The phase order matters and is not trivially permutable. From outermost to innermost:

  1. (opt-in) LLM lint — fix syntax-level errors before anything else parses.

  2. Download remote images — replace http(s):// refs with local paths.

  3. HTML table conversion — must run before line-splitting so multi-line <table> blocks are still in one piece.

  4. Absolutize image paths — rewrite relative ![](path) refs to absolute paths so the temp Markdown is portable across cwds (URLs and absolute paths pass through untouched).

  5. Process image assets — render SVGs to PNG (via rsvg-convert or cairosvg) and downscale oversized rasters with Gaussian-prefiltered Lanczos resampling so Pandoc gets clean, reasonably-sized media.

  6. Language detection — inject lang / date_format into YAML.

  7. Line-by-line pass: math-in-code unwrap, Mermaid render, blank-line- before-list normalization. Fenced code blocks are skipped wholesale so their content stays verbatim.

  8. Resize pipe-table cell images (physical resize).

  9. Pipe-table separator normalization (proportional dashes + trailing blank line) so Pandoc honours per-column width hints in DOCX/PPTX.

  10. {width=100%} injection on non-cell images.

  11. PPTX slide isolation — split images off slides containing tables.

Each phase has a stable name (see PHASES) so the CLI --skip-phase flag can address it directly. Names are deliberately snake_case and stable across versions; treat them as part of the public API.

Author

[Warith HARCHAOUI](https://linkedin.com/in/warith-harchaoui/)

md2star.preprocessing.pipeline.isolate_images_for_pptx(content)[source]

Push standalone images and pipe-tables onto fresh PPTX slides.

Pandoc’s PPTX writer maps each ## H2 (or # H1) heading to one slide. A slide that mixes prose with an image silently drops the image, and a slide that mixes prose with a table cramps everything together. Inserting a blank ## before the offending block forces it onto its own slide. Empty headings render as nothing in DOCX, so the rewrite is harmless for that output.

Both images and tables are isolated by the same pass — keeping them in one function avoids cascading ## insertions from two independent walkers tripping over each other’s output.

Parameters:

content (str)

Return type:

str

md2star.preprocessing.pipeline.preprocess_markdown(content, base_dir='.', inject_metadata=True, lint_enabled=False, skip_phases=None, *, allow_remote_images=False, offline=False)[source]

Run the full preprocessing pipeline on a Markdown string.

Parameters:

  • content (str) – Raw Markdown source.

  • base_dir (str) – Directory used to resolve relative image paths and to receive downloaded remote images / mermaid renders.

  • inject_metadata (bool) – Whether to inject lang / date_format based on language detection (default: True). Equivalent to skipping language.

  • lint_enabled (bool) – Whether to run the optional Ollama LLM lint (default: False). Opt-in because it requires Ollama, adds latency, and can in rare cases rewrite content despite the safety guard.

  • skip_phases (Iterable[str], optional) – Phase names to skip (see PHASES). Merged with any md2star_skip: list found in the document’s YAML front-matter.

  • allow_remote_images (bool, keyword-only) – Whether to download ![alt](https://...) references. Defaults to False (the safe-by-default policy introduced in v1.2.0): remote image markers are left in place, and the user sees a warning if any were skipped. Pass True to opt in.

  • offline (bool, keyword-only) – Hard-disable every network-touching phase. Takes precedence over allow_remote_images and lint_enabled.

Return type:

str