md2star package

Subpackages

Submodules

Module contents

md2star: Markdown → DOCX/PPTX/PDF bridge built on Pandoc.

Module summary

Public package surface for md2star. Re-exports the preprocessor entry points so consumers can import them either from the top-level package or from the md2star.preprocessing submodule.

Usage

>>> from md2star import preprocess_markdown
>>> out = preprocess_markdown("# Hello\n", base_dir=".")
>>> print(out.splitlines()[0])  # '# Hello'
# Hello

Author

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

md2star.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: the model call in _generate_alt() swallows every failure (engine unresolvable, backend/model unreachable, transport error) into None, and each such image is left untouched. The pass is never load-bearing. model is an optional per-call vision-model tag override; when None the tag comes from md2star’s resolved engine descriptor.

Parameters:

  • content (str)

  • base_dir (str)

  • model (str | None)

Return type:

str

md2star.lint_with_llm(content, model=None)[source]

Send content to the local LLM for syntax-only fixes; return original on any failure.

The 0.5×–2× length guard is a coarse hallucination/truncation check; if the response strays outside that band, the original is kept. Resolution of which model and backend to use is delegated entirely to the suite’s brief -> engine contract (md2star._engine.engine()); model is an optional per-call tag override passed straight through to best_engine_ai_helper.llm.chat(). Any failure — the engine cannot be resolved (missing brief, no reachable backend/model), the request errors, or the output looks wrong — degrades to the untouched content.

Parameters:

  • content (str)

  • model (str | None)

Return type:

str

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