Breng uw documenten in AI‑pijplijnen — rechtstreeks vanuit Python, on‑premise, met één pip install.

Vandaag brengen we de eerste openbare release van GroupDocs.Markdown voor Python via .NET uit op PyPI. De bibliotheek converteert PDF, Word, Excel, EPUB en meer dan 20 andere formaten naar schone, semantische Markdown — het formaat dat LLM’s, RAG‑pijplijnen en statische sitegeneratoren het beste gebruiken.

Als u de .NET‑release van september (of de volledige API‑herziening in 26.3) hebt gevolgd, is de reden dezelfde: documentopmaak draagt semantiek, en het behouden van die semantische structuur is wat een RAG‑systeem goede antwoorden laat geven. Het eerdere bericht behandelt het probleem (OCR vlakt structuur af, LLM’s hebben markdown nodig) en de oplossing (een DOM‑gebaseerde renderer die door het document loopt en Markdown genereert) uitvoerig — we zullen dat verhaal hier niet herhalen.

Laten we ons in plaats daarvan richten op wat er nieuw is voor Python‑ontwikkelaars.

Wat u krijgt

  • Een enkel wheel, geen runtime‑afhankelijkheden. pip install groupdocs-markdown-net haalt een zelfvoorzienend wheel op dat de .NET‑runtime en alle benodigde native bibliotheken bundelt. Geen dotnet‑installatie, geen Microsoft Office, geen Adobe Acrobat, geen cloudservices.
  • Cross‑platform. Windows x64/x86, Linux x64, macOS x64 en Apple Silicon (ARM64). Python 3.5 tot en met 3.14.
  • Een pythonic API. Klassen gebruiken PascalCase, methoden en eigenschappen gebruiken snake_case, enum‑waarden gebruiken UPPER_SNAKE_CASE. Contextmanagers ruimen geladen documenten deterministisch op.
  • Echt async. Elke statische en instantie‑methode heeft een _async‑tegenhanger. Bestands‑I/O is asynchroon en de CPU‑intensieve conversie draait op een werkthread — uw asyncio‑eventloop blijft vrij.
  • AI‑agentvriendelijk. Het geïnstalleerde wheel bevat een AGENTS.md‑bestand zodat code‑assistenten (Claude Code, Cursor, GitHub Copilot, Codex) automatisch de API‑oppervlakte, idiomatische gebruikspatronen en probleemoplossingstips ontdekken. Documentatie wordt ook gepubliceerd als llms.txt, een enkel‑bestand‑corpus (llms-full.txt), per‑pagina Markdown, en een MCP‑server — zie hieronder AI‑vriendelijk door ontwerp voor details.

Aan de slag

pip install groupdocs-markdown-net

De eenvoudigste conversie is een one‑liner:

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")

Dat is alles — geen configuratie, geen opties, geen boilerplate. Evaluatiemodus verwerkt de eerste 3 pagina’s en voegt een watermerk toe. Om de beperkingen te verwijderen, past u een licentie toe:

from groupdocs.markdown import License

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

Of stel GROUPDOCS_LIC_PATH in als een omgevingsvariabele en deze wordt automatisch toegepast bij import.

Ondersteunde formaten

De Python‑package behandelt dezelfde breedte aan formaten als de .NET‑bibliotheek:

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • Spreadsheets — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • eBooks — .epub, .mobi
  • Tekst / Markup / Help — .txt, .xml, .chm

Pythonic voorbeelden

Conversie‑opties en afbeeldingstrategieën

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)

Documentinspectie zonder conversie

from groupdocs.markdown import MarkdownConverter

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

Een wachtwoord‑beveiligd bestand laden

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 en contextmanagers

from groupdocs.markdown import MarkdownConverter

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

Async‑API — veel documenten gelijktijdig converteren

Omdat bestands‑I/O asynchroon is, laat asyncio.gather() een enkele worker veel documenten verwerken zonder te blokkeren:

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())

Dit maakt de bibliotheek een natuurlijke match voor ASGI‑frameworks zoals FastAPI — een enkele worker kan veel gelijktijdige conversieverzoeken afhandelen zonder thread‑contentie.

Foutafhandeling

Alle conversiemethoden werpen een uitzondering bij falen, met specifieke exceptietypen voor veelvoorkomende scenario’s:

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}")

Gebouwd voor RAG- en LLM-pijplijnen

Markdown is het voorkeurs‑invoerformaat voor embed‑modellen en retrieval‑pijplijnen — het behoudt koppen, lijsten, tabellen en nadruk, terwijl het gemakkelijk te chunk‑en en te tokeniseren is. Een typische RAG‑inname ziet er als volgt uit:

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()]

Omdat de bibliotheek volledig on‑premise draait, verlaten gevoelige documenten nooit uw omgeving — een veelvoorkomende eis voor gereguleerde sectoren, juridische teams en interne kennisbanken.

AI‑vriendelijk door ontwerp

De meeste Python‑SDK’s behandelen AI‑code‑assistenten als een bijzaak — een ontwikkelaar moet de agent nog steeds naar de documentatie wijzen, voorbeelden plakken of debuggen via trial‑and‑error. GroupDocs.Markdown voor Python via .NET keert dit om: de bibliotheek is zo ontworpen dat agenten zoals Claude Code, Cursor, GitHub Copilot en Codex het kunnen oppikken zonder enige handmatige configuratie.

