md2star.pipeline module

md2star’s conversion engine: Markdown → DOCX / PPTX / PDF.

This module is the pipeline, not the command line. It used to live in md2star/cli.py next to an argparse front-end, which meant the engine was reachable only by handing it an argv list that it re-parsed — the GUI server and the FastAPI surface both built fake command lines for that reason. Since 3.10.0 the single command line is click (see md2star.cli), the parsing happens there once, and every caller hands this module a typed ConvertOptions instead of a string list.

convert() orchestrates the four steps:

  1. Preprocess the input Markdown via md2star.preprocess_markdown().

  2. Resolve the reference template: prefer template.{docx,pptx} next to the input file, then the legacy .pandoc-reference.{docx,pptx}, then the XDG cache, then (the default since v2.5.0) a one-shot fetch from deraison.ai cached under XDG, and finally the bundled template. --no-remote-templates / --offline skip the fetch.

  3. Invoke pandoc with the bundled Lua filter, metadata defaults, and resolved reference doc. Everything in pandoc_args — the flags md2star does not know — is appended verbatim, last, so a user can override any choice md2star made.

  4. Postprocess (DOCX only), re-inject the MyTable / MyTableSmall table styles that Pandoc strips when rewriting word/styles.xml.

The PDF format is implemented as a wrapper: it produces the DOCX first (so all of md2star’s polish, from mermaid diagrams to table styles to slide-aware tweaks, is already applied) and then asks headless LibreOffice (soffice --headless --convert-to pdf) to render that DOCX to PDF. This guarantees the PDF visually matches the DOCX you would ship.

Author

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

class md2star.pipeline.ConvertOptions(input, output=None, author=None, bib=None, bibliography_name=None, lang=None, date=None, lint=False, skip_phase=(), reference_doc=None, offline=False, no_remote_templates=False, allow_remote_images=False, verbose=False, quiet=False, smart_layout=False, template=None, reference_slides=False, no_visual_confirm=False, eyeball_iterations=0, min_pt=None, refresh_catalog=False)[source]

Bases: object

Everything convert() needs, already parsed and typed.

This replaces the argparse Namespace the engine used to receive. The difference is not cosmetic: a Namespace is whatever the parser that built it happened to set, so the engine read five of these fields through getattr(args, name, False) because the pptx-only flags simply did not exist on the docx parser. Three in-tree callers (the CLI, the GUI server, the FastAPI app) each had to know the exact flag spellings to build an argv the engine would then re-parse, and nothing checked that they agreed.

A frozen dataclass makes the contract explicit and total: every field is present for every format, with the same default the CLI advertises, and a caller that forgets one gets a TypeError rather than a silent False.

Parameters:

  • input (str)

  • output (str | None)

  • author (str | None)

  • bib (str | None)

  • bibliography_name (str | None)

  • lang (str | None)

  • date (str | None)

  • lint (bool)

  • skip_phase (tuple[str, ...])

  • reference_doc (str | None)

  • offline (bool)

  • no_remote_templates (bool)

  • allow_remote_images (bool)

  • verbose (bool)

  • quiet (bool)

  • smart_layout (bool)

  • template (str | None)

  • reference_slides (bool)

  • no_visual_confirm (bool)

  • eyeball_iterations (int)

  • min_pt (float | None)

  • refresh_catalog (bool)

input

Path to the source .md file. The only required field.

Type:

str

output

Destination path. None means “next to the input, with the target format’s extension”.

Type:

str or None

author, lang, date

Pandoc metadata overrides. date is passed as date_override so it does not collide with Pandoc’s own date.

Type:

str or None

bib

BibTeX file; its presence turns on --citeproc.

Type:

str or None

bibliography_name

Heading for the appended references section. None resolves to the localized default for the document’s language.

Type:

str or None

lint

Run the opt-in local-LLM syntax + alt-text pass.

Type:

bool

skip_phase

Preprocessing phases to skip, by name. Repeatable on the CLI.

Type:

tuple of str

reference_doc

Explicit template, overriding the whole resolution chain.

Type:

str or None

offline

Hard kill-switch for every network-touching phase.

Type:

bool

no_remote_templates

Opt out of the deraison.ai default template only.

Type:

bool

allow_remote_images

Opt in to downloading ![](https://…) images.

Type:

bool

verbose, quiet

Logging threshold: DEBUG / ERROR, default INFO.

Type:

bool

smart_layout

pptx only — map slides onto a designer template’s own named layouts.

Type:

bool

template

The designer .pptx that smart_layout maps onto.

Type:

str or None

reference_slides

smart_layout only — clone the template’s own example pages.

Type:

bool

no_visual_confirm

smart_layout only — skip the VLM visual tie-break.

Type:

bool

eyeball_iterations

smart_layout only — bounded revision passes after assembly.

Type:

int

min_pt

smart_layout only — the smallest type allowed on a slide (Kawasaki’s 30). None keeps the historical sizing.

Type:

float or None

refresh_catalog

smart_layout only — rebuild the cached layout catalog.

Type:

bool

allow_remote_images: bool = False
author: str | None = None
bib: str | None = None
bibliography_name: str | None = None
date: str | None = None
eyeball_iterations: int = 0
input: str
lang: str | None = None
lint: bool = False
min_pt: float | None = None
no_remote_templates: bool = False
no_visual_confirm: bool = False
offline: bool = False
output: str | None = None
quiet: bool = False
reference_doc: str | None = None
reference_slides: bool = False
refresh_catalog: bool = False
skip_phase: tuple[str, ...] = ()
smart_layout: bool = False
template: str | None = None
verbose: bool = False
md2star.pipeline.convert(fmt, opts, pandoc_args=())[source]

Run the full Markdown → .docx/.pptx/.pdf pipeline. Returns the exit code.

Parameters:

  • fmt ({"docx", "pptx", "pdf"}) – Target format. pdf renders a DOCX first and hands it to soffice.

  • opts (ConvertOptions) – The parsed md2star options. See the dataclass for each field.

  • pandoc_args (sequence of str, optional) – Flags md2star does not know, forwarded to Pandoc verbatim and last so they override anything md2star chose. This is the feature the whole tool is built around — md2docx report.md --toc has to reach Pandoc as --toc — so it is a plain list here rather than something parsed.

Returns:

0 on success; a non-zero code (Pandoc’s, or soffice’s) otherwise.

Return type:

int