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
2017-01-10 23:55:58 +08:00
```bash
2016-11-26 17:24:32 +08:00
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 >
2017-02-05 09:50:08 +08:00
< script src = "//unpkg.com/docsify" > < / 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
2017-01-11 16:21:37 +08:00
```markdown
2016-11-26 17:24:32 +08:00
# 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
2017-01-10 23:55:58 +08:00
```bash
2016-11-26 17:24:32 +08:00
npm i docsify-cli -g
```
### Setup
Setup a boilerplate docs
2017-01-10 23:55:58 +08:00
```bash
2016-11-26 17:24:32 +08:00
docsify init docs
```
### Preview
Preview and serve your docs using
2017-01-10 23:55:58 +08:00
```bash
2016-11-26 17:24:32 +08:00
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
}
}
```
2017-01-10 23:32:25 +08:00
### Doc Helpers
#### p.tip
2017-01-24 22:29:50 +08:00
`!> ` add your content will rendered as `<p class="tip">content</p>`
2017-01-10 23:32:25 +08:00
```markdown
2017-01-24 22:29:50 +08:00
!> Important **information**
2017-01-10 23:32:25 +08:00
```
It will be rendered
```html
< p class = "tip" > Important < strong > information< / strong > < / p >
```
e.g.
2017-01-24 22:29:50 +08:00
!> Important **information**
2017-01-10 23:32:25 +08:00
2017-01-24 22:29:50 +08:00
#### p.warn
```markdown
?> todo info
```
?> todo info
### Combining Vue
We can write the Vue syntax directly in the markdown file, when the Vue library is loaded into `index.html` . Default will automatically initialize a Vue instance, of course, we can also manually.
index.html
```html
< script src = "//unpkg.com/vue" > < / script >
2017-02-05 09:50:08 +08:00
< script src = "//unpkg.com/docsify" > < / script >
2017-01-24 22:29:50 +08:00
```
```markdown
< ul >
< li v-for = "i in 10" > {{ i }}< / li >
< / ul >
```
Manual initialization
```markdown
< div >
< input type = "text" v-model = "msg" >
< p > Hello, {{ msg }}< / p >
< / div >
< script >
new Vue({
el: 'main',
data: { msg: 'Docsify' }
})
< / script >
```
2017-01-04 21:41:35 +08:00
## 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'
}
```
### 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
### 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
2017-02-05 09:50:08 +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.
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
}
```
2017-02-05 13:53:36 +08:00
### base-path
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
}
2017-01-12 20:28:59 +08:00
```
### name
Project name. It is displayed in the sidebar.
```html
< script src = "/lib/docsify.js" data-name = "docsify" > < / script >
```
```js
window.$docsify = {
name: 'docsify'
}
```
2017-02-05 13:53:36 +08:00
### name-link
2017-01-12 20:28:59 +08:00
Name link. The default value is `window.location.pathname` .
```html
< script src = "/lib/docsify.js" data-name-link = "/" > < / script >
```
```js
window.$docsify = {
nameLink: '/'
}
```
2017-02-04 23:45:35 +08:00
### theme-color
2017-01-12 20:28:59 +08:00
2017-02-04 23:45:35 +08:00
Customize the theme color.
```html
< script src = "/lib/docsify.js" data-theme-color = "#3F51B5" > < / script >
```
```js
window.$docsify = {
themeColor: '#3F51B5'
}
```
2017-02-09 20:57:58 +08:00
2017-02-11 10:21:38 +08:00
### alias
Create aliases to certain other pages more easily.
```js
window.$docsify = {
alias: {
'/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG'
}
}
```
2017-02-09 20:57:58 +08:00
## Plugins
### Full Text Search
2017-02-09 21:23:09 +08:00
If a document can have a search, can enhance some user experience. Installing the search plugin is easy. Such as
2017-02-09 20:57:58 +08:00
```html
2017-02-09 22:16:15 +08:00
< script src = "//unpkg.com/docsify" > < / script >
2017-02-09 20:57:58 +08:00
< script src = "//unpkg.com/docsify/lib/plugins/search.js" > < / script >
```
By default, the hyperlink on the current page is recognized and the content is saved in `localStorage` . You can also specify the path to the files.
!> Configure the content before the plugin is installed.
```js
window.$docsify = {
search: 'auto', // default
search : [
'/', // => /README.md
'/guide', // => /guide.md
'/get-started', // => /get-started.md
'/zh-cn/', // => /zh-cn/README.md
],
// Full configuration
search: {
maxAge: 86400000, // Expiration time, the default one day
paths: [], // or 'auto'
placeholder: 'Type to search'
}
}
```
2017-02-09 22:16:15 +08:00
### Google Analytics
Install the plugin and configure the track id.
```html
< script src = "//unpkg.com/docsify" data-ga = "UA-XXXXX-Y" > < / script >
< script src = "//unpkg.com/docsify/lib/plugins/ga.js" > < / script >
```
or
```js
window.$docsify = {
ga: 'UA-XXXXX-Y'
}
```
