md2star.preprocessing package

Submodules

Module contents

md2star Markdown preprocessor package.

The orchestrator preprocess_markdown() runs a fixed sequence of phases on a raw Markdown string before it reaches Pandoc. Each phase lives in its own submodule so the pipeline is easy to test, extend, or swap.

Public API

Author

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

md2star.preprocessing.fill_empty_alt_text(content, base_dir='.', model=None)[source]

Replace ![](src) empty-alt images with an LLM-generated description.

Mirrors md2star.preprocessing.lint.lint_with_llm()’s safety net: if Ollama is missing, the daemon is unreachable, the vision model is not pulled (and cannot be pulled), or the request fails, the original content is returned unchanged. The pass is never load-bearing.

Parameters:

  • content (str)

  • base_dir (str)

  • model (str | None)

Return type:

str

md2star.preprocessing.is_ollama_installed()[source]

True iff the ollama binary is reachable on PATH.

Used as the auto-enable gate for lint: if the user does not have Ollama installed at all, we stay completely silent. If they do, we take care of starting the daemon and pulling the model on demand — the rationale being “the tool is here, so use it without asking”.

Return type:

bool

md2star.preprocessing.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.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

md2star.preprocessing.render_mermaid_local(content, out_dir)[source]

Render content (Mermaid markup) to a PNG and return its absolute path.

out_dir is accepted for backwards compatibility but the cache lives in $XDG_CACHE_HOME/md2star/mermaid/ so renders are shared across runs.

Parameters:
Return type:

str