Çok hoş, aşırı basit, tamamen MarkDown destekleyen, Python ile yazılmış gerçekten hoş (biliyorum tekrar ettim ama gerçek bu yani :)) bir döküman hazırlama betiği.
Nedir Bu?
Eğer siz de benim gibi birden çok proje ile ilgileniyor, ve bir sürü döküman hazırlıyorsanız, HTML ile uğraşmanın tam bir sorun olduğunu biliyorsunuzdur. WYSIWYG editörleri de bir süre sonra bocalamaya, karışıklaşmaya başlıyor. İşte bu yüzden ya MarkDown geliştirildi. Hızlı, basit ama aşırı etkili. Ve döküman yazarken gerekebilecek bütün stillere de sahip. İşte MarkDown’ın gücünü, MkDocs ile birleştirince de ortaya çok hoş, hızlı ama kaliteli dökümanlar çıkıyor.
Kısaca Özellikleri
Sistem düzenlemelerinizi yaparken aynı zamanda hızlıca ön-izlemelere olanak sağlayan bir modüle de sahip, sizin yerinize hemen bir sunucu kuruyor. Yaptığınız güncellemeler anlık orada da güncelleniyor. İşiniz bitince de tek bir komutla ne gördüyseniz onun aynısını size bir klasörde hazırlıyor. Hazırladığı site statik, bu, onu Arduino da bile barındırabilirsiniz demek oluyor 🙂
Ayrıca MkDocs; eklenti, tema ve dil desteğine de sahip. Türkçe çevirisi de mevcut.
Nasıl Kurabilirim?
Kurulabilmesi için öncelikle sisteminizde Python bulunmalı. Ve PiP yani Python için çeşitli modülleri hızlıca kurmanıza yarayan bir arabirim, onun da kurulu ve güncel olması lazım. Eğer değilse hemen yardımcı olalım.
Hazırlıklar
pip install --upgrade pip
Eğer kullanıcı izinleri ile ilgili bir sorun alıyorsanız şu komutu çalıştırın
pip install --upgrade pip --user
Bu komut ile sorunsuz bir şekilde PiP’i güncelleyebilirsiniz.
Esas Kurulum
pip install mkdocs
Bu komut ile PiP MkDocs’u hızlıca kuracak. Çok beklemeniz de gerekmeyecek zaten.
Kullanım
Kullanımı çok basit, öncelikle hangi dizinde bir döküman oluşturmak istiyorsanız, orada bir terminal açın ve aşağıdaki komutu girin
mkdocs new benim-dokumanim cd benim-dokumanim
Şimdi ise bütün dizini favori editörünüz ile açabilirsiniz, ben VS Code kullanıyorum
code .
Dosya Yapısı
Tek bir yml dosyası ile kontrol edilen bir yapı karşımıza çıkıyor. site_name yazan yere döküman adını yazıyorsunuz. Ve bu kadar; isterseniz nav ile Üst Navigasyon ayarlarını, isterseniz de çeşitli ayarlar ile eklenti ve dil ayarlarını da halledebiliyorsunuz.
Üst Navigasyonu Yönetme
Çok basit bir şekilde nav: başlangıcından sonra bir alt satırda (gerekli girintileri unutmadan) Sayfa Adı : sayfa-adi.md şeklinde istediğiniz kadar sayfa ekleyebilir, benim yaptığım gibi markdown vermek yerine direk bir site adresi yazarak da yönlendirme sağlayabilirsiniz.
Serve Komutu
Bu komut ile az önce bahsettiğim sunucu kurma olayını yapıyorsunuz. Bu sunucu sayesinde değişiklikleriniz anında önünüze geliyor.
mkdocs serve
Büyük olasılıkla http://127.0.0.1:8000/
adresine bir sunucu kuracak, port çakışması varsa sizi zaten uyarır kendisi.
Build Komutu (Dışarı Aktarma)
Ve son olarak Build komutu ile dışarı aktarabiliyoruz dökümanımızı.
mkdocs build
Bu komut ile döküman dizininizin içerisine site/ adlı bir ek dizin açılacak. İçindeki tüm kodları kopyalayıp bir sunucuya attığınızda dökümanınızın çok hoş bir şekilde hazır olduğunu göreceksiniz.
Örnek
Örnek olarak yaptığım bu dökümana sizi yönlendirebilirim. CodeCanyon üzerinde sattığım bir betiğe ait bir döküman.
MkDocs ile İyi kodlamalar 🙂