From 6eada5a2f75e8d1e2b6329f055a14f782406dc1f Mon Sep 17 00:00:00 2001 From: Johannes Rappen Date: Thu, 9 Mar 2017 22:19:07 +0100 Subject: [PATCH] update english docs --- docs/README.md | 14 ++++++------- docs/_sidebar.md | 20 +++++++++---------- docs/cdn.md | 15 +++++++++----- docs/configuration.md | 26 +++++++------------------ docs/cover.md | 15 +++++++------- docs/custom-navbar.md | 40 ++++++++++++++++++++++++++++++-------- docs/deploy.md | 12 ++++++------ docs/helpers.md | 11 ++++++----- docs/language-highlight.md | 12 +++++------- docs/markdown.md | 2 +- docs/more-pages.md | 7 +++---- docs/plugins.md | 27 +++++++++++++------------ docs/pwa.md | 8 +++++--- docs/quickstart.md | 20 +++++++++---------- docs/sw.js | 1 + docs/themes.md | 23 +++++++++++++--------- docs/vue.md | 20 ++++++++++++------- docs/write-a-plugin.md | 5 ++--- docs/zh-cn/_sidebar.md | 10 +++++----- 19 files changed, 159 insertions(+), 129 deletions(-) diff --git a/docs/README.md b/docs/README.md index 4d407d7..1873d46 100644 --- a/docs/README.md +++ b/docs/README.md @@ -10,13 +10,13 @@ See the [Quick start](/quickstart) for more details. ## Features -- No statically built html files -- Simple and lightweight (~16kB gzipped) -- Smart full-text search plugin -- Multiple themes -- Useful plugin API -- Emoji support -- Compatible with IE10+ +* No statically built html files +* Simple and lightweight (~16kB gzipped) +* Smart full-text search plugin +* Multiple themes +* Useful plugin API +* Emoji support +* Compatible with IE10+ ## Examples diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 9d1885b..c41ac66 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,8 +1,8 @@ - Getting started - - [Quick start](/quickstart) - - [Writing more pages](/more-pages) - - [Custom navbar](/custom-navbar) - - [Cover page](/cover) + - [Quick start](/quickstart) + - [Writing more pages](/more-pages) + - [Custom navbar](/custom-navbar) + - [Cover page](/cover) - Customization - [Configuration](/configuration) @@ -13,10 +13,10 @@ - [Language highlighting](/language-highlight) - Guide - - [Deploy](/deploy) - - [Helpers](/helpers) - - [Vue compatibility](/vue) - - [CDN](/cdn) - - [Offline Mode(PWA)](/pwa) + - [Deploy](/deploy) + - [Helpers](/helpers) + - [Vue compatibility](/vue) + - [CDN](/cdn) + - [Offline Mode(PWA)](/pwa) -- [Changelog](/changelog) \ No newline at end of file +- [Changelog](/changelog) diff --git a/docs/cdn.md b/docs/cdn.md index 1e0b2ec..63f318b 100644 --- a/docs/cdn.md +++ b/docs/cdn.md @@ -2,10 +2,8 @@ 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 @@ -14,8 +12,9 @@ Recommended: [unpkg](//unpkg.com), which will reflect the latest version as soon ``` -## Specific version +Alternatively, use [compressed files](#compressed-files). +## Specific version ```html @@ -27,7 +26,6 @@ Recommended: [unpkg](//unpkg.com), which will reflect the latest version as soon ## Compressed file - ```html @@ -36,7 +34,14 @@ Recommended: [unpkg](//unpkg.com), which will reflect the latest version as soon ``` +```html + + + + + +``` + ## Other CDN [jsDelivr](http://www.jsdelivr.com/projects/docsify) is available. - diff --git a/docs/configuration.md b/docs/configuration.md index c418aaf..f5880f0 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,6 +1,6 @@ # Configuration -docsify supports two ways to configure. You can configure the `window.$docsify` or write configuration on the script tag via `data-*` attributes. +**docsify** supports two different ways of configuration. You can configure the `window.$docsify` or write configuration on the script tag via `data-*` attributes. ```html @@ -53,7 +53,6 @@ window.$docsify = { } ``` - ## max-level - Type: `Number` @@ -72,7 +71,7 @@ window.$docsify = { - Type: `Boolean|String` - Default: `false` -Load navbar from Markdown file. If **true** it will be loaded from `_navbar.md`. +Loads navbar from the Markdown file `_navbar.md` if **true**, or else from the path specified. ```js window.$docsify = { @@ -89,8 +88,7 @@ window.$docsify = { - Type: `Boolean|String` - Default: `false` - -Load sidebar from Markdown file. If **true** it will be loaded from `_sidebar.md`. +Loads sidebar from the Markdown file `_sidebar.md` if **true**, or else from the path specified. ```js window.$docsify = { @@ -107,7 +105,7 @@ window.$docsify = { - Type: `Number` - Default: `0` -Add TOC in custom sidebar. +Add table of contents (TOC) in custom sidebar. ```js window.$docsify = { @@ -115,13 +113,11 @@ window.$docsify = { } ``` - ## auto2top - Type: `Boolean` - Default: `false` - Scrolls to the top of the screen when the route is changed. ```js @@ -130,13 +126,11 @@ window.$docsify = { } ``` - ## 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 @@ -167,7 +161,6 @@ window.$docsify = { } ``` - ## coverpage - Type: `Boolean|String` @@ -188,8 +181,7 @@ window.$docsify = { - Type: `String` - -Website name appears in the sidebar. +Website name as it appears in the sidebar. ```js window.$docsify = { @@ -222,7 +214,6 @@ window.$docsify = { See [Markdown configuration](/markdown). - ```js window.$docsify = { // object @@ -247,8 +238,7 @@ window.$docsify = { - 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. +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 = { @@ -260,7 +250,6 @@ window.$docsify = { - Type: `Object` - Set the route alias. You can freely manage routing rules. ```js @@ -276,7 +265,7 @@ window.$docsify = { - type: `Boolean` -If `loadSidebar` and `autoHeader` are both enabled, for each link in _sidebar.md, prepend a header to the page before converting it to html. [#78](https://github.com/QingWei-Li/docsify/issues/78) +If `loadSidebar` and `autoHeader` are both enabled, for each link in `_sidebar.md`, prepend a header to the page before converting it to html. Compare [#78](https://github.com/QingWei-Li/docsify/issues/78). ```js window.$docsify = { @@ -303,7 +292,6 @@ window.$docsify = { - ``` Note that if you are running an external script, e.g. an embedded jsfiddle demo, make sure to include the [external-script](plugins?id=external-script) plugin. diff --git a/docs/cover.md b/docs/cover.md index 87bd495..4d7a4ea 100644 --- a/docs/cover.md +++ b/docs/cover.md @@ -1,6 +1,6 @@ # Cover -Activate the cover feature by setting `coverpage` to **true**. Details are available in the [coverpage configuration paragraph](configuration#coverpage). +Activate the cover feature by setting `coverpage` to **true**, compare [coverpage configuration](configuration#coverpage). ## Basic usage @@ -14,16 +14,15 @@ Set `coverpage` to **true**, and create a `_coverpage.md`: coverpage: true } - + ``` - ```markdown ![logo](_media/icon.svg) -# docsify 3.0 +# docsify 3.5 > A magical documentation site generator. @@ -31,27 +30,27 @@ Set `coverpage` to **true**, and create a `_coverpage.md`: - No statically built html files - Multiple themes - [GitHub](https://github.com/QingWei-Li/docsify/) [Get Started](#docsify) ``` -!> A document site can have only one cover page. +!> A document site can have only one coverpage! ## Custom background -The background color is generated randomly by default. You can customize the background color or image: +The background color is generated randomly by default. You can customize the background color or a background image: ```markdown -# docsify +# docsify 3.5 [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 ed75539..5c436be 100644 --- a/docs/custom-navbar.md +++ b/docs/custom-navbar.md @@ -2,7 +2,9 @@ ## HTML -If you need custom navigation, you can create a HTML-based navigation bar (but note that documentation links begin with `#/`). +If you need custom navigation, you can create a HTML-based navigation bar. + +!> Note that documentation links begin with `#/`. ```html @@ -18,7 +20,7 @@ If you need custom navigation, you can create a HTML-based navigation bar (but n ## Markdown -Alternatively, you can create a custom markdown-based navigation file by setting `loadNavbar` to **true** and creating `_navbar.md`. Details are available in the [load-navbar configuration paragraph](configuration#load-navbar). +Alternatively, you can create a custom markdown-based navigation file by setting `loadNavbar` to **true** and creating `_navbar.md`, compare [load-navbar configuration](configuration#load-navbar). ```html @@ -28,10 +30,9 @@ Alternatively, you can create a custom markdown-based navigation file by setting loadNavbar: true } - + ``` - ```markdown @@ -51,10 +52,10 @@ You can create sub-lists by indenting items that are under a certain parent. - Getting started - - [Quick start](/quickstart) - - [Writing more pages](/more-pages) - - [Custom navbar](/custom-navbar) - - [Cover page](/cover) + - [Quick start](/quickstart) + - [Writing more pages](/more-pages) + - [Custom navbar](/custom-navbar) + - [Cover page](/cover) - Configuration - [Configuration](/configuration) @@ -68,4 +69,27 @@ renders as ![Nesting navbar](_images/nested-navbar.png "Nesting navbar") +## Combining custom navbars with the emoji plugin +If you use the [emoji plugin](plugins#emoji): + +```html + + + + + +``` + +you could, for example, use flag emojis in your custom navbar Markdown file: + +```markdown + + +- [:us:, :uk:](/) +- [:cn:](/zh-cn/) +``` diff --git a/docs/deploy.md b/docs/deploy.md index ed25b02..8641bb9 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -1,16 +1,16 @@ # Deploy -As as GitBook, you can deploy files to GitHub Pages or VPS. +Similar to [GitBook](https://www.gitbook.com), you can deploy files to GitHub Pages or VPS. ## GitHub Pages -There're three places to populate your docs +There're three places to populate your docs for your Github repository: -- `docs/` folder -- master branch -- gh-pages branch +* `docs/` folder +* master branch +* gh-pages branch -You can save your files in `./docs` and setting `master branch /docs folder`. +It is recommended that you save your files to the `./docs` subfolder of the `master` branch of your repository. Then select `master branch /docs folder` as your Github Pages source in your repositories' settings page. ![github pages](_images/deploy-github-pages.png) diff --git a/docs/helpers.md b/docs/helpers.md index 85a7035..fe636b2 100644 --- a/docs/helpers.md +++ b/docs/helpers.md @@ -4,23 +4,24 @@ docsify extends Markdown syntax to make your documents more readable. ## important content -Suitable for displaying important information. +Important content like: ```markdown !> **Time** is money, my friend! ``` -!> **Time** is money, my friend! +is rendered as: +!> **Time** is money, my friend! ## General tips -General tips. - +General tips like: ```markdown ?> *TODO* unit test ``` -?> *TODO* unit test +are rendered as: +?> *TODO* unit test diff --git a/docs/language-highlight.md b/docs/language-highlight.md index 22a5700..2bd8a3c 100644 --- a/docs/language-highlight.md +++ b/docs/language-highlight.md @@ -1,13 +1,11 @@ # 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. - +**docsify** uses [Prism](https://github.com/PrismJS/prism) to highlight code blocks in your pages. By default it only supports CSS, JavaScipt and HTML. You can make **Prism** load additional languages: ```html - - - + + + ``` -?> See fully supported highlight component [files list](https://github.com/PrismJS/prism/tree/gh-pages/components). +?> Check the [component files](https://github.com/PrismJS/prism/tree/gh-pages/components) list for more options. diff --git a/docs/markdown.md b/docs/markdown.md index a45f188..a50411a 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -1,6 +1,6 @@ # Markdown configuration -The Markdown parser is [marked](https://github.com/chjj/marked). You can customize how docsify renders your Markdown content to HTML. Support customize `renderer`. +**docsify** uses [marked](https://github.com/chjj/marked) as its Markdown parser. You can customize how it renders your Markdown content to HTML by customizing `renderer`: ```js window.$docsify = { diff --git a/docs/more-pages.md b/docs/more-pages.md index 7068668..59ceb33 100644 --- a/docs/more-pages.md +++ b/docs/more-pages.md @@ -16,7 +16,6 @@ For example, the directory structure is as follows: Matching routes - ```text docs/README.md => http://domain.com docs/guide.md => http://domain.com/guide @@ -38,7 +37,7 @@ First, you need to set `loadSidebar` to **true**. Details are available in the [ loadSidebar: true } - + ``` Create the `_sidebar.md`: @@ -56,7 +55,7 @@ Create the `_sidebar.md`: ## Table of Contents -A custom sidebar can also automatically generate a table of contents by setting a `subMaxLevel`. Details are available in the [max-level configuration paragraph](configuration#sub-max-level). +A custom sidebar can also automatically generate a table of contents by setting a `subMaxLevel`, compare [sub-max-level configuration](configuration#sub-max-level). ```html @@ -67,5 +66,5 @@ A custom sidebar can also automatically generate a table of contents by setting subMaxLevel: 2 } - + ``` diff --git a/docs/plugins.md b/docs/plugins.md index 8c5f8bc..225a684 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -17,7 +17,7 @@ By default, the hyperlink on the current page is recognized and the content is s '/zh-cn/', // => /zh-cn/README.md ], - // 完整配置参数 + // complete configuration parameters search: { maxAge: 86400000, // Expiration time, the default one day paths: [], // or 'auto' @@ -39,11 +39,10 @@ By default, the hyperlink on the current page is recognized and the content is s } } - - + + ``` - ## Google Analytics Install the plugin and configure the track id. @@ -54,25 +53,29 @@ Install the plugin and configure the track id. ga: 'UA-XXXXX-Y' } - - + + ``` Configure by `data-ga`. +```html + + +``` + +## front matter ```html - - + ``` ## emoji The default is to support parsing emoji. For example `:100:` will be parsed to :100:. But it is not precise because there is no matching non-emoji string. If you need to correctly parse the emoji string, you need install this plugin. - ```html - + ``` ## External Script @@ -80,7 +83,7 @@ The default is to support parsing emoji. For example `:100:` will be parsed to : If the script on the page is an external one (imports a js file via `src` attribute), you'll need this plugin to make it work. ```html - + ``` ## Zoom image @@ -88,5 +91,5 @@ If the script on the page is an external one (imports a js file via `src` attrib Medium's Image Zoom. Based on [zoom-image](https://github.com/egoist/zoom-image). ```html - + ``` diff --git a/docs/pwa.md b/docs/pwa.md index 7cf0200..e8d1c74 100644 --- a/docs/pwa.md +++ b/docs/pwa.md @@ -1,10 +1,12 @@ # Offline Mode -[Progressive Web Apps](https://developers.google.com/web/progressive-web-apps/)(PWA) are experiences that combine the best of the web and the best of apps. we can enhance our website with service workers to work **offline** or on low-quality networks. +[Progressive Web Apps](https://developers.google.com/web/progressive-web-apps/) (PWA) are experiences that combine the best of the web with the best of apps. We can enhance our website with service workers to work **offline** or on low-quality networks. + It is also very easy to use it. ## Create serviceWorker -Create a sw.js file in your documents root directory and copy this code. + +Create a `sw.js` file in your documents root directory and copy the following code: *sw.js* @@ -96,7 +98,7 @@ self.addEventListener('fetch', event => { ## Register -Now, register it in your `index.html`. It only works on some modern browsers, so we need to judge. +Now, register it in your `index.html`. It only works on some modern browsers, so we need to judge: *index.html* diff --git a/docs/quickstart.md b/docs/quickstart.md index 845ea18..7e3df39 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -8,7 +8,7 @@ npm i docsify-cli -g ## Initialize -If you want to write the documentation in the `./docs` directory, you can use the `init` command. +If you want to write the documentation in the `./docs` subdirectory, you can use the `init` command. ```bash docsify init ./docs @@ -16,20 +16,18 @@ docsify init ./docs ## Writing content -After the init is complete, you can see the file list in the docs directory. +After the `init` is complete, you can see the file list in the `./docs` subdirectory. +* `index.html` as the entry file +* `README.md` as the home page +* `.nojekyll` prevents GitHub Pages from ignoring files that begin with an underscore -- `index.html` as the entry file -- `README.md` as the home page -- `.nojekyll` prevents 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). +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 with `docsify serve`. You can preview your site in your browser on `http://localhost:3000`. - ```bash docsify serve docs ``` @@ -38,7 +36,7 @@ docsify serve docs ## Manual initialization -If you don't like npm or have trouble installing the tool, you can manually create `index.html`: +If you don't like `npm` or have trouble installing the tool, you can manually create `index.html`: ```html @@ -52,7 +50,7 @@ If you don't like npm or have trouble installing the tool, you can manually crea
- + ``` @@ -85,3 +83,5 @@ You should set the `data-app` attribute if you changed `el`: } ``` + +Compare [el configuration](/configuration#el). diff --git a/docs/sw.js b/docs/sw.js index 1e4aaeb..92df1f4 100644 --- a/docs/sw.js +++ b/docs/sw.js @@ -9,6 +9,7 @@ const RUNTIME = 'docsify' const HOSTNAME_WHITELIST = [ self.location.hostname, + 'raw.githubusercontent.com', 'fonts.gstatic.com', 'fonts.googleapis.com', 'unpkg.com' diff --git a/docs/themes.md b/docs/themes.md index ed5ae40..7c69069 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -2,35 +2,40 @@ 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/`. +!> Compressed files are available 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). +```html + + + + + +``` + +If you have any ideas or would like to develop a new theme, you are welcome to submit a [pull request](https://github.com/QingWei-Li/docsify/pulls). #### Click to preview -
vue.css buble.css dark.css
- diff --git a/docs/vue.md b/docs/vue.md index b9714ee..4eaa1fe 100644 --- a/docs/vue.md +++ b/docs/vue.md @@ -1,19 +1,21 @@ # 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. +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`. +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. +Then you can immediately write Vue code at Markdown file. `new Vue({ el: '#main' })` script is executed by default to create instance. *README.md* @@ -62,6 +64,11 @@ You can manually initialize a Vue instance. + + + + + ``` *README.md* @@ -85,5 +92,4 @@ You can manually initialize a Vue instance. ``` -?> Example Refer to the vuep [documentation](https://qingwei-li.github.io/vuep/). - +?> Example Refer to the [vuep documentation](https://qingwei-li.github.io/vuep/). diff --git a/docs/write-a-plugin.md b/docs/write-a-plugin.md index 71a74a5..045cd61 100644 --- a/docs/write-a-plugin.md +++ b/docs/write-a-plugin.md @@ -1,7 +1,6 @@ # Write a plugin -A plugin is simply a function that takes `hook` as arguments. -The hook supports handling asynchronous tasks. +A plugin is simply a function that takes `hook` as an argument. The hook supports handling of asynchronous tasks. ## Full configuration @@ -68,4 +67,4 @@ window.$docsify = { } ] } -``` \ No newline at end of file +``` diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md index d9376b4..1802cf6 100644 --- a/docs/zh-cn/_sidebar.md +++ b/docs/zh-cn/_sidebar.md @@ -1,8 +1,8 @@ - 入门 - - [快速开始](zh-cn/quickstart) - - [多页文档](zh-cn/more-pages) - - [定制导航栏](zh-cn/custom-navbar) - - [封面](zh-cn/cover) + - [快速开始](zh-cn/quickstart) + - [多页文档](zh-cn/more-pages) + - [定制导航栏](zh-cn/custom-navbar) + - [封面](zh-cn/cover) - 定制化 - [配置项](zh-cn/configuration) @@ -19,4 +19,4 @@ - [CDN](zh-cn/cdn) - [离线模式(PWA)](zh-cn/pwa) -- [Changelog](zh-cn/changelog) \ No newline at end of file +- [Changelog](zh-cn/changelog)