VuePress ile Statik Siteler Oluşturmak ve Yayınlamak

Girizgah

Birkaç ay önce Özgür Yazılım Yaz Kampı 2019'da tuttuğum Markdown formatındaki günlükleri daha kolay okunabilir hâle getirmek için bir çözüm aramaya başladım. Jekyll, Gatsby gibi muadillerini de inceledikten sonra hem pratik kullanımıyla ihtiyacımı karşıladığı hem de bir süredir Vue.js ekosistemi içerisindeki araçlarla vakit geçirdiğim için VuePress’i tercih ettim.

VuePress Nedir?

VuePress, gücünü Vue.js’den alan bir statik site oluşturucu. Markdown formatında yazılan sayfalarla statik siteler oluşturmaya imkân tanıyor. Bunu yaparken tema, eklenti ve bileşen desteği sunmasıyla birlikte içerisinde tümleşik olarak gelen stillendirme, arama ve navigasyon özelliklerinden de faydalanmamızı sağlıyor. Marifetlerini görmek için kendisi de VuePress ile hazırlanmış olan VuePress sitesi incelenebilir.

Kurulum ve Site Oluşturma

VuePress’i kullanmaya başlamak için Node.js’in en az 8.0 sürümüne sahip olmak gerekiyor. Gerekli Node.js ortamı sağlandıktan sonra proje dizinimiz içerisine yarn veya npm üzerinden VuePress paketinin kurulumunu yapıyoruz. -D veya --save-dev parametresiyle geliştirme ortamı bağımlılığı olduğunu belirtiyoruz.

yarn add -D vuepress veya npm install -D vuepress

Daha sonra Markdown dosyalarımızı tutacağımız docs isimli bir dizin oluşturuyoruz. Ben foo.bar/posts/example.html gibi bir URL görünümü elde etmek istediğim için tüm dosyalarımı docs/posts altında topladım. İç içe dizinler oluşturabilmek içinmkdir komutunu-p parametresiyle birlikte kullandım.

mkdir -p docs/posts

Unutmadan ufak ama önemli bir hatırlatma yapayım. GitHub’dakine benzer bir kullanımla VuePress’in oluşturacağı statik sitelerde de README.mddosyaları ana sayfaları işaret ediyor. Oluşturacağımız dizinlere tarayıcı üzerinden doğrudan erişim sağlamak istiyorsak bir README.mddosyasına sahip olduğundan emin olmalıyız.

Son olarak ana dizinimiz içerisindeki package.json dosyasına gerekli scripts eklemelerini yaparak nihai hâline getiriyoruz.

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  },
  "devDependencies": {
    "vuepress": "^1.2.0"
  }
}

Bu sayede dilediğimiz zaman sitemizi yarn docs:dev komutuyla geliştirme modunda görüntüleyebilir veya yarn docs:build komutuyla çıktısını alabiliriz. Site çıktısı varsayılan olarakdocs/.vuepress/dist dizini altında oluşturuluyor ve aşağıdaki gibi bir dizin yapımız meydana geliyor.

Statik site dizin yapısı

Özelleştirme

Yukarıdaki işlemler en basit anlamıyla Markdown dosyalarından HTML’e dönüştürülen bir statik site oluşturmamızı sağladı. Fakat VuePress’in marifetleri asıl buradan sonra başlıyor. .vuepress dizini altında oluşturacağımız config.js dosyası sayesinde sitemizi özelleştirebiliyoruz.

module.exports = {
  title: 'VuePress Static Site',
  description: 'Powered by Vue.js'  
  themeConfig: {       
    nav: [      
     { text: 'VuePress', link: 'https://vuepress.vuejs.org/' },      
    ],    
    sidebar: [      
     '/posts/example-1',      
     '/posts/example-2',
    ]
  }
}

Kabaca sitemiz için başlık ve açıklama belirlemiş ve akabinde temamıza iki tane navigasyon eklemiş olduk. Bunlar gibi özelleştirebileceğimiz çok fazla seçenek mevcut. Tamamına VuePress sitesindeki Default Theme Config sayfasından ulaşıp denemek mümkün.

Yayınlama

Oluşturduğum siteyi ücretsiz olarak yayınlamak için yine önümde Heroku, GitHub Pages, Google Firebase, Netlify gibi birkaç alternatif vardı. Burada tercihimi GitHub ile entegrasyonunun pratikliğinden ötürü Netlify’dan yana kullandım.

İlk olarak .vuepress dizini altındaki dist dizinini silerek çalışmayı bir GitHub deposuna yükledim. Daha sonra Netlify’ın bu depoya erişmesi için GitHub ile giriş yaparak ilgili depoya erişim izni verdim.

Netlify bir CI/CD çözümü olduğu için GitHub deposunda herhangi bir değişiklik olduğunda package.jsondosyasındaki bağımlılıkları kurarak statik sitemizi yeniden oluşturacak. Bunun için Netlify’daki Continuous Deployment sayfasından projenin hangi komutla yeniden inşa edileceğini ve ana dizin olarak nereyi kullanacağını belirliyoruz.

Continuous Deployment ayarları

Hepsi bu kadar. Günün sonunda statik sitemizi pratik bir şekilde oluşturmuş ve dakikalar içerisinde yayına almış olduk. Umarım benzer dertleri olanlar için işe yarar bir çözüm olur. VuePress ile hazırladığım iki statik siteyi paylaşarak yazıyı bitirmiş olayım.

https://github.com/tugsanunlu/oyk2019yaz-web-guvenligi

Web Uygulama Güvenliği ve Güvenli Kod Geliştirme / Tuğsan Ünlü | #oyk2019yaz

https://github.com/tugsanunlu/nasil-akillica-soru-sorulur

Nasıl Akıllıca Soru Sorulur?

Kaynakça

https://vuepress.vuejs.org/
https://vuepress.vuejs.org/config/#basic-config
https://vuepress.vuejs.org/theme/default-theme-config.html#homepage
https://docs.netlify.com/site-deploys/create-deploys/