How to create a documentation site with Docsify and Github Pages (Doc as a code)
In this article, you will learn about GitHub pages, Docsify, documentation, technical writing, Doc as code, and how to create technical documentation with Doctify and Github pages.
There are so many docs as code tools/ templates but in this article i will use Docsify, below are the few static site generators for doc as code.
Docsify:
generates your documentation website on the fly. Unlike GitBook, it does not generate static Html to learn more about Docsify click here
Mkdocs:
builds completely static HTML sites that you can host on GitHub pages, Amazon S3, or anywhere else you choose. Great themes available click here to see awesome templates made with Mkdoc
Jekyll:
is a simple, blog-aware, static site generator perfect for personal, project, or organization sites. Think of it like a file-based CMS, without all the complexity. to generate a static documentation site click here
let's get to familiarize ourself with the following terms, because they will help us as you proceed in creating your first Doc as code static site.
Github Pages: is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub optionally runs the files through a build process and publishes a website. to learn more click here
Documentation: is any communicable material that is used to describe, explain, or instruct regarding some attributes of an object, system, or procedure, such as its parts, assembly, installation, maintenance, and use. to learn more click here
Technical writing: is a type of writing where the author is writing about a particular subject that requires direction, instruction, or explanation. to learn more click here
Doc as Code: Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code: Issue Trackers. Version Control (Git) Plain Text Markup (Markdown, reStructuredText, Asciidoc) to learn more click here
you need to have a Github account before you can proceed
Guide to create your first static documentation
I assume you know the basics of Github but if you don't know click here.
Firstly, you will create a new repository in Github by going to https://github.com/
- Name your repository
Doc as code. - Write a short description.
- Choose Public or Private
- Select Initialize this repository with a README.
- Choose a license after that click on the “Create repository” button, to create your repo on Github.
When your repo is ready, you will follow the step in this link to add Docsify in your repo.
Secondly, you will Enable GitHub Pages using the steps in the screenshot below.
Voila, you have your static site online with the URL above ❤️❤️❤️😍😍😍👌👌👌, you can also look up my already designed Docsify static site for clues here on how to modify your own.
To make the sidebar/nav bar to be visible you have to select the docs folder in Github pages
Thank you for reading my article.
Let’s connect on
Twitter: https://twitter.com/Joklinztech
LinkedIn: https://www.linkedin.com/in/wisdom-nwokocha-76212a77/
