Přiveďte své dokumenty do AI pipeline — přímo z Pythonu, on‑premise, jedním pip install.

Dnes uvádíme první veřejné vydání GroupDocs.Markdown pro Python přes .NET na PyPI. Knihovna převádí PDF, Word, Excel, EPUB a více než 20 dalších formátů do čistého, sémantického Markdownu — formátu, se kterým nejlépe pracují LLM, RAG pipeline a generátory statických webů.

Pokud jste sledovali .NET vydání ze září (nebo kompletní přestavbu API ve verzi 26.3), motivace je stejná: formátování dokumentu nese sémantiku a zachování této sémantické struktury je to, co umožňuje RAG systému poskytovat dobré odpovědi. Předchozí příspěvek podrobně popisuje problém (OCR zplošťuje strukturu, LLM potřebují markdown) a řešení (renderer založený na DOM, který prochází dokument a generuje Markdown) — tuto historii zde nebudeme opakovat.

Místo toho se zaměříme na to, co je nového pro vývojáře v Pythonu.

What you get

  • Jedno kolo (wheel), bez runtime závislostí. pip install groupdocs-markdown-net stáhne samostatný wheel, který obsahuje runtime .NET a všechny potřebné nativní knihovny. Žádná instalace dotnet, žádný Microsoft Office, žádný Adobe Acrobat, žádné cloudové služby.
  • Cross-platform (víceplatforemní). Windows x64/x86, Linux x64, macOS x64 a Apple Silicon (ARM64). Python 3.5 až 3.14.
  • Pythonické API. Třídy používají PascalCase, metody a vlastnosti snake_case, hodnoty enumů UPPER_SNAKE_CASE. Kontextové manažery deterministicky uvolňují načtené dokumenty.
  • Skutečně async. Každá statická i instance metoda má ekvivalent s příponou _async. Souborové I/O je asynchronní a konverze náročná na CPU běží ve worker vlákně — váš asyncio event loop zůstává volný.
  • Přátelské pro AI agenty. Instalovaný wheel obsahuje soubor AGENTS.md, takže kódovací asistenti (Claude Code, Cursor, GitHub Copilot, Codex) automaticky objeví API, idiomatické vzory použití a tipy na řešení problémů. Dokumentace je také publikována jako llms.txt, jednosouborový korpus (llms-full.txt), Markdown po stránkách a MCP server — podrobnosti viz AI-friendly by design níže.

Get started

pip install groupdocs-markdown-net

Nejjednodušší konverze je jednorázový příkaz:

from groupdocs.markdown import MarkdownConverter

# Convert to a string
md = MarkdownConverter.to_markdown("business-plan.docx")

# Or write directly to a file
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

A to je vše — žádná konfigurace, žádné volby, žádný boilerplate. Evaluační režim zpracuje první 3 stránky a přidá vodoznak. Pro odstranění omezení použijte licenci:

from groupdocs.markdown import License

License().set_license("path/to/license.lic")

Nebo nastavte GROUPDOCS_LIC_PATH jako proměnnou prostředí a licence bude automaticky použita při importu.

Supported formats

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • Tabulky — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • eKnihy — .epub, .mobi
  • Text / Značkování / Nápověda — .txt, .xml, .chm

Pythonic examples

Conversion options and image strategies

from groupdocs.markdown import (
    MarkdownConverter,
    ConvertOptions,
    MarkdownFlavor,
    ExportImagesToFileSystemStrategy,
)

strategy = ExportImagesToFileSystemStrategy("output/images")
strategy.images_relative_path = "images"  # ![](images/img-001.png)

options = ConvertOptions()
options.flavor = MarkdownFlavor.GIT_HUB
options.heading_level_offset = 1      # # Title -> ## Title
options.include_front_matter = True    # prepend YAML metadata
options.image_export_strategy = strategy

MarkdownConverter.to_file("report.docx", "output/report.md", convert_options=options)

Document inspection without conversion

from groupdocs.markdown import MarkdownConverter

info = MarkdownConverter.get_info("business-plan.docx")
print(f"{info.file_format}, {info.page_count} pages, author: {info.author}")

