Döküman oluşturmanın Hızlı Yolu Docsify

Merhabalar,

Bu yazımda sizlere yazılım projeleri oluştururken dökümantasyon yapmayı sevdirecek bir araçla tanıştırmak istiyorum.

Docsify nedir ne işe yarar?

Docsify kullanımı çok basit, markdown işaretleme dilinde projelerimiz için döküman oluşturabileceğimiz ve bunu bir web sitesi gibi yayınlayabileceğimiz açık kaynak bir araçtır.

Temel Özelliklerine baktığımızda öne çıkanlar şunlardır:

• Öncelikle basit ve hafif olması
• Full-text search yapabileceğiniz arama plugin’i olması
• Çoklu tema desteği
• Emoji desteği
• plugin desteği
• Server-side rendering desteği

Hadi gelin şimdi örnek bir proje yaparak konuyu pekiştirelim 🧑🏻‍💻

1. Kurulum

Kendi dökümantasyonunda global olarak kullanmamızı tavsiye ettiği için ben de öyle yapacağım

npm i docsify-cli -g

Kurulum bittikten sonra cli’yı kullanarak “example-docsify” adında projemizi oluşturalım.

docsify init ./example-docsify

daha sonra “example-docsify” klasörünün içine girip aşağıdaki komutla projeyi ayağa kaldıralım.

docsify serve

2. İçerik ekleme

örnek olarak daha önce yaptığım projenin dökümantasyonunu docsify’ la oluşturacağım. Tasarlayacağımız dökümanda şu özellikler olacak:

• cover sayfası
• sidebar kullanımı
• tema
• arama

a. Cover sayfası oluşturma

Öncelikle bir coverpage.md adında dosya oluşturup içeriğimizi markdown formatında ekliyoruz. Ardında da index.html dosyasına gidip oradaki script’e aşağıdaki kodu eklemek yeterli olacaktır.

coverpage: "coverpage.md"

index.html

<script>
    window.$docsify = {
      name: '',
      repo: '',
      coverpage: "coverpage.md",
      homepage: "README.md",
    }
  </script>

Not:

homepage kısmı standart olarak anasayfayı Readme.md olarak tanımlar.Ancak bu kesin bir kural değildir. İstendiği takdirde başka isimde bir dosya oluşturarak (ör: home.md) ya da harici bir url verilerek de atama yapılabilir.

window.$docsify = {
  homepage: 'home.md',
  // ya da 
  homepage:
    'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
};

b. Sidebar kullanımı

Sidebar’a yeni bir link eklemek için ekstra bir efor sarf etmenize gerek yok :) tek yapmanız gereken homepage içinde markdown formatında başlık tanımlamak. Otomatik olarak bu tanımladığınız başlıklar Sidebar’da gözükür.

# Getting Started

### Installation ⚙️

```bash
git clone https://github.com/melihs/rec-weather.git

cd rec-weather/

yarn

yarn start
```
### Built With 🛠️
* tailwindcss https://github.com/tailwindlabs/tailwindcss
* react-icons https://github.com/react-icons/react-icons
* sass        https://sass-lang.com
* dotenv      https://github.com/motdotla/dotenv

### TODO 📌
- multi-language support

### Demo 🚀

https://rec-weather.netlify.app

Sidebar’ın üst kısmına bir logo eklemek istersek yapmamız gereken tek şey index.html içindeki scripte “logo” key’ini eklemek olacaktır.

window.$docsify = {
      logo:"https://img.freepik.com/free-vector/bird-colorful-logo-gradient-vector_343694-1365.jpg",
      name: 'docsify example project',
      repo: "https://github.com/melihs",
      coverpage: "coverpage.md",
      homepage: "README.md",
    }

c. Tema

link, buton ve sağ üstteki github paylaşım kısmının rengi, yine tüm ayarları belirlediğimiz kısımda themeColor key’ i ekleyerek değiştirebiliriz.

  window.$docsify = {
      themeColor: '#FF0000',
      logo:"https://img.freepik.com/free-vector/bird-colorful-logo-gradient-vector_343694-1365.jpg",
      name: 'docsify example project',
      repo: "https://github.com/melihs",
      coverpage: "coverpage.md",
      homepage: "README.md",
    }

Ayrıca farklı arka plan renklerine sahip hazır css dosyaları da mevcut. Böylece koyu renkli ya da farklı renklerde tema kullanmak da mevcut.

Aktif hale getirmek için index.html dosyamızdaki import ettiğimiz css dosyasını değiştirmek yeterli olacaktır.

Aşağıda çeşitli temalar için hazır css dosyaları mevcut.

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css" />
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css" />

<head>
  <meta charset="UTF-8">
  <title>Document</title>
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  <meta name="description" content="Description">
  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
<!--  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">-->
  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/dark.css" />
</head>

d. Arama

Dökümanları okurken olmazsa olmazlardan ve en önemli unsurların başında arama özelliği gelir. Yine bu konuda docsify bize hızlı bir çözüm sunuyor. Arama kısmı eklemek için tek yapmamız gereken aşağıdaki script’i projemize dahil etmek.

<script src="https://unpkg.com/docsify/lib/plugins/search.js"></script>

Burayı tıklayarak ekstra pluginlere ulaşıp, kendi projelerinize dahil edebilirsiniz.

Sonuç olarak temel kullanımda işimize yarayacak olan özelliklerinden bahsettiğim docsify’ın bir çok farklı özellikleri de mevcut. Daha fazla ayrıntı için resmi sitesinden faydalanabilirsiniz.

https://docsify.js.org

Örnek projenin kaynak kodlarına bu linkten ulaşabilirsiniz. 🔗

İçeriklere devam 🚀

Diğer içeriklerime bu linke tıklayıp ulaşabilirsiniz. Beğenip yorum bırakırsanız çok mutlu olurum 😇