Statik Site Oluşturucular için Dokümantasyon Hazırlama: Tutarlı ve Aranabilir İçerik için Dosya Dönüştürme Stratejileri

Statik site oluşturucular (SSG’ler), modern dokümantasyon portalları, geliştirici blogları ve ürün bilgi tabanlarının belkemiği haline geldi. Hafif teslimat, sürüm‑kontrollü içerik ve CI boru hatlarıyla sorunsuz entegrasyon sunarlar. Ancak SSG’ler, içerikten çok belirli biçimler bekler – çoğu zaman Markdown, reStructuredText ya da düz HTML – ve gezinme, tema ve arama indekslerini yönlendirmek için front‑matter meta verilerine dayanırlar. Bir organizasyon, Word dosyaları, PDF’ler, PowerPoint sunumları ve eski yardım‑yazım formatlarından oluşan karışık bir koleksiyon devraldığında, dönüştürme adımı tutarlılık, erişilebilirlik ve arama kalitesini tehdit eden bir darboğaz haline gelebilir.

Bu makale, heterojen kaynak belgelerini temiz, SSG‑hazır bir depoya dönüştürmek için pratik bir iş akışı gösterir. Anlamsal yapıyı korumaya, aranabilir metni tutmaya, önemli meta verileri saklamaya ve PDF’lerin planlama olmadan Markdown’a dönüştürülürken sıkça kaybolan ince kalite kaybından kaçınmaya odaklanır. Teknikler geniş ölçekte uygulanabilir, ancak örnekler convertise.app adlı, gizliliğe saygı gösteren ve yüksek doğruluklu sonuçlar üreten bulut‑tabanlı dönüşüm hizmetinin iş akışı yeteneklerine referans verir.

SSG‑Güçlü Dokümanlarda Dönüştürme Adımının Önemi

Bir SSG, kaynak dosyalardan statik HTML sitesini derleme zamanında oluşturur. Üreteç, ikili biçimleri yorumlamaz; yalnızca ham metni okur ve şablonlarla zenginleştirir. PDF’yi doğrudan boru hattına verirseniz, üreteç bunu opak bir varlık olarak görür ve içindeki içerik arama motorları ve site içi arama için görünmez olur. Sonuç olarak kullanıcılar tam‑metin arama ile bilgi bulamaz ve dokümantasyon, iyi yapılandırılmış HTML ile gelen erişilebilirlik faydalarını (ör. ekran okuyucu gezinmesi) kaybeder.

Arama dışındaki dönüşüm etkileri şunlardır:

• Gezinme hiyerarşisi – Kaynaktaki başlıklar sitenin içindekiler tablosunu oluşturur. Başlık seviyelerini düzleştiren bir dönüşüm, kullanıcıların beklediği mantıksal akışı bozar.
• Kod snippet’leri – Teknik dokümanların çoğu, sözdizimi vurgulamasını koruması gereken kod blokları içerir. PDF kırpma işlemi, monospaced (tek aralıklı) yazı tiplerini normal metne dönüştürerek işaretlemeyi bozar.
• Çapraz‑referanslar – Şekiller, tablolar ve dipnotlar genellikle ID ile referanslanır. Bu ID’lerin kaybolması, site genelinde kırık bağlantılara yol açar.
• Meta veri – Yayın tarihi, yazar, sürüm ve etiketler front‑matter’dan okunur. Dönüşüm bu bilgileri atıyorsa, sınıflandırma, filtreleme ve sürüm‑kontrol ipuçlarını kaybedersiniz.

Bu yönlerin her birine değinen disiplinli bir dönüşüm süreci, sonraki yeniden inşa aşamalarının bir “yangın söndürme” egzersizine dönüşmesini engeller.

Kaynak Biçimlerini SSG‑Hazır Hedeflere Haritalama

İlk adım, desteklemeniz gereken kaynak biçimleri envanterlemenizdir. Aşağıda yaygın bir envanter ve her biri için tercih edilen SSG hedefi yer alıyor:

Kısaca: yapıyı koruyan en basit metinsel temsile dönüştürün – çoğu belge için Markdown, ince‑ayar stil gerekliyse HTML ve görsel‑yoğun kaynaklar için az sayıda görsel varlık.

Dönüştürme Boru Hattını Hazırlama

