2016-11-26 17:24:32 +08:00
## Quick Start
2016-11-20 22:41:18 +08:00
2016-11-26 17:24:32 +08:00
### Create a project
First create a project, then create a `docs` folder
```shell
mkdir my-project & & cd my-project
mkdir docs & & cd docs
```
### Create entry file
2016-12-24 19:50:04 +08:00
Create a `index.html` file
2016-11-20 22:41:18 +08:00
```html
<!DOCTYPE html>
< html >
< head >
< meta charset = "UTF-8" >
2016-11-20 22:49:32 +08:00
< link rel = "stylesheet" href = "//unpkg.com/docsify/themes/vue.css" >
2016-11-20 22:41:18 +08:00
< / head >
2016-11-26 17:24:32 +08:00
< body >
< div id = "app" > < / div >
< / body >
2016-12-24 19:50:04 +08:00
< script src = "//unpkg.com/docsify" data-router > < / script >
2016-11-20 22:41:18 +08:00
< / html >
```
2016-11-26 17:24:32 +08:00
Create `README.md` as the main page
```
# Title
2016-12-31 02:27:04 +08:00
## blabla
2016-11-26 17:24:32 +08:00
```
### Deploy!
2017-01-05 10:33:48 +08:00
Push code and activate **GitHub Pages** via your repo's settings
2016-11-26 17:24:32 +08:00
## CLI
2016-12-31 02:27:04 +08:00
Easy to setup and preview a docs.
2016-11-26 17:24:32 +08:00
### Install
```shell
npm i docsify-cli -g
```
### Setup
Setup a boilerplate docs
```shell
docsify init docs
```
### Preview
Preview and serve your docs using
```shell
docsify serve docs
```
Read more [docsify-cli ](https://github.com/QingWei-Li/docsify-cli )
2016-11-26 14:09:06 +08:00
2017-01-04 21:41:35 +08:00
## More
### Themes
2016-11-26 17:24:32 +08:00
Currently available `vue.css` and `buble.css`
```html
< link rel = "stylesheet" href = "//unpkg.com/docsify/themes/vue.css" >
< link rel = "stylesheet" href = "//unpkg.com/docsify/themes/buble.css" >
2016-11-26 14:09:06 +08:00
```
2016-11-27 13:30:40 +08:00
Minified files
```html
< link rel = "stylesheet" href = "//unpkg.com/docsify/lib/themes/vue.css" >
< link rel = "stylesheet" href = "//unpkg.com/docsify/lib/themes/buble.css" >
```
2016-11-26 17:24:32 +08:00
### Multiple pages
2016-12-24 19:50:04 +08:00
If you need other pages, directly create the markdown file, such as `guide.md` is `/#/guide` .
2016-11-26 17:24:32 +08:00
### Navbar
2016-12-24 19:50:04 +08:00
Code in `index.html`
2016-11-26 17:24:32 +08:00
```html
< nav >
2016-12-24 19:50:04 +08:00
< a href = "/#/docsify/" > En< / a >
< a href = "/#/docsify/zh-cn" > 中文< / a >
2016-11-26 17:24:32 +08:00
< / nav >
```
2016-12-20 10:20:56 +08:00
### CDN
- UNPKG [https://unpkg.com/docsify/ ](https://unpkg.com/docsify/ )
- jsDelivr [http://www.jsdelivr.com/projects/docsify ](http://www.jsdelivr.com/projects/docsify )
2016-12-22 00:24:54 +08:00
### Cover Page
2017-01-05 10:31:41 +08:00
Generate a cover page with markdown. Create a `_coverpage.md` and set `data-coverpage` in the script tag.
2016-12-22 00:24:54 +08:00
```markdown
# 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 )
```
2016-12-31 13:40:29 +08:00
#### Custom background
2017-01-05 10:31:41 +08:00
Currently the background of the cover page is generated randomly. We can customize the background color, or add a background image.
2016-12-31 13:40:29 +08:00
```markdown
# docsify <small>1.2.0</small>
> xxx
[GitHub ](https://github.com/QingWei-Li/docsify/ )
[Get Started ](#quick-start )
<!-- background image -->
<!-- background color -->
```
2017-01-04 21:41:35 +08:00
### Markdown parser
2017-01-05 10:31:41 +08:00
Docsify uses [marked ](https://github.com/chjj/marked ) to parse markdown. We can configure it
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
markdown: {
smartypants: true
}
}
```
2017-01-05 10:31:41 +08:00
And it can even be customized
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
markdown: function(marked) {
// ...
return marked
}
}
```
## Options
2016-12-22 00:24:54 +08:00
2017-01-05 10:31:41 +08:00
You can add configurations in the script tag attributes or with `window.$docsify` .
2016-11-27 13:09:18 +08:00
2017-01-04 21:41:35 +08:00
### repo
2016-11-27 13:09:18 +08:00
Display the [GitHub Corner ](http://tholman.com/github-corners/ ) widget.
2016-11-26 17:24:32 +08:00
```html
< script src = "//unpkg.com/docsify" data-repo = "your/repo" > < / script >
```
2016-11-27 13:09:18 +08:00
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
repo: 'your/repo'
}
```
### max-level
2016-12-31 02:27:04 +08:00
TOC level.
2016-11-27 13:09:18 +08:00
```html
< script src = "//unpkg.com/docsify" data-max-level = "6" > < / script >
```
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
maxLevel: 6
}
```
### el
2016-11-27 13:09:18 +08:00
Root element.
```html
< script src = "//unpkg.com/docsify" data-el = "#app" > < / script >
```
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
el: '#app'
}
```
### sidebar-toggle
2016-11-29 21:42:48 +08:00
Sidebar with toggle
```html
< script src = "//unpkg.com/docsify" data-sidebar-toggle > < / script >
```
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
sidebarToggle: true
}
```
### sidebar
2016-11-27 18:53:31 +08:00
2016-12-31 02:27:04 +08:00
Custom sidebar. If it's set, the TOC will be disabled. Bind global variables on the `data-sidebar` .
2016-11-27 18:53:31 +08:00
```html
< 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 >
```
2016-11-29 01:07:47 +08:00
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
sidebar: 'sidebar'
}
```
### load-sidebar
2016-11-29 01:07:47 +08:00
2017-01-05 10:31:41 +08:00
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.
2016-12-31 02:27:04 +08:00
** you should add `.nojekyll` into docs folder to prevent GitHub Pages from ignoring the `_sidebar.md` **
2016-11-29 01:07:47 +08:00
```html
< script src = "/lib/docsify.js" data-load-sidebar > < / script >
```
You can specify a file:
```html
< script src = "/lib/docsify.js" data-load-sidebar = "_sidebar.md" > < / script >
```
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
loadSidebar: '_sidebar.md'
}
```
2016-11-29 01:07:47 +08:00
The contents of the file can be:
```markdown
- [Home ](/ )
- [Installation ](/installation )
- Essentials
- [Getting Started ](/getting-started )
- [Dynamic Route Matching ](/dynamic-matching )
- [Nested Routes ](/nested-routes )
```
2017-01-04 21:41:35 +08:00
### sub-max-level
2016-12-30 18:09:13 +08:00
Display TOC in the custom sidebar. The default value is 0.
```html
< script src = "/lib/docsify.js" data-load-sidebar data-max-sub-level = "4" > < / script >
```
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
maxSubLevel: 4
}
```
2016-12-30 18:09:13 +08:00
2017-01-04 21:41:35 +08:00
### load-navbar
2016-11-29 01:07:47 +08:00
2016-12-31 02:27:04 +08:00
Load navbar markdown file. If it is configured, load the current directory `_navbar.md` by default.
2016-11-29 01:07:47 +08:00
```html
< script src = "/lib/docsify.js" data-load-navbar > < / script >
```
You can specify a file:
```html
< script src = "/lib/docsify.js" data-load-navbar = "_navbar.md" > < / script >
```
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
loadNavbar: '_navbar.md'
}
```
2016-11-29 01:07:47 +08:00
The contents of the file can be:
```markdown
- [en ](/ )
- [chinese ](/zh-cn )
```
2016-11-29 21:42:48 +08:00
If you write a sub level list, it will generate a dropdown list.
```markdown
- [download ](/download )
- language
- [en ](/ )
- [chinese ](/zh-cn )
```
2017-01-04 21:41:35 +08:00
### router
2016-11-29 01:07:47 +08:00
2016-12-24 19:50:04 +08:00
Hash router.
2016-11-29 01:07:47 +08:00
2016-12-08 21:11:18 +08:00
```html
< script src = "/lib/docsify.js" data-router > < / script >
```
2016-12-16 22:37:21 +08:00
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
router: true
}
```
### auto2top
2016-12-16 22:37:21 +08:00
Scroll to the top on changing hash.
```html
< script src = "/lib/docsify.js" data-auto2top > < / script >
2017-01-10 23:16:55 +08:00
<!-- Set offset top -->
< script src = "/lib/docsify.js" data-auto2top = "50" > < / script >
2016-12-16 22:37:21 +08:00
```
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
2017-01-10 23:16:55 +08:00
auto2top: true,
// auto2top: 50
2017-01-04 21:41:35 +08:00
}
```
### homepage
2016-12-20 21:18:52 +08:00
2016-12-31 02:27:04 +08:00
`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` ):
2016-12-20 21:18:52 +08:00
```html
< 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 >
```
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
homepage: true
}
```
### basePath
2016-12-20 21:18:52 +08:00
If your HTML entry file and the markdown files are in different directories, we can use:
```html
< 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 >
```
2016-12-22 00:24:54 +08:00
2017-01-04 21:41:35 +08:00
```js
window.$docsify = {
basePath: '/base/'
}
```
### coverpage
2016-12-22 00:24:54 +08:00
Generate cover page.
```html
< script src = "/lib/docsify.js" data-coverpage > < / script >
<!-- or -->
< script src = "/lib/docsify.js" data-coverpage = "other.md" > < / script >
2017-01-04 21:41:35 +08:00
```
```js
window.$docsify = {
coverpage: true
}
2016-12-22 00:24:54 +08:00
```
