mdBook - Markdown ile kitap oluşturmak için bir komut satırı aracı

 (rust-lang.github.io)
4 puan yazan GN⁺ 2023-07-01 | 1 yorum | WhatsApp'ta paylaş
  • Belgeleri ve eğitimleri kitap biçiminde dağıtmanız gerektiğinde, mdBook 0.5.3 Markdown tabanlı yazımı ve gezilebilir çıktıları birlikte sunar
  • Hafif Markdown sözdizimi ve entegre arama sayesinde yazarlar biçimden çok içeriğe odaklanabilir
  • Kod blokları için sözdizimi vurgulama ve tema dosyaları, teknik belgelerde gereken okunabilirliği ve çıktı biçimi ayarlarını sağlar
  • Ön işleyiciler ve arka uçlar, özel sözdizimi, içerik düzenleme ve birden çok çıktı biçiminde render alma için genişletme noktaları sunar
  • Rust projelerinde ve The Rust Programming Language kitabında kullanılan bir araç olduğu için Rust belge ekosistemiyle güçlü bir bağlantıya sahiptir

Markdown kitap üretimi için gerekli temel özellikler

  • mdBook, Markdown ile kitap oluşturmak için bir komut satırı aracıdır
  • Ürün belgeleri, API dokümantasyonu, eğitimler ve ders materyalleri gibi temiz ve kolay gezilebilir içerikler üretmek için uygundur
  • Yazma ve okuma deneyimini destekleyen özellikleri birlikte sunar
    • Hafif Markdown sözdizimi sayesinde içerik yazımına odaklanılabilir
    • Kitap içinde entegre arama desteği
    • Birden fazla dilde kod bloklarına renkli sözdizimi vurgulama uygulanabilir
    • Tema dosyalarıyla çıktı biçimi özelleştirilebilir

Genişletilebilirlik ve Rust ekosistemiyle bağlantı

  • Ön işleyiciler, özel sözdizimi genişletmeleri ve içerik düzenlemelerini üstlenebilir
  • Arka uçlar aracılığıyla birden fazla çıktı biçiminde render alınabilir
  • mdBook, hız, güvenlik ve sadelik için Rust ile yazılmıştır
  • Rust kod örnekleri için otomatik test desteği sunar

Gerçek kullanım örnekleri ve katkı yöntemi

  • mdBook dokümantasyonunun kendisi, mdBook ile üretilmiş çıktının bir örneğidir
  • Rust programlama dili projesi mdBook kullanır; The Rust Programming Language kitabı da buna bir kullanım örneğidir
  • mdBook, ücretsiz ve açık kaynaklı bir projedir
  • mdBook kaynak kodu ve dokümantasyonu Mozilla Public License v2.0 altında dağıtılır

İlgili okumalar

