Documentation is a vital a part of making any open supply undertaking helpful to customers. But it is not all the time builders’ high precedence, as they could be extra targeted on making their utility higher than on serving to folks use it. This is why making it simpler to publish documentation is so invaluable to builders. In this tutorial, I am going to present you one choice for doing so: combining the Docsify documentation generator with GitHub Pages.
If you like to be taught by video, you possibly can entry the YouTube model of this how-to:
By default, GitHub Pages prompts customers to make use of Jekyll, a static website generator that helps HTML, CSS, and different net applied sciences. Jekyll generates a static web site from documentation recordsdata encoded in Markdown format, which GitHub mechanically acknowledges because of their .md or .markdown extension. While this setup is sweet, I wished to attempt one thing else.
Fortunately, GitHub Pages’ HTML file help means you should use different site-generation instruments, together with Docsify, to create an internet site on the platform. Docsify is an MIT-Licensed open supply undertaking with features that make it simple to create a sexy superior documentation website on GitHub Pages.
Get began with Docsify
There are two methods to put in Docsify:
- Docsify’s command-line interface (CLI) by NPM
- Manually by writing your individual
index.html
Docsify recommends the NPM method, however I’ll use the second choice. If you wish to use NPM, comply with the directions within the quick-start guide.
Download the pattern content material from GitHub
I’ve revealed this instance’s supply code on the project’s GitHub page. You can obtain the recordsdata individually or clone the repo with:
git clone https://github.com/bryantson/OpensourceDotComDemosThen cd into the DocsifyDemo listing.
I’ll stroll you thru the cloned code from my pattern repo under, so you possibly can perceive the right way to modify Docsify. If you like, you can begin from scratch by creating a brand new index.html file, like within the example in Docsify’s docs:
<!-- index.html --><!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content material="IE=edge,chrome=1">
<meta identify="viewport" content material="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>
Explore how Docsify works
If you cloned my GitHub repo and become the DocsifyDemo listing, you must see a file construction like this:
| File/Folder Name | What It Is |
|---|---|
| index.html | The major Docsify initiation file (and an important file) |
| _sidebar.md | Renders the navigation |
| README.md | The default Markdown file on the root of your documentation |
| photographs | Contains a pattern .jpg picture from the README.md |
| Other directories and recordsdata | Contain navigatable Markdown recordsdata |
Index.html is the one factor required for Docsify to work. Open the file, so you possibly can discover the contents:
<!-- index.html --><!DOCTYPE html>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content material="IE=edge,chrome=1">
<meta identify="viewport" content material="width=device-width,initial-scale=1">
<meta charset="UTF-8">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
<title>Docsify Demo</title>
</head>
<body>
<div id="app"></div>
<script>
window.$docsify =
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>
This is basically only a plain HTML file, however check out these two traces:
These traces use content material supply community (CDN) URLs to serve the CSS and JavaScript scripts to rework the location right into a Docsify website. As lengthy as you embody these traces, you possibly can flip your common GitHub web page right into a Docsify web page.
The first line after the physique tag specifies what to render:
<div id="app"></div>Docsify is utilizing the single page application (SPA) method to render a requested web page as a substitute of refreshing a completely new web page.
Last, have a look at the traces contained in the script block:
In this block:
- The
elproperty mainly says, “Hey, that is theidI’m searching for, so find theidand render it there.” - Changing the
repoworth identifies which web page customers will probably be redirected to after they click on the GitHub icon within the top-right nook. - Setting
loadSideBartotruewill make Docsify search for the_sidebar.mdfile that incorporates your navigation hyperlinks.
You can discover all of the choices within the Configuration part of Docsify’s docs.
Next, have a look at the _sidebar.md file. Because you set the loadSidebar property worth to true in index.html, Docsify will search for the _sidebar.md file and generate the navigation file from its contents. The _sidebar.md contents within the pattern repo are:
<!-- docs/_sidebar.md -->* [HOME](./)
* [Tutorials](./tutorials/index)
* [Tomcat](./tutorials/tomcat/index)
* [Cloud](./tutorials/cloud/index)
* [Java](./tutorials/java/index)* [About](./about/index)
* [Contact](./contact/index)
This makes use of Markdown’s hyperlink format to create the navigation. Note that the Tomcat, Cloud, and Java hyperlinks are indented; this causes them to be rendered as sublinks below the father or mother hyperlink.
Files like README.md and photographs pertain to the repository’s construction, however all the opposite Markdown recordsdata are associated to your Docsify webpage.
Modify the recordsdata you downloaded nonetheless you need, primarily based in your wants. In the following step, you’ll add these recordsdata to your GitHub repo, allow GitHub Pages, and end the undertaking.
Enable GitHub Pages
Create a pattern GitHub repo, then use the next GitHub instructions to examine, commit, and push your code:
$ git clone LOCATION_TO_YOUR_GITHUB_REPO
$ cd LOCATION_TO_YOUR_GITHUB_REPO
$ git add .
$ git commit -m "My first Docsify!"
$ git push
Set up your GitHub Pages web page. From inside your new GitHub repo, click on Settings:
Scroll down till you see GitHub Pages:
Look for the Source part:
Click the drop-down menu below Source. Usually, you’ll set this to the grasp department, however you should use one other department, if you would like:
That’s it! You ought to now have a hyperlink to your GitHub Pages web page. Clicking the hyperlink will take you there, and it ought to render with Docsify:
And it ought to look one thing like this:
Conclusion
By enhancing a single HTML file and a few Markdown textual content, you possibly can create an awesome-looking documentation website with Docsify. What do you suppose? Please depart a remark and likewise share another open supply instruments that can be utilized with GitHub Pages.
