7.3 KiB
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 index.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" data-router></script>
</html>
Create README.md as the main page
# Title
## blabla
Deploy!
Push code and activate GitHub Pages via your repo's settings
CLI
Easy to setup and preview 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
More
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">
Multiple pages
If you need other pages, directly create the markdown file, such as guide.md is /#/guide.
Navbar
Code in index.html
<nav>
<a href="/#/docsify/">En</a>
<a href="/#/docsify/zh-cn">中文</a>
</nav>
CDN
Cover Page
Generate a cover page with markdown. Create a _coverpage.md and set data-coverpage in the script tag.
# docsify <small>1.2.0</small>
> A magical documentation site generator.
- Simple and lightweight (~12kb gzipped)
- Multiple themes
- Not build static html files
[GitHub](https://github.com/QingWei-Li/docsify/)
[Get Started](#quick-start)
Custom background
Currently the background of the cover page is generated randomly. We can customize the background color, or add a background image.
# docsify <small>1.2.0</small>
> xxx
[GitHub](https://github.com/QingWei-Li/docsify/)
[Get Started](#quick-start)
<!-- background image -->
<!-- background color -->
Markdown parser
Docsify uses marked to parse markdown. We can configure it
window.$docsify = {
markdown: {
smartypants: true
}
}
And it can even be customized
window.$docsify = {
markdown: function(marked) {
// ...
return marked
}
}
Options
You can add configurations in the script tag attributes or with window.$docsify.
repo
Display the GitHub Corner widget.
<script src="//unpkg.com/docsify" data-repo="your/repo"></script>
window.$docsify = {
repo: 'your/repo'
}
max-level
TOC level.
<script src="//unpkg.com/docsify" data-max-level="6"></script>
window.$docsify = {
maxLevel: 6
}
el
Root element.
<script src="//unpkg.com/docsify" data-el="#app"></script>
window.$docsify = {
el: '#app'
}
sidebar-toggle
Sidebar with toggle
<script src="//unpkg.com/docsify" data-sidebar-toggle></script>
window.$docsify = {
sidebarToggle: true
}
sidebar
Custom sidebar. If it's set, the TOC will be disabled. 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>
window.$docsify = {
sidebar: 'sidebar'
}
load-sidebar
Load sidebar markdown file. If it is configured, load the current directory _sidebar.md by default. If the file doesn't exist, the sidebar will appear as a 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>
window.$docsify = {
loadSidebar: '_sidebar.md'
}
The contents of the file can be:
- [Home](/)
- [Installation](/installation)
- Essentials
- [Getting Started](/getting-started)
- [Dynamic Route Matching](/dynamic-matching)
- [Nested Routes](/nested-routes)
sub-max-level
Display TOC in the custom sidebar. The default value is 0.
<script src="/lib/docsify.js" data-load-sidebar data-max-sub-level="4"></script>
window.$docsify = {
maxSubLevel: 4
}
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>
window.$docsify = {
loadNavbar: '_navbar.md'
}
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.
<script src="/lib/docsify.js" data-router></script>
window.$docsify = {
router: true
}
auto2top
Scroll to the top on changing hash.
<script src="/lib/docsify.js" data-auto2top></script>
<!-- Set offset top -->
<script src="/lib/docsify.js" data-auto2top="50"></script>
window.$docsify = {
auto2top: true,
// auto2top: 50
}
homepage
README.md will be rendered as a homepage for your website in the 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>
window.$docsify = {
homepage: true
}
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>
window.$docsify = {
basePath: '/base/'
}
coverpage
Generate cover page.
<script src="/lib/docsify.js" data-coverpage></script>
<!-- or -->
<script src="/lib/docsify.js" data-coverpage="other.md"></script>
window.$docsify = {
coverpage: true
}