1 yorum

 
GN⁺ 2023-07-01
Hacker News yorumları

  • Bu platformun, kütüphaneleri bundle etmeyip ya da vendor olarak eklemeyip CDN üzerinde barındırılan kütüphaneler kullandığını hatırlıyorum. Bu yüzden kullanıcılar sadece CDN kesintilerine değil, ilgili sunucunun topladığı verilere de maruz kalıyor
    Daha da can sıkıcı olan, frontend tarafında Highlight.js ve MathJax kullanım biçiminin çok savurgan olması. Tüm istemciler sözdizimini ve LaTeX'i kendileri parse edip render etmek zorunda kalıyor ve aynı sonucu elde etmek için her ziyarette aynı işi tekrar yapıyor. Sözdizimi vurgulama build aşamasında yapılabilir ve JavaScript gerektirmesi için neredeyse hiçbir sebep yok

    • MathJax CDN'de barındırılıyor gibi görünüyor, CSS ve diğer JS dosyaları ise HTML dosyasının yanında yer alıyor
      MathJax desteği isteğe bağlı olduğu için böyle bir tercih yapılmış gibi görünüyor: https://rust-lang.github.io/mdBook/format/mathjax.html
      Ancak MathJax JS'nin yine CDN'den ek dosyalar çekmesi çok muhtemel; bu yüzden neden MathJax dosyalarının tamamını üretilen HTML'in yanına koymadıklarını anlamak zor
    • Bununla ilgili açık bir PR zaten var gibi görünüyor: https://github.com/rust-lang/mdBook/pull/1918

  • Bu başlıkta geçen dokümantasyon/statik site araçları kabaca şunlar: Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook
    Jekyll, Hugo Book, MdBook, MkDocs, MkDocs Material, GitBook, Antora, Docusaurus, Nextra, Astro, Starlight, Clowncar, Keenwrite, Quarto, Honkit, JupyterBook

    • nimibook da kullandım
      Bu, mdBook'un Nim'e port edilmiş hâli, ancak Nim'in JavaScript backend'ini kullanarak etkileşimli içerik üretme özelliği de genişletilmiş. Bizzat kullanmadım ama ihtiyaç olduğunda etkileşimli unsurları tek bir yerde oluşturabilme fikri hoşuma gidiyor: https://pietroppeter.github.io/nimib/interactivity.html
    • Sphinx de atlanması zor bir seçenek. İş akışı, blog, forum ya da thread formatından ziyade kitap formatına daha uygun
    • HackMD, formül gösterimini destekliyor ve paylaşılabilir, ortak düzenlenebilir Markdown belgeleri oluştururken sık sık tercih ediliyor: https://hackmd.io/
    • Keşke bu araçlar için özellik karşılaştırma tablosu ya da sitesi olsa. Yerleşik arama, PDF çıktısı, ePub çıktısı, çoklu tema ve diğer özellikleri karşılaştırmak isterdim
    • https://jupyterbook.org/en/stable/ de var. Jupyter Book'a katkıda bulunuyorum.

  • MdBook, Jekyll ve MkDocs'u denedim; MdBook varsayılan projelerde pürüzsüz ama fazla minimal hissettirdi. Beğendiğim MdBook sitelerinin kaynaklarına baktığımda, bazılarının özel Rust koduyla genişletildiğini gördüm
    Önerim şu: MkDocs makul ölçüde esnek, iyi bir varsayılan seçenek; Jekyll açılış sayfası veya blog gibi daha fazla esnekliğin gerektiği durumlar için; Antora ise birden çok proje ve birden çok sürüm dokümantasyonunu bir araya getirip en iyi dokümantasyon sitesini yapmak istiyorsanız ve ciddi emek harcamaya hazırsanız uygun. AsciiDoc'ta da dokümantasyon yazımı için faydalı pek çok özellik var
    Hugo, Jekyll kadar esnek görünüyor ama istediğim hale getirmek için daha fazla çaba gerekiyor ve temalar arasında çalışma biçimi farkı fazla büyük gibi. Kullandığım temada ihtiyaç duyduğum özellik yoktu, başka bir temaya geçmeye çalıştım ama geçiş kolay olmadı, sonunda vazgeçtim. MdBook oldukça aktif görünüyor, bu yüzden sonunda arayı kapatacak gibi

    • Eski bir Jekyll kullanıcısıyım ve blog için hâlâ harika olduğunu düşünüyorum, ama dokümantasyon sitelerine yönelik statik site oluşturucular arasında Docusaurus en iyisiydi: https://docusaurus.io/
      JavaScript tabanlı araçlar kullanmak istemediğim için uzun süre erteledim, ama deneyince başlaması kolay, çok hızlı, varsayılan site güzel ve özelleştirmesi de kolaydı. MDX desteği de harika
    • material mkdocs theme(https://squidfunk.github.io/mkdocs-material/) açılış sayfası gerçekten çok şık. Ayrı bir yazılım için tema olduğunu düşününce özellikle etkileyici
    • Bilim ve istatistik tarafında Quarto'nun harika olduğunu düşünüyorum: https://quarto.org
    • Antora'yı ilk kez duydum ama birden çok depodan dokümantasyon derleyip branch'lerle sürüm yönetmesi tam istediğim davranış. Yalnız mevcut dokümanlarım Markdown ile etkileşimli React bileşenlerinin karışımı olduğu için MDX kullanmaması üzücü
    • MkDocs'u çok kullanıyorum ve çok seviyorum
      BookStack'i de deniyorum; daha çok wiki'ye yakın ama teknik olmayan kişiler için iyi. Genelde MkDocs projelerini VSCode'da düzenleyip Git deposunda tutuyorum, ama BookStack tamamen web tabanlı

  • Eskiden til.secretGeek.net üretimini GitBook ile yapıyordum ama zamanla o kadar yavaşladı ki siteyi build etmek 45 dakika sürmeye başladı ve kullandığım özellikler ya kaldırıldı ya da “premium” oldu. Sonunda enshittification başlamış oldu
    Çok iyi görünen ücretsiz bir araç kullanıyorsanız, birkaç yıl beklerseniz bozulma ihtimali yüksek. Sonunda .NET ile son derece minimal bir statik site oluşturucu yazdım ve build süresi yeniden birkaç saniyeye indi. Başkalarına kullanmaları için pek tanıtmıyorum; çünkü popüler olursa ben de muhtemelen aynı şekilde bozardım

  • mdBook'u birkaç projede kullandım ama son zamanlarda material for mkdocs çok daha fazla yerleşik özellik sunduğu için kullanımı daha iyi geliyor
    Mesela sağdaki sayfa içi içindekiler tablosunu seviyorum ama bu özellik mdBook'ta belirgin şekilde eksik. mdBook'ta SUMMARY'yi çok ayrıntılı kurup aslında tek sayfada durabilecek içeriği birden fazla dosyaya bölmek standart yaklaşım gibi görünüyor

    • material for mkdocs, Python kurulumu ve sanal ortam ayarına katlanmaya değecek kadar iyi
    • MkDocs'u epey uzun zamandır seviyorum. İşi minimum zahmetle bitiriyor, seçilebilecek çok tema var ve kendin özelleştirmek ya da sıfırdan yapmak da görece kolay
    • Bölüm bazlı içindekiler için https://github.com/JorelAli/mdBook-pagetoc kullanıyorum

  • Birkaç gün önce küçük bir projenin dokümantasyonu için mdBook kullanmaya başladım; tam ihtiyacım olan küçük bir statik sayfa oluşturucu
    HUGO'yu da denedim ama mdBook'la kıyaslayınca fazla büyük ve hantal geliyor. Şu anda belgeleri Obsidian/VIM ile düzenliyorum, Gitea'ya push ettiğimde bir dakika içinde herkese açık dokümantasyon oluşuyor

    • Hugo'yu book theme(https://github.com/alex-shpak/hugo-book) ile birlikte kullanıyorum. Hugo'ya alışık değilseniz biraz uyum süresi gerekiyor ama sonrasında Hugo'nun sunduğu shortcode gibi esneklikler çok hoş oluyor
      Uygun shortcode'larla görseller, denklemler vb. için otomatik numaralandırma yapılabiliyor. mdBook'ta da otomatik numaralandırma mümkün mü merak ediyorum. Sağ tarafta içindekiler, etiketler ve sayfaları sütunlara ayırma özelliği de var; KaTeX desteği de iyi. mdBook ise sanırım MathJax kullanıyor ve dağıtım push ya da rsync ile kolay
    • Son zamanlarda PlantUML eklentisini kullanmaya başladım; dokümantasyona mimari diyagramlar eklemekte yardımcı oluyor

  • Son dönemde içerikleri yavaş yavaş .md yerine .mdx’e taşımaya başlayıp incelemeye koyuldum ve oldukça tazeleyici geldi. Markdown’da en zorlandığım nokta, kullanılan her lehçenin sınırlarının farklı olması ve bu sınırları genişletme biçimlerinin de birbirinden ayrı olmasıydı
    Standart GitBook Markdown lehçesinin %80-90’ından çok memnunum, ama bazen karmaşık tablolar, yalnızca birkaç satırı vurgularken sözdizimi vurgusunu koruyan kod blokları, etkileşimli slider’lar, belgenin içine gömülü hesap makineleri, belirli grafikler ya da chart’lar gerekiyor. Büyük ekiplerde MDX nasıl işler bilmiyorum, ama bireysel çalışmada kesinlikle bir iyileşme gibi görünüyor

    • .mdx’i ilk kez duydum ve [0]’ı arayıp baktım. Frontend standardizasyon akışını yeterince yakından takip etmiyormuşum
      Lehçeler ortadan kalkıp tek bir evrensel yaklaşım ortaya çıksa güzel olurdu, ancak belgede “MDX React’e bağlı değil; Preact, Vue, Emotion, Theme UI ve diğerlerinde de kullanılabilir, ayrıca classic/automatic JSX runtime’ın ikisini de destekler” deniyor. Svelte implementasyonu [1] de zaten var; o yüzden bunun frontend framework’lerine bağlı daha fazla lehçenin çıktığı bir Pandora’nın kutusu olup olmadığından emin değilim. .mdx kendi içinde de bölünebilir ve .md ile de uyumlu olmayabilir
      [0] https://mdxjs.com/docs/what-is-mdx/
      [1] https://mdsvex.com/docs
    • Buna tamamen katılıyorum. Mdsvex’i bulduğumda hayat değiştirici gelmişti: https://mdsvex.com
    • .mdx, https://astro.build/ ile çok kolay kullanılabiliyor. Astro bir JavaScript meta-framework’ü ve istemciye JS göndermeyen önce statik site üretimi yaklaşımını benimsiyor
      Kullanılabilecek temalar da var, ama modern bir web geliştiricisiyseniz kendiniz yapmanız da oldukça kolay olacaktır

  • Markdown tabanlı kitaplar oluşturmak için ücretsiz, açık kaynaklı ve çapraz platform bir araç olan KeenWrite’ı geliştirdim: https://github.com/DaveJarvis/keenwrite
    KeenWrite, belge dizgisi için ConTeXt’i çağırıyor ve önizleme modunda formül dizgisi için KeenType fork’unu kullanıyor. Komut satırından PDF üretebiliyor. Şu anda yazdığım kitap, dış dosyalarda tanımlanan çeşitli değişkenlere metin içinde başvuruyor, metadata ile PDF özelliklerini iletiyor ve chapters argümanıyla yalnızca bazı bölümleri build edebiliyor. theme dizini; renkler, yazı tipleri, yerleşim, dipnotlar ve benzeri dizgi talimatlarını içeriyor
    Örnek çıktı: https://github.com/DaveJarvis/keenwrite-themes/tree/main/exa...

  • Markdown’un ya da ona benzer bir biçimin neden kitaplar, belgeler ve neredeyse tüm yazılar için varsayılan format olmadığını merak ediyorum. Birkaç yıl önce Typora’ya geçtikten sonra kendi yazdıklarım için Word/Writer’a neredeyse hiç ihtiyaç duymuyorum; onları artık sadece başkalarının gönderdiği belgeleri açmak için kullanıyorum
    Okuduğum kitapların %90’ının da Markdown formatında olmaması için belirgin bir neden yok gibi görünüyor. Basılı kitabı güzel bastırmak için dizgi gerektiğini anlıyorum, ama bilgisayarda ya da akıllı telefonda okunan veya MS/LibreOffice’ten doğrudan yazdırılan çoğu metinde zaten böyle bir dizgi işi düzgün yapılmış olmuyor

    • Markdown, saklama formatı olarak oldukça zayıf. Yarı resmî standart olan CommonMark var, ama özellikleri yetersiz olduğu için çoğu kişi GitHub Markdown gibi başka varyantlar kullanıyor; ayrıca tek tek uygulamalar Markdown’u birbiriyle uyumsuz şekillerde genişletebiliyor
      AsciiDoc gibi daha iyi alternatifler de var ama onlar daha çok dokümantasyona odaklı ve Markdown’a yakın bir ivmeleri yok. Markdown’un görece geç ortaya çıkmış bir format olduğu düşünülürse, asıl soru kitapların neden Markdown olması gerektiği olabilir. İkili ya da XML tabanlı biçimlere kıyasla Markdown’un en büyük avantajı, düz metin olarak bir ölçüde okunabilmesi; ama bu, çoğu yayıncı ve okur için pek önemli değil
    • Kitap dizgisinde, eğitim almamış gözlerin pek fark etmeyeceği çok sayıda incelik ve karmaşıklık var ve Markdown+CSS bunları ele almak için yeterince gelişmiş değil. HTML/CSS+JS teknik olarak mümkün olsa da dijital dizginin güncel seviyesinin oldukça gerisinde kalıyor
      Bu aynı zamanda tipik bir “ben daha iyisini yaparım” mühendis tuzağı; dolayısıyla araştırmadan böyle varsaymamak gerekir. Dizgi, burada konuşulan araçlardan çok daha eski bir alan ve Markdown bazı kullanım senaryolarında neredeyse yeterli diye, yıllar içinde birikmiş değerli içgörü ve teknikleri çöpe atmamak gerekir
    • İşte çok belge yazıyorum ve Markdown’u render edilmiş çıktıyla yan yana görmek hoşuma gidiyor. Sözdizimine alışınca Markdown, Word benzeri editörlerden çok daha hızlı oluyor; hatta bir metin editöründe tek bir liste yazmak bile külfetli gelmeye başlıyor

  • mdBook kullanımı kolay ve özellikle kullanıcının tema seçebilmesini seviyorum. Bunu çoğunlukla e-kitapların çevrimiçi sürümü [0] ve derlediğim kaynaklar [1][2] için kullanıyorum
    [0] https://github.com/learnbyexample/scripting_course#ebooks
    [1] https://learnbyexample.github.io/py_resources/
    [2] https://learnbyexample.github.io/curated_resources/