diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a2915e9..0365bbf8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,13 +1,14 @@ ### 2.3.0 -> 2017-02-12 +> 2017-02-13 #### Features - feat(src): add alias feature -- update all documents +- 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 diff --git a/README.md b/README.md index fc5df498..88937d14 100644 --- a/README.md +++ b/README.md @@ -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`. diff --git a/docs/README.md b/docs/README.md index efd805b0..31602abe 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,526 +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) { - // ... - - 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' -} -``` - -### 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' -} -``` 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/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 index 3f4aa27f..0b2a1c9d 100644 Binary files a/docs/_images/zh-cn/nested-navbar.png and b/docs/_images/zh-cn/nested-navbar.png differ diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 44f33bca..76261f0d 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,7 +1,7 @@ -- Get started +- Getting started - [Quick start](/quickstart) - [Writing more pages](/more-pages) - - [Custom nav](/custom-navbar) + - [Custom navbar](/custom-navbar) - [Cover page](/cover) - Configuration diff --git a/docs/cdn.md b/docs/cdn.md index e69de29b..1e0b2ec8 100644 --- a/docs/cdn.md +++ 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 index e69de29b..5af25150 100644 --- a/docs/configuration.md +++ 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 index e69de29b..7054a06b 100644 --- a/docs/cover.md +++ 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 index e69de29b..cc787410 100644 --- a/docs/custom-navbar.md +++ 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 index e69de29b..ed25b028 100644 --- a/docs/deploy.md +++ 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 index e69de29b..85a7035c 100644 --- a/docs/helpers.md +++ 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/language-highlight.md b/docs/language-highlight.md index e69de29b..22a5700c 100644 --- a/docs/language-highlight.md +++ 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 index e69de29b..d3843657 100644 --- a/docs/markdown.md +++ 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 index e69de29b..9ac0be5c 100644 --- a/docs/more-pages.md +++ 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 index e69de29b..402588f1 100644 --- a/docs/plugins.md +++ 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 index 5297e733..0628e70a 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,3 +1,63 @@ # Quick start -Remme \ No newline at end of file +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 index e69de29b..67b9a5d9 100644 --- a/docs/themes.md +++ 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 index e69de29b..40b98fd4 100644 --- a/docs/vue.md +++ 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/README.md b/docs/zh-cn/README.md index 27d26475..00035eb4 100644 --- a/docs/zh-cn/README.md +++ b/docs/zh-cn/README.md @@ -6,9 +6,9 @@ docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 `.md` 转成 `.html` 文件，所有转换工作都是在运行时进行。 -这将非常实用，如果只是需要快速的写一个小型的文档，或者不想因为生成的一堆 `.html` 文件“污染” commit 记录，只需要创建一个 `index.html` 就可以开始写文档而且直接[部署在 GitHub Pages](zh-cn/deploy)。 +这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生成的一堆 `.html` 文件“污染” commit 记录，只需要创建一个 `index.html` 就可以开始写文档而且直接[部署在 GitHub Pages](zh-cn/deploy)。 -可以查看[快速开始](zh-cn/quickstart)一章了解详情。 +查看[快速开始](zh-cn/quickstart)了解详情。 ## 特性 - 无需构建，写完文档直接发布 @@ -24,4 +24,4 @@ docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo ## 捐赠 -如果你觉得 docsify 对你有帮助，或者想对我微小的工作一些资瓷，欢迎给我[捐赠](https://github.com/QingWei-Li/donate)。 \ No newline at end of file +如果你觉得 docsify 对你有帮助，或者想对我微小的工作一点资瓷，欢迎给我[捐赠](https://github.com/QingWei-Li/donate)。 diff --git a/docs/zh-cn/cdn.md b/docs/zh-cn/cdn.md index f585793b..b9697f5e 100644 --- a/docs/zh-cn/cdn.md +++ b/docs/zh-cn/cdn.md @@ -1,6 +1,6 @@ # CDN -推荐使用 [UNPKG](//unpkg.com) —— 能及时获取到最新版。 +推荐使用 [unpkg](//unpkg.com) —— 能及时获取到最新版。 ## 获取最新版本 diff --git a/docs/zh-cn/configuration.md b/docs/zh-cn/configuration.md index 9dece41f..c79db818 100644 --- a/docs/zh-cn/configuration.md +++ b/docs/zh-cn/configuration.md @@ -1,6 +1,6 @@ # 配置项 -docsify 有两种配置参数的方式。一种是配置 `window.$docsify` 对象，另一种是给 `script` 标签添加 `data-*` 属性。 +docsify 有两种配置参数的方式。一种是配置在 `window.$docsify` 里，另一种是给 `script` 标签添加 `data-*` 属性。 ```html @@ -137,7 +137,7 @@ window.$docsify = { - 类型：`String` - 默认值: `README.md` -设置首页文件加载路径。适合不想将 `README.md` 作为入口文件渲染，或者是文档在仓库根目录的情况使用。 +设置首页文件加载路径。适合不想将 `README.md` 作为入口文件渲染，或者是文档存放在其他位置的情况使用。 ```js window.$docsify = { @@ -162,7 +162,7 @@ window.$docsify = { // 直接渲染其他域名的文档 basePath: 'https://docsify.js.org/', - // 甚至直接渲染其他仓库下的内容 + // 甚至直接渲染其他仓库 readme basePath: 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/' } ``` @@ -216,11 +216,20 @@ window.$docsify = { 参考 [Markdown 配置](/zh-cn/markdown)。 +```js +window.$docsify = { + markdown: function (marked, renderer) { + // ... + return marked + } +} +``` + ## theme-color - 类型：`String` -替换默认的主题配置。利用 CSS3 支持变量的特性，对于老的浏览器有 polyfill 处理。 +替换主题色。利用 [CSS3 支持变量]((https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_variables)的特性，对于老的浏览器有 polyfill 处理。 ```js window.$docsify = { @@ -230,6 +239,8 @@ window.$docsify = { ## alias +- 类型：`Object` + 定义路由别名，可以更自由的定义路由规则。 diff --git a/docs/zh-cn/cover.md b/docs/zh-cn/cover.md index cd6a566a..01efe710 100644 --- a/docs/zh-cn/cover.md +++ b/docs/zh-cn/cover.md @@ -1,10 +1,12 @@ # 封面 -一个有封面的文档网站会给用户留下好的印象，通过设置 `coverpage` 参数，可以开启渲染封面的功能。具体用法见见[配置项#coverpage](zh-cn/configuration#coverpage)。 +通过设置 `coverpage` 参数，可以开启渲染封面的功能。具体用法见[配置项#coverpage](zh-cn/configuration#coverpage)。 ## 基本用法 -封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 `_coverpage.md` 文件。 +封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 `_coverpage.md` 文件。渲染效果如本文档。 + +*index.html* ```html ``` -其他的语言高亮插件可以查看[Prims 仓库](https://github.com/PrismJS/prism/tree/gh-pages/components)。 \ No newline at end of file +?> 其他的语言高亮插件可以查看[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 index 579822f1..d134e1f1 100644 --- a/docs/zh-cn/markdown.md +++ b/docs/zh-cn/markdown.md @@ -1,6 +1,6 @@ # Markdown 配置 -内置的 Markdown 解析插件是 [marked](https://github.com/chjj/marked)，可以修改它的配置。 +内置的 Markdown 解析器是 [marked](https://github.com/chjj/marked)，可以修改它的配置。 ```js window.$docsify = { @@ -17,7 +17,7 @@ window.$docsify = { ```js window.$docsify = { - markdown: function(marked) { + markdown: function(marked, renderer) { // ... return marked diff --git a/docs/zh-cn/more-pages.md b/docs/zh-cn/more-pages.md index 5c558e00..455b2037 100644 --- a/docs/zh-cn/more-pages.md +++ b/docs/zh-cn/more-pages.md @@ -1,8 +1,8 @@ # 多页文档 -如果需要创建多个页面，或者需要提供多语言的文档。在 docsify 里也能很容易的实现。例如创建一个 `guide.md` 文件，那么对应的路由就是 `/#/guide`。 +如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。例如创建一个 `guide.md` 文件，那么对应的路由就是 `/#/guide`。 -一个简单的例子： +假设你的目录结构如下： ```text -| docs/ @@ -26,7 +26,7 @@ docs/zh-cn/guide.md => http://domain.com/zh-cn/guide 默认情况下，侧边栏会根据当前文档的标题生成目录。也可以设置文档链接，通过 Markdown 文件生成，效果如当前的文档的侧边栏。 -首先配置 docsify 的 `loadSidebar` 选项，具体配置规则见[配置项#load-sidebar](zh-cn/configuration#load-sidebar)一节。 +首先配置 `loadSidebar` 选项，具体配置规则见[配置项#load-sidebar](zh-cn/configuration#load-sidebar)。 ```html ``` -接着就可以直接在 Markdown 里写 Vue 了。默认会自动执行 `new Vue({ el: 'main' })` 脚本。 +接着就可以愉快地在 Markdown 里写 Vue 了。默认会执行 `new Vue({ el: 'main' })` 创建示例。 *README.md* @@ -40,6 +40,7 @@ Docsify 的一大特色是可以配合 Vue 一起使用。你可以直接在 Mar # Vue 的基本用法
hello {{ msg }}
+