MkDocs ile Kolay ve Hızlı Dökümanlar Oluşturun

Ç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ıya sahip. Diğer her şey MarkDown dosyaları ile kontrol ediliyor.

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 🙂

Post A Reply