## Quick Start
### Create a project
First create a project, then create a `docs` folder
```bash
mkdir my-project && cd my-project
mkdir docs && cd docs
```
### Create entry file
Create a `index.html` file
```html
```
Create `README.md` as the main page
```markdown
# Title
## blabla
```
### Deploy!
Push code and activate **GitHub Pages** via your repo's settings
## CLI
Easy to setup and preview a docs.
### Install
```bash
npm i docsify-cli -g
```
### Setup
Setup a boilerplate docs
```bash
docsify init docs
```
### Preview
Preview and serve your docs using
```bash
docsify serve docs
```
Read more [docsify-cli](https://github.com/QingWei-Li/docsify-cli)
## More
### Themes
Currently available `vue.css` and `buble.css`
```html
```
Minified files
```html
```
### Multiple pages
If you need other pages, directly create the markdown file, such as `guide.md` is `/#/guide`.
### Navbar
Code in `index.html`
```html
```
### CDN
- UNPKG [https://unpkg.com/docsify/](https://unpkg.com/docsify/)
- jsDelivr [http://www.jsdelivr.com/projects/docsify](http://www.jsdelivr.com/projects/docsify)
### Cover Page
Generate a cover page with markdown. Create a `_coverpage.md` and set `data-coverpage` in the script tag.
```markdown
# docsify 1.2.0
> 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.
```markdown
# docsify 1.2.0
> xxx
[GitHub](https://github.com/QingWei-Li/docsify/)
[Get Started](#quick-start)
```
### Markdown parser
Docsify uses [marked](https://github.com/chjj/marked) to parse markdown. We can configure it
```js
window.$docsify = {
markdown: {
smartypants: true
}
}
```
And it can even be customized
```js
window.$docsify = {
markdown: function(marked) {
// ...
return marked
}
}
```
### Doc Helpers
#### p.tip
`!> ` add your content will rendered as `
content
`
```markdown
!> Important **information**
```
It will be rendered
```html
Important information
```
e.g.
!> Important **information**
#### 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
```
```markdown
{{ i }}
```
Manual initialization
```markdown
Hello, {{ msg }}
```
## Options
You can add configurations in the script tag attributes or with `window.$docsify`.
### repo
Display the [GitHub Corner](http://tholman.com/github-corners/) widget.
```html
```
```js
window.$docsify = {
repo: 'your/repo'
}
```
### max-level
TOC level.
```html
```
```js
window.$docsify = {
maxLevel: 6
}
```
### el
Root element.
```html
```
```js
window.$docsify = {
el: '#app'
}
```
### 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`**
```html
```
You can specify a file:
```html
```
```js
window.$docsify = {
loadSidebar: '_sidebar.md'
}
```
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)
```
### sub-max-level
Display TOC in the custom sidebar. The default value is 0.
```html
```
```js
window.$docsify = {
maxSubLevel: 4
}
```
### load-navbar
Load navbar markdown file. If it is configured, load the current directory `_navbar.md` by default.
```html
```
You can specify a file:
```html
```
```js
window.$docsify = {
loadNavbar: '_navbar.md'
}
```
The contents of the file can be:
```markdown
- [en](/)
- [chinese](/zh-cn)
```
If you write a sub level list, it will generate a dropdown list.
```markdown
- [download](/download)
- language
- [en](/)
- [chinese](/zh-cn)
```
### auto2top
Scroll to the top on changing hash.
```html
```
```js
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.
```html
```
```js
window.$docsify = {
homepage: true
}
```
### base-path
If your HTML entry file and the markdown files are in different directories, we can use:
```html
```
```js
window.$docsify = {
basePath: '/base/'
}
```
### coverpage
Generate cover page.
```html
```
```js
window.$docsify = {
coverpage: true
}
```
### name
Project name. It is displayed in the sidebar.
```html
```
```js
window.$docsify = {
name: 'docsify'
}
```
### name-link
Name link. The default value is `window.location.pathname`.
```html
```
```js
window.$docsify = {
nameLink: '/'
}
```
### theme-color
Customize the theme color.
```html
```
```js
window.$docsify = {
themeColor: '#3F51B5'
}
```
### alias
Create aliases to certain other pages more easily.
```js
window.$docsify = {
alias: {
'/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG'
}
}
```
## Plugins
### Full Text Search
If a document can have a search, can enhance some user experience. Installing the search plugin is easy. Such as
```html
```
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'
}
}
```
### Google Analytics
Install the plugin and configure the track id.
```html
```
or
```js
window.$docsify = {
ga: 'UA-XXXXX-Y'
}
```