diff --git a/CHANGELOG.md b/CHANGELOG.md index ac7f16a4..0365bbf8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,336 +1,66 @@ -## 2.2.1 +### 2.3.0 + +> 2017-02-13 + +#### Features + +- feat(src): add alias feature +- docs: update all documents +- feat(src): dynamic title +- feat(hook): support custom plugin +- feat(themes): add dark theme + +#### Bug fixes +- fix(event): `auto2top` has no effect on a FF mobile browser, fixed #67 +- fix: sidebar style +- fix(render): fix render link + +### 2.2.1 > 2017-02-11 -### Bug fixes +#### Bug fixes - fix(search): crash when not content, fixed #68 - fix(event): scroll active sidebar - fix(search): not work in mobile -## 2.2.0 +### 2.2.0 -### Features +#### Features - Add `Google Analytics` plugin. ```html ``` -## 2.1.0 -### Features + +### 2.1.0 +#### Features - Add search plugin ```html ``` -### Bug fixes +#### Bug fixes - fix sidebar style -## 2.0.3 -### Bug fixes +### 2.0.3 +#### Bug fixes - fix: rendering emojis - fix: css var polyfill -## 2.0.2 +### 2.0.2 -### Bug fixes +#### Bug fixes - fix button style in cover page. -## 2.0.1 -### Bug fixes +### 2.0.1 +#### Bug fixes - border style. -## 2.0.0 -### Features +### 2.0.0 +#### Features - Customize the theme color -### Break change +#### Break change - Remove `data-router`, `data-sidebar`, `data-sidebar-toggle` APIs - -## 1.10.5 -### Bug fixes -- fix initialize the Vue instance - -## 1.10.4 -### Bug fixes -- fix execute script - -## 1.10.3 -### Bug fixes -- compatible vuep QingWei-Li/vuep/issues/2 -- fix sidebar scroll, fixed #63 - -## 1.10.2 -### Bug fixes -- Fix render emojis again - -## 1.10.1 -### Bug fixes -- Fix render emojis - -## 1.10.0 -### Features -- Support emoji :laughing: - -## 1.9.0 - -### Bug fixes -- Destroys the vue instance when the route is changed - -### Features -- Add `!>` and `?>` doc helper. - -### Break change -- Remove `!` doc helper. - -## 1.8.0 -### Bug fixes -- Using `v-pre` skip compilation. - -### Features -- Execute script when vue exists. - -## 1.7.4 -### Bug fixes -- Fix bugs caused by the previous version - -## 1.7.3 -### Bug fixes -- Add `hr` style -- Fixed option is an empty string - -## 1.7.2 -### Bug fixes -- Fix sidebar click event in mobile browser. - -## 1.7.1 -### Bug fixes -- Fix sidebar style in mobile browser. - -## 1.7.0 - -### Bug fixes -- Fixed custom cover background, fixed #52 -- Fixed sticky sidebar - -## Features -- Add `name` and `nameLink` - -## 1.6.1 -### Bug fixes -- Fixed sidebar bug when the coverpage exist - -## 1.6.0 -### Features -- Improve sidebar performance. The active item is automatically scrolled in the visible view. -- New doc helper: `! `. e.g. `! content` will be rendered as `

content

` - -## 1.5.2 -### Bug fixes -- Fixed number at the beginning of the slug - -## 1.5.1 -### Bug fixes -- Remove HTML tag when handling slug - -## 1.5.0 - -### Bug fixes -- Fix slugify. -- Fix nav highlight. - -### Features -- Initialize the configuration by `window.$docsify`. -- Markdown parser is configurable. - -## 1.4.3 -### Bug fixes -- Tweak style. - -## 1.4.2 - -### Bug fixes -- Fix toggle button style. -- Support `mailto`, `tel`, etc. href type -- Fix scroll to top. - - -## 1.4.1 -### Bug fixes -- Fix generate slug. - -## 1.4.0 Happly new year 🎉 -### Features -- Display TOC in the custom sidebar, `data-sub-max-level`. -- Custom background in coverpage. - -### Bug fixes -- Fix scroll highlight when Vue exist. - -## 1.3.5 -### Bug fixes -- Fix vue - -## 1.3.4 -### Bug fixes - -- Supports [vuep](https://github.com/QingWei-Li/vuep) - -## 1.3.3 -### Bug fixes -- Fixed cover rendering timing - -## 1.3.2 - -### Bug fixes -- Fixed render link - -## 1.3.1 - -### Bug fixes -- Fixed cover page style -- Generate the correct link when rendering the article - -## 1.3.0 -### Features -- Add cover page -- add `` style -- headling can be cliked - -### Bug fixes -- sidebar highlight - - -### break change -- Navbar no longer fixed at the top - -## 1.2.0 -### Features -- custom basePath -- custom homepage - -## 1.1.7 -### Bug fixes -- Optimize progress bar - -## 1.1.6 -### Features -- Add logo 😂 - -### Bug fixes -- Remove table background color -- Fixed highlight sidebar using chinese ids - -## 1.1.5 -### Features -- Add table style - -### Bug fixes -- Not fixed position of hte navbar in the mobile browser -- Correct calculation of whether the mobile browser - -## 1.1.4 -### Bug fixes -- Fixed chinese auchor link - -## 1.1.3 -### Bug fixes -- Optimize progress bar again - -## 1.1.2 -### Bug fixes -- fix failed `auto2top` in mobile - - -## 1.1.1 -### Bug fixes -- Optimize progress bar - -## 1.1.0 -## Features -- Add progress bar -- Add `auto2top` option for hash router - -## 1.0.3 -### Bug fixes -- Fix cache - -## 1.0.2 -### Bug fixes -- Fix binding events bug, fixed #24 -- Fix regular expression, fixed #23 - -## 1.0.1 -### Bug fixes -- `img` style - -## 1.0.0 -## Features -- Support hash router - -### Bug fixes -- Improved scrolling on mobile - -## 0.7.0 -### Breaking change -- `themes/` was removed, only exists in the npm package. - -### Bug fixes -- Fix style. -- Fix sidebar animation again. - -## 0.6.1 -### Bug fixes -- In the mobile, it should collapse the sidebar when toggle is clicked. -- Fix the dropdown list style. -- Fix sidebar animation. - -## 0.6.0 -### Features -- Navbar support dropdown list, #6 -- Sidebar with toggle - -### Bug fixes -- Fix ineffective option, fixed #10 - -## 0.5.0 -### Features -- Custom sidebars and navbars by markdown file - -## 0.4.2 -### Bug fixes -- Correct catch ajax error - -## 0.4.1 -### Bug fixes -- catch ajax error - -## 0.4.0 -### Features -- Custom sidebar - -### Bug fixes -- Fix undefined language - -## 0.3.1 -### Bug fixes -- Strip HTML tag when rendering the headings - -## 0.3.0 -### Features -- Add minified css files -- Add max level option -- Add pure.css - -## 0.2.1 -### Bug fixes -- Fix vue.css - -## 0.2.0 -### Bug fixes -- Fix route -- Remove dynamic title - -## 0.1.0 -### Features -- Add buble.css \ No newline at end of file diff --git a/HISTORY.md b/HISTORY.md new file mode 100644 index 00000000..d3cc3e3c --- /dev/null +++ b/HISTORY.md @@ -0,0 +1,287 @@ +### 1.10.5 +#### Bug fixes +- fix initialize the Vue instance + +### 1.10.4 +#### Bug fixes +- fix execute script + +### 1.10.3 +#### Bug fixes +- compatible vuep QingWei-Li/vuep/issues/2 +- fix sidebar scroll, fixed #63 + +### 1.10.2 +#### Bug fixes +- Fix render emojis again + +### 1.10.1 +#### Bug fixes +- Fix render emojis + +### 1.10.0 +#### Features +- Support emoji :laughing: + +### 1.9.0 + +#### Bug fixes +- Destroys the vue instance when the route is changed + +#### Features +- Add `!>` and `?>` doc helper. + +#### Break change +- Remove `!` doc helper. + +### 1.8.0 +#### Bug fixes +- Using `v-pre` skip compilation. + +### Features +- Execute script when vue exists. + +### 1.7.4 +#### Bug fixes +- Fix bugs caused by the previous version + +### 1.7.3 +#### Bug fixes +- Add `hr` style +- Fixed option is an empty string + +### 1.7.2 +#### Bug fixes +- Fix sidebar click event in mobile browser. + +### 1.7.1 +#### Bug fixes +- Fix sidebar style in mobile browser. + +### 1.7.0 + +#### Bug fixes +- Fixed custom cover background, fixed #52 +- Fixed sticky sidebar + +### Features +- Add `name` and `nameLink` + +### 1.6.1 +#### Bug fixes +- Fixed sidebar bug when the coverpage exist + +### 1.6.0 +#### Features +- Improve sidebar performance. The active item is automatically scrolled in the visible view. +- New doc helper: `! `. e.g. `! content` will be rendered as `

content

