Belgelerinizi AI boru hatlarına getirin — Python’dan, yerinde, tek bir pip install ile.

Bugün GroupDocs.Markdown for Python via .NET‘in ilk genel sürümünü PyPI’de yayımlıyoruz. Kütüphane PDF, Word, Excel, EPUB ve 20+ başka formatı temiz, anlamsal Markdown’a dönüştürüyor — LLM’lerin, RAG boru hatlarının ve statik site üreticilerinin en iyi çalıştığı format.

Eğer .NET sürümünü Eylül ayında takip ettiyseniz (veya 26.3’teki tam API revizyonunu incelediyseniz), mantık aynı: belge biçimlendirmesi anlamsal bilgi taşır ve bu anlamsal yapıyı korumak, bir RAG sisteminin iyi yanıtlar vermesini sağlar. Önceki gönderi problemi (OCR yapısı düzleştirir, LLM’ler markdown ister) ve çözümü (belgeyi dolaşan ve Markdown üreten DOM tabanlı bir render) derinlemesine ele alıyor — burada bu hikayeyi tekrarlamayacağız.

Bunun yerine, Python geliştiricileri için yeniliklere odaklanalım.

Neler elde edersiniz

  • Tek bir tekerlek, çalışma zamanı bağımlılığı yok. pip install groupdocs-markdown-net .NET çalışma zamanını ve ihtiyaç duyduğu tüm yerel kütüphaneleri içinde barındıran bağımsız bir tekerlek indirir. dotnet kurulumu, Microsoft Office, Adobe Acrobat ya da bulut hizmetleri gerekmez.
  • Çapraz platform. Windows x64/x86, Linux x64, macOS x64 ve Apple Silicon (ARM64). Python 3.5‑den 3.14’e kadar.
  • Pythonik bir API. Sınıflar PascalCase, metod ve özellikler snake_case, enum değerleri UPPER_SNAKE_CASE kullanır. Bağlam yöneticileri (context managers) yüklü belgeleri belirli bir şekilde serbest bırakır.
  • Gerçekten async. Her statik ve örnek metodun bir _async karşılığı vardır. Dosya I/O asenkronik ve CPU‑ağır dönüşüm bir işçi iş parçacığında çalışır — asyncio döngünüz serbest kalır.
  • AI‑ajan dostu. Kurulu tekerlek bir AGENTS.md dosyası içerir; böylece kodlama asistanları (Claude Code, Cursor, GitHub Copilot, Codex) API yüzeyini, idiomatik kullanım kalıplarını ve sorun giderme ipuçlarını otomatik keşfeder. Dokümantasyon ayrıca llms.txt, tek‑dosya korpus (llms-full.txt), sayfa‑sayfa Markdown ve bir MCP sunucusu olarak yayımlanır — ayrıntılar için aşağıdaki AI‑friendly by design bölümüne bakın.

Başlarken

pip install groupdocs-markdown-net

En basit dönüşüm tek satırda yapılır:

from groupdocs.markdown import MarkdownConverter

# Bir dizeye dönüştür
md = MarkdownConverter.to_markdown("business-plan.docx")

# Ya da doğrudan bir dosyaya yaz
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

Hepsi bu — yapılandırma, seçenek ya da kalıp yok. Değerlendirme modu ilk 3 sayfayı işler ve bir filigran ekler. Sınırlamaları kaldırmak için bir lisans uygulayın:

from groupdocs.markdown import License

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

Ya da GROUPDOCS_LIC_PATH ortam değişkenini ayarlayın; bu değişken içe aktarma sırasında otomatik olarak uygulanır.

Desteklenen formatlar

Python paketi, .NET kütüphanesiyle aynı format çeşitliliğini destekler:

  • PDF — .pdf
  • Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
  • Elektronik tablolar — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • eKitaplar — .epub, .mobi
  • Metin / İşaretleme / Yardım — .txt, .xml, .chm

Pythonik örnekler

