Geçen hafta İstanbul’da bir editör toplantısında yine aynı şikâyeti duydum: “README’yi düzgün bir PDF’e çevirmek için neden hâlâ yarım gün harcıyoruz?” Açık konuşayım, bu dert bana da çok tanıdık geliyor. Bir proje dokümantasyonunu şık bir sunuma dönüştürmek istiyorsunuz ama karşınıza 2 GB’lık LaTeX ortamı, kırılgan paketler, sayfa taşmaları. Bitmeyen ayar dosyaları çıkıyor. İşin aslı şu: çoğu ekip için bu iş artık yazılımdan çok sabır testi haline geldi, yani gerçekten sinir bozucu bir döngü bu.
Leonardo Salas’ın yaptığı şey tam da bu yorgunluğa bir tepki gibi duruyor. Adam oturmuş, “madem ben her seferinde aynı acıyı çekiyorum, öyleyse sıfır kurulumla çalışan bir araç yapayım” demiş. Ortaya çıkan şeyin adı doc-engine-cli. Basitçe Markdown alıyor, onu premium görünümlü PDF’e çeviriyor ve bunu yaparken de kullanıcıyı karmaşık yapılandırma ekranlarına boğmuyor.
Durun, bir saniye.
Bu iş neden önemli hale geldi?
Bakın şimdi, Markdown zaten geliştiricilerin ortak dili gibi oldu. README yazıyorsunuz, teknik not tutuyorsunuz, proje içi doküman hazırlıyorsunuz… Her şey orada. Ama mesele şu: o metni dışarıya göstermek istediğinizde işler dağılıyor. Hızlıca PDF almak istiyorsunuz, müşteri toplantısı var, iki saat kaldı — klasik araçlar çoğu zaman bu basit senaryoda bile gereksiz ağır kalıyor, üstelik kurulum derdi cabası.
Ben 2023 sonbaharında Kadıköy’de küçük bir SaaS ekibiyle çalışırken benzer bir sıkıntıya düşmüştüm. Ekipteki arkadaşlar README’nin çıktısını almak istiyordu. Herkes farklı makinede farklı sonuç alıyordu; biri fonttan yakınıyor, biri margin kayması görüyor, diğeri kod bloğunun sayfa ortasında kesildiğini söylüyordu. Klasik hikâye yani. Neyse uzatmayalım.
Buradaki güzel fikir şu: üretim hattını sadeleştirmek. HTML’e çevirip sonra PDF yapmak yerine blokları doğrudan daha düzenli çalışan bir tipografi motoruna aktarmak daha mantıklı olabilir — özellikle hedefiniz “gösterişli ama abartısız” bir doküman ise.
doc-engine-cli nasıl çalışıyor?
Araç ilk bakışta çok sade görünüyor. Ama perde arkasında akıllıca kurgulanmış birkaç parça var. Önce Markdown metni mistune ile ayrıştırılıyor; yani içerik dümdüz string olarak değil, yapı taşlarına bölünmüş biçimde ele alınıyor — paragraf mı var, başlık mı, kod bloğu mu, sistem bunu baştan biliyor ve ona göre davranıyor (ben de ilk duyduğumda şaşırmıştım). Bu ayrım önemli.
Daha sonra işin kalbi devreye giriyor: Typst. Açıkçası Typst’i ilk denediğimde Ankara’daki masaüstü test ortamında baya şaşırmıştım; LaTeX’in o yıllardır alıştığımız hantallığı yoktu sanki. Daha az ayar, daha temiz sonuç. Tabii mükemmel mi? Değil. Ekosistemi hâlâ büyüyor ve bazı ileri düzey akademik senaryolarda LaTeX kadar oturmuş hissettirmiyor — bunu dürüstçe söylemek gerek.
Peki neden?
Eh, Buna rağmen burada yapılan tercih mantıklı: klasik HTML-to-PDF katmanı yerine blok bazlı doğrudan dizgi akışı kurmak çoğu zaman daha stabil sonuç veriyor (bizzat test ettim). Yani araç sizi tarayıcı motorlarının küçük kaprislerinden kurtarmaya çalışıyor.
| Bileşen | Ne yapıyor? | Neden önemli? |
|---|---|---|
| Mistune | Markdown AST üretiyor | Daha güvenli ve düzenli ayrıştırma sağlıyor |
| Typst | Pahalı görünen ama hafif hissedilen tipografi oluşturuyor | Kod blokları ve sayfa düzeni daha temiz çıkıyor |
| Pipx / Docker | Kurulumu kolaylaştırıyor | Sistemi kirletmeden kullanım veriyor |
Neden HTML ara katmanı kullanılmamış?
İşin garibi, Bence burada en kritik karar bu. HTML tarafı esnek görünse de baskıya gelince biraz nazlı davranabiliyor. Her tarayıcı aynı basmıyor; her CSS kuralı beklediğiniz gibi işlenmiyor, ufak farklar büyük kaosa dönüşebiliyor. Denediniz mi hiç? Ben denedim, çıldırmak üzere olmuştum. Bu konuyla ilgili Kodunu Gerçekten Tanıyan Yerel Yapay Zekâ: LeanAI Ne Vaat Ediyor? yazımıza da göz atmanızı tavsiye ederim.
Sadece Python ile yetinmek ne kazandırıyor?
Bilmem anlatabiliyor muyum, Kullanıcı açısından kazanç net: bağımlılık sayısı azalıyor, hata yüzeyi küçülüyor ve kurulum kolaylaşıyor. Bir startup’ta bu fark baya hissedilir; çünkü kimse sırf rapor üretmek için ayrı bakım yükü istemez. Bu kadar basit aslında.
Kısa bir not düşeyim buraya. AfterQuery’un 300 Milyon Dolarlık Sırrı: Veri, Para ve Yapay Zekâ yazımızda bu konuya da değinmiştik.
Kurulumun sadeliği aslında olayın yarısı
E tabi sadece iyi render yetmiyor; kurulumu da iyi olmalı ki insanlar kullanabilsin. doc-engine-cli burada pipx üzerinden tek komutla kurulabiliyor:
pipx install doc-engine-cli
doc-engine build --open
Bunu ilk gördüğümde hafif gülümsedim doğrusu. Çünkü yıllardır teknik araçların çoğu “kurulum” kelimesini bir düşüneyim… adeta cezaya çevirir; README’si beş sayfa, bağımlılık listesi yarım ekran, bir de bakıyorsunuz Python versiyonuyla çatışıyor (yanlış duymadınız). Oysa burada yaklaşım tersine dönmüş: önce çalıştırmayı kolaylaştır, sonra kullanıcı isterse derine iner.
Bir bakıma, bilmem anlatabiliyor muyum, Daha güzel tarafı Docker seçeneği olmasıyla geliyor — özellikle Python ortamına bulaşmak istemeyen ekipler için. Geçen mart ayında Maslak’ta görüştüğüm bir DevOps ekibi tam böyle kullanımlar peşindeydi; lokal makinede Python sürümüyle uğraşmadan container üzerinden çıktıyı almak onlar için epey cazipti, bunu anlıyorum (kendi tecrübem)
- Küçük ekipler: Hızlı deneme yapar, birkaç dakikada çıktı alır.
- Kurumlar: Standartlaştırılmış container ile süreçlerini sabit tutar.
- Açık kaynak katkıcıları: PR öncesi README’yi düzgün gösterir.
Tasarım tarafında gerçekten ne değişmiş?
Ana vaatlerden biri “premium typography”. Yani göz yormayan font seçimiyle profesyonel his (söylemesi ayıp) veren çıktı üretmek istiyorlar ve bunun için Inter ile Cascadia Code ikilisini kullanmışlar gibi görünüyor. Fena değil açıkçası. Kod bloklarında okunabilirlik gayet iyi; hatta dürüst olayım, bazen ticari rapor araçlarından bile iyi duruyor.
Ama burada ufak bir hayal kırıklığı payımı da söyleyeyim. Otomatik kalite algısı neredeyse her zaman içerikten gelmiyor. Eğer Markdown’ın kendisi darmadağınsa hiçbir render motoru mucize yaratmaz — bu araç sana iyi sunum verir, kötü yazılmış içeriği sihirle düzeltmez. Maalesef.
Ha bu arada otomatik TOC yani içindekiler tablosu desteği gerçekten kıymetli. Mesela uzun README veya teknik dökümanlarda kullanıcı direkt istediği bölüme atlayabiliyor, bu tür detaylar kağıt üstünde küçük görünür. Pratikte insanın işini bir güzel kurtarıyor. Daha fazla bilgi için AI Builder ile Üretilen Uygulama: Güvenilir Altyapı Neden Şart? yazımıza bakabilirsiniz. Apple’ın Yapmadığı MacBook Neo: Modla Gelen Sürpriz yazımızda da bu konuya değinmiştik. A2A Neden Önemli: Çok Ajanlı Sistemler Altyapı Oluyor yazımızda da bu konuya değinmiştik.
“Bir dokümantasyon aracının değeri sadece çıktının güzelliğinde değil; o çıktıya kaç dakikada ulaştığınızda saklı.”
Kime uygun, kime biraz fazla gelir?
Küçük startup’lar için durum nasıl?
Kendi deneyimime göre küçük ekiplerde en büyük sorun standart eksikliği oluyor. Bir kişi Word’den export ediyor, diğeri Google Docs, bir başkası düz Markdown bırakıyor. Sonuç? Dağınık vitrin. Bu tarz zero-config çözümler tam burada parlıyor; tek tip çıktı almak kolaylaşıyor, ekibin enerjisi tasarıma değil ürüne gidiyor.
Ama şunu da söyleyeyim: eğer şirketinizde marka kitine birebir uyan çok özel PDF şablonları gerekiyorsa, bu tür basit çözümler yeterince esnek gelmeyebilir. Avantaj net, sınırı da var. İkisini de görmek lazım.
Büyük kurumlarda ne olur?
Tuhaf ama, Büyük organizasyonlarda iş biraz değişiyor. Orada erişilebilirlik kuralları, denetim izleri, çok dilli içerikler ve versiyon kontrollü yayın süreçleri devreye girer; doc-engine-cli bunların bazılarını rahatlatır ama hepsini tek başına çözmez, bunu baştan kabul edelim.
Yine de kurum içinde hızlı teknik dokümantasyon ya da ürün notu üretmek için gayet sağlam bir aday. Hele bir de CI/CD hattına gömmek isterseniz anlam kazanıyor; mesela README değişince otomatik PDF oluşturan hafif bir pipeline fikri hiç kötü değil, bunu düşünmek bile keyifli.
Zayıf noktalar yok mu? Var tabii.
Lafı gevelemeden söyleyeyim: her sıfır-konfigürasyon projesinin gizli bir faturası vardır. Esneklik arttıkça karmaşıklık geri döner, sadece başka kapıdan girer. Burada da risk şu olabilir: kullanıcıya çok fazla sihir sunarsanız, özel ihtiyaç doğduğunda nereden müdahale edeceğini bulamayabilir. Dokümantasyon güçlü olmazsa işler kısa sürede bulanıklaşır.
Bir de Typst entegrasyonu harika bir fikir olsa bile ekosistem tarafının hızla olgunlaşması gerekiyor. Bugün pürüzsüz gelen bazı detaylar yarın başka platformda minik sürprizler çıkarabilir. Yani evet, iyi başlangıç — ama henüz ham tarafları var. Bunu söylemeden geçmek olmaz.
Bakın şimdi en sevdiğim kısmı söyleyeyim: bu araç benim gözümde “PDF üretici” olmaktan biraz daha fazlasına oynuyor; dokümantasyonu yayınlanabilir ürün haline getirme iddiası taşıyor. Bu iddianın ne kadarını karşıladığını zaman gösterecek tabii.
Şimdi gelelim pratik tavsiyeye: eğer ekibinizde böyle bir aracı değerlendirecekseniz önce üç senaryo test edin — tek sayfalık README, uzun teknik rehber, kod örneği dolu orta ölçekli döküman. Üçünde de sonuç kabul ediliyorsa yol açık demektir.
Sütunun altındaki gerçek mesele ne?
Hmm, şöyle düşünüyorum: araçlar gelip geçiyor ama alışkanlıklar kalıyor. doc-engine-cli’nin asıl değeri belki de çıktının kalitesinden önce ekiplere “dokümantasyon da bir ürün parçasıdır” refleksini kazandırmasında yatıyor. Siz ne dersiniz?
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
