Belgelerinizi AI boru hatlarına getirin — doğrudan Python’dan, şirket içinde, tek bir pip install ile.

Bugün GroupDocs.Markdown for Python via .NET‘in ilk genel sürümünü PyPI’da yayımlıyoruz. Kütüphane PDF, Word, Excel, EPUB ve 20’den fazla 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 doğru 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) ayrıntılı olarak ele alıyordu — burada bu hikayeyi tekrarlamıyoruz.

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

What you get

  • Tek bir wheel, çalışma zamanı bağımlılığı yok. pip install groupdocs-markdown-net komutu, .NET çalışma zamanını ve ihtiyaç duyduğu tüm yerel kütüphaneleri içinde barındıran bağımsız bir wheel indirir. dotnet kurulumu, Microsoft Office, Adobe Acrobat veya bulut hizmetleri gerekmez.
  • Çapraz platform. Windows x64/x86, Linux x64, macOS x64 ve Apple Silicon (ARM64). Python 3.5‑den 3.14’e kadar.
  • Pythonic bir API. Sınıflar PascalCase, metod ve özellikler snake_case, enum değerleri UPPER_SNAKE_CASE biçimindedir. Bağlam yöneticileri (context managers) yüklü belgeleri deterministik olarak serbest bırakır.
  • Gerçekten async. Her statik ve örnek metodun bir _async eşdeğeri vardır. Dosya I/O asenkronik, 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 wheel, 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 korpusu (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.

Get started

pip install groupdocs-markdown-net

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

from groupdocs.markdown import MarkdownConverter

# Bir string olarak 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 veya kalıp gerekmez. Değerlendirme modu ilk 3 sayfayı işler ve bir filigran ekler. Sınırlamaları kaldırmak için 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; import edildiğinde otomatik olarak uygulanır.

Supported formats

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
  • Spreadsheets — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
  • eBooks — .epub, .mobi
  • Text / Markup / Help — .txt, .xml, .chm

Pythonic examples

Dönüşüm seçenekleri ve görüntü 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    # prepend YAML metadata
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ı 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 doğal bir uyum sağlar — tek bir işçi, çoklu eşzamanlı dönüşüm isteğini thread çatışması olmadan hizmet verir.

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("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, 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ümlenmesi ve tokenlemesi kolaydır. Tipik bir RAG alımı şu şekilde 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 şirket içinde çalıştığı için, hassas belgeler ortamınızdan dışarı çıkmaz — düzenleyici sektörler, hukuk ekipleri ve dahili bilgi tabanları için ortak bir gereksinimdir.

AI-friendly by design

Çoğu Python SDK’sı AI kodlama asistanlarını bir sonradan ek olarak görür — geliştiricinin belgeye yönlendirme yapması, örnek yapıştırması veya 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 wheel içinde gelir

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

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

site-packages/groupdocs/markdown/AGENTS.md

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

  • Tam kamu API yüzeyi (sınıflar, metodlar, enumlar, istisnalar) ve bunların ilişkileri.
  • İdiomatik kullanım kalıpları en yaygın senaryolar için — statik vs örnek API, senkron vs asenkron, görüntü stratejileri, front‑matter, hata yönetimi.
  • Ortak tuzaklar ve kaçınılması gereken durumlar — örneğin 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ın (macOS’ta libSkiaSharp, Linux’ta ICU) troubleshooting rehberi.

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 kod üretmesi anlamına gelir — hayali metod isimleri, hatalı argüman sırası veya tahmini importlar yoktur.

Makine‑okunur dokümantasyon

AGENTS.md içinde bulunmayan bir bilgiye ihtiyaç duyan ajanlar için tam ürün dokümantasyonu da makine‑okunur biçimde sunulur:

  • Tek‑dosya korpusu — tüm dokümanlar birleştirilmiş bir Markdown dosyası olarak, ajan bağlam penceresine doğrudan eklenebilir:
    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-stil içerik tablosu:
    https://docs.groupdocs.com/markdown/python-net/llms.txt

MCP sunucusu ile canlı doküman sorgulamaları

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

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

Böylece ajan, eğitim verileri eski olsa bile ihtiyaç duyduğu zaman dokümantasyonu anlık olarak sorgulayabilir.

Markdown giriş, Markdown çıkış

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

Export Example

Yukarıdaki kod parçacıkları, kütüphane ile yazabileceğiniz en kısa faydalı program örnekleridir. 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 meta veriler içeren kısa, zengin biçimli 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 string'i 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 meta verilerinden 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) bulunur.

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

Her şey bir arada: sample-app.zip. Zip’i 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

Summary

GroupDocs.Markdown for Python via .NET, tam belge‑to‑Markdown dönüşüm motorunu Python’a bağımsız bir wheel olarak getirir — dış runtime, bulut ya da sürpriz yok. Pythonic 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.

Learn more

Support & feedback

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