Dönüşüm seçenekleri ve resim stratejileri

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    # YAML üst verisini ekle
options.image_export_strategy = strategy

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

Dönüşüm olmadan belge inceleme

from groupdocs.markdown import MarkdownConverter

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

Şifre korumalı bir dosya yükleme

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)

Akışlar ve bağlam yöneticileri

from groupdocs.markdown import MarkdownConverter

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

Async API — birden çok belgeyi aynı anda dönüştürme

Dosya I/O asenkron olduğundan, asyncio.gather() tek bir işçiyle birçok belgeyi bloklamadan işleyebilir:

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

Bu, FastAPI gibi ASGI çerçeveleri için kütüphaneyi doğal bir uyumlu hâle getirir — tek bir işçi, çoklu eşzamanlı dönüşüm isteğini thread çatışması olmadan hizmet verebilir.

Hata yönetimi

Tüm dönüşüm metodları başarısızlıkta istisna fırlatır; yaygın senaryolar için özel istisna tipleri bulunur:

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

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("Yanlış ya da eksik şifre.")
except InvalidFormatException:
    print("Dosya bozuk ya da desteklenmiyor.")
except GroupDocsMarkdownException as ex:
    print(f"Dönüşüm başarısız: {ex}")

RAG ve LLM boru hatları için inşa edildi

Markdown, gömme modelleri ve retrieval (geri getirme) boru hatları için tercih edilen giriş formatıdır — başlıkları, listeleri, tabloları ve vurgulamaları korur, aynı zamanda bölümlendirme ve tokenleştirme açısından kolaydır. Tipik bir RAG alımı şöyle görünür:

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

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # RAG için sadece metin
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()

# Üst‑seviye başlıklara göre böl, ardından her parçayı göm/indeksle
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

Kütüphane tamamen yerinde çalıştığı için hassas belgeler ortamınızdan dışarı çıkmaz — düzenlenmiş sektörler, hukuk ekipleri ve dahili bilgi tabanları için ortak bir gereksinim.

Tasarım itibarıyla AI‑friendly

Çoğu Python SDK’sı AI kodlama asistanlarını bir sonradan ekleme olarak görür — geliştiricinin belgeye yönlendirmesi, örnek yapıştırması ya da deneme‑yanılma ile hata ayıklaması gerekir. GroupDocs.Markdown for Python via .NET bu yaklaşımı tersine çevirir: kütüphane, Claude Code, Cursor, GitHub Copilot ve Codex gibi ajanların manuel kurulum olmadan doğrudan benimseyebileceği şekilde tasarlanmıştır.

AGENTS.md tekerleğin içinde gelir

Bu, kurulu tekerleğin içinde doğrudan bir AGENTS.md dosyası barındıran ilk GroupDocs paketidir. Dosya, yeni ortaya çıkan AGENTS.md standardına uygun — insanlardan ziyade AI kodlama asistanları için yazılmış sade‑Markdown bir README.

pip install groupdocs-markdown-net çalıştırdığınızda dosya şu konuma yerleşir:

site-packages/groupdocs/markdown/AGENTS.md

Bir AI asistanı projenizi açtığında bu dosyayı okuyarak anında şunları öğrenir:

  • Tam public API yüzeyi (sınıflar, metodlar, enumlar, istisnalar) ve bunların ilişkileri.
  • En yaygın senaryolar için idiomatik kullanım kalıpları — statik vs örnek API, sync vs async, resim stratejileri, front matter, hata yönetimi.
  • Ortak tuzaklar ve nasıl kaçınılacağı — örn. hangi ConvertOptions aşırı yüklemeleri None kabul eder, şifre korumalı dosyalar nasıl işlenir, dönüşüm uyarıları nasıl yakalanır.
  • Platform‑spesifik sorunlar için sorun giderme (macOS’ta libSkiaSharp, Linux’ta ICU).

Pratikte bu, “groupdocs-markdown-net’i bu PDF klasörünü RAG boru hattım için Markdown’a dönüştürmek üzere kullan” dediğinizde ajanın ilk denemede çalışan kodu üretmesi demektir — hayali metod isimleri, yanlış argüman sırası ya da tahmini importlar yok.

