md2star.preprocessing package

Submodules

• md2star.preprocessing.alt_text module
  • Author
  • fill_empty_alt_text()
• md2star.preprocessing.images module
  • Author
  • absolutize_image_paths()
  • download_remote_images()
  • fix_image_widths()
  • html_images_to_markdown()
  • image_size_attr()
  • process_image_assets()
  • resize_image_for_cell()
  • resize_images_in_markdown_tables()
• md2star.preprocessing.language module
  • Author
  • get_language_metadata()
• md2star.preprocessing.lint module
  • Author
  • lint_with_llm()
• md2star.preprocessing.math module
  • Author
  • unwrap_math_in_code_spans()
• md2star.preprocessing.mermaid module
  • Box-overflow fix
  • Author
  • render_mermaid_local()
• md2star.preprocessing.pipeline module
  • Author
  • isolate_images_for_pptx()
  • preprocess_markdown()
• md2star.preprocessing.regexes module
  • Author
• md2star.preprocessing.tables module
  • Author
  • convert_html_tables()
  • html_table_to_markdown()
  • normalize_grid_tables()
  • normalize_pipe_tables()

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

• preprocess_markdown() — the orchestrator (only thing wrappers call)

• render_mermaid_local() — re-exported for tests/mocks

• PHASES — canonical phase-name set (for --skip-phase)

Author

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

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

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.preprocessing.isolate_images_for_pptx(content)

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.lint_with_llm(content, model=None)

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.preprocessing.preprocess_markdown(content, base_dir='.', inject_metadata=True, lint_enabled=False, skip_phases=None, *, allow_remote_images=False, offline=False)

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)

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:

• content (str)

• out_dir (str)

Return type:

str