In this tutorial, I’ll show you one how to create nice documentation with Docsify and GitHub Pages. I have created a nice template that is available on GitHub.
So, documentation is an essential part of making any project useful to users. It’s not always developers’ top priority, as they may be more focused on making their application better than on helping people use it. This is why making it easier to publish documentation is so valuable to developers.
By default, GitHub Pages prompts users to use Jekyll. Jekyll is a static site generator that supports HTML, CSS, and other web technologies. Jekyll generates a static website from documentation files encoded in Markdown format, which GitHub automatically recognizes due to their .md or .markdown extension. While this setup is nice, I wanted to try something else.
Fortunately, GitHub Pages’ HTML file support means you can use other site-generation tools to create a website on the platform. Docsify is an MIT-Licensed open-source project with features that make it easy to create an attractive advanced documentation site on GitHub Pages.
Get started with Docsify
There are two ways to install Docsify:
- Docsify’s command-line interface (CLI) through NPM
- Manually by writing your own
index.html
Docsify recommends the NPM approach. If you want to use NPM, follow the instructions in the quick-start guide.
Get the template
I’ve published this example’s source code on the project’s GitHub page. You can download the files individually or clone the repo with
git clone https://github.com/erossini/docsify-template
So, in this template you have everything to start with your documentation. The features I added are:
- Full index search. This plugin ignores diacritical marks when performing a full text search (e.g., “cafe” will also match “café”). Legacy browsers like IE11 require the following String.normalize() polyfill library to ignore diacritical marks
- Zoom on images
- Pagination
- Reading progress bar
- Mermaid
Walkthrough the code
Now, I walk you through the cloned code from my sample repo below, so you can understand how to modify Docsify. If you prefer, you can start from scratch by creating a new index.html file, like in the example in Docsify’s docs:
<!-- index.html -->
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta charset="UTF-8">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
</head>
<body>
<div id="app"></div>
<script>
window.$docsify = {
//...
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>
In this file you can add more plugins and the configuration for the Docsify. To initialize Docsify, you have to add the script and the CSS style at least
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
These lines use content delivery network (CDN) URLs to serve the CSS and JavaScript scripts to transform the site into a Docsify site. As long as you include these lines, you can turn your regular GitHub page into a Docsify page.
The first line after the body tag specifies what to render:
<div id="app"></div>
Docsify is using the single page application (SPA) approach to render a requested page instead of refreshing an entirely new page.
Last, look at the lines inside the script block:
window.$docsify = {
name: 'Docsify Template',
el: "#app",
repo: "https://github.com/erossini/docsify-template",
loadSidebar: true
}
In this block:
- The
elproperty basically says, “Hey, this is theidI am looking for, so locate theidand render it there.” - Changing the
repovalue identifies which page users will be redirected to when they click the GitHub icon in the top-right corner. - Setting
loadSideBartotruewill make Docsify look for the_sidebar.mdfile that contains your navigation links.
You can find all the options in the Configuration section of Docsify’s docs.
Sidebar
Next, look at the _sidebar.md file. Because you set the loadSidebar property value to true in index.html, Docsify will look for the _sidebar.md file and generate the navigation file from its contents. The _sidebar.md contents in the sample repo are:
<!-- docs/_sidebar.md -->
* [HOME](./)
* [Examples](./examples/index)
* [Mermaid](./examples/Mermaid/index.md)
- [Flowchart](./examples/Mermaid/flowchart.md)
* [📊 Charty](./examples/Charty/index)
- [Area](./examples/Charty/area.md)
* [About](./about/index)
* [Contact](./contact/index)
This uses Markdown’s link format to create the navigation.
README
In the root of the folder, you have a README.md file. This is the default Markdown file that Docsify reads first. The content is in Markdown format.
The result
Now, the result we expect from this code is what you see in the following screenshot.
How to run Docsify locally
Before continuing to create our documentation with Docsify and GitHub Pages, we want to see the result in our local machines. For that, we have to install Docsify from NPM first running the following command from the Command Prompt (if you are using Windows, don’t use Power Shell or Windows Terminal)
npm i docsify-cli -g
This command installs Docsify globally in the NPM. Now, you can start the Docsify server on your local machine using the directory where the project is. For example, in my case I have the project in the folder C:\Projects\FromGitHub\docsify-template. So, I run
docsify serve C:\Projects\FromGitHub\docsify-template
Now, you can open the browser on `https://localhost:54981`. From same reasons, Microsoft Edge doesn’t allow you to open this URL. So, I’m using Firefox and the result is in the following screenshot
Now, if you change your files or add new one and save, immediately you will see the change in the browser. I found Visual Studio Code fit for this job.
Enable GitHub Pages
Next step in create documentation with Docsify and GitHub Pages is to publish your documents on GitHub. I assume you have already created a repository on GitHub and push your documents on it.
Now, click on Settings and the Pages in your GitHub repository.
So, the first thing to do is to select from the dropdown list the branch that contains the documentation. GitHub advises to create a docs branch for it. In my case, I decided to use the main brach. Also, it is possible to choose a theme. This is useful only if you don’t use Docsify.
After this step, GitHub gives you the URL of your documentation. You have to wait at least 15 minutes before GitHub copies the files to the URL. So, if you try immediately to open the URL, you will receive a 404 error.
Custom domain
Now, I want to use a custom domain for my documentation. GitHub has this option. The setup is very easy. Add to your DNS the CNAME you want and then the main part of the URL. For example, I have a documentation about Agile on https://erossini.github.io/agile but I have to use the custom domain https://agile.puresourcecode.com. So, in the PureSourceCode DNS I added:
CNAME agile erossini.github.io
After this change, GitHub takes at least 15 minutes to recognize the DNS changes. When it finds the change, your GitHub Pages starts to reply to the custom domain.
Enforce HTTPS
If you domain has an SSL certificate, you can ask GitHub to enfors HTTPS for your GitHub Pages.
When you set or change your custom domain in the Pages settings, an automatic DNS check begins. This check determines if your DNS settings are configured to allow GitHub to obtain a certificate automatically. If the check is successful, GitHub queues a job to request a TLS certificate from Let’s Encrypt. On receiving a valid certificate, GitHub automatically uploads it to the servers that handle TLS termination for Pages. When this process completes successfully, a check mark is displayed beside your custom domain name.
The process may take some time. If the process has not completed several minutes after you clicked Save, try clicking Remove next to your custom domain name. Retype the domain name and click Save again. This will cancel and restart the provisioning process.
