Markdown'i Yayın‑Hazır Biçimlere Dönüştürme

Markdown, geliştiriciler, yazarlar ve açık‑kaynak toplulukları için ortak bir dil haline geldi. Düz‑metin sözdizimi yazması, sürüm kontrolü yapması ve farklı platformlarda render edilmesi kolaydır. Ancak, çoğu izleyici hâlâ cilalı PDF’ler, duyarlı HTML sayfaları veya EPUB e‑kitaplar bekler. Markdown’ı bu hedef biçimlere, başlıkları, tabloları, kod bloklarını veya meta verileri kaybetmeden dönüştürmek şaşırtıcı derecede zor olabilir. Aşağıdaki kılavuz, doğruluk, performans ve gizliliği dengeleyen yeniden üretilebilir bir iş akışını adım adım gösterir.

Kaynak Materyali Anlamak

Herhangi bir dönüşümden önce, Markdown dosyasını tamamlanmış bir ürün yerine bir kaynak belge olarak ele alın. Özel işlem gerektiren öğeleri belirleyin:

  • Front‑matter meta verileri (başlık, yazar, tarih, etiketler). Birçok statik site oluşturucusunda bu, --- ile sınırlanmış YAML olarak görünür. Alt biçimlerin kapak sayfaları veya gömülü meta veri için buna ihtiyaç duyması sık olduğu için koruyun.
  • Dil tanımlayıcıları içeren kod çitleri. Sözdizimi vurgulaması dönüşüm sırasında ayakta kalmalı, özellikle teknik kitaplarda.
  • Tablolar, dipnotlar ve tanım listeleri. Hedef formatların hepsi bunları doğal olarak desteklemez; HTML <table> ya da PDF tablo yapıları gibi şekillere dönüştürmek gerekebilir.
  • İlişkili yollarla referans verilen görseller ve varlıklar. Dönüştürme hattının bu yolları çözmesi ve isteğe bağlı olarak ikili veriyi gömmesi gerekir.
  • Dahili bağlantılar (ör. [Bölüm](#bolum)) ve belge‑ötesi referanslar. Tek bir PDF veya EPUB oluşturulurken bunlar işlevsel yer imleri veya köprüler olmalıdır.

Bu unsurları erken cataloglayarak, iş akışının ilerleyen aşamalarında sürprizlerle karşılaşmazsınız.

Doğru Dönüştürme Motorunu Seçmek

Markdown için üç geniş dönüştürücü ailesi vardır:

  1. Pandoc‑tabanlı iş akışları – Pandoc, Markdown okuyup PDF, HTML, EPUB, DOCX ve daha pek çok biçime dönüştürebilen evrensel bir belge çeviricisidir. Atıflar, dipnotlar ve özelleştirilmiş şablonlarla başa çıkmada üstündür.
  2. Statik site oluşturucular (SSG’ler) – Hugo, Jekyll ya da MkDocs gibi araçlar, temalandırma sistemleriyle Markdown’ı HTML’e render eder. Tam özellikli bir web sitesi gerektiğinde idealdir, ancak baskı araçlarıyla da birleştirilebilir.
  3. Web‑tabanlı hizmetler – convertise.app gibi platformlar, bir Markdown dosyasını alıp seçilen çıktı biçimini döndüren bir REST uç noktası sunar. Yazılım kurmadan tek seferlik dönüşümler için kullanışlıdır.

Tekrarlanabilir, gizlilik‑öncelikli bir iş akışı için yerel bir Pandoc kurulumu önerilir. Tamamen kullanıcı makinesinde çalışır ve uzaktaki bir sunucuda iz bırakmaz.

Ortamı Hazırlamak

  1. Pandoc’u kurun (en yeni kararlı sürüm) ve PDF oluşturacaksanız bir LaTeX dağıtımı (ör. TinyTeX) ekleyin.
  2. Sanal ortam oluşturun (Python venv ya da Node nvm) ve yardımcı araçları izole tutun.
  3. Varlıkları toplayın – tüm referans verilen görselleri, PDF’leri ve font dosyalarını tek bir klasöre kopyalayın. Bu, dönüştürücünün yol çözümlemesini basit hâle getirir.
  4. Meta veri dosyası oluşturun – Markdown dosyanızda front‑matter yoksa, metadata.yaml içinde title, author, date ve eklemek istediğiniz diğer alanları tanımlayın.
---
title: "Effective Open‑Source Documentation"
author: "Jane Doe"
date: "2026-05-10"
keywords: [markdown, documentation, publishing]
---

Bu bloğu her kaynak dosyanın başına ekleyebilir ya da Pandoc’a --metadata-file ile iletebilirsiniz.

PDF’e Dönüştürme

Adım 1: Bir LaTeX şablonu seçin

Pandoc, PDF çıktısı için LaTeX’i arka planda kullanır. İyi hazırlanmış bir şablon kenar boşluklarını, üst‑alt bilgi stillerini, fontları ve kod‑bloğu render’ını kontrol eder. Resmi eisvogel şablonu popüler bir başlangıçtır çünkü:

  • listings paketiyle sözdizimi vurgulamalı kod bloklarını destekler.
  • Tıklanabilir bir içindekiler tablosu üretir.
  • PDF’in XMP paketine meta verileri gömer; bu, dijital kütüphaneler için faydalıdır.

Şablonu indirin ve varlıklarınızın yanına koyun.

Adım 2: Pandoc’u uygun bayraklarla çalıştırın

pandoc main.md \
  --metadata-file=metadata.yaml \
  --template=eisvogel.tex \
  --toc \
  --highlight-style=pygments \
  --pdf-engine=xelatex \
  -V mainfont="Libre Baskerville" \
  -V monofont="Fira Code" \
  -o output.pdf

Önemli seçeneklerin açıklaması:

  • --toc otomatik bir içindekiler tablosu oluşturur.
  • -V mainfont ve -V monofont PDF’in istediğiniz görsel kimliği yansıtmasını sağlar.
  • --highlight-style kod çitleri için tutarlı renklemeyi garantiler.

Adım 3: Sonucu doğrulayın

PDF’i açıp şunları kontrol edin:

  • Tüm başlıklar TOC’da doğru sayfa numaralarıyla yer alıyor mu?
  • Kod blokları okunaklı ve dil‑spesifik renkleri koruyor mu?
  • Görseller gömülü (bağlantı değil) ve orantılı mı ölçeklenmiş?
  • Meta veriler (yazar, başlık) belge özelliklerinde (Dosya → Özellikler → Açıklama) görünüyor mu?

Eksik bir unsur varsa şablonu ayarlayın ya da Pandoc filtreleri ekleyin (ör. atıflar için pandoc-citeproc).

HTML’e Dönüştürme

HTML, çoğu Markdown motorunun yerel çıktısıdır, ancak yayın‑hazır bir çıktı için SSG’lerin eklediği ekstra sınıfları içermeyen temiz bir işaretleme gerekir.

Adım 1: Minimal bir CSS çerçevesi seçin

Pure.css gibi hafif bir stil sayfası ya da özel bir style.css sayfa hızını korurken tablolar, alıntılar ve kod için akıllı varsayılanlar sağlar. CSS dosyasını oluşturulan HTML ile aynı dizine koyun.

Adım 2: Pandoc ile HTML üretin

pandoc main.md \
  --metadata-file=metadata.yaml \
  --standalone \
  --toc \
  --css=style.css \
  --highlight-style=pygments \
  -o output.html

--standalone bayrağı gövdeyi tam bir HTML belgesine sarar, --toc ise sabit bir konuma stil verilebilecek bir gezinme kenar çubuğu ekler.

Adım 3: Erişilebilirliği artırın

  • <html> etiketine lang="en" ekleyin (Pandoc, lang=en ayarlarsanız bunu otomatik yapar).
  • Tüm görsellere alt özniteliği ekleyin; Markdown’da eksikse bir Pandoc filtresiyle ya da kaynağı düzenleyerek ekleyin.
  • Başlık seviyelerinin hiyerarşik olduğundan emin olun (h1 → h2 → h3).

Adım 4: Tarayıcılarda test edin

output.html dosyasını Chrome, Firefox ve Edge’de açın. Dar görünümde kod bloklarının kaydırılabilir olduğundan ve TOC’nun sorunsuz çökebildiğinden emin olun. Chrome DevTools içinde gelen Lighthouse’u çalıştırarak sayfanın performans ve erişilebilirlik puanlarını kontrol edin.

EPUB’a (e‑Kitap) Dönüştürme

EPUB, aslında XHTML, CSS ve meta verilerin bir ZIP arşividir. Pandoc, karmaşıklığı soyutlayarak düzenli bir paket üretir.

Adım 1: EPUB meta verilerini iyileştirin

Pandoc’un --epub-metadata bayrağıyla ID, yayıncı ve dil bilgilerini gömün. Basit bir epub-metadata.xml dosyası oluşturun:

<?xml version="1.0" encoding="UTF-8"?>
<dc:metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:title>Effective Open‑Source Documentation</dc:title>
  <dc:creator>Jane Doe</dc:creator>
  <dc:language>en</dc:language>
  <dc:identifier id="bookid" opf:scheme="ISBN">978-3-16-148410-0</dc:identifier>
  <dc:publisher>Self‑Published</dc:publisher>
</dc:metadata>

Adım 2: EPUB seçenekleriyle Pandoc’u çalıştırın

pandoc main.md \
  --metadata-file=metadata.yaml \
  --epub-metadata=epub-metadata.xml \
  --toc \
  --css=style.css \
  --highlight-style=pygments \
  -o book.epub

İçindekiler tablosu e‑kitabın navigasyon dosyasına dönüşür ve CSS, cihazlar arasında tutarlı bir stil sağlar.

Adım 3: EPUB’u doğrulayın

epubcheck (açık kaynak bir doğrulayıcı) kullanarak kırık bağlantıları, eksik görselleri veya hatalı XHTML’i tespit edin. Çalıştırın:

java -jar epubcheck.jar book.epub

Okuyuculara dağıtmadan veya Kindle Direct Publishing gibi platformlara göndermeden önce raporlanan tüm sorunları giderin.

Varlık Gömme ve Yol Çözümlemesi

Markdown sık sık görselleri ilişkisel yollarla referans verir (![](images/logo.png)). Dönüştürürken özellikle PDF ve EPUB için bu varlıkların gömülmesi gerekir.

  • Pandoc, --resource-path seçeneğiyle varlıkların aranacağı klasörleri belirtmenizi sağlar.
  • --extract-media=./media bayrağı, bağlanan tüm medyayı media klasörüne kopyalar ve işaretlemeyi bu kopyalara yönlendirir.
  • PDF için, LaTeX’i dış dosyaları ekleyebilmesi adına --pdf-engine-opt=--shell-escape seçeneği gerekir.

Tek dosyalık bir çıktı (ör. kendi içinde barındırılan HTML) isterseniz, pandoc --self-contained ya da wget --convert-links gibi bir dış aracıyla post‑işlem yapabilirsiniz.

Farklı Biçimlerde Kod Vurgulamasını Koruma

Geliştirici odaklı belgelerde tutarlı sözdizimi vurgulaması hayati önemdedir.

  • Pandoc, pygments, kate, tango gibi birçok vurgulama stilini destekler. PDF ve HTML’de aynı görünecek bir tanesini seçin.
  • PDF’ta, Pandoc vurgulamayı LaTeX listings ya da mintede çevirir. minted kullanıyorsanız --pdf-engine-opt=-shell-escape ve pygments Python paketine ihtiyaç vardır.
  • EPUB’da vurgulama, satır içi CSS <span class="hlkwd"> etiketleriyle gösterilir; CSS dosyanızda karşılık gelen stil kurallarını bulundurun.

Özel bir renk şeması isterseniz, pygmentize -S <style> -f html -a .code komutuyla bir stil dosyası üretip CSS’nize ekleyin.

İş Akışını Makefile ile Otomatikleştirme

Her format için aynı komut satırı adımlarını tekrarlamak hataya açık olabilir. Basit bir Makefile, tekrar üretilebilirliği garantiler:

SOURCES = main.md metadata.yaml
ASSETS  = $(wildcard images/*)

PDF    = output.pdf
HTML   = output.html
EPUB   = book.epub

all: $(PDF) $(HTML) $(EPUB)

$(PDF): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --template=eisvogel.tex \
	  --toc \
	  --highlight-style=pygments \
	  --pdf-engine=xelatex \
	  -V mainfont="Libre Baskerville" \
	  -V monofont="Fira Code" \
	  -o $@

$(HTML): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --standalone \
	  --toc \
	  --css=style.css \
	  --highlight-style=pygments \
	  -o $@

$(EPUB): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --epub-metadata=epub-metadata.xml \
	  --toc \
	  --css=style.css \
	  --highlight-style=pygments \
	  -o $@

clean:
	rm -f $(PDF) $(HTML) $(EPUB)

Şimdi make komutunu çalıştırmak, aynı komut satırlarını manuel yazmadan üç çıktıyı da üretir ve her biçimin aynı kaynak dosyalardan geldiğini garantiler.

convertise.app Gibi Bir Bulut Hizmeti Ne Zaman Kullanılır?

Bazı durumlarda yerel bir LaTeX kurulumu bulunmayabilir veya geçici bir makinede dosya dönüştürmek gerekebilir. Çevrimiçi bir dönüştürücü, işi hafifletirken hafıza içinde işleyip dosyaları uzun vadeli saklamıyorsa gizliliğe saygı gösterir. Genel bir dönüşüm uç noktasına POST isteği örneği şu şekildedir:

POST https://convertise.app/api/convert
Content-Type: multipart/form-data

---
Content-Disposition: form-data; name="file"; filename="main.md"
Content-Type: text/markdown

<Markdown content>
---
Content-Disposition: form-data; name="target"

pdf
---

Yanıt, dönüştürülmüş PDF’i ikili akış olarak döndürür. Tek seferlik görevler için bu yöntem iyidir, fakat tekrarlanabilir yayın hatları için yerel Pandoc çözümü hâlâ en şeffaf ve denetlenebilir yaklaşımdır.

Biçimler Arası Doğruluk Testi

Dönüştürme sonrası otomatik bir dizi kontrol çalıştırın:

  1. Checksum karşılaştırması – Kaynak Markdown’un SHA‑256 hash’ini üretip çıktı dosyalarının yanına kaydedin. Böylece yapılandırmalar arasında kaynak değişmemiş olur.
  2. Bağlantı doğrulama – pandoc --filter pandoc-citeproc kullanarak tüm dahili referansların çözüldüğünden emin olun.
  3. Görsel rasterizasyon testi – PDF ve EPUB’u ayrı görüntüleyicilerde açıp, görüntülerin istenen DPI’ye (baskı için genellikle 300 dpi, ekran için 72 dpi) kadar aşağı örneklenmediğini teyit edin.
  4. Erişilebilirlik denetimi – PDF için pdfaPilot, HTML için axe-core gibi araçlar eksik alt metinleri ya da hatalı başlık sıralamasını tespit eder.
  5. Yazım denetimi – aspell ya da hunspell ile üretilen HTML ya da PDF’i (PDF’ten pdftotext ile çıkartarak) tarayarak filtrelerden kaynaklanan yazım hatalarını yakalayın.

Bu kontrolleri bir CI hattına (GitHub Actions, GitLab CI) entegre etmek, her commit’in doğrulanmış bir yayın seti üretmesini garantiler.

İş Akışı Özeti

  1. Kaynak Markdown ve varlıkları toplayın. Eksikse front‑matter ekleyin.
  2. Dönüştürme motorunu seçin (Tam kontrol için Pandoc önerilir).
  3. Her hedef biçim için şablonları ve CSS’i yapılandırın.
  4. Dönüştürme komutlarını çalıştırın – PDF LaTeX ile, HTML minimal stil sayfası ile, EPUB meta verilerle.
  5. Çıktıları doğrulayın – checksum, bağlantı bütünlüğü, erişilebilirlik ve görsel inceleme.
  6. Makefile ya da CI ile otomatikleştirin; böylece süreç tekrarlanabilir olur.

Bu tarif, tek bir Markdown kaynağından tutarlı, yayın‑hazır belgeler üretmenizi sağlar; ister bir geliştirici rehberi, akademik el kitabı ya da dağıtım için bir e‑kitap hazırlıyor olun.

Burada anlatılan teknikler, convertise.app gibi gizlilik‑odaklı hizmetlerle uyumludur; yerel araçların bulunmadığı durumlarda isteğe bağlı bir “talep üzerine” dönüşüm uç noktası olarak kullanılabilir.