README'den PDF'e Dönüştürücü

Bir README.md dosyası; bir projeyi, depoyu, paketi, uygulamayı, veri kümesini veya iş akışını açıklayan bir Markdown belgesidir.

README dosyaları genellikle şunları içerir:

• bir proje başlığı ve özeti;
• kurulum talimatları;
• kullanım örnekleri;
• komut satırı kod parçacıkları;
• yapılandırma örnekleri;
• özellik listeleri;
• görev listeleri;
• tablolar;
• ekran görüntüleri;
• rozetler (badges);
• katkıda bulunma talimatları;
• lisans veya destek bilgileri;
• belgelere ve sürümlere bağlantılar.

.md uzantısı, dosyanın Markdown biçiminde yazıldığını gösterir. Bunu PDF'e dönüştürmek, Markdown kaynağını düzenlenebilir sürüm olarak korurken sabit bir belge oluşturur.

Bir PDF, README'nin orijinal deposundan çıkması gerektiğinde veya sayfa tabanlı bir belge olarak incelenmek istendiğinde kullanışlıdır.

Yaygın nedenler şunlardır:

• proje dokümantasyonunu bir müşteri veya paydaşla paylaşmak;
• bir e-postaya veya talebe teknik bir genel bakış eklemek;
• dokümantasyonu inceleme veya onay için sunmak;
• belirli bir zaman diliminde deponun çevrimdışı bir anlık görüntüsünü (snapshot) oluşturmak;
• kurulum talimatlarını veya operasyonel el kitabını (runbook) yazdırmak;
• sürüm dokümantasyonunu arşivlemek;
• GitHub kullanmayan okuyuculara bir README dağıtmak;
• uzun kodları, denklemleri, diyagramları ve tabloları sabit bir düzende incelemek.

Orijinal README, bakımı yapılabilir kaynak olarak kalmalıdır. README değiştikten sonra PDF'i yeniden oluşturun.

SolConverter, README dosyalarında yaygın olarak kullanılan Markdown öğelerini destekler.

Bunlar şunları içerir:

• ATX ve Setext başlıkları;
• kalın, italik ve üstü çizili metinler;
• sıralı ve sırasız listeler;
• içe içe listeler;
• GFM görev listeleri;
• blok alıntılar;
• Markdown bağlantıları ve otomatik bağlantılar;
• satır içi kod;
• backtick veya tilde kullanan çevrelenmiş kod blokları;
• kod bloğu dil etiketleri;
• hizalamalı GFM tabloları;
• güvenli ham HTML tabloları;
• details ve summary bölümleri;
• kbd, sub, sup, figure ve figcaption;
• başlık bağlantıları (anchors);
• kaynağın başlangıcındaki YAML front matter deki bloğu.

Dolar işaretleri veya LaTeX benzeri sınırlayıcılar içeren kod çevrelemeleri, denklem olarak yorumlanmak yerine kod olarak kalır.

README dosyaları genellikle kurulum komutları, yapılandırma dosyaları, API örnekleri, ortam değişkenleri ve kaynak kod parçacıkları içerir.

SolConverter, kod bloğu dili tanındığında Highlight.js ile sözdizimi vurgulaması uygular. Tanınmayan diller orijinal kaynağı güvenli bir şekilde korur.

Kod blokları, onları çevreleyen açıklamalardan ayıran özel bir tek aralıklı yazı tipi ve baskı stili kullanır. Sağdan sola yazılan bir README dosyasında bile kod soldan sağa kalır.

Teknik bir README; formüller, matrisler, bilimsel gösterimler, olasılık ifadeleri veya kimya içerebilir.

SolConverter, yaygın Markdown matematik sınırlayıcıları, AMS denklem ortamları, Presentation MathML, temel Content MathML ve \ce{...} ile yazılmış kimya ifadeleri için MathJax SVG çıktısını destekler.

Desteklenen matematik şunları içerir:

• $...$ ve \(...\) satır içi ifadeleri;
• $$...$$ ve \[...\] blok ifadeleri;
• denklem ve hizalama ortamları;
• kesirler, kökler, toplamlar, integraller, limitler ve matrisler;
• belge kapsamındaki makrolar;
• satır bölünmesi gerektiren uzun toplamsal ifadeler.

