Convenience Functions

The doc2mark package exposes a set of module-level helper functions that wrap UnifiedDocumentLoader so you can convert documents in a single call without instantiating the loader yourself. Use them for scripts, notebooks, and quick one-off conversions; reach for the loader directly when you need to reuse a single instance across many files or customise format handlers.

Function	When to use
`load()`	Load one file and get a `ProcessedDocument`.
`document_to_markdown()`	Convert one file to Markdown (optionally save to disk).
`batch_convert_to_markdown()`	Convert every supported file in a directory to Markdown.
`batch_process_documents()`	Like `batch_convert_to_markdown` but with full control over output format and file-saving behaviour.
`batch_process_files()`	Process an explicit list of files instead of scanning a directory.

Single-document helpers

load

from doc2mark import load

result = load("report.pdf")
print(result.content[:200])

# With image extraction and OCR
result = load(
    "slides.pptx",
    extract_images=True,
    ocr_images=True,
    ocr_provider="openai",
    api_key="sk-...",
)

Signature

def load(
    file_path: Union[str, Path],
    output_format: Union[str, OutputFormat] = OutputFormat.MARKDOWN,
    extract_images: bool = False,
    ocr_images: bool = False,
    ocr_provider: Union[str, OCRProvider] = "openai",
    api_key: Optional[str] = None,
    ocr_cache: Optional[OCRCache] = None,
    **kwargs: Any,
) -> ProcessedDocument: ...

Parameters

file_path: Path to the document to process.
output_format: Desired output format. Accepts a string ("markdown", "html", "text") or an OutputFormat member. Defaults to OutputFormat.MARKDOWN.
extract_images: When True, images embedded in the document are extracted as base64 data. Defaults to False.
ocr_images: When True and extract_images is also True, extracted images are sent to the configured OCR provider for text recognition. Defaults to False.
ocr_provider: The OCR backend to use. Accepts "openai" or "vertex_ai" (or an OCRProvider member). Defaults to "openai".
api_key: API key for the chosen OCR provider. When None the provider falls back to its own environment-variable lookup.
ocr_cache: An optional OCRCache instance for request-scoped caching of OCR results.
**kwargs: Forwarded to UnifiedDocumentLoader.load().

Returns

A ProcessedDocument containing the converted content and metadata.

doc2mark.load(file_path, output_format=OutputFormat.MARKDOWN, extract_images=False, ocr_images=False, ocr_provider='openai', api_key=None, ocr_cache=None, **kwargs)[source]

Quick load function for single documents.

Parameters:

file_path (str | Path) – Path to the document
output_format (str | OutputFormat) – Output format (default: markdown)
extract_images (bool) – Whether to extract images from documents - True: Extract images as base64 data - False: Skip image extraction entirely
ocr_images (bool) – Whether to perform OCR on extracted images (requires extract_images=True) - True: Use batch OCR processing to convert images to text descriptions - False: Keep images as base64 data in output
ocr_provider (str | OCRProvider) – OCR provider to use
api_key (str | None) – API key for OCR provider
ocr_cache (OCRCache | None) – Optional request-scoped OCR cache handler
**kwargs (Any) – Additional options

Returns:

ProcessedDocument

Return type:

ProcessedDocument

Examples

# Basic text extraction only load(“document.pdf”)

# Extract images as base64 (no OCR) load(“document.pdf”, extract_images=True, ocr_images=False)

# Extract images and perform OCR load(“document.pdf”, extract_images=True, ocr_images=True)

document_to_markdown

A backward-compatible helper that converts a single file to Markdown and optionally writes the result to disk.

from doc2mark import document_to_markdown

md = document_to_markdown("report.docx", output_path="report.md")

Signature

def document_to_markdown(
    file_path: Union[str, Path],
    output_path: Optional[Union[str, Path]] = None,
    extract_images: bool = False,
    ocr_images: bool = False,
    ocr_provider: Union[str, OCRProvider] = "openai",
    api_key: Optional[str] = None,
    ocr_cache: Optional[OCRCache] = None,
    show_progress: bool = True,
    **kwargs: Any,
) -> str: ...

Parameters

file_path: Path to the source document.
output_path: If provided, the Markdown string is written to this path (parent directories are created automatically).
extract_images: Extract images as base64 data. Defaults to False.
ocr_images: Run OCR on extracted images (requires extract_images=True). Defaults to False.
ocr_provider: OCR backend ("openai" or "vertex_ai"). Defaults to "openai".
api_key: API key for the OCR provider.
ocr_cache: Optional OCRCache instance.
show_progress: Print a confirmation message after saving. Defaults to True.
**kwargs: Forwarded to UnifiedDocumentLoader.load().

Returns

The Markdown content as a plain str.