Makine‑okunur dokümantasyon

AGENTS.md içinde bulunmayan bir şeyi arayan ajanlar için tam ürün dokümantasyonu da makine‑okunur biçimde yayımlanır:

  • Tek‑dosya korpus — tüm dokümanlar birleştirilmiş Markdown dosyası olarak, bir ajanın bağlam penceresine doğrudan konulabilir:
    https://docs.groupdocs.com/markdown/python-net/llms-full.txt
  • Sayfa‑sayfa Markdown — herhangi bir doküman URL’sine .md ekleyerek ham kaynağı alabilirsiniz:
    https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
  • llms.txt indeksi — ajanları ihtiyaç duydukları sayfalara yönlendiren bir llms.txt-stili içerik tablosu:
    https://docs.groupdocs.com/markdown/python-net/llms.txt

Canlı doküman sorgulamaları için MCP sunucusu

Model Context Protocol konuşan ajanlar için dokümanları bir MCP sunucusu olarak sunarız. Claude Code ya da Cursor yapılandırmanıza şunu ekleyin:

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

Böylece ajan, eğitim verilerinin eski olma riskine dayanmak yerine ihtiyaca göre dokümantasyonu sorgulayabilir.

Markdown içinde, Markdown dışarı

Burada güzel bir simetri var: kütüphanenin çıktısı Markdown — LLM’lerin RAG için en iyi parse ettiği format — ve dokümantasyonu da Markdown, tek dosya olarak kolayca bağlam penceresine alınabilir. Bir ajan, kütüphaneyi kullanan kodu yazsın ya da belgelerinizi kütüphane aracılığıyla anlamasını sağlasın, ortak ortam Markdown’dır.

Dışa Aktarım Örneği

Yukarıdaki kod parçacıkları, kütüphane ile yazabileceğiniz en kısa faydalı programlara yakındır. Aynı fikri çalıştırılabilir bir proje olarak paketledik — kaynak belge, Python betiği, önceden oluşturulmuş çıktı, requirements.txt ve bir Dockerfile — böylece sıfırdan bir şey yazmadan uçtan uca deneyebilirsiniz.

Kaynak DOCX

Kaynak dosya business-plan.docx, başlıklar, tablolar, görseller ve üst veri içeren kısa, zengin biçimlendirilmiş bir iş planıdır.

Python betiği

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """GitHub flavor ve YAML front matter ile bir Word belgesini Markdown'a dönüştür."""

    # Tek satır — bir Markdown dizesi döndürür
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # Seçeneklerle — bir dosyaya yazar
    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()

Çıktı Markdown

quick-example.md çıktısı, belge üst verisinden otomatik çıkarılan bir YAML front‑matter bloğu ile başlar, ardından GitHub Flavored tablolar ve kaydırılmış başlık hiyerarşisi (daha büyük bir belgeye gömülmeye hazır) içerir.

Çalıştırılabilir örnek uygulama

Her şey bir arada: sample-app.zip. Açın, ardından:

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

Veya Docker’da çalıştırın — dahil edilen Dockerfile, Linux’ta paketlenmiş .NET çalışma zamanının ihtiyaç duyduğu ICU bağımlılığını kurar:

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

Özet

GroupDocs.Markdown for Python via .NET, tam belge‑to‑Markdown dönüşüm motorunu Python’a bağımsız bir tekerlek olarak getiriyor — dış runtime, bulut ya da sürpriz yok. Pythonik API, async desteği ve birinci sınıf AI araç entegrasyonu, RAG sistemleri, statik site üreticileri veya belge işleme boru hatları geliştiren Python ekipleri için pratik bir seçim yapar.

Daha fazla bilgi

Destek & geri bildirim

Sorularınız veya teknik yardım için lütfen Free Support Forum adresini kullanın — size yardımcı olmaktan memnuniyet duyarız.