Bugün sizlere bir dökümantasyon aracı olan Docsify dan bahsedeceğiz. Dokümantasyon oluşturmak, herhangi bir projenin veya iş sürecinin devamını sağlamak için oldukça önemlidir. İyi bir dokümantasyon, iş süreçlerinin ayrıntılı olarak izlenmesini ve yürütülmesini mümkün kılar. Ayrıca, bir proje veya iş sürecindeki hataları tespit edip gidermek, uygun bir şekilde planlama yapmak ve başarılı sonuçlar elde etmek için gereklidir.
Dokümantasyon oluşturmak, aynı zamanda bilgi paylaşımını da kolaylaştırır. Ekip üyeleri arasında bilgi alışverişi yapmak, bir projenin farklı aşamaları hakkında bilgi edinmek veya bir iş sürecindeki belirli görevleri tamamlamak için gerekli bilgilere erişmek daha kolaydır.
Sonuç olarak, dokümantasyon oluşturmak bir işletmenin başarısı için hayati öneme sahip bir unsurdur. İyi bir dokümantasyon, iş süreçlerinin düzenli olarak izlenmesini ve yürütülmesini sağlar, bilgi paylaşımını kolaylaştırır ve işletmenin başarısı için gereken tüm bilgilere erişimi sağlar.
Dokümantasyon başarılı bir ürün için kritik öneme sahiptir. Dokümantasyon olmadan insanların ürününüzü kullanması daha zordur ve açık kaynaklı bir proje yürütüyorsanız bu da aynı derecede önemlidir.
Özellikle ön uç geliştirmeye aşina değilseniz, bir dokümantasyon sitesi oluşturmak zor olabilir. Ancak bunların çoğunu kullanabilmeniz için JavaScript, Next.js ve React hakkında temel bilgilere sahip olmanız gerekir. Aşağıdakiler gibi bazı zorluklarla karşılaşabilirsiniz:
- JavaScript, React veya diğer gerekli araçlar hakkında bilgi eksikliği
- Dokümantasyon versiyonlama
- Yapılandırma
- Dağıtım
Bu kılavuzda size, çok fazla teknik bilgiye ihtiyaç duymadan belge yazmanıza yardımcı olabilecek güçlü bir aracı tanıtacağız.
Docsify Nedir?
Docsify, kullanıcıların markdown veya HTML dosyalarınızdaki belgeleri web sayfasına dönüştürmelerine olanak tanıyan açık kaynaklı bir belge oluşturma aracıdır. Bu araç sayesinde hızlı ve kolay bir şekilde belgelerinizi yükleyebilir, düzenleyebilir ve paylaşabilirsiniz. Ayrıca, Docsify’nin sunduğu özellikler sayesinde yüksek kaliteli belgeler oluşturabilirsiniz, örneğin; belgelerinizi bir arama motoru ile arayabilir, anahtar kelimeleri kullanarak belgelerinizi filtreleyebilir ve belgenizdeki içeriklere hızlı bir şekilde erişebilirsiniz. Bu araç, özellikle belge paylaşımı yapmak isteyenler için oldukça faydalıdır.
Docsify Nasıl Kurulur ve Kullanılır
docsify-cli ile yeni bir proje oluşturabilirsiniz. Docsify-cli’yi kullanmak için, henüz kurulu değilse Node ve NPM’yi kurmanız gerekir.
npm install -g docsify-cli
# veya
yarn add -g docsify-cli
# veya
pnpm add -g docsify-cli
Komut çıktısı şöyle görünür:
❯ pnpm add -g docsify-cli
Packages: +198
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 199, reused 114, downloaded 84, added 198, done
.pnpm/docsify@4.13.1/node_modules/docsify: Running postinstall script, done in 196ms
+ docsify-cli 4.4.4
+ pnpm 8.7.0
Done in 13.9s
Yeni projenizi docsify-cli init seçeneğiyle oluşturun.
➜ docsify init docs
Initialization succeeded! Please run docsify serve ./docs
Ayrıca tema (–theme) ve eklenti (–plugins) de belirtebilirsiniz.
➜ docsify init docs --theme buble --plugins
Daha sonra docsify-cli’yi kullanarak yerel geliştirme sunucunuzu başlatın. Bunun için aşağıdaki komutu çalıştırın:
docsify serve docs
# veya
docsify serve .
Yerel sunucunuz yerel olarak 3000 bağlantı noktasında çalışır.
Tarayıcıda açtığınızda web siteniz şu şekilde görünmelidir:
Docsify Dizin Yapısı
Docsify basit bir dizin yapısına sahiptir. Docsify-cli ile yeni bir proje oluşturduğunuzda varsayılan olarak üç ana dosya vardır:
├── index.html // Bu bir HTML giriş dosyasıdır.
├── .nojekyll // Bu, projenizi GitHub sayfalarına dağıttığınızda faydalıdır.
├── README.md // Bu ana sayfa veya / yönlendiricidir
Docsify Nasıl Özelleştirilir
Docsify çok sayıda özelleştirme seçeneğiyle birlikte gelir ve yapılandırmak için herhangi bir ek bilgiye ihtiyacınız yoktur; tıpkı kodu kopyalayıp yapıştırmak gibi oldukça basittir. Bu kılavuzda en yaygın özelleştirme seçeneklerinden bazılarını inceleyeceğiz. Gelişmiş yapılandırma için Docsify belgelerine göz atabilirsiniz.
- Basit Konfigürasyon
- Yüklenme (Loading) Ekranı
- Yan Menü
- Başlık
- Kapak Sayfası
- Eklentiler
- Temalar
- Yükleme
1. Basit Konfigürasyon
Temel yapılandırmada bir logoyu, adı değiştirebilir veya ekleyebilir, GitHub veri havuzu bağlantınızı, tema rengini vb. ekleyebilirsiniz. İşte bunu yapmanın kodu; kendi bilgilerinizi girebilirsiniz.
<!-- index.html -->
<script>
window.$docsify = {
logo: '/_media/icon.svg', <!-- add logo -->
name: "Document", <!-- Website name it appears in sidebar. -->
nameLink: '/', <!-- url for name -->
repo: "docsify/docsifyjs",<!--github repository-->
maxLevel: 2, <!-- Maximum Table of content level. -->
themeColor: '#3F51B5', <!-- Customize theme color -->
};
</script>
2. Yüklenme (Loading) Ekranı
Bir yükleme ekranını veya diyalogu etkinleştirmek, özellikle de JavaScript ve React.js ekosisteminden geliyorsanız genellikle çok zordur.
Docsify’da herhangi bir yapılandırma olmadan yükleme ekranını etkinleştirebilirsiniz. Uygulama kimliğinizin içine bir HTML öğesiyle birlikte bir miktar metin yazmanız yeterlidir; bu, daha sonra bir yükleme ekranı olarak gösterilir. Şuna benziyor:
<!-- index.html -->
<div id="app">Loading...</div>
<!-- veya -->
<div id="app">
<h1> Loading... </h1>
</div>
3. Yan Menü (Sideebar)
Varsayılan olarak kenar çubuğu içindekiler tablosunu gösterir. Ancak bunu çok kolay bir şekilde özelleştirebilirsiniz. Öncelikle kenar çubuğunu etkinleştirmeniz gerekir.
<!-- index.html -->
<script>
window.$docsify = {
loadSidebar: true, <!-- Enable sidebar -->
};
</script>
Daha sonra kök düzeyinde yeni bir _sidebar.md dosyası oluşturun ve aşağıdaki kodu yapıştırın:
- [Home](README.md)
- [Draft Article](draft-article.md)
- [Guide](guide.md)
- [First](page-first.md)
- [Second](page-second.md)
- [Third](page-third.md)
- [Four](page-four.md)
Kenar çubuğunuz artık şöyle görünmelidir:
4. Başlık (Header)
Varsayılan olarak Docsify sitenizde Gezinti Çubuğunu (Navbar) göremezsiniz:
Ama endişelenmeyin, bunu değiştirebilirsiniz. Navbar’ı göstermek için önce onu şu şekilde etkinleştirmeniz gerekir:
<!-- index.html -->
<script>
window.$docsify = {
loadNavbar: true, <!-- enable navbar -->
};
</script>
Daha sonra kök düzeyinde yeni bir _navbar.md dosyası oluşturun ve aşağıdaki kodu yapıştırın:
* Getting started
* [Quick start](quickstart.md)
* [Writing more pages](more-pages.md)
* [Custom navbar](custom-navbar.md)
* [Cover page](cover.md)
* Configuration
* [Configuration](configuration.md)
* [Themes](themes.md)
* [Using plugins](plugins.md)
* [Markdown configuration](markdown.md)
* [Language highlight](language-highlight.md)
Navbar ımız artık aşağıdaki gibi görünecektir.
5. Kapak Sayfası (Cover Page)
İlk olarak, aşağıdaki kodla dokümantasyondaki kapak sayfasını etkinleştirin:
<!-- index.html -->
<script>
window.$docsify = {
coverpage: true, <!-- enable coverpage -->
};
</script>
Bir sonraki adım yeni bir _coverpage.md dosyası oluşturmaktır.
# Docsify
### Başlangıç seviyesinden itibaren belgelendirmeyi öğrenin.
[Start]()
[Github](#/README)
6. Eklentiler (Plugins)
Eklentiler, Docsify’a ek işlevsellik ve özellikler sağlamaya ve aynı zamanda kullanıcı deneyimini geliştirmeye yardımcı olur.
Kendi gereksinimlerinize göre eklentiler oluşturabilir ve kullanabilirsiniz. Docsify’da açık kaynaklı ve çeşitli katkıda bulunanlar tarafından oluşturulan birçok eklenti bulunmaktadır.
Kodu kopyalayıp yapıştırarak herhangi bir eklentiyi kullanabilirsiniz. Docsify ile kendi eklentilerinizi bile oluşturabilirsiniz.
A. Üçüncü parti eklentiler nasıl kullanılır?
Bu örnekte, docsify eklentisinin yardımıyla arama çubuğunu işlevsel olarak etkinleştireceğiz.
Arama çubuğunu etkinleştirmek için aşağıdaki komut dosyasını kopyalayıp index.html dosyanıza yapıştırın:
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
Artık arama çubuğu sitenizde görünecek ve çalışacaktır. Arama eklentisi ile çeşitli işlevleri de yapılandırabilirsiniz; bunun hakkında daha fazla bilgiyi arama eklentisi kurulumu ve yapılandırma sayfasında bulabilirsiniz.
B. Docsify ile kendi eklentinizi nasıl oluşturabilirsiniz?
Docsify’da kendi eklentinizi oluşturmak için eklenti için kullanmanız gereken dahili bir hook vardır.
Docsify’ın altı dahili hook vardır: init, mount, beforeEach, afterEach, doneEach ve ready.
- init: docsify betiği başlatıldığında bir kez çağrılır.
- mount: docsify örneği DOM’a bağlandığında bir kez çağrılır.
- beforeEach: yeni işaretleme HTML’ye dönüştürülmeden önce her sayfa yüklemesinde çağrılır.
- afterEach: işaretleme HTML’ye dönüştürüldükten sonra her sayfa yüklemesinde çağrılır.
- doneEach: DOM’a yeni HTML eklendikten sonra her sayfa yüklemesinde çağrılır.
- ready: ilk sayfayı oluşturduktan sonra bir kez çağrılır.
Bu hook ların yardımıyla bir eklenti oluşturabilirsiniz. Kendi eklentilerinizi oluşturma hakkında daha fazla bilgi edinmek için özel eklenti belge sayfasına göz atın.
Bu örnekte beforeEach eklenti hook unu kullanarak bir düzenleme düğmesi oluşturacağız. Her sayfada BELGEYİ DÜZENLE düğmesini gösterir.
<!-- index.html -->
<script>
window.$docsify = {
plugins: [
<!-- write own custom plugin -->
function editButton(hook, vm) {
// call the hook
hook.beforeEach(function (html) {
var url = "https://github.com/docsify/docsifyjs/edit/master/" + vm.route.file;
// basic route fix
let tempFile = url.replace("docsifyjs/README.md", "README.md",)
? url.replace("docsifyjs/README.md", "README.md")
: url;
// Add Edit Button
var editHtml = "[📝 EDIT DOCUMENT](" + url + ")\n";
// Add edit button on top of file
return editHtml + html + "\n----\n" + "Last modified " + editHtml;
});
},
],
};
</script>
7. Temalar (Themes)
Docsify’ın hem resmi hem de topluluk yapımı temaları vardır. Bunlardan herhangi birini kullanabilirsiniz ve iyi tarafı, temaları değiştirdiğinizde ekstra kod yazmanıza gerek kalmamasıdır.
<!--vue theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" />
<!-- buble theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css" />
<!-- dark theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css" />
<!-- pure theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css" />
Tema CSS dosyalarını sıkıştırmayı veya sıkıştırmamayı seçebilirsiniz. Sıkıştırılmış CSS dosyası, temanın küçültülmüş bir sürümüdür ve üretim için hafif bir CSS dosyasıdır. Öte yandan, sıkıştırılmamış bir tema CSS dosyası geliştirme için faydalıdır.
CSS teması (Vue, bubble, dark ve pure) dosyasını kopyalayıp head öğesinin içine yapıştırmanız yeterlidir. Ve bununla birlikte temanız da değişir.
Resmi olmayan temalar açısından, belgelenebilir temanın sizin için en iyi seçenek olduğunu düşünüyorum.
8. Yükleme (Deployment)
Docsify’ın dağıtım için çeşitli seçenekleri vardır. Docsify sitenizi GitHub sayfalarında, GitLab Sayfalarında, Firebase Hosting, VPS (Nginx), Netlify, Vercel, AWS Amplify ve Docker’da dağıtabilirsiniz.
GitHub sayfaları gibi bazı platformlarda, docsify sitenizi herhangi bir yapılandırma yazmadan doğrudan GitHub deposuyla dağıtırsınız.
İşte bunu yapmak için:
Settings > Pages > Source > seçeneğine gidip bracnh dağıt’ı seçin > Branch > Klasörlü şubenizi seçin ve kaydet düğmesine tıklayın.
Paylaş
Takip Et
Eğitimin, Eğlencenin ve Haberin Sitesi TEKNOKODİ