` + +### 1.5.2 +#### Bug fixes +- Fixed number at the beginning of the slug + +### 1.5.1 +#### Bug fixes +- Remove HTML tag when handling slug + +### 1.5.0 + +#### Bug fixes +- Fix slugify. +- Fix nav highlight. + +#### Features +- Initialize the configuration by `window.$docsify`. +- Markdown parser is configurable. + +### 1.4.3 +#### Bug fixes +- Tweak style. + +### 1.4.2 + +#### Bug fixes +- Fix toggle button style. +- Support `mailto`, `tel`, etc. href type +- Fix scroll to top. + + +### 1.4.1 +#### Bug fixes +- Fix generate slug. + +### 1.4.0 Happly new year 🎉 +#### Features +- Display TOC in the custom sidebar, `data-sub-max-level`. +- Custom background in coverpage. + +#### Bug fixes +- Fix scroll highlight when Vue exist. + +### 1.3.5 +#### Bug fixes +- Fix vue + +### 1.3.4 +#### Bug fixes + +- Supports [vuep](https://github.com/QingWei-Li/vuep) + +### 1.3.3 +#### Bug fixes +- Fixed cover rendering timing + +### 1.3.2 + +#### Bug fixes +- Fixed render link + +### 1.3.1 + +#### Bug fixes +- Fixed cover page style +- Generate the correct link when rendering the article + +### 1.3.0 +#### Features +- Add cover page +- add `` style +- headling can be cliked + +#### Bug fixes +- sidebar highlight + + +#### break change +- Navbar no longer fixed at the top + +### 1.2.0 +#### Features +- custom basePath +- custom homepage + +### 1.1.7 +#### Bug fixes +- Optimize progress bar + +### 1.1.6 +#### Features +- Add logo 😂 + +#### Bug fixes +- Remove table background color +- Fixed highlight sidebar using chinese ids + +### 1.1.5 +#### Features +- Add table style + +#### Bug fixes +- Not fixed position of hte navbar in the mobile browser +- Correct calculation of whether the mobile browser + +### 1.1.4 +#### Bug fixes +- Fixed chinese auchor link + +### 1.1.3 +#### Bug fixes +- Optimize progress bar again + +### 1.1.2 +#### Bug fixes +- fix failed `auto2top` in mobile + + +### 1.1.1 +#### Bug fixes +- Optimize progress bar + +### 1.1.0 +#### Features +- Add progress bar +- Add `auto2top` option for hash router + +### 1.0.3 +#### Bug fixes +- Fix cache + +### 1.0.2 +#### Bug fixes +- Fix binding events bug, fixed #24 +- Fix regular expression, fixed #23 + +### 1.0.1 +#### Bug fixes +- `img` style + +### 1.0.0 +#### Features +- Support hash router + +#### Bug fixes +- Improved scrolling on mobile + +### 0.7.0 +#### Breaking change +- `themes/` was removed, only exists in the npm package. + +#### Bug fixes +- Fix style. +- Fix sidebar animation again. + +### 0.6.1 +#### Bug fixes +- In the mobile, it should collapse the sidebar when toggle is clicked. +- Fix the dropdown list style. +- Fix sidebar animation. + +### 0.6.0 +#### Features +- Navbar support dropdown list, #6 +- Sidebar with toggle + +#### Bug fixes +- Fix ineffective option, fixed #10 + +### 0.5.0 +#### Features +- Custom sidebars and navbars by markdown file + +### 0.4.2 +#### Bug fixes +- Correct catch ajax error + +### 0.4.1 +#### Bug fixes +- catch ajax error + +### 0.4.0 +#### Features +- Custom sidebar + +#### Bug fixes +- Fix undefined language + +### 0.3.1 +#### Bug fixes +- Strip HTML tag when rendering the headings + +### 0.3.0 +#### Features +- Add minified css files +- Add max level option +- Add pure.css + +### 0.2.1 +#### Bug fixes +- Fix vue.css + +### 0.2.0 +#### Bug fixes +- Fix route +- Remove dynamic title + +### 0.1.0 +#### Features +- Add buble.css \ No newline at end of file diff --git a/README.md b/README.md index 66cf9cd0..88937d14 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@

Travis Status npm - code style + donate

## Links @@ -19,10 +19,12 @@ - [CLI](https://github.com/QingWei-Li/docsify-cli) ## Features -- Simple and lightweight (~13kB gzipped) -- Multiple themes - Not build static html files -- Support emoji :laughing: +- Simple and lightweight (~13kB gzipped) +- Smart full-text search plugin +- Multiple themes +- Useful plugin API +- Compatible with IE9+ ## Quick start Create a `index.html`. @@ -43,10 +45,6 @@ index.html ``` -## CDN -- UNPKG [https://unpkg.com/docsify/](https://unpkg.com/docsify/) -- jsDelivr [http://www.jsdelivr.com/projects/docsify](http://www.jsdelivr.com/projects/docsify) - ## Browser Support Modern browsers and Internet Explorer 9+. @@ -54,7 +52,6 @@ Modern browsers and Internet Explorer 9+. ## Showcase These open-source projects are using docsify to generate their sites. Pull requests welcome : ) -- [docsify](https://docsify.js.org) - A magical documentation site generator. - [Snipaste](https://docs.snipaste.com/) - A new way to boost your productivity. - [puck](https://puck.zz173.com/) - A small & magical php framework. - [Samaritan](http://samaritan.stockdb.org) - An Algorithmic Trading Framework for Digital Currency. @@ -82,14 +79,5 @@ npm i && npm run dev open http://localhost:3000 ``` -## More Language Highlight - -```html - - - -``` - ## License MIT - diff --git a/dev.html b/dev.html index 11faff77..54becd0a 100644 --- a/dev.html +++ b/dev.html @@ -2,18 +2,23 @@ + docsify
- diff --git a/docs/README.md b/docs/README.md index e83f66f3..31602abe 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,514 +1,27 @@ -## 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 -![image](https://cloud.githubusercontent.com/assets/7565692/20639058/e65e6d22-b3f3-11e6-9b8b-6309c89826f2.png) - -## 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 -![logo](_media/icon.svg) - -# docsify 1.2.0 +## docsify > A magical documentation site generator. -- Simple and lightweight (~12kb gzipped) -- Multiple themes +## What is it + +docsify generates your documentation website on the fly. Unlike GitBook, it does not generate static html files. It smartly loads and parses your Markdown files and displays them in website. All you need to do is create an `index.html` to start and [deploy it on GitHub Pages](/deploy). + +See the [Quick start](/quickstart) for more details. + +## Features + - Not build static html files +- Simple and lightweight (~13kB gzipped) +- Smart full-text search plugin +- Multiple themes +- Useful plugin API +- Compatible with IE9+ +## Examples -[GitHub](https://github.com/QingWei-Li/docsify/) -[Get Started](#quick-start) -``` +Check out the [Showcase](https://github.com/QingWei-Li/docsify/#showcase) to see use the docsify generated website. -#### Custom background -Currently the background of the cover page is generated randomly. We can customize the background color, or add a background image. +## Donate -```markdown -# docsify 1.2.0 +If you think docsify is helpful to you or that my work is valuable. I am happy if you can help me [buy a cup of coffee](https://github.com/QingWei-Li/donate). :heart: -> xxx - -[GitHub](https://github.com/QingWei-Li/docsify/) -[Get Started](#quick-start) - - -![](_media/bg.png) - -![color](#f0f0f0) -``` - -### 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, renderer) { - // ... - - 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 - -``` - -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' -} -``` - -## 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' -} -``` diff --git a/docs/_coverpage.md b/docs/_coverpage.md index 47336500..0a84e863 100644 --- a/docs/_coverpage.md +++ b/docs/_coverpage.md @@ -6,7 +6,6 @@ - Simple and lightweight (~13kB gzipped) - Not build static html files -- Support emoji :laughing: - Multiple themes diff --git a/docs/_images/deploy-github-pages.png b/docs/_images/deploy-github-pages.png new file mode 100644 index 00000000..278e40b3 Binary files /dev/null and b/docs/_images/deploy-github-pages.png differ diff --git a/docs/_images/nested-navbar.png b/docs/_images/nested-navbar.png new file mode 100644 index 00000000..25f23418 Binary files /dev/null and b/docs/_images/nested-navbar.png differ diff --git a/docs/_images/zh-cn/nested-navbar.png b/docs/_images/zh-cn/nested-navbar.png new file mode 100644 index 00000000..0b2a1c9d Binary files /dev/null and b/docs/_images/zh-cn/nested-navbar.png differ diff --git a/docs/favicon.ico b/docs/_media/favicon.ico similarity index 100% rename from docs/favicon.ico rename to docs/_media/favicon.ico diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 00000000..76261f0d --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,20 @@ +- Getting started + - [Quick start](/quickstart) + - [Writing more pages](/more-pages) + - [Custom navbar](/custom-navbar) + - [Cover page](/cover) + +- Configuration + - [Configuration](/configuration) + - [Themes](/themes) + - [Using plugins](/plugins) + - [Markdown configuration](/markdown) + - [Lanuage highlight](/language-highlight) + +- Guide + - [Deploy](/deploy) + - [Doc helper](/helpers) + - [Compatible Vue](/vue) + - [CDN](/cdn) + +- [Changelog](/changelog) \ No newline at end of file diff --git a/docs/cdn.md b/docs/cdn.md new file mode 100644 index 00000000..1e0b2ec8 --- /dev/null +++ b/docs/cdn.md @@ -0,0 +1,42 @@ +# CDN + +Recommended: [unpkg](//unpkg.com), which will reflect the latest version as soon as it is published to npm. You can also browse the source of the npm package at [unpkg.com/docsify/](//unpkg.com/docsify/). + + +## Latest version + + +```html + + + + + +``` + +## Specific version + + +```html + + + + + +``` + +## Compressed file + + +```html + + + + + +``` + +## Other CDN + +[jsDelivr](http://www.jsdelivr.com/projects/docsify) is available. + diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..5af25150 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,256 @@ +# Configuration + +docsify supports two ways to configure. You can configure the `window.$docsify` or write configuration on the script tag via `data-*` attributes. + +```html + + + + + +``` + +Both ways are compatible. However, the first way is recommended. It is clear and can be configured in a separate file. + +!> In `window.$docsfiy`, the options should be written by camelCase. + +## el + +- Type: `String` +- Default: `#app` + +The DOM element to be mounted on initialization. It can be a CSS selector string or an actual HTMLElement. + +```js +window.$docsify = { + el: '#app' +} +``` + +## repo + +- Type: `String` +- Default: `null` + +Configure the repository url or a string of `username/repo` can add the [GitHub Corner](http://tholman.com/github-corners/) widget in the top right corner of the site. + +```js +window.$docsify = { + repo: 'QingWei-Li/docsify', + // or + repo: 'https://github.com/QingWei-Li/docsify/' +} +``` + + +## max-level + +- Type: `Number` +- Default: `6` + +Maximum Table of content level. + +```js +window.$docsify = { + maxLevel: 4 +} +``` + +## load-navbar + +- Type: `Boolean|String` +- Default: `false` + +Load navbar from Markdown file. If **true** it will be loaded from `_navbar.md`. + +```js +window.$docsify = { + // load from _navbar.md + loadNavbar: true, + + // load from nav.md + loadNavbar: 'nav.md' +} +``` + +## load-sidebar + +- Type: `Boolean|String` +- Default: `false` + + +Load sidebar from Markdown file. If **true** it will be loaded from `_sidebar.md`. + +```js +window.$docsify = { + // load from _sidebar.md + loadSidebar: true, + + // load from summary.md + loadSidebar: 'summary.md' +} +``` + +## sub-max-level + +- Type: `Number` +- Default: `0` + +Add TOC in custom sidebar. + +```js +window.$docsify = { + subMaxLevel: 3 +} +``` + + +## auto2top + +- Type: `Boolean` +- Default: `false` + + +Scrolls to the top of the screen when the route is changed. + +```js +window.$docsify = { + auto2top: true +} +``` + + +## homepage + +- Type: `String` +- Default: `README.md` + + +`README.md` in your docs folder will be treated as homepage for your website, but sometimes you may need to serve another file as your homepage. + +```js +window.$docsify = { + // Change to /home.md + homepage: 'home.md', + + // Or use the readme in your repo + homepage: 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/README.md' +} +``` + +## base-path + +- Type: `String` + +Base path of the website. You can set it to another directory or another domain name. + +```js +window.$docsify = { + basePath: '/path/', + + // Load the files from another site + basePath: 'https://docsify.js.org/', + + // Even can load files from other repo + basePath: 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/' +} +``` + + +## coverpage + +- Type: `Boolean|String` +- Default: `false` + +Activate the [cover feature](/cover). If ture, it will load from `_coverpage.md`. + +```js +window.$docsify = { + coverpage: true, + + // Custom file name + coverpage: 'cover.md' +} +``` + +## name + +- Type: `String` + + +Website name appears in the sidebar. + +```js +window.$docsify = { + name: 'docsify' +} +``` + +## name-link + +- Type: `String` +- Default: `window.location.pathname` + +The name of the link. + +```js +window.$docsify = { + nameLink: '/' +} +``` + +## markdown + +- Type: `Function` + +See [Markdown configuration](/markdown). + + +```js +window.$docsify = { + markdown: function (marked, renderer) { + // ... + return marked + } +} +``` + +## theme-color + +- Type: `String` + +Customize the theme color. +Use [CSS3 variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables) feature and polyfill in old browser. + +```js +window.$docsify = { + themeColor: '#3F51B5' +} +``` + +## alias + +- Type: `Object` + + +Set the route alias. You can freely manage routing rules. + +```js +window.$docsify = { + alias: { + '/zh-cn/changelog': '/changelog', + '/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG' + } +} +``` diff --git a/docs/cover.md b/docs/cover.md new file mode 100644 index 00000000..7054a06b --- /dev/null +++ b/docs/cover.md @@ -0,0 +1,57 @@ +# Cover + +Activate the cover feature by setting `coverpage`. The detail in [Configuration#coverpage](zh-cn/configuration#coverpage). + +## Basic usage + +Set `coverpage` to **true**, and create a `_coverpage.md`. You can see the effect in current website. + + +*index.html* + +```html + + +``` + +*_coverpage.md* + +```markdown +![logo](_media/icon.svg) + +# docsify + +> 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) +``` + +!> A document site can have only one cover page. + +## Custom background + +The background color is generated randomly by default. You can customize the background color or image. + +*_coverpage.md* + +```markdown +# docsify + +[GitHub](https://github.com/QingWei-Li/docsify/) +[Get Started](#quick-start) + + +![](_media/bg.png) + +![color](#f0f0f0) +``` diff --git a/docs/custom-navbar.md b/docs/custom-navbar.md new file mode 100644 index 00000000..cc787410 --- /dev/null +++ b/docs/custom-navbar.md @@ -0,0 +1,66 @@ +# Custom navbar + +You can create navbar in HTML file. But note that the link begins with `#/`. + +*index.html* + +```html + + +
+ +``` + +## Writing by Markdown + +You can custom navbar by Markdown file. Set the `loadNavbar` to **true** and create a `_navbar.md`. The detail in [Configuration#load-navbar](configuration#load-navbar). + +*index.html* + + +```html + + +``` + +*_navbar.md* + + +```markdown +- [En](/) +- [chinese](/zh-cn/) +``` + +`_navbar.md` is loaded from each level directory. If this directory doesn't have `_navbar.md`, it will fallback to parent directory. For example, the current path is `/guide/quick-start`, the `_navbar.md` will be loaded from `/guide/_navbar.md`. + +## Nesting + +You can create sub-lists by indenting items that are under a certain parent. + +```markdown +- Getting started + - [Quick start](/quickstart) + - [Writing more pages](/more-pages) + - [Custom navbar](/custom-navbar) + - [Cover page](/cover) + +- Configuration + - [Configuration](/configuration) + - [Themes](/themes) + - [Using plugins](/plugins) + - [Markdown configuration](/markdown) + - [Lanuage highlight](/language-highlight) +``` + +Example. + +![Nesting navbar](_images/nested-navbar.png "Nesting navbar") + + diff --git a/docs/deploy.md b/docs/deploy.md new file mode 100644 index 00000000..ed25b028 --- /dev/null +++ b/docs/deploy.md @@ -0,0 +1,33 @@ +# Deploy + +As as GitBook, you can deploy files to GitHub Pages or VPS. + +## GitHub Pages + +There're three places to populate your docs + +- `docs/` folder +- master branch +- gh-pages branch + +You can save your files in `./docs` and setting `master branch /docs folder`. + +![github pages](_images/deploy-github-pages.png) + +!> You can also save files in the root directory and select `master branch`. + +## VPS + +Try following nginx config. + +```nginx +server { + listen 80; + server_name your.domain.com; + + location / { + alias /path/to/dir/of/docs; + index index.html; + } +} +``` diff --git a/docs/helpers.md b/docs/helpers.md new file mode 100644 index 00000000..85a7035c --- /dev/null +++ b/docs/helpers.md @@ -0,0 +1,26 @@ +# Doc helper + +docsify extends Markdown syntax to make your documents more readable. + +## important content + +Suitable for displaying important information. + +```markdown +!> **Time** is money, my friend! +``` + +!> **Time** is money, my friend! + + +## General tips + +General tips. + + +```markdown +?> *TODO* unit test +``` + +?> *TODO* unit test + diff --git a/docs/index.html b/docs/index.html index 56af51f2..7748c821 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2,8 +2,9 @@ - docsify - A magical documentation site generator. - + docsify + + @@ -11,16 +12,27 @@
- + + + diff --git a/docs/language-highlight.md b/docs/language-highlight.md new file mode 100644 index 00000000..22a5700c --- /dev/null +++ b/docs/language-highlight.md @@ -0,0 +1,13 @@ +# language highlight + + +The code language highlight tool is [Prism](https://github.com/PrismJS/prism). Only supports CSS, JavaScipt and HTML by default. You can load its component to highlight the language you need. + + +```html + + + +``` + +?> See fully supported highlight component [files list](https://github.com/PrismJS/prism/tree/gh-pages/components). diff --git a/docs/markdown.md b/docs/markdown.md new file mode 100644 index 00000000..d3843657 --- /dev/null +++ b/docs/markdown.md @@ -0,0 +1,26 @@ +# Markdown configuration + +The Markdown parser is [marked](https://github.com/chjj/marked). You can customize how docsify renders your Markdown content to HTML. + +```js +window.$docsify = { + markdown: { + smartypants: true + // ... + } +} +``` + +?> Configuration Options Reference [marked documentation](https://github.com/chjj/marked#options-1) + +Even you can completely customize the parsing rules. + +```js +window.$docsify = { + markdown: function(marked, renderer) { + // ... + + return marked + } +} +``` diff --git a/docs/more-pages.md b/docs/more-pages.md new file mode 100644 index 00000000..9ac0be5c --- /dev/null +++ b/docs/more-pages.md @@ -0,0 +1,66 @@ +# More pages + +If you need more pages multi-level routing site. It is easy to achieve in docsify. A simple example: If you create a `guide.md`, then get the route is `/#/guide`. + +For example, the directory structure is as follows: + + +```text +-| docs/ + -| README.md + -| guide.md + -| zh-cn/ + -| README.md + -| guide.md +``` + +Matching routes + + +```text +docs/README.md => http://domain.com +docs/guide.md => http://domain.com/guide +docs/zh-cn/README.md => http://domain.com/zh-cn/ +docs/zh-cn/guide.md => http://domain.com/zh-cn/guide +``` + +## Custom sidebar + +By default, the TOC in sidebar is automatically generated based on Markdown file. You can create a Table of Contents page to list down pages in your site. + +First, you need to set `loadSidebar` to **true**. The detail in [Configuration#load-sidebar](configuration#load-sidebar). + +```html + + +``` + +Create the `_sidebar.md` + +```markdown +- [Home](/) +- [Guide](/guide) +``` + +!> Need create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore. + +`_sidebar.md` is loaded from each level directory. If this directory doesn't have `_sidebar.md`, it will fallback to parent directory. For example, the current path is `/guide/quick-start`, the `_sidebar.md` will be loaded from `/guide/_sidebar.md`. + +## Table of Contents + +Custom sidebar can also be automatically generate TOC by setting `subMaxLevel`. The detail in [Configuration#sub-max-level](configuration#sub-max-level). + +```html + + +``` + diff --git a/docs/plugins.md b/docs/plugins.md new file mode 100644 index 00000000..402588f1 --- /dev/null +++ b/docs/plugins.md @@ -0,0 +1,119 @@ +# Using plugins + +## List of Plugins + +### Full text search + +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. + + +```html + + + +``` + + +### Google Analytics + +Install the plugin and configure the track id. + +```html + + + +``` + +Configure by `data-ga`. + + +```html + + +``` + + +## Write a plugin + +A plugin is simply a function that takes `hook` as arguments. +The hook supports handling asynchronous tasks. + +#### Full configuration + +```js +window.$docsify = { + plugins: [ + function (hook) { + hook.init(function() { + // Called when the script starts running, only trigger once. + }) + + hook.beforeEach(function(content) { + // Invoked each time before parsing the Markdown file. + // ... + return content + }) + + hook.afterEach(function(html, next) { + // Invoked each time after the Markdown file is parsed. + // beforeEach and afterEach support asynchronous。 + // ... + // call `next(html)` when task is done. + next(html) + }) + + hook.ready(function() { + // Called after initialization is complete. Only trigger once. + }) + } + ] +} +``` + +!> You can get internal methods through `window.Docsify.utils`. + +#### Example + +Add footer component in each pages. + +```js +window.$docsify = { + plugins: [ + function (hook) { + var footer = [ + '
', + '' + ].join('') + + hook.afterEach(function (html) { + return html + footer + }) + } + ] +} +``` diff --git a/docs/quickstart.md b/docs/quickstart.md new file mode 100644 index 00000000..0628e70a --- /dev/null +++ b/docs/quickstart.md @@ -0,0 +1,63 @@ +# Quick start + +Recommended install `docsify-cli` globally, which can help us to initialize and preview the website locally. + +```bash +npm i docsify-cli -g +``` + +## initialize + +If you want to write the documentation in `./docs` directory, you can use the `init` command. + +```bash +docsify init ./docs +``` + +## Writing content + +After the init is complete, you can see the file list in the docs directory. + + +- `index.html` as the entry file +- `README.md` as the home page +- `.nojekyll` can prevent GitHub Pages from ignoring files that begin with an underscore + +You can easily update the documentation in `docs/README.md`, of course you can add [more pages](more-pages). + +## Preview your site + +Run the local server via `docsify serve`. You can preview your site in browser via http://localhost:3000. + + +```bash +docsify serve docs +``` + +?> More usages of reference [docsify-cli documentation](https://github.com/QingWei-Li/docsify-cli). + +## Manually + +If you don't like npm or feel the trouble to install the tool. What we need is an `index.html`. + +*index.html* + +```html + + + + + + + +
+ + + +``` + +If your system has Python, you can easily to run a static server to preview your site. + +```bash +cd docs && python -m SimpleHTTPServer 3000 +``` diff --git a/docs/themes.md b/docs/themes.md new file mode 100644 index 00000000..67b9a5d9 --- /dev/null +++ b/docs/themes.md @@ -0,0 +1,14 @@ +# Themes + +There are currently three themes available. Copy [Vue](//vuejs.org) and [buble](//buble.surge.sh) website custom theme and [@liril-net](https://github.com/liril-net) contribution to the theme of the black style. + + +```html + + + +``` + +!> This compressed files in `/lib/themes/`. + +If you have any ideas or would like to develop new theme, welcome submit [PR](https://github.com/QingWei-Li/docsify/pulls). diff --git a/docs/vue.md b/docs/vue.md new file mode 100644 index 00000000..40b98fd4 --- /dev/null +++ b/docs/vue.md @@ -0,0 +1,89 @@ +# Compatible with Vue + +You can write Vue components directly in the Markdown file, and it will be parsed. +You can use this feature to write vue demo and documentation together. + +## Basic usage + +Load the Vue in `index.html`. + +```html + + +``` + +Then you can immediately write Vue code at Markdown file. +`new Vue({ el: 'main' })` script is executed by default to create instance. + +*README.md* + +```markdown +# Vue guide + +`v-for` usage. + +```html + +`` + + +``` + +You can manually initialize a Vue instance. + +*README.md* + +```markdown +# Vue demo + +
hello {{ msg }}
+ + +``` + +!> In a Markdown file, only the script within the first script tag is executed. + +## Combine Vuep to write playground + +[Vuep](https://github.com/QingWei-Li/vuep) is a component for rendering Vue components with live editor and preview. Supports Vue component spec and JSX. + +*index.html* + +```html + + + +``` + +*README.md* +```markdown +# Vuep + + + + + +``` + +?> Example Refer to the vuep [documentation](https://qingwei-li.github.io/vuep/). + diff --git a/docs/zh-cn.md b/docs/zh-cn.md deleted file mode 100644 index ce8b5301..00000000 --- a/docs/zh-cn.md +++ /dev/null @@ -1,520 +0,0 @@ - -## 特性 -- 无需构建，写完 markdown 直接发布 -- 支持自定义主题 -- 容易使用并且轻量 (~12kb gzipped) - -## 快速上手 - -### 创建项目 -新建一个空项目，接着创建一个 `docs` 目录并进入到 docs 目录下 -```bash -mkdir my-project && cd my-project -mkdir docs && cd docs -``` - -### 创建入口文件 -创建一个 `index.html` 文件，内容为 -```html - - - - - - - -
- - - -``` - -新建 `README.md` 文件，作为主页面 - -``` -# Title - -## balabala -``` - -### 部署！ -将项目 `push` 到 GitHub 仓库后到设置页面开启 **GitHub Pages** 功能，选择 `docs/` 选项 -![image](https://cloud.githubusercontent.com/assets/7565692/20639058/e65e6d22-b3f3-11e6-9b8b-6309c89826f2.png) - -## 命令行工具 - -方便快速创建文档目录，会读取项目的 `package.json` 里的选项作为 docsify 的配置，支持本地预览。 - -### 安装 -```bash -npm i docsify-cli -g -``` - -### 初始化文档 - -默认初始化在当前目录，推荐将文档放在 `docs` 目录下 -```bash -docsify init docs -``` - -### 启动本地服务 -启动一个 server 方便预览，打开 http://localhost:3000 -```bash -docsify serve docs -``` - -更多选项参考 [docsify-cli](https://github.com/QingWei-Li/docsify-cli) - - -## 更多功能 - -### 主题 -目前提供 vue.css 和 buble.css，直接修改 `index.html` 里的 cdn 地址即可 -```html - - -``` - -压缩版 - -```html - - -``` - -### 多页面 -`README.md` 作为主页面，如果需要其他页面，直接在文档目录下创建对应的 `*.md` 文件，例如创建一个 `guide.md` 那么对应的路由就是 `/#/guide`。 - -### 导航 -导航需要自己写在 `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) - -### 封面 - -只需要写几行简单的 markdown 就可以拥有一页精致的封面，通过添加 `data-coverpage` 属性，并创建 `_coverpage.md`，按照下面的格式书写即可。 - -```markdown -![logo](_media/icon.svg) - -# 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) -``` - - -#### 自定义封面背景 -默认的背景是随机生成的，你可以自定义背景色或者背景图片。只需要在文档末尾用添加图片的 Markdown 语法 - -```markdown -# docsify 1.2.0 - -> xxx - -[GitHub](https://github.com/QingWei-Li/docsify/) -[Get Started](#quick-start) - - -![](_media/bg.png) - -![color](#f0f0f0) -``` - -### 自定义 Markdown parser - -默认使用 [marked](https://github.com/chjj/marked) 处理 markdown 部分，你可以修改默认配置 - -```js -window.$docsify = { - markdown: { - smartypants: true - } -} -``` - -甚至可以完全定制化 - -```js -window.$docsify = { - markdown: function(marked, renderer) { - // ... - - return marked - } -} -``` - -### 文档助手 -#### 内置「提示」语法 - -`!>`后面接内容，会渲染成带 tip 类名的段落。 - -```markdown -!> 提示信息，**支持其他 markdown 语法** -``` - -将被渲染成 - -```html -

提示信息支持其他 markdown 语法

-``` - -效果 - -!> 适合显示醒目的内容 - -#### 内置「警示」语法 - -`?>`后面接内容，会渲染成带 warn 类名的段落。 - -```markdown -?> 警示内容样式 -``` - -效果 - -?> 警示内容样式 - -### 结合 Vue - -`index.html` 内引入 Vue 后，可以在文档里直接写 Vue 语法。默认会自己初始化一个 Vue 示例，当然我们也可以手动初始化一个实例。 - -index.html -```html - - -``` - -```markdown - -``` - -手动初始化示例 - -```markdown -
- -

Hello, {{ msg }}

-
- - -``` - -## 配置参数 - -你可以通过在标签上添加属性的方式，或者给 `window.$docsify` 传配置信息。 - -### repo -参考本文档的右上角的 GitHub 图标，如果要开启的话，将 `index.html` 里的 script 改成 - -```html - -``` - - -```js -window.$docsify = { - repo: 'your/repo' -} -``` - -### max-level -目录最大展开层级，默认值为 6 - -```html - -``` - - -```js -window.$docsify = { - maxLevel: 6 -} -``` - -### el -替换节点元素，默认为 `#app` -```html - -``` - - -```js -window.$docsify = { - el: '#app' -} -``` - -### load-sidebar - -读取侧边栏配置文件，如果配置，默认加载当前目录下的 `_sidebar.md`。如果文件不存在，会显示 TOC 作为侧边栏内容。如果你有二级目录，也应该放置一份配置文件。 -**如果用 `_` 开头作为文件名，你应该在文档目录下添加 `.nojekyll`，阻止 GitHub Pages 忽略下划线开头的文件。** - -```html - -``` - - -你可以指定侧边栏文件名 - -```html - -``` - -```js -window.$docsify = { - loadSidebar: '_sidebar.md' -} -``` - -`_sidebar.md` 的内容可以是这样的 - -```markdown -- [Home](/) -- [Installation](/installation) -- Essentials - - [Getting Started](/getting-started) - - [Dynamic Route Matching](/dynamic-matching) - - [Nested Routes](/nested-routes) -``` - -### sub-max-level - -显示 TOC 在自定义的侧边栏里，默认最大显示 0 层。 - - -```html - -``` - -```js -window.$docsify = { - maxSubLevel: 4 -} -``` - -### load-navbar - -读取导航配置文件，如果配置，默认加载当前目录下的 `_navbar.md`。如果文件不存在，会显示 html 里定义的导航栏。 - -```html - -``` - -你可以指定导航栏文件名 - -```html - -``` - -```js -window.$docsify = { - loadNavbar: '_navbar.md' -} -``` - -`_navbar.md` 的内容可以是这样 - -```markdown -- [en](/) -- [中文](/zh-cn) -``` - -当然也支持二级列表，将生成一个下拉列表 -```markdown -- [download](/download) -- language - - [en](/) - - [中文](/zh-cn) -``` - - -### auto2top - -切换路由时自动跳转到页面顶部 - - -```html - -``` - -```js -window.$docsify = { - auto2top: true -} -``` - -### homepage - -默认情况下网站会将根目录下 `README.md` 作为首页渲染，但是有些时候我们想指定其他文件，甚至想直接将 repo 下的 README 作为首页。 - - -```html - - - -``` - -```js -window.$docsify = { - homepage: true -} -``` - -### base-path - -指定加载文档的路径，如果你的 HTML 入口文件和文档是放在不同地方，你可以设置： - -```html - - - - -``` - - -```js -window.$docsify = { - basePath: '/base/' -} -``` - -### coverpage - -生成封面，参考 [#封面](/zh-cn#封面). - -```html - - - - -``` - - -```js -window.$docsify = { - coverpage: true -} -``` - - -### name - -项目名，将显示在侧边栏。 - -```html - -``` - -```js -window.$docsify = { - name: 'docsify' -} -``` - -### name-link - -项目名链接，默认为 `window.location.pathname`。 - -```html - -``` - -```js -window.$docsify = { - nameLink: '/' -} -``` - -### theme-color - -自定义主题色。 - - -```html - -``` - -```js -window.$docsify = { - themeColor: '#3F51B5' -} -``` - -## Plugins - -### 全文检索 - search - -一份文档如果能有搜索功能会提升一些用户体验，加载搜索插件也很简单，直接引入就自动安装并启用。默认情况下会自动分析当前页面上的超链接，获取内容后建立索引并存储在 `localStorage` 里，默认过期时间为一天，当然这是可配置的。 - -自动识别的方式不一定能识别完整或者如果你想指定某些文件可索引，你可以自己指定文件的路径。 - -```html - - -``` - -!> 配置要在 docsify 引入之前 - -```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 - -安装插件并且配置 track id。 - -```html - - -``` - -或者 - -```js -window.$docsify = { - ga: 'UA-XXXXX-Y' -} -``` diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md new file mode 100644 index 00000000..00035eb4 --- /dev/null +++ b/docs/zh-cn/README.md @@ -0,0 +1,27 @@ +## docsify + +> 一个神奇的文档网站生成工具 + +## 是什么 + +docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 `.md` 转成 `.html` 文件，所有转换工作都是在运行时进行。 + +这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生成的一堆 `.html` 文件“污染” commit 记录，只需要创建一个 `index.html` 就可以开始写文档而且直接[部署在 GitHub Pages](zh-cn/deploy)。 + +查看[快速开始](zh-cn/quickstart)了解详情。 + +## 特性 +- 无需构建，写完文档直接发布 +- 容易使用并且轻量 (~13Kb gzipped) +- 智能的全文检索 +- 提供多套主题 +- 丰富的 API +- 兼容 IE9+ + +## 例子 + +可以查看 [Showcase](https://github.com/QingWei-Li/docsify/#showcase) 来了解使用 docsify 的文档项目。 + +## 捐赠 + +如果你觉得 docsify 对你有帮助，或者想对我微小的工作一点资瓷，欢迎给我[捐赠](https://github.com/QingWei-Li/donate)。 diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md new file mode 100644 index 00000000..e911c388 --- /dev/null +++ b/docs/zh-cn/_sidebar.md @@ -0,0 +1,20 @@ +- 入门 + - [快速开始](zh-cn/quickstart) + - [多页文档](zh-cn/more-pages) + - [定制导航栏](zh-cn/custom-navbar) + - [封面](zh-cn/cover) + +- 配置 + - [配置项](zh-cn/configuration) + - [主题](zh-cn/themes) + - [使用插件](zh-cn/plugins) + - [Markdown 配置](zh-cn/markdown) + - [代码高亮](zh-cn/language-highlight) + +- 指南 + - [部署](zh-cn/deploy) + - [文档助手](zh-cn/helpers) + - [兼容 Vue](zh-cn/vue) + - [CDN](zh-cn/cdn) + +- [Changelog](zh-cn/changelog) \ No newline at end of file diff --git a/docs/zh-cn/cdn.md b/docs/zh-cn/cdn.md new file mode 100644 index 00000000..b9697f5e --- /dev/null +++ b/docs/zh-cn/cdn.md @@ -0,0 +1,48 @@ +# CDN + +推荐使用 [unpkg](//unpkg.com) —— 能及时获取到最新版。 + +## 获取最新版本 + +根据 UNPKG 的规则，不指定特定版本号时将引入最新版。 + +```html + + + + + +``` + +## 获取指定版本 + +如果担心频繁地版本更新又可能引入未知 Bug，我们也可以使用具体的版本。规则是 `//unpkg.com/docsify@VERSION/` + +```html + + + + + +``` + +!> 指定 *VERSION* 为 `latest` 可以强制每次都请求最新版本。 + +## 压缩版 + +CSS 的压缩文件位于 `/lib/themes/` 目录下 + +```html + +``` + +JS 的压缩文件是原有文件路径的基础上加 `.min`后缀 + +```html + +``` + +## 其他 CDN + +[jsDelivr](http://www.jsdelivr.com/projects/docsify) 也是可用的，具体用法参考其文档。 + diff --git a/docs/zh-cn/configuration.md b/docs/zh-cn/configuration.md new file mode 100644 index 00000000..c79db818 --- /dev/null +++ b/docs/zh-cn/configuration.md @@ -0,0 +1,255 @@ +# 配置项 + +docsify 有两种配置参数的方式。一种是配置在 `window.$docsify` 里，另一种是给 `script` 标签添加 `data-*` 属性。 + +```html + + + + + +``` + +两种方式可以共存，推荐第一种做法——直接配置 `window.$docsify` 对象——这会让你的配置更加清晰，同时也可以方便的将配置单独写到另一个文件里。 + +!> 通过 `window.$docsify` 配置属性，需要将属性改成驼峰命名法。通过 `data-*` 属性配置，保持短横线的命名规则。 + + +## el + +- 类型：`String` +- 默认值：`#app` + +docsify 初始化的挂载元素，可以是一个 CSS 选择器，默认为 `#app` 如果不存在就直接绑定在 `body` 上。 + +```js +window.$docsify = { + el: '#app' +} +``` + +## repo + +- 类型：`String` +- 默认值: `null` + +配置仓库地址或者 `username/repo` 的字符串，会在页面右上角渲染一个 [GitHub Corner](http://tholman.com/github-corners/) 挂件。 + +```js +window.$docsify = { + repo: 'QingWei-Li/docsify', + // or + repo: 'https://github.com/QingWei-Li/docsify/' +} +``` + + +## max-level + +- 类型：`Number` +- 默认值: `6` + +默认情况下会抓取文档中所有标题渲染成目录，可配置最大支持渲染的标题层级。 + + +```js +window.$docsify = { + maxLevel: 4 +} +``` + +## load-navbar + +- 类型：`Boolean|String` +- 默认值: `false` + +加载自定义导航栏，参考[定制导航栏](zh-cn/custom-navbar) 了解用法。设置为 `true` 后会加载 `_navbar.md` 文件，也可以自定义加载的文件名。 + +```js +window.$docsify = { + // 加载 _navbar.md + loadNavbar: true, + + // 加载 nav.md + loadNavbar: 'nav.md' +} +``` + +## load-sidebar + +- 类型：`Boolean|String` +- 默认值: `false` + +加载自定义侧边栏，参考[多页文档](zh-cn/more-pages)。设置为 `true` 后会加载 `_sidebar.md` 文件，也可以自定义加载的文件名。 + +```js +window.$docsify = { + // 加载 _sidebar.md + loadSidebar: true, + + // 加载 summary.md + loadSidebar: 'summary.md' +} +``` + +## sub-max-level + +- 类型：`Number` +- 默认值: `0` + +自定义侧边栏后默认不会再生成目录，你也可以通过设置生成目录的最大层级开启这个功能， + + +```js +window.$docsify = { + subMaxLevel: 3 +} +``` + + +## auto2top + +- 类型：`Boolean` +- 默认值: `false` + +切换页面后是否自动跳转到页面顶部。 + +```js +window.$docsify = { + auto2top: true +} +``` + + +## homepage + +- 类型：`String` +- 默认值: `README.md` + +设置首页文件加载路径。适合不想将 `README.md` 作为入口文件渲染，或者是文档存放在其他位置的情况使用。 + +```js +window.$docsify = { + // 入口文件改为 /home.md + homepage: 'home.md', + + // 文档和仓库根目录下的 README.md 内容一致 + homepage: 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/README.md' +} +``` + +## base-path + +- 类型：`String` + +文档加载的根路径，可以是二级路径或者是其他域名的路径。 + +```js +window.$docsify = { + basePath: '/path/', + + // 直接渲染其他域名的文档 + basePath: 'https://docsify.js.org/', + + // 甚至直接渲染其他仓库 readme + basePath: 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/' +} +``` + + +## coverpage + +- 类型：`Boolean|String` +- 默认值: `false` + +启用[封面页](/zh-cn/cover)。开启后是加载 `_coverpage.md` 文件，也可以自定义文件名。 + +```js +window.$docsify = { + coverpage: true, + + // 自定义文件名 + coverpage: 'cover.md' +} +``` + +## name + +- 类型：`String` + + +文档标题，会显示在侧边栏顶部。 + +```js +window.$docsify = { + name: 'docsify' +} +``` + +## name-link + +- 类型：`String` +- 默认值：`window.location.pathname` + +点击文档标题后跳转的链接地址。 + +```js +window.$docsify = { + nameLink: '/' +} +``` + +## markdown + +- 类型: `Function` + +参考 [Markdown 配置](/zh-cn/markdown)。 + +```js +window.$docsify = { + markdown: function (marked, renderer) { + // ... + return marked + } +} +``` + +## theme-color + +- 类型：`String` + +替换主题色。利用 [CSS3 支持变量]((https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables)的特性，对于老的浏览器有 polyfill 处理。 + +```js +window.$docsify = { + themeColor: '#3F51B5' +} +``` + +## alias + +- 类型：`Object` + +定义路由别名，可以更自由的定义路由规则。 + + +```js +window.$docsify = { + alias: { + '/zh-cn/changelog': '/changelog', + '/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG' + } +} +``` + diff --git a/docs/zh-cn/cover.md b/docs/zh-cn/cover.md new file mode 100644 index 00000000..01efe710 --- /dev/null +++ b/docs/zh-cn/cover.md @@ -0,0 +1,58 @@ +# 封面 + +通过设置 `coverpage` 参数，可以开启渲染封面的功能。具体用法见[配置项#coverpage](zh-cn/configuration#coverpage)。 + +## 基本用法 + +封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 `_coverpage.md` 文件。渲染效果如本文档。 + +*index.html* + +```html + + +``` + +*_coverpage.md* + +```markdown +![logo](_media/icon.svg) + +# docsify + +> 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) +``` + + + +!> 一份文档只会在根目录下加载封面，其他页面或者二级目录下都不会加载。 + +## 自定义背景 + +目前的背景是随机生成的渐变色，我们自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。 + +*_coverpage.md* + +```markdown +# docsify + +[GitHub](https://github.com/QingWei-Li/docsify/) +[Get Started](#quick-start) + + +![](_media/bg.png) + +![color](#f0f0f0) +``` diff --git a/docs/zh-cn/custom-navbar.md b/docs/zh-cn/custom-navbar.md new file mode 100644 index 00000000..56708656 --- /dev/null +++ b/docs/zh-cn/custom-navbar.md @@ -0,0 +1,67 @@ +# 自定义导航栏 + +我们可以直接在 HTML 里定义导航栏，要注意链接要以 `#/` 开头。 + +*index.html* + +```html + + +
+ +``` + + +## 配置文件 + +那我们可以通过 Markdown 文件来配置导航。首先配置 `loadNavbar`，默认加载的文件为 `_navbar.md`。具体配置规则见[配置项#load-navbar](zh-cn/configuration#load-navbar)。 + +*index.html* + + +```html + + +``` + +*_navbar.md* + +```markdown +- [En](/) +- [中文](/zh-cn/) +``` + +`_navbar.md` 加载逻辑和 `sidebar` 文件一致，从每层目录下获取。例如当前路由为 `/zh-cn/custom-navbar` 那么是从 `/zh-cn/_navbar.md` 获取导航栏。 + +## 嵌套 + +如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式。 + +*_navbar.md* + + +```markdown +- 基础 + - [快速开始](zh-cn/quickstart) + - [多页文档](zh-cn/more-pages) + - [定制导航栏](zh-cn/custom-navbar) + - [封面](zh-cn/cover) + +- 配置 + - [配置项](zh-cn/configuration) + - [主题](zh-cn/themes) + - [使用插件](zh-cn/plugins) + - [Markdown 配置](zh-cn/markdown) + - [代码高亮](zh-cn/language-highlight) +``` + +效果图 + +![嵌套导航栏](_images/zh-cn/nested-navbar.png "嵌套导航栏") diff --git a/docs/zh-cn/deploy.md b/docs/zh-cn/deploy.md new file mode 100644 index 00000000..7126f556 --- /dev/null +++ b/docs/zh-cn/deploy.md @@ -0,0 +1,34 @@ +# 部署 + +和 GitBook 生成的文档一样，我们可以直接把文档网站部署到 GitHub Pages 或者 VPS 上。 + +## GitHub Pages + +GitHub Pages 支持从三个地方读取文件 +- `docs/` 目录 +- master 分支 +- gh-pages 分支 + +我们推荐直接将文档放在 `docs/` 目录下，在设置页面开启 **GitHub Pages** 功能并选择 `master branch /docs folder` 选项。 + +![github pages](_images/deploy-github-pages.png) + +!> 可以将文档放在根目录下，然后选择 **master 分支** 作为文档目录。 + +## VPS + +和部署所有静态网站一样，只需将服务器的访问根目录设定为 `index.html` 文件。 + +例如 nginx 的配置 + +```nginx +server { + listen 80; + server_name your.domain.com; + + location / { + alias /path/to/dir/of/docs; + index index.html; + } +} +``` diff --git a/docs/zh-cn/helpers.md b/docs/zh-cn/helpers.md new file mode 100644 index 00000000..ec8b76e6 --- /dev/null +++ b/docs/zh-cn/helpers.md @@ -0,0 +1,26 @@ +# 文档助手 + +docsify 扩展了一些 Markdown 语法，可以让文档更易读。 + + +## 强调内容 + +适合显示重要的提示信息，语法为 `!> 内容`。 + +```markdown +!> 一段重要的内容，可以和其他 **Markdown** 语法混用。 +``` + +!> 一段重要的内容，可以和其他 **Markdown** 语法混用。 + + +## 普通提示 + +普通的提示信息，比如写 TODO 或者参考内容等。 + +```markdown +?> *TODO* 完善示例 +``` + +?> *TODO* 完善示例 + diff --git a/docs/zh-cn/language-highlight.md b/docs/zh-cn/language-highlight.md new file mode 100644 index 00000000..dffae89b --- /dev/null +++ b/docs/zh-cn/language-highlight.md @@ -0,0 +1,11 @@ +# 代码高亮 + +内置的代码高亮工具是 [Prism](https://github.com/PrismJS/prism)，默认支持 CSS、JavaScript 和 HTML。如果需要高亮其语言——例如 PHP——可以手动引入代码高亮插件。 + +```html + + + +``` + +?> 其他的语言高亮插件可以查看[Prims 仓库](https://github.com/PrismJS/prism/tree/gh-pages/components)。 \ No newline at end of file diff --git a/docs/zh-cn/markdown.md b/docs/zh-cn/markdown.md new file mode 100644 index 00000000..d134e1f1 --- /dev/null +++ b/docs/zh-cn/markdown.md @@ -0,0 +1,26 @@ +# Markdown 配置 + +内置的 Markdown 解析器是 [marked](https://github.com/chjj/marked)，可以修改它的配置。 + +```js +window.$docsify = { + markdown: { + smartypants: true + // ... + } +} +``` + +?> 完整配置参数参考 [marked 文档](https://github.com/chjj/marked#options-1) + +当然也可以完全定制 Markdown 解析规则。 + +```js +window.$docsify = { + markdown: function(marked, renderer) { + // ... + + return marked + } +} +``` \ No newline at end of file diff --git a/docs/zh-cn/more-pages.md b/docs/zh-cn/more-pages.md new file mode 100644 index 00000000..455b2037 --- /dev/null +++ b/docs/zh-cn/more-pages.md @@ -0,0 +1,66 @@ +# 多页文档 + +如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。例如创建一个 `guide.md` 文件，那么对应的路由就是 `/#/guide`。 + +假设你的目录结构如下： + +```text +-| docs/ + -| README.md + -| guide.md + -| zh-cn/ + -| README.md + -| guide.md +``` + +那么对应的访问页面将是 + +```text +docs/README.md => http://domain.com +docs/guide.md => http://domain.com/guide +docs/zh-cn/README.md => http://domain.com/zh-cn/ +docs/zh-cn/guide.md => http://domain.com/zh-cn/guide +``` + +## 定制侧边栏 + +默认情况下，侧边栏会根据当前文档的标题生成目录。也可以设置文档链接，通过 Markdown 文件生成，效果如当前的文档的侧边栏。 + +首先配置 `loadSidebar` 选项，具体配置规则见[配置项#load-sidebar](zh-cn/configuration#load-sidebar)。 + +```html + + +``` + +接着创建 `_sidebar.md` 文件，内容如下 + +```markdown +- [首页](zh-cn/) +- [指南](zh-cn/guide) +``` + +!> 需要在文档根目录创建 `.nojekyll` 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。 + + +`_sidebar.md` 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 `/zh-cn/more-pages` 则从 `/zh-cn/_sidebar.md` 获取文件，如果不存在则从 `/_sidebar.md` 获取。 + +## 显示目录 + +自定义侧边栏同时也可以开启目录功能。设置 `subMaxLevel` 配置项，具体介绍见 [配置项#sub-max-level](zh-cn/configuration#sub-max-level)。 + +```html + + +``` + + diff --git a/docs/zh-cn/plugins.md b/docs/zh-cn/plugins.md new file mode 100644 index 00000000..30bcdd5d --- /dev/null +++ b/docs/zh-cn/plugins.md @@ -0,0 +1,114 @@ +# 使用插件 + +## 内置插件 + +### 全文检索 - Search + +全文检索插件会根据当前页面上的超链接获取文档内容，在 `localStorage` 内建立文档索引。默认过期时间为一天，当然我们可以自己指定需要缓存的文件列表或者配置过期时间。 + + +```html + + + +``` + +### 谷歌统计 - Google Analytics + +需要配置 track id 才能使用。 + +```html + + + +``` + +也可以通过 `data-ga` 配置 id。 + +```html + + +``` + +## 自定义插件 + +docsify 提供了一套插件机制，其中提供的钩子（hook）支持处理异步逻辑，可以很方便的扩展功能。 + +#### 完整功能 + +```js +window.$docsify = { + plugins: [ + function (hook) { + hook.init(function() { + // 初始化时调用，只调用一次 + }) + + hook.beforeEach(function(content) { + // 每次开始解析 Markdown 内容时调用 + // ... + return content + }) + + hook.afterEach(function(html, next) { + // 解析成 html 后调用。beforeEach 和 afterEach 支持处理异步逻辑 + // ... + // 异步处理完成后调用 next(html) 返回结果 + next(html) + }) + + hook.ready(function() { + // docsify 初始化完成后调用，只调用一次 + }) + } + ] +} +``` + +!> 如果需要用 docsify 的内部方法，可以通过 `window.Docsify.utils` 获取。 + +#### 例子 + +给每个页面的末尾加上 `footer` + +```js +window.$docsify = { + plugins: [ + function (hook) { + var footer = [ + '
', + '' + ].join('') + + hook.afterEach(function (html) { + return html + footer + }) + } + ] +} +``` diff --git a/docs/zh-cn/quickstart.md b/docs/zh-cn/quickstart.md new file mode 100644 index 00000000..c4ebc282 --- /dev/null +++ b/docs/zh-cn/quickstart.md @@ -0,0 +1,61 @@ +# 快速开始 + +推荐安装 `docsify-cli` 工具，可以方便创建及本地预览文档网站。 + +```bash +npm i docsify-cli -g +``` + +## 初始化项目 + +如果想在项目的 `./docs` 目录里写文档，直接通过 `init` 初始化项目。 + +```bash +docsify init ./docs +``` + +## 开始写文档 + +初始化成功后，可以看到 `./docs` 目录下创建的几个文件 + +- `index.html` 入口文件 +- `README.md` 会做为主页内容渲染 +- `.nojekyll` 用于阻止 GitHub Pages 会忽略掉下划线开头的文件 + +直接编辑 `docs/README.md` 就能更新网站内容，当然也可以[写多个页面](zh-cn/more-pages)。 + +## 本地预览网站 + +运行一个本地服务器通过 `docsify serve` 可以方便的预览效果，而且提供 LiveReload 功能，可以让实时的预览。默认访问 http://localhost:3000 。 + +```bash +docsify serve docs +``` + +?> 更多命令行工具用法，参考 [docsify-cli 文档](https://github.com/QingWei-Li/docsify-cli)。 + +## 手动初始化 + +如果不喜欢 npm 或者觉得安装工具太麻烦，我们其实只需要直接创建一个 `index.html` 文件。 + +*index.html* + +```html + + + + + + + +
+ + + +``` + +如果系统里安装 Python 的话，也可以很轻易的启动一个静态服务器。 + +```bash +cd docs && python -m SimpleHTTPServer 3000 +``` diff --git a/docs/zh-cn/themes.md b/docs/zh-cn/themes.md new file mode 100644 index 00000000..b728d7ab --- /dev/null +++ b/docs/zh-cn/themes.md @@ -0,0 +1,13 @@ +# 主题 + +目前提供三套主题可供选择，模仿 [Vue](//vuejs.org) 和 [buble](//buble.surge.sh) 官网订制的主题样式。还有 [@liril-net](https://github.com/liril-net) 贡献的黑色风格的主题。 + +```html + + + +``` + +!> CSS 的压缩文件位于 `/lib/themes/` + +如果你有其他想法或者想开发别的主题，欢迎提 [PR](https://github.com/QingWei-Li/docsify/pulls)。 \ No newline at end of file diff --git a/docs/zh-cn/vue.md b/docs/zh-cn/vue.md new file mode 100644 index 00000000..37dd8079 --- /dev/null +++ b/docs/zh-cn/vue.md @@ -0,0 +1,87 @@ +# 兼容 Vue + +你可以直接在 Markdown 文件里写 Vue 代码，它将被执行。我们可以用它写一些 Vue 的 Demo 或者示例代码。 + + +## 基础用法 + +在 `index.html` 里引入 Vue。 + +```html + + +``` + +接着就可以愉快地在 Markdown 里写 Vue 了。默认会执行 `new Vue({ el: 'main' })` 创建示例。 + +*README.md* + +```markdown +# Vue 介绍 + +`v-for` 的用法 + +```html + +`` + + +``` + +当然你也可以手动初始化 Vue，这样你可以自定义一些配置。 + +*README.md* + +```markdown +# Vue 的基本用法 + +
hello {{ msg }}
+ + +``` + +!> 一个 Markdown 文件里只有第一个 `script` 标签内的内容会被执行。 + +## 搭配 Vuep 写 Playground + +[Vuep](https://github.com/QingWei-Li/vuep) 是一个提供在线编辑和预览效果的 Vue 组件，搭配 docsify 可以直接在文档里写 Vue 的示例代码，支持 Vue component spec 和 JSX。 + +*index.html* + +```html + + + +``` + +*README.md* +```markdown +# Vuep 使用 + + + + + +``` + +?> 具体效果参考 [Vuep 文档](https://qingwei-li.github.io/vuep/)。 diff --git a/src/event.js b/src/event.js index 72130cc2..536899c0 100644 --- a/src/event.js +++ b/src/event.js @@ -19,7 +19,9 @@ export function scrollActiveSidebar () { for (let i = 0, len = lis.length; i < len; i += 1) { const li = lis[i] - let href = li.querySelector('a').getAttribute('href') + const a = li.querySelector('a') + if (!a) continue + let href = a.getAttribute('href') if (href !== '/') { const match = href.match('#([^#]+)$') @@ -135,8 +137,10 @@ export function bindToggle (dom) { } } +const scrollingElement = document.scrollingElement || document.documentElement + export function scroll2Top (offset = 0) { - document.body.scrollTop = offset === true ? 0 : Number(offset) + scrollingElement.scrollTop = offset === true ? 0 : Number(offset) } export function sticky () { diff --git a/src/hook.js b/src/hook.js new file mode 100644 index 00000000..311103d9 --- /dev/null +++ b/src/hook.js @@ -0,0 +1,52 @@ +export default class Hook { + constructor () { + this.beforeHooks = [] + this.afterHooks = [] + this.initHooks = [] + this.readyHooks = [] + } + + beforeEach (fn) { + this.beforeHooks.push(fn) + } + + afterEach (fn) { + this.afterHooks.push(fn) + } + + init (fn) { + this.initHooks.push(fn) + } + + ready (fn) { + this.readyHooks.push(fn) + } + + emit (name, data, next) { + let newData = data + const queue = this[name + 'Hooks'] + const step = function (index) { + const hook = queue[index] + if (index >= queue.length) { + next && next(newData) + } else { + if (typeof hook === 'function') { + if (hook.length === 2) { + hook(data, result => { + newData = result + step(index + 1) + }) + } else { + const result = hook(data) + newData = result !== undefined ? result : newData + step(index + 1) + } + } else { + step(index + 1) + } + } + } + + step(0) + } +} diff --git a/src/index.js b/src/index.js index 3604f3f6..066d0949 100644 --- a/src/index.js +++ b/src/index.js @@ -1,6 +1,7 @@ import * as utils from './util' import { scrollIntoView, activeLink } from './event' import * as render from './render' +import Hook from './hook' const OPTIONS = utils.merge({ el: '#app', @@ -33,11 +34,14 @@ if (script) { if (OPTIONS.name === true) OPTIONS.name = '' } +const hook = new Hook() + // utils window.$docsify = OPTIONS window.Docsify = { installed: true, - utils: utils.merge({}, utils) + utils: utils.merge({}, utils), + hook } // load options @@ -46,11 +50,20 @@ render.init() let cacheRoute = null let cacheXhr = null +const getAlias = function (route) { + if (OPTIONS.alias[route]) { + return getAlias(OPTIONS.alias[route]) + } else { + return route + } +} + const mainRender = function (cb) { - const route = OPTIONS.basePath + utils.getRoute() + let page + let route = utils.getRoute() if (cacheRoute === route) return cb() - let basePath = cacheRoute = route + let basePath = cacheRoute = OPTIONS.basePath + route if (!/\//.test(basePath)) { basePath = '' @@ -58,10 +71,18 @@ const mainRender = function (cb) { basePath = basePath.match(/(\S*\/)[^\/]+$/)[1] } - let page + // replace route + route = '/' + route + if (OPTIONS.alias && OPTIONS.alias[route]) { + route = getAlias(route) + } else { + route = (OPTIONS.basePath + route).replace(/\/+/, '/') + } if (!route) { page = OPTIONS.homepage || 'README.md' + } else if (/\.md$/.test(route)) { + page = route } else if (/\/$/.test(route)) { page = `${route}README.md` } else { @@ -99,21 +120,26 @@ const mainRender = function (cb) { } const Docsify = function () { - const dom = document.querySelector(OPTIONS.el) || document.body - const replace = dom !== document.body - const main = function () { - mainRender(_ => { - scrollIntoView() - activeLink('nav') - ;[].concat(window.$docsify.plugins).forEach(fn => fn && fn()) - }) - } + setTimeout(_ => { + ;[].concat(OPTIONS.plugins).forEach(fn => typeof fn === 'function' && fn(hook)) + window.Docsify.hook.emit('init') - // Render app - render.renderApp(dom, replace) - main() - if (!/^#\//.test(window.location.hash)) window.location.hash = '#/' - window.addEventListener('hashchange', main) + const dom = document.querySelector(OPTIONS.el) || document.body + const replace = dom !== document.body + const main = function () { + mainRender(_ => { + scrollIntoView() + activeLink('nav') + }) + } + + // Render app + render.renderApp(dom, replace) + main() + if (!/^#\//.test(window.location.hash)) window.location.hash = '#/' + window.addEventListener('hashchange', main) + window.Docsify.hook.emit('ready') + }, 0) } export default Docsify() diff --git a/src/plugins/ga.js b/src/plugins/ga.js index 5200240c..40c455f2 100644 --- a/src/plugins/ga.js +++ b/src/plugins/ga.js @@ -25,18 +25,18 @@ function collect () { } const install = function () { - if (!window.Docsify || !window.Docsify.installed) { - console.error('[Docsify] Please load docsify.js first.') - return - } + if (install.installed) return + install.installed = true if (!window.$docsify.ga) { console.error('[Docsify] ga is required.') return } - collect() - window.$docsify.plugins = [].concat(window.$docsify.plugins, collect) + window.$docsify.plugins = [].concat(function (hook) { + hook.init(collect) + hook.beforeEach(collect) + }, window.$docsify.plugins) } export default install() diff --git a/src/plugins/search.js b/src/plugins/search.js index 17aff340..b76e1d02 100644 --- a/src/plugins/search.js +++ b/src/plugins/search.js @@ -44,8 +44,7 @@ const getAllPaths = function () { /** * return file path */ -const genFilePath = function (path) { - const basePath = window.$docsify.basePath +const genFilePath = function (path, basePath = window.$docsify.basePath) { let filePath = /\/$/.test(path) ? `${path}README.md` : `${path}.md` filePath = basePath + filePath @@ -294,6 +293,7 @@ const searchPlugin = function () { const paths = isAuto ? getAllPaths() : CONFIG.paths const len = paths.length const { load, marked, slugify } = window.Docsify.utils + const alias = window.$docsify.alias const done = () => { localStorage.setItem('docsify.search.expires', Date.now() + CONFIG.maxAge) localStorage.setItem('docsify.search.index', JSON.stringify(INDEXS)) @@ -301,8 +301,16 @@ const searchPlugin = function () { paths.forEach(path => { if (INDEXS[path]) return count++ + let route - load(genFilePath(path)).then(content => { + // replace route + if (alias && alias[path]) { + route = genFilePath(alias[path] || path, '') + } else { + route = genFilePath(path) + } + + load(route).then(content => { genIndex(path, marked(content)) slugify.clear() count++ @@ -313,12 +321,8 @@ const searchPlugin = function () { } const install = function () { - if (!window.Docsify || !window.Docsify.installed) { - console.error('[Docsify] Please load docsify.js first.') - return - } - - window.$docsify.plugins = [].concat(window.$docsify.plugins, searchPlugin) + if (install.installed) return + install.installed = true const userConfig = window.$docsify.search const isNil = window.Docsify.utils.isNil @@ -331,7 +335,15 @@ const install = function () { CONFIG.placeholder = userConfig.placeholder || CONFIG.placeholder } - new SearchComponent() + window.$docsify.plugins = [].concat(hook => { + const isAuto = CONFIG.paths === 'auto' + + hook.ready(() => { + new SearchComponent() + !isAuto && searchPlugin() + }) + isAuto && hook.beforeEach(searchPlugin) + }, window.$docsify.plugins) } export default install() diff --git a/src/render.js b/src/render.js index 8b49f1c2..05cef156 100644 --- a/src/render.js +++ b/src/render.js @@ -8,6 +8,7 @@ import { genTree, getRoute, isMobile, slugify, merge, emojify } from './util' let markdown = marked let toc = [] const CACHE = {} +const originTitle = document.title const renderTo = function (dom, content) { dom = typeof dom === 'object' ? dom : document.querySelector(dom) @@ -42,10 +43,9 @@ export function init () { return `
${hl}
` } renderer.link = function (href, title, text) { - if (!/:/.test(href)) { + if (!/:|(\/{2})/.test(href)) { href = `#/${href}`.replace(/\/+/g, '/') } - return `${text}` } renderer.paragraph = function (text) { @@ -56,6 +56,12 @@ export function init () { } return `

${text}

` } + renderer.image = function (href, title, text) { + const url = /:|(\/{2})/.test(href) ? href : ($docsify.basePath + href).replace(/\/+/g, '/') + const titleHTML = title ? ` title="${title}"` : '' + + return `${text}` + } if (typeof $docsify.markdown === 'function') { markdown = $docsify.markdown.call(this, markdown, renderer) @@ -118,25 +124,34 @@ export function renderApp (dom, replace) { * article */ export function renderArticle (content) { - renderTo('article', content ? markdown(content) : 'not found') - if (!$docsify.loadSidebar) renderSidebar() + const hook = window.Docsify.hook + const renderFn = function (data) { + renderTo('article', data) + if (!$docsify.loadSidebar) renderSidebar() - if (content && typeof Vue !== 'undefined') { - CACHE.vm && CACHE.vm.$destroy() + if (data && typeof Vue !== 'undefined') { + CACHE.vm && CACHE.vm.$destroy() - const script = [].slice.call( - document.body.querySelectorAll('article>script')) - .filter(script => !/template/.test(script.type) - )[0] - const code = script ? script.innerText.trim() : null + const script = [].slice.call( + document.body.querySelectorAll('article>script')) + .filter(script => !/template/.test(script.type) + )[0] + const code = script ? script.innerText.trim() : null - script && script.remove() - CACHE.vm = code - ? new Function(`return ${code}`)() - : new Vue({ el: 'main' }) // eslint-disable-line - CACHE.vm && CACHE.vm.$nextTick(_ => event.scrollActiveSidebar()) + script && script.remove() + CACHE.vm = code + ? new Function(`return ${code}`)() + : new Vue({ el: 'main' }) // eslint-disable-line + CACHE.vm && CACHE.vm.$nextTick(_ => event.scrollActiveSidebar()) + } + if ($docsify.auto2top) setTimeout(() => event.scroll2Top($docsify.auto2top), 0) } - if ($docsify.auto2top) setTimeout(() => event.scroll2Top($docsify.auto2top), 0) + + hook.emit('before', content, result => { + const html = result ? markdown(result) : '' + + hook.emit('after', html, result => renderFn(result || 'not found')) + }) } /** @@ -165,15 +180,21 @@ export function renderSidebar (content) { } renderTo('.sidebar-nav', html) + + if (toc[0] && toc[0].level === 1) { + document.title = `${toc[0].title}${originTitle ? ' - ' + originTitle : ''}` + } + const target = event.activeLink('.sidebar-nav', true) if (target) renderSubSidebar(target) - toc = [] + toc = [] event.scrollActiveSidebar() } export function renderSubSidebar (target) { if (!$docsify.subMaxLevel) return + toc[0] && toc[0].level === 1 && toc.shift() target.parentNode.innerHTML += tpl.tree(genTree(toc, $docsify.subMaxLevel), '