GroupDocs.Markdown per Python via .NET — Esporta documenti in Markdown

Porta i tuoi documenti nei pipeline AI — direttamente da Python, on‑premise, con un solo pip install.

Oggi rilasciamo la prima versione pubblica di GroupDocs.Markdown for Python via .NET su PyPI. La libreria converte PDF, Word, Excel, EPUB e oltre 20 altri formati in Markdown pulito e semantico — il formato con cui LLM, pipeline RAG e generatori di siti statici lavorano al meglio.

Se hai seguito il rilascio .NET di settembre /markdown/groupdocs-markdown-for-net-first-public-release/ (o il rework completo dell’API nella 26.3 (https://releases.groupdocs.com/markdown/net/release-notes/2026/groupdocs-markdown-for-net-26-3-release-notes/)), la motivazione è la stessa: la formattazione dei documenti trasporta semantica, e preservare quella struttura semantica è ciò che permette a un sistema RAG di fornire risposte corrette. Il post precedente descrive il problema (OCR appiattisce la struttura, gli LLM hanno bisogno di markdown) e la soluzione (un renderer basato su DOM che attraversa il documento ed emette Markdown) in dettaglio — non ripeteremo quella storia qui.

Invece, concentriamoci su ciò che è nuovo per gli sviluppatori Python.

Cosa ottieni

Un unico wheel, senza dipendenze a runtime. pip install groupdocs-markdown-net scarica un wheel auto‑contenuto che include il runtime .NET e tutte le librerie native necessarie. Nessuna installazione di dotnet, nessun Microsoft Office, nessun Adobe Acrobat, nessun servizio cloud.
Cross‑platform. Windows x64/x86, Linux x64, macOS x64 e Apple Silicon (ARM64). Python 3.5‑3.14.
API pythonica. Le classi usano PascalCase, i metodi e le proprietà usano snake_case, i valori enum usano UPPER_SNAKE_CASE. I context manager rilasciano i documenti caricati in modo deterministico.
Davvero async. Ogni metodo statico e di istanza ha una controparte _async. L’I/O dei file è asincrono e la conversione CPU‑bound viene eseguita su un thread di lavoro — il tuo loop asyncio rimane libero.
Amichevole per gli agenti AI. Il wheel installato contiene un file AGENTS.md così gli assistenti di codifica (Claude Code, Cursor, GitHub Copilot, Codex) scoprono automaticamente l’API, i pattern d’uso idiomatici e i consigli di troubleshooting. La documentazione è pubblicata anche come llms.txt, un corpus a file unico (llms-full.txt), Markdown per pagina e un server MCP — vedi la sezione AI‑friendly by design per i dettagli.

Inizia

pip install groupdocs-markdown-net

La conversione più semplice è una singola riga:

from groupdocs.markdown import MarkdownConverter

# Converti in una stringa
md = MarkdownConverter.to_markdown("business-plan.docx")

# Oppure scrivi direttamente su file
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

Tutto qui — nessuna configurazione, nessuna opzione, nessun boilerplate. La modalità di valutazione elabora le prime 3 pagine e aggiunge un watermark. Per rimuovere i limiti, applica una licenza:

from groupdocs.markdown import License

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

Oppure imposta GROUPDOCS_LIC_PATH come variabile d’ambiente; verrà applicata automaticamente all’importazione.

Formati supportati

Il pacchetto Python gestisce la stessa ampiezza di formati della libreria .NET:

PDF — .pdf
Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
Fogli di calcolo — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
eBook — .epub, .mobi
Testo / Markup / Help — .txt, .xml, .chm

Esempi pythonici

Opzioni di conversione e strategie per le immagini

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)

Ispezione del documento senza conversione

from groupdocs.markdown import MarkdownConverter

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

Caricamento di un file protetto da password

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)

Stream e context manager

from groupdocs.markdown import MarkdownConverter

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

API async — conversione di molti documenti in parallelo

Poiché l’I/O dei file è asincrono, asyncio.gather() permette a un singolo worker di elaborare molti documenti senza blocchi:

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

Questo rende la libreria una scelta naturale per framework ASGI come FastAPI — un singolo worker può servire molte richieste di conversione concorrenti senza contese sui thread.

Gestione degli errori

Tutti i metodi di conversione sollevano eccezioni in caso di errore, con tipi specifici per gli scenari più comuni:

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

Progettato per pipeline RAG e LLM

Il Markdown è il formato di input preferito per i modelli di embedding e le pipeline di recupero — conserva intestazioni, elenchi, tabelle e enfasi, ed è facile da suddividere e tokenizzare. Un tipico ingest RAG appare così:

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

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # solo testo per 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()

# Suddividi per intestazioni di livello superiore, poi embed/indexa ogni chunk
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

Poiché la libreria gira interamente on‑premise, i documenti sensibili non lasciano mai il tuo ambiente — requisito comune per settori regolamentati, team legali e knowledge base interne.

AI‑friendly by design

La maggior parte degli SDK Python tratta gli assistenti di codifica AI come un ripensamento — lo sviluppatore deve comunque indicare all’agente la documentazione, incollare esempi o fare debug a tentoni. GroupDocs.Markdown for Python via .NET ribalta la situazione: la libreria è progettata affinché agenti come Claude Code, Cursor, GitHub Copilot e Codex la possano utilizzare senza alcuna configurazione manuale.

`AGENTS.md` incluso nel wheel