Sağlam bir boru hattı üç aşamadan oluşur: çıkarma, temizleme ve zenginleştirme.

1. Çıkarma – Kaynak dosyadan ham metin, görseller, tablolar ve meta verileri çekin. Yerel formatı okuyan araçlar (örn. LibreOffice headless, Microsoft Office Open XML ayrıştırıcıları) en temiz çıktıyı üretir. PDF’ler için metin nesneleri ile taranmış görselleri ayırabilen bir kütüphane kullanın; convertise.app, düzeni koruyan ve temiz bir Markdown dosyasıyla birlikte çıkarılan varlıkları sunan bir PDF‑to‑Markdown uç noktası sağlar.
2. Temizleme – Ham çıktıyı düzeltin. Şunları içerir:
   • Başlık seviyelerini normalleştirme (ör. belgenin # ile başlamasını ve doğru şekilde dallanmasını sağlama).
   • Özel karakterleri UTF‑8’e yeniden kodlama.
   • <table> parçacıklarını Markdown boru sözdizimine dönüştürme, sütun hizalamasını koruma.
   • Front‑matter ayrıştırıcılarını bozabilecek görünmez ya da yinelenen boşlukları temizleme.
3. Zenginleştirme – SSG‑özel verileri ekleyin:
   • title, date, author, tags ve version gibi alanları içeren front‑matter bloğu (--- YAML).
   • Üreteç destekliyorsa bir içindekiler yer tutucu ({{ toc }}) otomatik oluşturma.
   • Görsel optimizasyonu – büyük ekran görüntülerini web‑dostu bir genişliğe (ör. 1200 px) küçültme ve paket boyutunu azaltmak için WebP’ye çevirme.

Her aşama seçtiğiniz dilde (Python, Node.js, Bash) betiklenebilir. Önemli olan işlemlerin deterministik olmasıdır; aynı kaynak her zaman aynı çıktıyı üretmeli – CI yapıların güvenilirliği için şarttır.

Dönüştürme Sırasında Anlamsal Yapıyı Korumak

Sıkça yapılan bir hata, dönüşümü sadece bir düz metin dumplama olarak görmektir. Bu yaklaşım şu anlamsal ipuçlarını yok eder:

• Listeler – Sıralı ve sırasız listeler basit paragraf sonlarına dönüşür, hiyerarşi kaybolur.
• Kod blokları – Satır içi kod normal metine dönüşür, çitli bloklar sözdizimi vurgulaması için gereken dil tanımlayıcısını yitirir.
• Dipnot ve sonnot – Çoğunlukla paragraf gövdesine karıştırılır, referans gezinmesi bozulur.

Bu tuzaklardan kaçınmak için dönüşüm motorunu her yapıyı açıkça eşleyecek şekilde yapılandırın. Örneğin, convertise.app kullanarak bir Word belgesini dönüştürürken preserveLists ve preserveCodeBlocks seçeneklerini (API üzerinden erişilebilir) etkinleştirin. Ortaya çıkan Markdown, listeler için - ya da 1. öneklerini ve dil etiketli üç back‑tick çitlerini içerecektir.

Aşağıda dönüştürme betiğinize ekleyebileceğiniz kısa bir eşleme tablosu bulabilirsiniz:

• Başlıklar → # … (Seviye 1) → ## … (Seviye 2) → …
• Kalın → **metin**
• Italik → *metin*
• Tablolar → Markdown boru sözdizimi | Başlık | …
• Görseller → ![alt text](yol/görsel.ext)
• Bağlantılar → [bağlantı metni](url)
• Kod →

   language\nkod\n

• Dipnotlar → [^1]: dipnot metni

Bu unsurları koruduğunuzda, SSG’nin yerleşik eklentileri (örn. jekyll-toc, hugo-pagetoc) doğru gezinme menüleri üretir ve site arama indeksi öğeleri düzgün şekilde işler.

Görseller ve Medya Varlıklarını Ele Alma

Çoğu dokümantasyon ekran görüntüleri, diyagramlar ve ara sıra kısa videolar içerir. Dönüştürme boru hattı bu varlıkları birinci sınıf vatandaş olarak ele almalıdır:

• Çıkarma – Kaynak dosyadan gömülü her görseli çekin. Word ve PowerPoint’te görsel ayrı bir ikili parça olarak saklanır; çıkarmak basittir. PDF’lerde ise görseller raster nesneleridir; kayıpsız bir ayar (PNG veya TIFF) ile dışa aktarılabilir.
• Tutarlı yeniden adlandırma – dokumanadi-figür01.png gibi deterministik bir adlandırma şeması kullanın. Aynı görsel birden çok belgede göründüğünde çakışma önlenir.
• Optimizasyon – Görselleri kayıpsız sıkıştırıcı (örn. pngquant --quality=100) ile işleyin, ardından WebP’ye dönüştürün. Eski tarayıcıları kapsamak için hem WebP hem de geri dönüş PNG saklayın.
• Referans – Son görsel yolunu Markdown’a ekleyin; SSG bunu çıktı varlık klasörüne kopyalar.

Arşivleme amacıyla orijinal çözünürlüğü tutmak isterseniz, bunu raw/ gibi ayrı bir dizinde saklayın; bu dizin herkese açık siteden hariç tutulur ancak gelecekte yeniden dışa aktarma için depoda kalır.

Meta Veri Transferi: Kaynaktan Front‑Matter’a

Meta veri, dokümantasyonu yaşam döngüsüyle bağlayan yapıştırıcıdır. Çoğu yazar araç, aşağıdaki özellikleri gömülü olarak bulundurur:

• Başlık
• Yazar(lar)
• Oluşturma ve son‑değiştirme tarihleri
• Sürüm numarası
• Anahtar kelimeler / etiketler

Çıkarma sırasında dosyanın paketinden bu özellikleri sorgulayın. Office Open XML biçimlerinde core.xml bölümü Dublin Core meta verilerini tutar. PDF’lerde XMP paketi benzer alanları içerir. Elde ettiklerinizi, Markdown dosyasının en üstüne bir YAML front‑matter bloğu olarak ekleyin:

---
title: "Apache için TLS Nasıl Yapılandırılır"
author: "Jane Doe"
date: 2024-06-12
lastmod: 2025-01-03
tags: [security, apache, tls]
version: "1.3"
---

Bir kaynak dosya bir alanı içermiyorsa, akıllı bir varsayıla geri dönün (ör. başlık için dosya adı, date için geçerli tarih). Depodaki tutarlı meta veri, SSG’nin etiket sayfaları, değişiklik günlükleri ve RSS akışları otomatik oluşturmasını sağlar.

CI/CD ile İş Akışını Otomatikleştirme

Dönüştürme betiği kararlı hâle geldiğinde, bunu bir CI boru hattına (GitHub Actions, GitLab CI, Azure Pipelines) gömün. Tipik bir iş şu adımları izler:

1. Checkout – Dokümantasyon reposunu alın.
2. Detect – git diff ile yeni eklenen ya da değiştirilmiş kaynak dosyaları tespit edin.
3. Run – Değişen dosyalar üzerinde convertise.app API’sini çağıran bir Docker konteyneri (dönüştürme konteyneri) çalıştırın.
4. Commit – Oluşan Markdown ve varlıkları docs/ dalına geri commit edin.
5. Trigger – SSG derlemesini (örn. hugo --minify) başlatın.
6. Deploy – Statik siteyi bir CDN’ye dağıtın.

Dönüştürme adımı deterministik ve izole bir konteyner içinde çalıştığı için yeniden üretilebilir derlemeler elde edersiniz. Örneğin OCR‑lanamayan bir PDF hatası, CI hatası olarak ortaya çıkar ve erken müdahaleyi teşvik eder.

Kalite Güvencesi: Dönüştürme Doğruluğunu Doğrulama

Otomasyon, doğrulama olmadan sadece bir hayaldir. İki kat QA uygulayın:

• Otomatik diff – Dönüştürmeden sonra, çıkarılan metni orijinaliyle checksum ya da boşlukları yoksayan bir diff aracıyla karşılaştırın. İçerik kaybı %5’ten fazla ise uyarı oluşturun.
• Görsel regresyon – Görsel‑ağır sayfalar için, render edilmiş HTML’nin ekran görüntüsünü alıp pixelmatch gibi bir araçla bir temel sürümle karşılaştırın. Bozuk tablolar ya da eksik CSS kaynaklı yerleşim kaymaları tespit edilir.

Pipeline bir regresyon tespit ettiğinde dağıtımı durdurmalı ve farkı pull‑request yorumları içinde göstermelidir. Bu uygulama, yayımlanan dokümantasyonun sessizce kaymasını engeller.

Vaka Çalışması: Legacy Bilgi Tabanını Hugo’ya Taşıma

Orta ölçekli bir SaaS satıcısı, yardım merkezini Word belgeleri, PowerPoint sunumları ve arşivlenmiş PDF’lerin karışımında tutuyordu. İçerik paylaşılan bir sürücüde saklanıyor, destek ekibi dosyaları manuel olarak bir web portalına kopyalıyordu. Şirket, hızı ve sürüm‑kontrol dostu yapısı nedeniyle Hugo’ya geçmeye karar verdi.

Uygulanan adımlar:

1. Envanter – Bir betik sürücüyü tarayarak dosyaları uzantıya göre sınıflandırdı.
2. Toplu dönüştürme – convertise.app kullanılarak, ekip bir toplu iş yürüttü; Markdown dosyaları ve çıkarılan varlıklar content/ dizinine yazıldı.
3. Meta veri eşlemesi – Özel bir Python betiği, Word’un core.xml özelliklerini okuyarak her Markdown dosyasına front‑matter ekledi.
4. Görsel boru hattı – Tüm ekran görüntüleri WebP’ye dönüştürüldü, Markdown linkleri static/images/ klasörüne işaret edecek şekilde yeniden yazıldı.
5. CI entegrasyonu – GitHub Actions, her PR’da dönüşümü çalıştırdı; böylece yeni bir destek makalesi aynı süreci izledi.

Sonuçlar:

• Metin artık aranabilir olduğu için arama indeksi %40 küçüldü.
• Görseller WebP’ye geçirildiği için sayfa yükleme süresi %30 iyileşti.
• Destek ekibi, belgeleri doğrudan depoda düzenleyebildi; bu da geri dönüşler ve denetim izleri sağladı.

Bu örnek, disiplinli bir dönüşüm stratejisinin dağınık bir belge kütüphanesini hızlı, aranabilir ve sürdürülebilir bir statik siteye nasıl dönüştürebileceğini gösterir.

SSG‑Hazır Dokümantasyon Dönüştürmesi İçin En İyi Uygulama Kontrol Listesi

• Kaynak biçimlerini belirleyin ve tek bir metinsel hedefe (Markdown/HTML) karar verin.
• Metin, görseller ve meta verileri mümkün olduğunca format‑yerel ayrıştırıcılarla çıkarın.
• Anlamsal öğeleri (başlıklar, listeler, kod blokları, dipnotlar) çıkarma sırasında koruyun.
• Satır sonlarını ve kodlamayı UTF‑8’e normalleştirin.
• Varlıklar ve Markdown dosyaları için deterministik dosya adları üretin.
• Front‑matter oluşturun; içinde başlık, yazar, tarih, etiket ve sürüm olsun.
• Görselleri optimize edin (kayıpsız sıkıştırma, WebP dönüşümü) ve orijinalleri ayrı tutun.
• Dönüştürme betiğini konteynerleştirilmiş bir CI işine entegre edin.
• Çıktıyı otomatik diff ve görsel regresyon kontrolleriyle doğrulayın.
• Boru hattını belgeleyin; yeni katkıda bulunanlar çalışmayı bozmayacak şekilde genişletebilsin.

Sonuç

Legacy ve heterojen dokümantasyonu, statik site oluşturucuların tüketebileceği bir formata dönüştürmek sadece bir dosya‑tipi değişimi değildir; yapı, meta veri ve aranabilirliği koruyan disiplinli bir dönüşümdür. Format‑bilinçli araçlarla içeriği çıkarıp, çıktıyı temizleyip, SSG‑özel front‑matter ile zenginleştirip ve tüm süreci yeniden üretilebilir bir CI boru hattına yerleştirerek, ekipler bilgi tabanlarını taze, hızlı ve aranabilir tutabilir.

Yukarıda özetlenen yaklaşım, convertise.app gibi yüksek‑kalite, gizlilik‑öncelikli dönüşüm hizmetlerinden yararlanır; böylece orijinal dosyalar güvenli bir ortamdan çıkmazken modern dokümantasyon iş akışları için gerekli temiz Markdown veya HTML elde edilir.