2016-12-18 15:30:50 +08:00
< p align = "center" >
< img alt = "docsify" src = "https://cloud.githubusercontent.com/assets/7565692/21292094/5c206de4-c533-11e6-9493-29ea67b01dde.png" >
< / p >
2016-11-20 22:41:18 +08:00
2016-12-18 15:30:50 +08:00
< p align = "center" >
A magical documentation site generator.
< / p >
2016-11-20 22:41:18 +08:00
## Features
2016-12-19 20:38:35 +08:00
- Easy and lightweight (~12kb gzipped)
2016-11-26 17:24:32 +08:00
- Custom themes
- No build
2016-11-20 22:41:18 +08:00
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
Create a `404.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-11-22 22:46:44 +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
```
# Title
## balabala
```
### Deploy!
Push and open the **GitHub Pages** feature
## CLI
Easy to setup and preivew a docs.
### 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
2016-11-26 17:24:32 +08:00
## Themes
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
## More
### Multiple pages
If you need other pages, directly create the markdown file, such as `guide.md` is `/guide` .
### Navbar
Code in `404.html`
```html
< nav >
2016-11-26 18:13:39 +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-11-27 13:09:18 +08:00
### Options
#### repo
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
#### max-level
Toc level.
```html
< script src = "//unpkg.com/docsify" data-max-level = "6" > < / script >
```
#### el
Root element.
```html
< script src = "//unpkg.com/docsify" data-el = "#app" > < / script >
```
2016-11-29 21:42:48 +08:00
#### sidebar-toggle
Sidebar with toggle
```html
< script src = "//unpkg.com/docsify" data-sidebar-toggle > < / script >
```
2016-11-27 18:53:31 +08:00
#### sidebar
Custom sidebar. if it'set, the TOC will be disabeld. Bind global variables on the `data-sidebar` .
```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
#### 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.
2016-12-19 23:05:47 +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 >
```
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 )
- [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.
```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 >
```
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 )
```
2016-12-18 15:30:50 +08:00
#### router
2016-11-29 01:07:47 +08:00
2016-12-08 21:11:18 +08:00
Hash router. You can replace `404.html` with `index.html` .
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
2016-12-18 15:30:50 +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 >
```
