Build a Markdown-based docs site using DocsifyJS and GH Pages 👩🏫 🏗 📒 🕸
Follow the online tutorial. Start with the basics or get to the menu customization and styling in later sections. Code snippets and recommendations are provided, so you don't have to spend a lot of time on all the possible options and features covered in the docs that you don't need to know.
Want to make a Docsify site? I have a template project you can use. It has enough structure and sample content to get you going.
You don't need to fork it - unless you want to contribute changes.
This repo is one of my most starred and most forked repos - thanks for supporting.
The Docsify site has a great guide for beginners. But with all the configs and plugin options available, the guide feels more like a dictionary than a recipe for setting up a custom docs site that is focused on content and not adding too much code or configuration. So I created this tutorial to take beginners and advanced users through setting up Docsify in ordered steps - noting as well when steps are optional or what choices there are.
This tutorial takes you from basic site setup and content to optional configuration of styling, menus and plugins. It aims to cover common use-cases in a logical sequence, rather than covering everything you could do. You can also jump to a later step if you want to use that as a reference.
It also assumes you already have a docs directory in a project and you want to turn it into a docs site. The tutorial gives you some tips and pitfalls to avoid, based on the author's experience.
This project's own site is built on DocsifyJS so serves as a good example. It serves from the docs directory. There is no main application to separate from docs directory, so serving from that directory is just convenient.
See also the Nested Example section on the repo for understanding links in Markdown and the sidebar.
If want to skip the tutorial and want a base project which has some sample data then go to the template repo linked at the top.
That is a template repo which was created to accompany this tutorial, so the layout and conventions will mostly be the same. The template only implements the basic steps from the tutorial.
Click Use this template button and follow the instructions in the README.md doc.
Some background on how I arrived at DocsifyJS as a docs site builder.
My aims for building a docs site were as follows and Docsify meets all of them:
- Add as little code and configuration as possible. Focus on the content, with a bit of styling.
- Be easy to maintain.
- Quick to get set up on existing projects.
- It should be easy to repeat across many projects, without having to deal to have headaches with each. (Like a lot of boilerplate code, or installation issues, or drift as layouts/features are added to one and not the others.)
- Have no HTML template/layout files to maintain.
- Reduce dependencies and keep installation simple.
- Light or no build step needed.
The docs site tool used here is DocsifyJS which is a frontend JS library written in VueJS. But if you have never used before or never coded in JS before, you'll be guided through. The only JS you need to write in your config values. You also need to edit some HTML values and possibly write a YAML file for your navbar, which again is more configuration than code.
This project's tutorial covers the basics and provides minimal setup instructions. You can add the quickstart project to your existing docs folder. If you doc files are markdown files, you don't have to rename them and their formatting can mostly stay the same i.e. no frontmatter or special syntax and the pages still render well as plain markdown even. But some links may need updating since /docs folder is now the root of the app.
Unlike static site builders like Jekyll or Hugo, you do not need to install or run a site generator or change the formatting or metadata of your markdown files. Your also don't need any separate config file - the configuration is handled in the index.html page, which is also where dependencies are fetched in the browser and where the app starts.
Docsify works as a single-page application on this one page - data from your markdown files is pulled in and displayed within the Docsify UI shell. There are no template layout files to manage and you can choose from some themes easily without things breaking like when you switch themes in other static site generators.
See Contributing guidelines.
Released under MIT by @MichaelCurrin.
- You can modify and reuse this project.
- A copy of the license and copyright notice must be included with the software, according to this MIT definition.
- Please link back to this repo somewhere in your project.