Loading a password-protected file

from groupdocs.markdown import MarkdownConverter, LoadOptions, FileFormat

load_opts = LoadOptions(FileFormat.DOCX)
load_opts.password = "secret"

MarkdownConverter.to_file("protected.docx", "output.md", load_options=load_opts)

Streams and context managers

from groupdocs.markdown import MarkdownConverter

with open("document.docx", "rb") as stream:
    with MarkdownConverter(stream) as converter:
        converter.convert("document.md")

Async API — converting many documents concurrently

Protože souborové I/O je asynchronní, asyncio.gather() umožní jednomu workeru zpracovat mnoho dokumentů bez blokování:

import asyncio
from groupdocs.markdown import MarkdownConverter

async def convert_many():
    await asyncio.gather(
        MarkdownConverter.to_file_async("a.docx", "a.md", None),
        MarkdownConverter.to_file_async("b.pdf",  "b.md", None),
        MarkdownConverter.to_file_async("c.xlsx", "c.md", None),
    )

asyncio.run(convert_many())

To dělá knihovnu přirozenou volbou pro ASGI frameworky jako FastAPI — jeden worker může obsluhovat mnoho souběžných požadavků na konverzi bez soutěže o vlákna.

Error handling

Všechny konverzní metody vyhazují výjimku při selhání, s konkrétními typy výjimek pro běžné scénáře:

from groupdocs.markdown import (
    MarkdownConverter,
    DocumentProtectedException,
    InvalidFormatException,
    GroupDocsMarkdownException,
)

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("Wrong or missing password.")
except InvalidFormatException:
    print("File is corrupt or unsupported.")
except GroupDocsMarkdownException as ex:
    print(f"Conversion failed: {ex}")

Built for RAG and LLM pipelines

Markdown je preferovaný vstupní formát pro embedovací modely a retrieval pipeline — zachovává nadpisy, seznamy, tabulky a zvýraznění a zároveň se snadno rozděluje a tokenizuje. Typický RAG ingest vypadá takto:

import re
from groupdocs.markdown import MarkdownConverter, ConvertOptions, SkipImagesStrategy, MarkdownFlavor

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # text-only for RAG
options.flavor = MarkdownFlavor.COMMON_MARK

MarkdownConverter.to_file("business-plan.pdf", "business-plan.md", convert_options=options)

with open("business-plan.md", "r", encoding="utf-8") as f:
    markdown = f.read()

# Split by top-level headings, then embed/index each chunk
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

Protože knihovna běží zcela on‑premise, citlivé dokumenty nikdy neopustí vaše prostředí — běžná požadavek pro regulované odvětví, právní týmy a interní znalostní báze.

AI-friendly by design

Většina Python SDK považuje AI kódovací asistenty za doplněk — vývojář stále musí agenta nasměrovat na dokumentaci, vložit příklady nebo ladit zkouškou a omylem. GroupDocs.Markdown pro Python přes .NET to obrací: knihovna je navržena tak, aby agenti jako Claude Code, Cursor, GitHub Copilot a Codex ji mohli využít bez jakékoli ruční konfigurace.

AGENTS.md ships inside the wheel

Toto je první balíček GroupDocs, který v instalovaném wheelu obsahuje soubor AGENTS.md. Soubor následuje vznikající AGENTS.md konvenci — jednoduchý Markdown README psaný speciálně pro AI kódovací asistenty místo lidí.

Když spustíte pip install groupdocs-markdown-net, soubor se objeví na:

site-packages/groupdocs/markdown/AGENTS.md
  • Celý veřejný API povrch (třídy, metody, enumy, výjimky) a jak spolu souvisejí.
  • Idiomatické vzory použití pro nejčastější scénáře — statické vs. instance API, sync vs. async, strategie obrázků, front matter, handling chyb.
  • Běžné úskalí a jak se jim vyhnout — např. které přetížení ConvertOptions akceptují None, jak zacházet se soubory chráněnými heslem, jak zachytit varování během konverze.
  • Řešení problémů pro platformově specifické potíže (libSkiaSharp na macOS, ICU na Linuxu).