doc2mark.document_to_markdown(file_path, output_path=None, extract_images=False, ocr_images=False, ocr_provider='openai', api_key=None, ocr_cache=None, show_progress=True, **kwargs)[source]

Convert any supported document to Markdown (backward compatibility function).

Parameters:

file_path (str | Path) – Path to the document
output_path (str | Path | None) – Optional path to save the markdown file
extract_images (bool) – Whether to extract images from documents - True: Extract images as base64 data - False: Skip image extraction entirely
ocr_images (bool) – Whether to perform OCR on extracted images (requires extract_images=True) - True: Use batch OCR processing to convert images to text descriptions - False: Keep images as base64 data in output
ocr_provider (str | OCRProvider) – OCR provider to use
api_key (str | None) – API key for OCR provider
ocr_cache (OCRCache | None) – Optional request-scoped OCR cache handler
show_progress (bool) – Whether to show progress messages
**kwargs (Any) – Additional options

Returns:

Markdown string

Return type:

str

Batch helpers

batch_convert_to_markdown

Scans a directory for supported documents and converts each one to Markdown. Files are optionally saved to output_dir with a .md extension.

from doc2mark import batch_convert_to_markdown

results = batch_convert_to_markdown(
    "incoming/",
    output_dir="converted/",
    recursive=True,
)
for path, info in results.items():
    if info.get("success"):
        print(f"{path} -> OK")

Signature

def batch_convert_to_markdown(
    input_dir: Union[str, Path],
    output_dir: Optional[Union[str, Path]] = None,
    extract_images: bool = False,
    ocr_images: bool = False,
    recursive: bool = True,
    ocr_provider: Union[str, OCRProvider] = "openai",
    api_key: Optional[str] = None,
    ocr_cache: Optional[OCRCache] = None,
    show_progress: bool = True,
    **kwargs: Any,
) -> Dict[str, Dict[str, Any]]: ...

Parameters

input_dir: Directory to scan for documents.
output_dir: Destination directory for the generated Markdown files. When None, files are not saved to disk (results are still returned in the dictionary).
extract_images: Extract images as base64 data. Defaults to False.
ocr_images: Run OCR on extracted images. Defaults to False.
recursive: Descend into subdirectories. Defaults to True.
ocr_provider: OCR backend. Defaults to "openai".
api_key: API key for the OCR provider.
ocr_cache: Optional OCRCache instance.
show_progress: Print progress messages during processing. Defaults to True.
**kwargs: Forwarded to UnifiedDocumentLoader.batch_process().

Returns

A dict mapping each input file path (as a string) to a result dictionary containing at minimum a "success" key.

doc2mark.batch_convert_to_markdown(input_dir, output_dir=None, extract_images=False, ocr_images=False, recursive=True, ocr_provider='openai', api_key=None, ocr_cache=None, show_progress=True, **kwargs)[source]

Batch convert documents to Markdown (backward compatibility function).

Parameters:

input_dir (str | Path) – Directory containing documents
output_dir (str | Path | None) – Optional output directory
extract_images (bool) – Whether to extract images from documents - True: Extract images as base64 data - False: Skip image extraction entirely
ocr_images (bool) – Whether to perform OCR on extracted images (requires extract_images=True) - True: Use batch OCR processing to convert images to text descriptions - False: Keep images as base64 data in output
recursive (bool) – Whether to process subdirectories
ocr_provider (str | OCRProvider) – OCR provider to use
api_key (str | None) – API key for OCR provider
ocr_cache (OCRCache | None) – Optional request-scoped OCR cache handler
show_progress (bool) – Whether to show progress messages
**kwargs (Any) – Additional options

Returns:

Dictionary mapping input paths to results

Return type:

Dict[str, Dict[str, Any]]

batch_process_documents

A fully configurable batch processor that adds control over the output format and whether files are written to disk. Use this instead of batch_convert_to_markdown() when you need HTML or plain-text output, or want to keep results in memory only.

Signature

def batch_process_documents(
    input_dir: Union[str, Path],
    output_dir: Optional[Union[str, Path]] = None,
    output_format: Union[str, OutputFormat] = OutputFormat.MARKDOWN,
    extract_images: bool = False,
    ocr_images: bool = False,
    recursive: bool = True,
    ocr_provider: Union[str, OCRProvider] = "openai",
    api_key: Optional[str] = None,
    ocr_cache: Optional[OCRCache] = None,
    show_progress: bool = True,
    save_files: bool = True,
    **kwargs: Any,
) -> Dict[str, Dict[str, Any]]: ...

Parameters

