5.5 KiB
A magical documentation site generator.
Features
- Simple and lightweight (~12kb gzipped)
- Multiple themes
- Not build static html files
Quick Start
Create a project
First create a project, then create a docs folder
mkdir my-project && cd my-project
mkdir docs && cd docs
Create entry file
Create a 404.html file
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
<div id="app"></div>
</body>
<script src="//unpkg.com/docsify"></script>
</html>
Create README.md as the main page
# Title
## balabala
Deploy!
Push and open the GitHub Pages feature
CLI
Easy to setup and preivew a docs.
Install
npm i docsify-cli -g
Setup
Setup a boilerplate docs
docsify init docs
Preview
Preview and serve your docs using
docsify serve docs
Read more docsify-cli
Themes
Currently available vue.css and buble.css
<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css">
Minified files
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css">
More
Multiple pages
If you need other pages, directly create the markdown file, such as guide.md is /guide.
Navbar
Code in 404.html
<nav>
<a href="/docsify/">En</a>
<a href="/docsify/zh-cn">中文</a>
</nav>
CDN
Options
repo
Display the GitHub Corner widget.
<script src="//unpkg.com/docsify" data-repo="your/repo"></script>
max-level
Toc level.
<script src="//unpkg.com/docsify" data-max-level="6"></script>
el
Root element.
<script src="//unpkg.com/docsify" data-el="#app"></script>
sidebar-toggle
Sidebar with toggle
<script src="//unpkg.com/docsify" data-sidebar-toggle></script>
sidebar
Custom sidebar. if it'set, the TOC will be disabeld. Bind global variables on the data-sidebar.
<script>
window.sidebar = [
{ slug: '/', title: 'Home' },
{
slug: '/pageA',
title: 'page A',
children: [
{ slug: '/pageA/childrenB', title: 'children B' }
]
},
{ slug: '/PageC', title: 'Page C' }
]
</script>
<script src="/lib/docsify.js" data-sidebar="sidebar"></script>
load-sidebar
Load sidebar markdown file. If it is configured, load the current directory _sidebar.md by default. If the file isn't exist, sidebar will appear TOC.
** you should add .nojekyll into docs folder, to prevent GitHub Pages from ignoring the _sidebar.md**
<script src="/lib/docsify.js" data-load-sidebar></script>
You can specify a file:
<script src="/lib/docsify.js" data-load-sidebar="_sidebar.md"></script>
The contents of the file can be:
- [Home](/)
- [Installation](/installation)
- Essentials
- [Getting Started](/getting-started)
- [Dynamic Route Matching](/dynamic-matching)
- [Nested Routes](/nested-routes)
- [Programmatic Navigation](/navigation)
- [Named Routes](/named-routes)
- [Named Views](/named-views)
- [Redirect and Alias](/redirect-and-alias)
- [HTML5 History Mode](/history-mode)
load-navbar
Load navbar markdown file. If it is configured, load the current directory _navbar.md by default.
<script src="/lib/docsify.js" data-load-navbar></script>
You can specify a file:
<script src="/lib/docsify.js" data-load-navbar="_navbar.md"></script>
The contents of the file can be:
- [en](/)
- [chinese](/zh-cn)
If you write a sub level list, it will generate a dropdown list.
- [download](/download)
- language
- [en](/)
- [chinese](/zh-cn)
router
Hash router. You can replace 404.html with index.html.
<script src="/lib/docsify.js" data-router></script>
auto2top
Scroll to the top on changing hash.
<script src="/lib/docsify.js" data-auto2top></script>
homepage
README.md will be render as homepage for your website in docs folder, but sometimes we want to specify another file as a homepage, or even use the README.md in your repo. we can use (need data-router):
<script src="/lib/docsify.js" data-homepage="https://raw.githubusercontent.com/QingWei-Li/docsify/master/README.md"></script>
<!-- Or using `Welcome.md` as homepge -->
<script src="/lib/docsify.js" data-homepage="Welcome.md"></script>
basePath
If your HTML entry file and the markdown files are in different directories, we can use:
<script src="/lib/docsify.js" data-base-path="/base/"></script>
<!-- Even if the docs is on another site 😄 -->
<script src="/lib/docsify.js" data-base-path="https://docsify.js.org/"></script>