Bawa dokumen Anda ke pipeline AI — langsung dari Python, on‑premise, dengan satu pip install.

Hari ini kami merilis rilisan publik pertama GroupDocs.Markdown untuk Python via .NET di PyPI. Perpustakaan ini mengonversi PDF, Word, Excel, EPUB, dan lebih dari 20 format lainnya menjadi Markdown bersih dan semantik — format yang paling cocok untuk LLM, pipeline RAG, dan generator situs statis.

Jika Anda telah mengikuti rilis .NET dari September (atau perombakan lengkap API pada 26.3), alasannya sama: pemformatan dokumen membawa semantik, dan mempertahankan struktur semantik itulah yang membuat sistem RAG memberikan jawaban yang baik. Posting sebelumnya membahas masalah (OCR meratakan struktur, LLM membutuhkan markdown) dan solusi (renderer berbasis DOM yang menelusuri dokumen dan menghasilkan Markdown) secara mendalam — kami tidak akan mengulang cerita itu di sini.

Sebagai gantinya, mari fokus pada apa yang baru bagi pengembang Python.

Apa yang Anda Dapatkan

  • Satu wheel tunggal, tanpa dependensi runtime. pip install groupdocs-markdown-net mengunduh wheel yang berdiri sendiri dan menyertakan runtime .NET serta semua pustaka native yang dibutuhkan. Tidak perlu instalasi dotnet, tidak perlu Microsoft Office, tidak perlu Adobe Acrobat, tidak ada layanan cloud.
  • Lintas platform. Windows x64/x86, Linux x64, macOS x64, dan Apple Silicon (ARM64). Python 3.5 hingga 3.14.
  • API yang pythonic. Kelas menggunakan PascalCase, metode dan properti menggunakan snake_case, nilai enum menggunakan UPPER_SNAKE_CASE. Context manager membuang dokumen yang dimuat secara deterministik.
  • Benar‑benar async. Setiap metode statis dan instance memiliki pasangan _async. I/O file bersifat asynchronous dan konversi yang memakan CPU dijalankan pada thread pekerja — asyncio event loop Anda tetap bebas.
  • Ramah agen AI. Wheel yang diinstal menyertakan file AGENTS.md sehingga asisten kode (Claude Code, Cursor, GitHub Copilot, Codex) dapat menemukan permukaan API, pola penggunaan idiomatik, dan tip pemecahan masalah secara otomatis. Dokumentasi juga dipublikasikan sebagai llms.txt, korpus satu‑file (llms-full.txt), Markdown per halaman, dan server MCP — lihat Ramah AI secara desain di bawah untuk detailnya.

Mulai

pip install groupdocs-markdown-net

Konversi paling sederhana hanya satu baris:

from groupdocs.markdown import MarkdownConverter

# Konversi ke string
md = MarkdownConverter.to_markdown("business-plan.docx")

# Atau tulis langsung ke file
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

Itu saja — tanpa konfigurasi, tanpa opsi, tanpa boilerplate. Mode evaluasi memproses 3 halaman pertama dan menambahkan watermark. Untuk menghapus batasan, terapkan lisensi:

from groupdocs.markdown import License

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

Atau tetapkan GROUPDOCS_LIC_PATH sebagai variabel lingkungan dan lisensi akan diterapkan secara otomatis saat impor.

Format yang didukung

Paket Python menangani cakupan format yang sama dengan perpustakaan .NET:

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

Contoh Pythonic

Opsi konversi dan strategi gambar

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)

Inspeksi dokumen tanpa konversi

from groupdocs.markdown import MarkdownConverter

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

Memuat file yang dilindungi kata sandi

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 dan 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 — mengonversi banyak dokumen secara bersamaan

Karena I/O file bersifat asynchronous, asyncio.gather() memungkinkan satu pekerja memproses banyak dokumen tanpa blocking:

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

Hal ini membuat perpustakaan cocok secara alami untuk kerangka kerja ASGI seperti FastAPI — satu pekerja dapat melayani banyak permintaan konversi bersamaan tanpa kontensi thread.

Penanganan error

Semua metode konversi melempar exception saat gagal, dengan tipe exception khusus untuk skenario umum:

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

Dibangun untuk pipeline RAG dan LLM

Markdown adalah format input yang disukai untuk model embedding dan pipeline retrieval — ia mempertahankan heading, list, tabel, dan penekanan sambil mudah di‑chunk dan di‑tokenisasi. Ingest RAG tipikal terlihat seperti ini:

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

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # hanya teks untuk 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()

# Bagi berdasarkan heading tingkat atas, lalu embed/index tiap potongan
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

Karena perpustakaan berjalan sepenuhnya on‑premise, dokumen sensitif tidak pernah meninggalkan lingkungan Anda — persyaratan umum untuk industri yang diatur, tim hukum, dan basis pengetahuan internal.

Ramah AI secara desain

Sebagian besar SDK Python memperlakukan asisten coding AI sebagai pemikiran setelahnya — pengembang masih harus menunjuk agen ke dokumentasi, menempel contoh, atau debug melalui trial‑and‑error. GroupDocs.Markdown untuk Python via .NET membalikkan hal itu: perpustakaan dirancang sehingga agen seperti Claude Code, Cursor, GitHub Copilot, dan Codex dapat memanfaatkannya tanpa penyiapan manual.