Matematik, PDF'te keskin kalması için SVG olarak işlenir. Geçersiz matematik, README'nin geri kalanını otomatik olarak durdurmadan yerel düzeyde bir yedeğe düşebilir.

README dosyaları sıklıkla mimariyi, sırayı (sequence), durumu, iş akışını veya bileşen ilişkilerini açıklamak için diyagramlar kullanır.

Desteklenen Mermaid kod blokları yerel olarak SVG olarak işlenir. ZenUML, paketlenmiş bir Mermaid entegrasyonu aracılığıyla desteklenir. Diyagramlar kullanılabilir sayfa genişliğiyle sınırlandırılır ve bağımsız olarak işlenir.

Bir diyagram geçersiz olursa, dönüştürücü kaynak kodu içeren bir yedek ekler ve kalan bölümleri işlemeye devam eder.

PlantUML, Graphviz, D2, WaveDrom, BPMN, Nomnoml ve tam TikZ şu anda desteklenmemektedir ve bu sayfada reklamı yapılmamalıdır.

Dönüştürücü, genel HTTP ve HTTPS görüntülerinin yanı sıra PNG, GIF, JPEG, WebP and SVG biçimlerindeki geçerli base64 veri görüntülerini destekler.

Görüntüler sayfaya sığacak şekilde ölçeklenir ve en boy oranları korunur. Şekiller, altyazılar, alt metinler, başlıklar, güvenli boyutlar ve hizalama korunabilir.

Bununla birlikte, birçok depo README'si aşağıdaki gibi göreceli yollar kullanır:

./images/screenshot.png
docs/architecture.svg
../assets/demo.gif

Mevcut yükleme iş akışı, depo klasörünü paketlemez veya bu göreceli varlıkları otomatik olarak çözümlemez. PDF'i oluşturmadan önce bunları genel görüntü URL'lerine veya desteklenen base64 veri görüntülerine dönüştürün.

Rozetler genellikle genel görüntü URL'lerini kullanır ve görüntü sunucusuna genel olarak erişilebildiğinde işlenebilir. Bir rozet veya görüntü yüklenemezse, SolConverter yerel bir yer tutucu ekler ve dönüştürmeye devam eder.

Bir README içindeki Markdown bağlantıları mutlak, depoya göreceli veya sayfa içi bağlantılar olabilir.

Mutlak HTTP ve HTTPS bağlantıları deponun dışında da anlamlı kalır. ./docs/setup.md veya ../CONTRIBUTING.md gibi göreceli bağlantılar, README bağımsız bir PDF haline geldikten sonra yararlı bir hedefe işaret etmeyebilir.

PDF'i paylaşmadan önce:

• önemli göreceli bağlantıları genel mutlak URL'lerle değiştirin;
• yalnızca bağlantılı dosyalara güvenmek yerine kritik talimatları doğrudan yazın;
• işlemeden sonra başlık bağlantılarını doğrulayın;
• belgenin depo navigasyonu olmadan da mantıklı olup olmadığını kontrol edin;
• PDF bir arşiv olarak amaçlandığında sürüm veya yayın bilgilerini ekleyin.

Bir GitHub README dosyası yine de bir Markdown dosyasıdır, ancak GitHub, yüklenen dosyanın kendisinde bulunmayan depo bağlamını ekleyebilir.

PDF; tablolar, görev listeleri, çevrelenmiş kodlar, otomatik bağlantılar ve başlıklar gibi desteklenen GFM yapılarını koruyebilir. Ayrıca desteklenen MathJax ifadelerini ve Mermaid diyagramlarını da işleyebilir.

Dönüştürücü her GitHub arayüz öğesini yeniden üretmez. Depo sekmeleri, sorun sayıları, sürüm bileşenleri, dal seçiciler, dinamik olarak oluşturulan kartlar ve diğer GitHub sayfa çerçeveleri Markdown kaynağının bir parçası değildir.

