diff --git a/docs/cdn.md b/docs/cdn.md index 05fff3c28..37acde825 100644 --- a/docs/cdn.md +++ b/docs/cdn.md @@ -1,48 +1,53 @@ # CDN -Recommended: [jsDelivr](//cdn.jsdelivr.net), 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 [cdn.jsdelivr.net/npm/docsify/](//cdn.jsdelivr.net/npm/docsify/). +Recommended: [jsDelivr](//cdn.jsdelivr.net). You can also browse the source of the npm package at [cdn.jsdelivr.net/npm/docsify/](//cdn.jsdelivr.net/npm/docsify/). -## Latest version +## Specific version (RECOMMENDED) ```html - + - + ``` -Alternatively, use [compressed files](#compressed-file). +## Latest version (_NOT_ RECOMMENDED!) -## Specific version +We highly recommend you do **not** use this method. -```html - - - - - -``` - -## Compressed file +Using the latest version can break your app when docsify is updated due to +breaking changes, either when accidental bugs are introduced, or when a new +major version is realeased with altered features. ```html - + ``` +## Uncompressed files for debugging + ```html - + - + ``` -## Other CDN +## Other CDNs - https://www.bootcdn.cn/docsify/ - https://cdn.jsdelivr.net/npm/docsify/ diff --git a/docs/cover.md b/docs/cover.md index bf8c3c54e..eb1486369 100644 --- a/docs/cover.md +++ b/docs/cover.md @@ -11,10 +11,10 @@ Set `coverpage` to **true**, and create a `_coverpage.md`: - + ``` ```markdown @@ -81,7 +81,7 @@ Now, you can set ```js window.$docsify = { - coverpage: ['/', '/zh-cn/'] + coverpage: ['/', '/zh-cn/'], }; ``` @@ -91,7 +91,7 @@ Or a special file name window.$docsify = { coverpage: { '/': 'cover.md', - '/zh-cn/': 'cover.md' - } + '/zh-cn/': 'cover.md', + }, }; ``` diff --git a/docs/custom-navbar.md b/docs/custom-navbar.md index 14b6c8b3b..d345b36e2 100644 --- a/docs/custom-navbar.md +++ b/docs/custom-navbar.md @@ -27,17 +27,17 @@ Alternatively, you can create a custom markdown-based navigation file by setting - + ``` ```markdown -* [En](/) -* [chinese](/zh-cn/) +- [En](/) +- [chinese](/zh-cn/) ``` !> You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore. @@ -51,19 +51,19 @@ You can create sub-lists by indenting items that are under a certain parent. ```markdown -* Getting started +- Getting started - * [Quick start](quickstart.md) - * [Writing more pages](more-pages.md) - * [Custom navbar](custom-navbar.md) - * [Cover page](cover.md) + - [Quick start](quickstart.md) + - [Writing more pages](more-pages.md) + - [Custom navbar](custom-navbar.md) + - [Cover page](cover.md) -* Configuration - * [Configuration](configuration.md) - * [Themes](themes.md) - * [Using plugins](plugins.md) - * [Markdown configuration](markdown.md) - * [Language highlight](language-highlight.md) +- Configuration + - [Configuration](configuration.md) + - [Themes](themes.md) + - [Using plugins](plugins.md) + - [Markdown configuration](markdown.md) + - [Language highlight](language-highlight.md) ``` renders as @@ -80,10 +80,10 @@ If you use the [emoji plugin](plugins#emoji): - - + + ``` you could, for example, use flag emojis in your custom navbar Markdown file: @@ -91,6 +91,6 @@ you could, for example, use flag emojis in your custom navbar Markdown file: ```markdown -* [:us:, :uk:](/) -* [:cn:](/zh-cn/) +- [:us:, :uk:](/) +- [:cn:](/zh-cn/) ``` diff --git a/docs/index.html b/docs/index.html index de3ce2663..df19b4a1f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -20,24 +20,24 @@ /> @@ -55,7 +55,7 @@
Loading ...
- + - - - - - - + + + + + + - - + + diff --git a/docs/language-highlight.md b/docs/language-highlight.md index 1956af71f..b59585cd6 100644 --- a/docs/language-highlight.md +++ b/docs/language-highlight.md @@ -2,16 +2,16 @@ Docsify uses [Prism](https://prismjs.com) to highlight code blocks in your pages. Prism supports the following languages by default: -* Markup - `markup`, `html`, `xml`, `svg`, `mathml`, `ssml`, `atom`, `rss` -* CSS - `css` -* C-like - `clike` -* JavaScript - `javascript`, `js` +- Markup - `markup`, `html`, `xml`, `svg`, `mathml`, `ssml`, `atom`, `rss` +- CSS - `css` +- C-like - `clike` +- JavaScript - `javascript`, `js` Support for [additional languages](https://prismjs.com/#supported-languages) is available by loading the language-specific [grammar files](https://cdn.jsdelivr.net/npm/prismjs@1/components/) via CDN: ```html - - + + ``` To enable syntax highlighting, wrap each code block in triple backticks with the [language](https://prismjs.com/#supported-languages) specified on the first line: @@ -27,7 +27,7 @@ echo "hello" ``` ```php -function getAdder(int $x): int +function getAdder(int $x): int { return 123; } @@ -46,18 +46,19 @@ echo "hello" ``` ```php -function getAdder(int $x): int +function getAdder(int $x): int { return 123; } ``` ## Highlighting Dynamic Content + Code blocks [dynamically created from javascript](https://docsify.js.org/#/configuration?id=executescript) can be highlighted using the method `Prism.highlightElement` like so: ```javascript -var code = document.createElement("code"); +var code = document.createElement('code'); code.innerHTML = "console.log('Hello World!')"; -code.setAttribute("class", "lang-javascript"); +code.setAttribute('class', 'lang-javascript'); Prism.highlightElement(code); ``` diff --git a/docs/markdown.md b/docs/markdown.md index fef036e96..e562e3a13 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -9,10 +9,10 @@ window.$docsify = { renderer: { link: function() { // ... - } - } - } -} + }, + }, + }, +}; ``` ?> Configuration Options Reference: [marked documentation](https://marked.js.org/#/USING_ADVANCED.md) @@ -24,17 +24,16 @@ window.$docsify = { markdown: function(marked, renderer) { // ... - return marked - } -} + return marked; + }, +}; ``` ## Supports mermaid ```js -// Import mermaid -// -// +// First include mermaid in your page with: +// var num = 0; mermaid.initialize({ startOnLoad: false }); @@ -43,14 +42,16 @@ window.$docsify = { markdown: { renderer: { code: function(code, lang) { - if (lang === "mermaid") { + if (lang === 'mermaid') { return ( - '
' + mermaid.render('mermaid-svg-' + num++, code) + "
" + '
' + + mermaid.render('mermaid-svg-' + num++, code) + + '
' ); } return this.origin.code.apply(this, arguments); - } - } - } -} + }, + }, + }, +}; ``` diff --git a/docs/more-pages.md b/docs/more-pages.md index bf84a980e..cd34d7ed2 100644 --- a/docs/more-pages.md +++ b/docs/more-pages.md @@ -34,10 +34,10 @@ First, you need to set `loadSidebar` to **true**. Details are available in the [ - + ``` Create the `_sidebar.md`: @@ -45,8 +45,8 @@ Create the `_sidebar.md`: ```markdown -* [Home](/) -* [Guide](guide.md) +- [Home](/) +- [Guide](guide.md) ``` You need to create a `.nojekyll` in `./docs` to prevent GitHub Pages from ignoring files that begin with an underscore. @@ -76,9 +76,9 @@ You can specify `alias` to avoid unnecessary fallback. window.$docsify = { loadSidebar: true, alias: { - '/.*/_sidebar.md': '/_sidebar.md' - } - } + '/.*/_sidebar.md': '/_sidebar.md', + }, + }; ``` @@ -90,8 +90,9 @@ A page's `title` tag is generated from the _selected_ sidebar item name. For bet ```markdown -* [Home](/) -* [Guide](guide.md "The greatest guide in the world") + +- [Home](/) +- [Guide](guide.md 'The greatest guide in the world') ``` ## Table of Contents @@ -106,10 +107,10 @@ A custom sidebar can also automatically generate a table of contents by setting - + ``` ## Ignoring Subheaders diff --git a/docs/plugins.md b/docs/plugins.md index b7ccb971f..70528a4d8 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -9,11 +9,11 @@ By default, the hyperlink on the current page is recognized and the content is s window.$docsify = { search: 'auto', // default - search : [ - '/', // => /README.md - '/guide', // => /guide.md + search: [ + '/', // => /README.md + '/guide', // => /guide.md '/get-started', // => /get-started.md - '/zh-cn/', // => /zh-cn/README.md + '/zh-cn/', // => /zh-cn/README.md ], // complete configuration parameters @@ -25,7 +25,7 @@ By default, the hyperlink on the current page is recognized and the content is s // Localization placeholder: { '/zh-cn/': '搜索', - '/': 'Type to search' + '/': 'Type to search', }, noData: 'No Results!', @@ -33,7 +33,7 @@ By default, the hyperlink on the current page is recognized and the content is s // Localization noData: { '/zh-cn/': '找不到结果', - '/': 'No Results' + '/': 'No Results', }, // Headline depth, 1 - 6 @@ -54,12 +54,12 @@ By default, the hyperlink on the current page is recognized and the content is s // You can provide a regexp to match prefixes. In this case, // the matching substring will be used to identify the index - pathNamespaces: /^(\/(zh-cn|ru-ru))?(\/(v1|v2))?/ - } - } + pathNamespaces: /^(\/(zh-cn|ru-ru))?(\/(v1|v2))?/, + }, + }; - - + + ``` This plugin ignores diacritical marks when performing a full text search (e.g., "cafe" will also match "café"). Legacy browsers like IE11 require the following [String.normalize()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/normalize) polyfill to ignore diacritical marks: @@ -75,18 +75,21 @@ Install the plugin and configure the track id. ```html - - + + ``` Configure by `data-ga`. ```html - - + + ``` ## emoji @@ -94,17 +97,17 @@ Configure by `data-ga`. 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 - + ``` -?> If you don't want to parse to emoji, you can use __colon__ or `:`. If you need to use in the title, we recommend using `:`. For example, `:100:` +?> If you don't want to parse to emoji, you can use \__colon_\_ or `:`. If you need to use in the title, we recommend using `:`. For example, `:100:` ## External Script 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 @@ -112,13 +115,13 @@ If the script on the page is an external one (imports a js file via `src` attrib Medium's image zoom. Based on [medium-zoom](https://github.com/francoischalifour/medium-zoom). ```html - + ``` Exclude the special image ```markdown -![](image.png ":no-zoom") +![](image.png ':no-zoom') ``` ## Edit on github @@ -138,10 +141,10 @@ When readers expand the demo box, the source code and description are shown ther Add a simple `Click to copy` button to all preformatted code blocks to effortlessly allow users to copy example code from your docs. Provided by [@jperasmus](https://github.com/jperasmus) ```html - + ``` -See [here](https://github.com/jperasmus/docsify-copy-code/blob/master/README.md) for more details. +See [docsify-copy-code's repo](https://github.com/jperasmus/docsify-copy-code/blob/master/README.md) for more details. ## Disqus @@ -150,10 +153,10 @@ Disqus comments. https://disqus.com/ ```html - + ``` ## Gitalk @@ -161,20 +164,25 @@ Disqus comments. https://disqus.com/ [Gitalk](https://github.com/gitalk/gitalk) is a modern comment component based on Github Issue and Preact. ```html - + - - + + ``` @@ -183,8 +191,8 @@ Disqus comments. https://disqus.com/ Pagination for docsify. By [@imyelo](https://github.com/imyelo) ```html - - + + ``` Click [here](https://github.com/imyelo/docsify-pagination#readme) to get more information. diff --git a/docs/quickstart.md b/docs/quickstart.md index e5da5e2b3..db24e541b 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -18,9 +18,9 @@ docsify init ./docs 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.md). @@ -43,21 +43,24 @@ If you don't like `npm` or have trouble installing the tool, you can manually cr - - - - - - - -
- - - + + + + + + + +
+ + + ``` @@ -65,18 +68,42 @@ If you don't like `npm` or have trouble installing the tool, you can manually cr ?> Note that in both of the examples below, docsify URLs will need to be manually updated when a new major version of docsify is released (e.g. `v4.x.x` => `v5.x.x`). Check the docsify website periodically to see if a new major version has been released. -Specifying a major version in the URL (`@4`) will allow your site will receive non-breaking enhancements (i.e. "minor" updates) and bug fixes (i.e. "patch" updates) automatically. This is the recommended way to load docsify resources. +The recommended way to load docsify resources to ensure that your website will +not break on some update of docsify is to lock docsify to a specific version. +Specify the full version after the `@` symbol in the URL. This is the safest way +to ensure your site will look and behave the same way regardless of any changes +made to future versions of docsify: + +```html + + +``` + +If you are ok taking more risk for your website, you can specify only the major +version in the URL (f.e. `@4`) to allow your site to receive non-breaking +enhancements (i.e. "minor" updates) and bug fixes (i.e. "patch" updates) +automatically. ```html ``` -If you prefer to lock docsify to a specific version, specify the full version after the `@` symbol in the URL. This is the safest way to ensure your site will look and behave the same way regardless of any changes made to future versions of docsify. +!> **Warning:** not specifying the full version (f.e. `@4.12.2`) can cause your +website to eventually break. Sometimes bugs can happen unintentionally in any project, +including Docsify. + +!> **Warning:** The following is the most risky way to include Docsify because it means you +will get the latest version, even major versions which can include intentional breaking +changes: ```html - - + + + ``` ### Manually preview your site @@ -86,6 +113,7 @@ If you have Python installed on your system, you can easily use it to run a stat ```python2 cd docs && python -m SimpleHTTPServer 3000 ``` + ```python3 cd docs && python -m http.server 3000 ``` @@ -107,11 +135,11 @@ You should set the `data-app` attribute if you changed `el`:
Please wait...
- + ``` Compare [el configuration](configuration.md#el). diff --git a/docs/ssr.md b/docs/ssr.md index 444abeb5f..133e2986a 100644 --- a/docs/ssr.md +++ b/docs/ssr.md @@ -32,9 +32,7 @@ Edit `package.json`. The below assumes the documentation is in the `./docs` subd "start": "docsify start . -c ssr.config.js", "deploy": "now -p" }, - "files": [ - "docs" - ], + "files": ["docs"], "docsify": { "config": { "basePath": "https://docsify.js.org/", @@ -72,27 +70,35 @@ You can provide a template for an entire page's HTML, such as ```html - - - docsify - - - - - - - - - - - - + + + docsify + + + + + + + + + + + + ``` The template should contain these comments for rendered app content. - - `` - - `` + +- `` +- `` ## Configuration @@ -103,9 +109,9 @@ module.exports = { template: './ssr.html', maxAge: 60 * 60 * 1000, // lru-cache config config: { - // docsify config - } -} + // docsify config + }, +}; ``` ## Deploy for your VPS @@ -113,19 +119,20 @@ module.exports = { You can run `docsify start` directly on your Node server, or write your own server app with `docsify-server-renderer`. ```js -var Renderer = require('docsify-server-renderer') -var readFileSync = require('fs').readFileSync +var Renderer = require('docsify-server-renderer'); +var readFileSync = require('fs').readFileSync; // init var renderer = new Renderer({ template: readFileSync('./docs/index.template.html', 'utf-8'), config: { name: 'docsify', - repo: 'docsifyjs/docsify' - } -}) + repo: 'docsifyjs/docsify', + }, +}); -renderer.renderToString(url) +renderer + .renderToString(url) .then(html => {}) - .catch(err => {}) + .catch(err => {}); ``` diff --git a/docs/themes.md b/docs/themes.md index 07009f762..0fde29477 100644 --- a/docs/themes.md +++ b/docs/themes.md @@ -4,10 +4,10 @@ There is a handful of themes available, both official and community-made. Copy [ ```html - - - - + + + + ``` @@ -17,10 +17,10 @@ There is a handful of themes available, both official and community-made. Copy [ ```html - - - - + + + + ``` diff --git a/docs/vue.md b/docs/vue.md index 57a760127..9aceb7456 100644 --- a/docs/vue.md +++ b/docs/vue.md @@ -8,20 +8,20 @@ To get started, add Vue [2.x](https://vuejs.org) or [3.x](https://v3.vuejs.org) ```html - + - + ``` #### Vue 3.x ```html - + - + ``` ## Template syntax diff --git a/index.html b/index.html index 206c1fe3d..f2e81c548 100644 --- a/index.html +++ b/index.html @@ -23,7 +23,7 @@
- + - - - - + + + + diff --git a/packages/docsify-server-renderer/README.md b/packages/docsify-server-renderer/README.md index 9968b1e0b..6858e1e28 100644 --- a/packages/docsify-server-renderer/README.md +++ b/packages/docsify-server-renderer/README.md @@ -9,38 +9,46 @@ yarn add docsify-server-renderer ## Usage ```js -var Renderer = require('docsify-server-renderer') -var readFileSync = require('fs').readFileSync +var Renderer = require('docsify-server-renderer'); +var readFileSync = require('fs').readFileSync; // init var renderer = new Renderer({ template: readFileSync('./docs/index.template.html', 'utf-8'), config: { name: 'docsify', - repo: 'docsifyjs/docsify' - } -}) + repo: 'docsifyjs/docsify', + }, +}); -renderer.renderToString(url) +renderer + .renderToString(url) .then(html => {}) - .catch(err => {}) + .catch(err => {}); ``` -*index.template.html* +_index.template.html_ ```html - - - docsify - - - - - - - - + + + docsify + + + + + + + + ```