Hello,
In this article, I would like to introduce you to a tool that will make you love documentation while creating software projects.
What is Docsify and what does it do?
Docsify is a very simple to use, open source tool where we can create documents for our projects in markdown markup language and publish it like a website.
When we look at its key features, these are the highlights:
- First of all, it is simple and lightweight
- Having a search plugin where you can do full-text search
- Multiple theme support
- Emoji support
- plugin support
- Server-side rendering support
Let’s reinforce the subject by making a sample project 🧑🏻💻
1. Installation
Since its own documentation recommends to use it globally, I will do the same.
npm i docsify-cli -g
After the installation is finished, let’s create our project named “example-docsify” using cli.
docsify init ./example-docsify
Then let’s go inside the “example-docsify” folder and stand up the project with the following command.
docsify serve
2. Adding content
As an example, I will create the documentation of the project I did before with docsify. The document we will design will have the following features:
- cover page
- sidebar usage
- Theme
- Search
a. Create a cover page
First, we create a file called “coverpage.md” and add our content in markdown format. Then it will be enough to go to the “index.html” file and add the following code to the script there.
coverpage: "coverpage.md"
index.html
<script>
window.$docsify = {
name: '',
repo: '',
coverpage: "coverpage.md",
homepage: "README.md",
}
</script>
Note:
The homepage section defines the homepage as Readme.md by default, but this is not a hard and fast rule. If desired, it can be assigned by creating a file with another name (e.g. home.md) or by giving an external url.
window.$docsify = {
homepage: 'home.md',
// or
homepage:
'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
};
b. Sidebar usage
You don’t need to make an extra effort to add a new link to the sidebar :) all you need to do is define a title in markdown format in the homepage. Automatically these headings will appear in the Sidebar.
# Getting Started
### Installation ⚙️
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
If we want to add a logo at the top of the sidebar, all we need to do is add the “logo” key to the script in “index.html”.
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. Theme
We can change the color of the link, button and the github sharing section at the top right by adding the themeColor key in the section where we set all the settings.
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",
}
There are also ready-made css files with different background colors. Thus, it is also possible to use dark or different colored themes.
To activate it, it will be enough to change the imported css file in our index.html file.
Below are ready-made css files for various themes.
<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. Search
The search feature is one of the indispensable and most important elements when reading documents. Again, docsify offers us a quick solution in this regard. All we need to do to add a search section is to include the following script in our project.
<script src="https://unpkg.com/docsify/lib/plugins/search.js"></script>
Click here to access extra plugins and include them in your own projects.
As a result, docsify, which I mentioned the features that will be useful for basic use, has many different features. You can use the official site for more details.
You can access the source codes of the sample project from this link. 🔗
Continue with content 🚀
You can access my other content by clicking this link. I would be very happy if you like and leave a comment 😇
Top comments (0)