V praxi to znamená, že můžete říct „použij groupdocs-markdown-net k převodu této složky PDF do Markdownu pro můj RAG pipeline“ a agent napíše funkční kód hned na první pokus — žádná vymýšlená jména metod, žádné špatné pořadí argumentů, žádné hádané importy.

Machine-readable documentation

Pro agenty, kteří potřebují vyhledat něco, co není v AGENTS.md, je kompletní produktová dokumentace také publikována ve strojově čitelné formě:

  • Jednosouborový korpus — kompletní dokumentace jako jeden spojený Markdown soubor, připravený vložit do kontextového okna agenta: https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • Markdown po stránkách — přidejte .md k libovolné URL dokumentace a získáte surový zdroj: https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • llms.txt index — llms.txt-styl tabulky obsahu, který nasměruje agenty na potřebné stránky: https://docs.groupdocs.com/markdown/python-net/llms.txt

MCP server for live doc lookups

Pro agenty, kteří podporují Model Context Protocol, zpřístupňujeme dokumentaci jako MCP server. Přidejte toto do konfigurace Claude Code nebo Cursor:

{
  "mcpServers": {
    "groupdocs-docs": {
      "url": "https://docs.groupdocs.com/mcp"
    }
  }
}

Po tom může váš agent dotazovat dokumentaci na vyžádání místo spoléhaní se na tréninková data, která mohou být zastaralá.

Markdown in, Markdown out

Je zde pěkná symetrie: výstup knihovny je Markdown — formát, který LLM nejlépe parsují pro RAG — a její dokumentace je také v Markdownu, poskytovaná jako jeden soubor pro snadné nasazení do kontextového okna. Ať už žádáte agenta, aby napsal kód, který používá knihovnu, nebo aby pochopil vaše dokumenty pomocí knihovny, Markdown je společným médiem.

Export Example

Ukázky výše jsou téměř nejkratším užitečným programem, který můžete s knihovnou napsat. Zde je stejný nápad zabalený jako spustitelný projekt — zdrojový dokument, Python skript, předgenerovaný výstup, requirements.txt a Dockerfile — takže si můžete vše vyzkoušet od začátku do konce bez psaní čehokoli od nuly.

Source DOCX

Zdrojový soubor business-plan.docx je krátký, bohatě formátovaný podnikatelský plán s nadpisy, tabulkami, obrázky a metadaty.

Python script

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """Convert a Word document to Markdown with GitHub flavor and YAML front matter."""

    # One-liner — returns a Markdown string
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # With options — writes to a file
    options = ConvertOptions()
    options.flavor = MarkdownFlavor.GIT_HUB
    options.include_front_matter = True
    options.heading_level_offset = 1
    MarkdownConverter.to_file("business-plan.docx", "quick-example.md", convert_options=options)

if __name__ == "__main__":
    quick_example()

Output Markdown

Výstup quick-example.md začíná blokem YAML front‑matter automaticky extrahovaným z metadat dokumentu, následovaným převedeným obsahem s GitHub Flavored tabulkami a posunutou hierarchií nadpisů (připravený k vložení do většího dokumentu).

Runnable sample app

Vše je zabalené dohromady: sample-app.zip. Rozbalte a poté:

cd src
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python quick_example.py

Nebo to spusťte v Dockeru — přiložený Dockerfile nastaví závislost ICU, kterou zabalený .NET runtime potřebuje na Linuxu:

cd src
docker build -t groupdocs-markdown-python-example .
docker run --rm -v "$(pwd)/output:/app/output" groupdocs-markdown-python-example

Summary

GroupDocs.Markdown pro Python přes .NET přináší plný engine pro konverzi dokumentu na Markdown do Pythonu jako samostatný wheel — žádný externí runtime, žádný cloud, žádná překvapení. Pythonické API, podpora async a integrace první třídy AI nástrojů z něj dělají praktickou volbu pro Python týmy budující RAG systémy, generátory statických webů nebo pipeline pro zpracování dokumentů.

Learn more

Support & feedback

Pro otázky nebo technickou pomoc použijte naše Free Support Forum — rádi vám pomůžeme.