input_dir: Directory to scan for documents.
output_dir: Destination directory. Ignored when save_files is False.
output_format: Output format (string or OutputFormat). Defaults to OutputFormat.MARKDOWN.
extract_images: Extract images as base64 data. Defaults to False.
ocr_images: Run OCR on extracted images. Defaults to False.
recursive: Descend into subdirectories. Defaults to True.
ocr_provider: OCR backend. Defaults to "openai".
api_key: API key for the OCR provider.
ocr_cache: Optional OCRCache instance.
show_progress: Print progress messages. Defaults to True.
save_files: Write output files to output_dir. Defaults to True.
**kwargs: Forwarded to UnifiedDocumentLoader.batch_process().

Returns

A dict mapping each input file path to a result dictionary with detailed metadata.

doc2mark.batch_process_documents(input_dir, output_dir=None, output_format=OutputFormat.MARKDOWN, extract_images=False, ocr_images=False, recursive=True, ocr_provider='openai', api_key=None, ocr_cache=None, show_progress=True, save_files=True, **kwargs)[source]

Advanced batch processing with full configuration options.

Parameters:

input_dir (str | Path) – Directory containing documents
output_dir (str | Path | None) – Optional output directory
output_format (str | OutputFormat) – Output format
extract_images (bool) – Whether to extract images from documents - True: Extract images as base64 data - False: Skip image extraction entirely
ocr_images (bool) – Whether to perform OCR on extracted images (requires extract_images=True) - True: Use batch OCR processing to convert images to text descriptions - False: Keep images as base64 data in output
recursive (bool) – Whether to process subdirectories
ocr_provider (str | OCRProvider) – OCR provider to use
api_key (str | None) – API key for OCR provider
ocr_cache (OCRCache | None) – Optional request-scoped OCR cache handler
show_progress (bool) – Whether to show progress messages
save_files (bool) – Whether to save output files
**kwargs (Any) – Additional options

Returns:

Dictionary mapping input paths to results with detailed metadata

Return type:

Dict[str, Dict[str, Any]]

batch_process_files

Processes an explicit list of file paths rather than scanning a directory. Useful when you already know exactly which files to convert, or when the files are spread across multiple directories.

from doc2mark import batch_process_files

results = batch_process_files(
    ["reports/q1.pdf", "reports/q2.pdf", "notes/meeting.docx"],
    output_dir="out/",
)

Signature

def batch_process_files(
    file_paths: List[Union[str, Path]],
    output_dir: Optional[Union[str, Path]] = None,
    output_format: Union[str, OutputFormat] = OutputFormat.MARKDOWN,
    extract_images: bool = False,
    ocr_images: bool = False,
    ocr_provider: Union[str, OCRProvider] = "openai",
    api_key: Optional[str] = None,
    ocr_cache: Optional[OCRCache] = None,
    show_progress: bool = True,
    save_files: bool = True,
    **kwargs: Any,
) -> Dict[str, Dict[str, Any]]: ...

Parameters

file_paths: A list of paths to the documents to process.
output_dir: Destination directory for output files. Ignored when save_files is False.
output_format: Output format (string or OutputFormat). Defaults to OutputFormat.MARKDOWN.
extract_images: Extract images as base64 data. Defaults to False.
ocr_images: Run OCR on extracted images. Defaults to False.
ocr_provider: OCR backend. Defaults to "openai".
api_key: API key for the OCR provider.
ocr_cache: Optional OCRCache instance.
show_progress: Print progress messages. Defaults to True.
save_files: Write output files to output_dir. Defaults to True.
**kwargs: Forwarded to UnifiedDocumentLoader.batch_process_files().

Returns

A dict mapping each input file path to a result dictionary.

doc2mark.batch_process_files(file_paths, output_dir=None, output_format=OutputFormat.MARKDOWN, extract_images=False, ocr_images=False, ocr_provider='openai', api_key=None, ocr_cache=None, show_progress=True, save_files=True, **kwargs)[source]

Batch process a specific list of files.

Parameters:

file_paths (List[str | Path]) – List of file paths to process
output_dir (str | Path | None) – Optional output directory
output_format (str | OutputFormat) – Output format
extract_images (bool) – Whether to extract images from documents - True: Extract images as base64 data - False: Skip image extraction entirely
ocr_images (bool) – Whether to perform OCR on extracted images (requires extract_images=True) - True: Use batch OCR processing to convert images to text descriptions - False: Keep images as base64 data in output
ocr_provider (str | OCRProvider) – OCR provider to use
api_key (str | None) – API key for OCR provider
ocr_cache (OCRCache | None) – Optional request-scoped OCR cache handler
show_progress (bool) – Whether to show progress messages
save_files (bool) – Whether to save output files
**kwargs (Any) – Additional options

Returns:

Dictionary mapping input paths to results

Return type:

Dict[str, Dict[str, Any]]

Examples

# Basic text extraction only batch_process_files([“doc1.pdf”, “doc2.docx”])

# Extract images as base64 (no OCR) batch_process_files(files, extract_images=True, ocr_images=False)

# Extract images and perform batch OCR batch_process_files(files, extract_images=True, ocr_images=True)