Questo è il primo pacchetto GroupDocs a includere un file AGENTS.md direttamente dentro il wheel installato. Il file segue la convenzione emergente AGENTS.md convention — un README in puro Markdown scritto specificamente per assistenti di codifica AI anziché per esseri umani.

Quando esegui pip install groupdocs-markdown-net, il file viene posizionato in:

site-packages/groupdocs/markdown/AGENTS.md

Un assistente AI che apre il tuo progetto può leggerlo e apprendere immediatamente:

L’intera superficie API pubblica (classi, metodi, enum, eccezioni) e le loro relazioni.
Pattern d’uso idiomatici per gli scenari più comuni — API statica vs istanza, sync vs async, strategie immagine, front matter, gestione errori.
Trappole comuni e come evitarle — ad es. quali overload di ConvertOptions accettano None, come gestire file protetti da password, come catturare avvisi di conversione.
Troubleshooting per problemi specifici di piattaforma (libSkiaSharp su macOS, ICU su Linux).

In pratica, puoi dire “usa groupdocs-markdown-net per convertire questa cartella di PDF in Markdown per il mio pipeline RAG” e l’agente scrive codice funzionante al primo tentativo — nessun nome di metodo allucinato, nessun ordine di argomenti errato, nessun import indovinato.

Documentazione leggibile da macchine

Per gli agenti che hanno bisogno di cercare qualcosa non presente in AGENTS.md, la documentazione completa è pubblicata anche in forma leggibile da macchine:

Corpus a file unico — la documentazione completa in un unico file Markdown, pronto da inserire nel contesto di un agente:
https://docs.groupdocs.com/markdown/python-net/llms-full.txt
Markdown per pagina — aggiungi .md a qualsiasi URL della docs per ottenere il sorgente grezzo:
https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
Indice llms.txt — una tabella dei contenuti in stile llms.txt che indirizza gli agenti alle pagine necessarie:
https://docs.groupdocs.com/markdown/python-net/llms.txt

Server MCP per lookup live della documentazione

Per gli agenti che parlano Model Context Protocol, esponiamo le docs come server MCP. Aggiungi questo alla configurazione di Claude Code o Cursor:

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

Dopo di che, l’agente può interrogare la documentazione su richiesta invece di affidarsi a dati di training potenzialmente obsoleti.

Markdown in, Markdown out

C’è una bella simmetria: l’output della libreria è Markdown — il formato che gli LLM analizzano meglio per il RAG — e la sua documentazione è anch’essa Markdown, servita come file unico per un facile inserimento nel contesto. Che tu chieda a un agente di scrivere codice che usa la libreria, o di comprendere i tuoi documenti tramite la libreria, il Markdown è il mezzo comune.

Esempio di esportazione

Gli snippet sopra sono quasi il programma più breve e utile che si possa scrivere con la libreria. Ecco la stessa idea confezionata come progetto eseguibile — documento sorgente, script Python, output pre‑generato, requirements.txt e un Dockerfile — così puoi provarlo end‑to‑end senza scrivere nulla da zero.

DOCX sorgente

Il file sorgente business-plan.docx è un breve piano aziendale riccamente formattato con intestazioni, tabelle, immagini e metadati.

Script Python

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

Markdown di output

L’output quick-example.md inizia con un blocco YAML front‑matter estratto automaticamente dai metadati del documento, seguito dal contenuto convertito con tabelle in stile GitHub Flavored e una gerarchia di intestazioni spostata (pronta per essere inserita in un documento più grande).

App di esempio eseguibile

Tutto confezionato insieme: sample-app.zip. Decomprimi, poi:

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

Oppure eseguilo in Docker — il Dockerfile incluso installa la dipendenza ICU di cui il runtime .NET bundlato ha bisogno su Linux:

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

Riepilogo

GroupDocs.Markdown for Python via .NET porta il motore completo di conversione documento‑to‑Markdown in Python come wheel auto‑contenuto — nessun runtime esterno, nessun cloud, nessuna sorpresa. Un’API pythonica, il supporto async e l’integrazione di primo livello con strumenti AI lo rendono una scelta pratica per i team Python che costruiscono sistemi RAG, generatori di siti statici o pipeline di elaborazione documenti.

Per saperne di più

Pacchetto PyPI: https://pypi.org/project/groupdocs-markdown-net/
Home prodotto: https://products.groupdocs.com/markdown/python-net/
Documentazione: https://docs.groupdocs.com/markdown/python-net/
Note di rilascio: https://releases.groupdocs.com/markdown/python-net/release-notes/
Esempi di codice su GitHub: https://github.com/groupdocs-markdown/GroupDocs.Markdown-for-Python-via-.NET
Informazioni sulla licenza: https://about.groupdocs.com/legal/
Post di rilascio correlato per .NET: GroupDocs.Markdown for .NET — First Public Release

Supporto e feedback

Per domande o assistenza tecnica, utilizza il nostro Free Support Forum — saremo felici di aiutarti.

Cosa ottieni#

Inizia#

Formati supportati#

Esempi pythonici#

Opzioni di conversione e strategie per le immagini#

Ispezione del documento senza conversione#

Caricamento di un file protetto da password#

Stream e context manager#

API async — conversione di molti documenti in parallelo#

Gestione degli errori#

Progettato per pipeline RAG e LLM#

AI‑friendly by design#

AGENTS.md incluso nel wheel#

Documentazione leggibile da macchine#

Server MCP per lookup live della documentazione#

Markdown in, Markdown out#

Esempio di esportazione#

Riepilogo#

Per saperne di più#

Supporto e feedback#