En temiz bağımsız PDF için README'nin proje kimliğini, sürüm bağlamını ve önemli bağlantıları belgenin kendisinde barındırdığından emin olun.

Bir README PDF'i, okuyucunun aşağıdakilere ihtiyaç duyduğu durumlarda kısa bir teknik teslim belgesi olarak işe yarayabilir:

• bir projeye genel bakış;
• kurulum ve yapılandırma adımları;
• örnek komutlar;
• yapılandırma gereksinimleri;
• mimari diyagramları;
• API örnekleri;
• operasyonel notlar;
• sorun giderme talimatları;
• katkı sağlama veya destek ayrıntıları.

Büyük dokümantasyon setleri için, her kılavuzu tek bir dosyaya sığdırmaya çalışmak yerine README'yi giriş belgesi olarak ele alın. Çok uzun bir README'den oluşturulan bir PDF hala yararlı olabilir, ancak ayrı belgelerin bakımı ve navigasyonu daha kolay olabilir.

Depolar zamanla değişir. README'yi PDF'e dönüştürmek, bir sürüm, teslimat, inceleme veya dönüm noktası ile ilişkili okunabilir bir anlık görüntü oluşturur.

Arşivlemeden önce:

1. proje veya paket sürümünü ekleyin;
2. ilgili tarihi veya sürüm tanımlayıcısını ekleyin;
3. komutları ve yapılandırma örneklerini doğrulayın;
4. geçici bağlantıları değiştirin;
5. görüntüleri, diyagramları ve denklemleri gözden geçirin;
6. nihai PDF'i oluşturun ve inceleyin;
7. PDF'i sürüm kaydının yanında saklayın.

Oluşturulan bir PDF, sürüm kontrollü README'nin yerine geçen bir belge değil, bir anlık görüntüdür.

README dosyaları ham HTML, harici görüntü URL'leri ve hatalı biçimlendirilmiş bloklar içerebilir.

SolConverter, işlenen HTML'yi temizler, betikleri ve olay işleyicilerini kaldırır, güvenli olmayan URL'leri reddeder, ham HTML'yi bir izin verilenler listesiyle sınırlandırır, tablo birleştirmelerini kısıtlar, kısıtlayıcı bir içerik güvenlik politikası uygular ve izin verilen görüntü politikasının dışındaki tarayıcı isteklerini engeller.

Yerel dosyalar, localhost hedefleri, özel IP değerleri, javascript: URL'leri ve desteklenmeyen kaynak şemaları engellenir. Geçersiz görüntüler, denklemler ve diyagramlar, kalan README'nin işlenmeye devam edebilmesi için mümkün olduğunca yerel düzeyde ele alınır.

SolConverter, README dosyalarına tutarlı bir belge düzeni uygular.

Mevcut web formu şunları kullanır:

• A4 sayfa boyutu;
• dikey yönlendirme;
• okunabilir çıktı için yönetilen kenar boşlukları;
• mevcut / toplam sayfa numaralandırması;
• README dosya adına dayalı bir çıktı başlığı;
• yazdırılan arka planlar.

Dikey düzen genel okuma için tasarlanmıştır. Geniş tabloları ve kodları indirmeden önce her zaman önizleyin.

Kaynak bir proje README'si olduğunda ve kod çevrelemeleri, GFM yapıları, rozetler, depoya göreceli görüntüler ve depo bağlantıları hakkında rehberliğe ihtiyaç duyduğunuzda bu README odaklı sayfayı kullanın.

Raporlar, matematiksel belgeler, teknik notlar, teklifler, çok dilli belgeler ve genel .md dosyaları için ana Markdown'dan PDF'e dönüştürücüyü kullanın.

Her iki sayfa da aynı temel dönüştürme yeteneğini kullanır, ancak farklı kullanıcı görevlerine hizmet eder ve farklı hazırlık yönergeleri sunar.

• Herhangi bir Markdown dosyasını PDF'e dönüştürün
• PDF'i Markdown'a dönüştürün
• HTML'i Markdown'a dönüştürün
• Word'ü Markdown'a dönüştürün
• Tüm dosyadan-Markdown'a araçlarına göz atın