AGENTS.md wordt meegeleverd in het wheel

Dit is het eerste GroupDocs‑pakket dat een AGENTS.md‑bestand direct in het geïnstalleerde wheel bundelt. Het bestand volgt de opkomende AGENTS.md‑conventie — een eenvoudige Markdown‑README specifiek geschreven voor AI‑code‑assistenten in plaats van mensen.

Wanneer u pip install groupdocs-markdown-net uitvoert, wordt een bestand geplaatst op:

site-packages/groupdocs/markdown/AGENTS.md

Een AI‑assistent die uw project opent, kan het lezen en onmiddellijk leren:

  • Het volledige publieke API‑oppervlak (klassen, methoden, enums, uitzonderingen) en hoe ze zich tot elkaar verhouden.
  • Idiomatische gebruikspatronen voor de meest voorkomende scenario’s — statische versus instantie‑API, sync versus async, afbeeldingstrategieën, front‑matter, foutafhandeling.
  • Veelvoorkomende valkuilen en hoe ze te vermijden — bijv. welke ConvertOptions‑overloads None accepteren, hoe wachtwoord‑beveiligde bestanden te behandelen, hoe conversiewaarschuwingen vast te leggen.
  • Probleemoplossing voor platformspecifieke issues (libSkiaSharp op macOS, ICU op Linux).

In de praktijk betekent dit dat u kunt zeggen “use groupdocs-markdown-net to convert this folder of PDFs to Markdown for my RAG pipeline” en de agent schrijft werkende code bij de eerste poging — geen verzonnen methodenamen, geen verkeerde argumentvolgorde, geen geraden imports.

Machine‑leesbare documentatie

Voor agenten die iets moeten opzoeken dat niet in AGENTS.md staat, wordt de volledige productdocumentatie ook gepubliceerd in machine‑leesbare vorm:

  • Enkel‑bestand‑corpus — de volledige documentatie als één aaneengeschakelde Markdown‑file, klaar om in het context‑venster van een agent te plaatsen: https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • Per‑pagina Markdown — voeg .md toe aan elke documentatie‑URL om de ruwe bron op te halen: https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • llms.txt‑index — een llms.txt-stijl inhoudsopgave die agenten naar de benodigde pagina’s leidt: https://docs.groupdocs.com/markdown/python-net/llms.txt

MCP‑server voor live document‑opzoekingen

Voor agenten die Model Context Protocol spreken, stellen we de documentatie beschikbaar als een MCP‑server. Voeg dit toe aan uw Claude Code‑ of Cursor‑configuratie:

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

Daarna kan uw agent de documentatie op aanvraag opvragen in plaats van te vertrouwen op trainingsdata die mogelijk verouderd is.

Markdown in, Markdown out

Er is hier een mooie symmetrie: de output van de bibliotheek is Markdown — het formaat dat LLM’s het beste kunnen parseren voor RAG — en de documentatie is ook Markdown, aangeboden als één bestand voor gemakkelijke opname in een context‑venster. Of u nu een agent vraagt code te schrijven die de bibliotheek gebruikt, of een agent vraagt uw documenten te begrijpen via de bibliotheek, Markdown is het gemeenschappelijke medium.

Export‑voorbeeld

De bovenstaande fragmenten zijn bijna het kortste bruikbare programma dat u met de bibliotheek kunt schrijven. Hier is hetzelfde idee verpakt als een uitvoerbaar project — bron‑document, Python‑script, vooraf gegenereerde output, requirements.txt en een Dockerfile — zodat u het end‑to‑end kunt uitproberen zonder iets vanaf nul te schrijven.

Bron‑DOCX

Het bronbestand business-plan.docx is een kort, rijk opgemaakt businessplan met koppen, tabellen, afbeeldingen en metadata.

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

De quick-example.md output begint met een YAML front‑matter‑blok dat automatisch uit de documentmetadata is gehaald, gevolgd door de geconverteerde inhoud met GitHub‑Flavored tabellen en een verschoven kop‑hiërarchie (klaar om in een groter document te embedden).

Uitvoerbare voorbeeld‑app

Alles samengebundeld: sample-app.zip. Pak uit, dan:

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

Of voer het uit in Docker — de meegeleverde Dockerfile zet de ICU‑afhankelijkheid op die de meegeleverde .NET‑runtime nodig heeft op Linux:

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

Samenvatting

GroupDocs.Markdown voor Python via .NET brengt de volledige document‑naar‑Markdown conversie‑engine naar Python als een zelfvoorzienend wheel — geen externe runtime, geen cloud, geen verrassingen. Een pythonic API, async‑ondersteuning en eersteklas AI‑tool‑integratie maken het een praktische keuze voor Python‑teams die RAG‑systemen, statische site‑generatoren of documentverwerkings‑pijplijnen bouwen.

Meer informatie

Ondersteuning & feedback

Voor vragen of technische ondersteuning kunt u ons Free Support Forum gebruiken — we helpen u graag.