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!
Push and open the **GitHub Pages** feature
## 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
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
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
2016-12-31 02:27:04 +08:00
Generate a cover page through with markdown. Create a `_coverpage.md` and set `data-coverpage` in 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-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
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 >
```
#### 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
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
#### load-sidebar
2016-12-31 02:27:04 +08:00
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 as a TOC.
** 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 )
```
2016-12-31 11:50:30 +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 >
```
2016-11-29 01:07:47 +08:00
#### load-navbar
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 >
```
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-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
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 >
```
2016-12-20 21:18:52 +08:00
#### homepage
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 >
```
#### basePath
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
#### coverpage
Generate cover page.
```html
< script src = "/lib/docsify.js" data-coverpage > < / script >
<!-- or -->
< script src = "/lib/docsify.js" data-coverpage = "other.md" > < / script >
```