AGENTS.md disertakan di dalam wheel

Ini adalah paket GroupDocs pertama yang menyertakan file AGENTS.md langsung di dalam wheel yang diinstal. File tersebut mengikuti konvensi AGENTS.md yang sedang berkembang — README berformat Markdown polos yang khusus ditulis untuk asisten coding AI, bukan manusia.

Saat Anda menjalankan pip install groupdocs-markdown-net, sebuah file muncul di:

site-packages/groupdocs/markdown/AGENTS.md

Asisten AI yang membuka proyek Anda dapat membacanya dan langsung mempelajari:

  • Permukaan API publik lengkap (kelas, metode, enum, exception) serta hubungannya.
  • Pola penggunaan idiomatik untuk skenario paling umum — API statis vs instance, sync vs async, strategi gambar, front matter, penanganan error.
  • Jebakan umum dan cara menghindarinya — misalnya overload ConvertOptions mana yang menerima None, cara menangani file yang diproteksi kata sandi, cara menangkap peringatan konversi.
  • Pemecahan masalah untuk isu spesifik platform (libSkiaSharp di macOS, ICU di Linux).

Dalam praktiknya, ini berarti Anda dapat berkata “gunakan groupdocs-markdown-net untuk mengonversi folder PDF ini ke Markdown untuk pipeline RAG saya” dan agen menulis kode yang berfungsi pada percobaan pertama — tanpa nama metode yang dihalusinasi, tanpa urutan argumen yang salah, tanpa impor yang ditebak.

Dokumentasi yang dapat dibaca mesin

Untuk agen yang perlu mencari sesuatu yang tidak ada di AGENTS.md, dokumentasi produk lengkap juga dipublikasikan dalam bentuk yang dapat dibaca mesin:

  • Korpus satu‑file — dokumen lengkap sebagai satu file Markdown yang digabungkan, siap dimasukkan ke jendela konteks agen:
    https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • Markdown per halaman — tambahkan .md ke URL dokumen apa pun untuk mengambil sumber mentah:
    https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • Indeks llms.txt — tabel isi gaya llms.txt yang mengarahkan agen ke halaman yang mereka butuhkan:
    https://docs.groupdocs.com/markdown/python-net/llms.txt

Server MCP untuk pencarian dokumen secara langsung

Untuk agen yang menggunakan Model Context Protocol, kami mengekspos dokumen sebagai server MCP. Tambahkan ini ke konfigurasi Claude Code atau Cursor Anda:

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

Setelah itu, agen Anda dapat menanyakan dokumentasi sesuai permintaan alih‑alih mengandalkan data pelatihan yang mungkin usang.

Markdown masuk, Markdown keluar

Ada simetri yang menyenangkan di sini: output perpustakaan adalah Markdown — format yang paling mudah dipahami LLM untuk RAG — dan dokumentasinya juga berupa Markdown, disajikan sebagai satu file untuk memudahkan ingest jendela konteks. Baik Anda meminta agen menulis kode yang menggunakan perpustakaan, atau meminta agen memahami dokumen Anda melalui perpustakaan, Markdown adalah media umum.

Contoh Ekspor

Potongan kode di atas hampir merupakan program paling singkat yang berguna dengan perpustakaan ini. Berikut ide yang sama dibungkus sebagai proyek yang dapat dijalankan — dokumen sumber, skrip Python, output yang sudah dihasilkan, requirements.txt, dan Dockerfile — sehingga Anda dapat mencobanya end‑to‑end tanpa menulis apa pun dari awal.

DOCX sumber

File sumber business-plan.docx adalah rencana bisnis singkat yang kaya format dengan heading, tabel, gambar, dan metadata.

Skrip Python

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """Mengonversi dokumen Word ke Markdown dengan flavor GitHub dan front matter YAML."""

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

    # Dengan opsi — menulis ke 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 output

Output quick-example.md dimulai dengan blok front‑matter YAML yang diekstrak otomatis dari metadata dokumen, diikuti oleh konten yang telah dikonversi dengan tabel bergaya GitHub dan hierarki heading yang digeser (siap di‑embed ke dalam dokumen yang lebih besar).

Aplikasi contoh yang dapat dijalankan

Semua terbundel bersama: sample-app.zip. Ekstrak, lalu:

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

Atau jalankan di Docker — Dockerfile yang disertakan menyiapkan dependensi ICU yang dibutuhkan runtime .NET yang dibundel di Linux:

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

Ringkasan

GroupDocs.Markdown untuk Python via .NET membawa mesin konversi dokumen‑ke‑Markdown lengkap ke Python sebagai wheel yang berdiri sendiri — tanpa runtime eksternal, tanpa cloud, tanpa kejutan. API yang pythonic, dukungan async, dan integrasi alat AI kelas satu menjadikannya pilihan praktis bagi tim Python yang membangun sistem RAG, generator situs statis, atau pipeline pemrosesan dokumen.

Pelajari lebih lanjut

Dukungan & umpan balik

Untuk pertanyaan atau bantuan teknis, silakan gunakan Free Support Forum kami — kami dengan senang hati membantu.