From 9cb6c2d1e7d9bb998e608c6fc0247cc1f3d6f051 Mon Sep 17 00:00:00 2001 From: "qingwei.li" Date: Sun, 1 Jul 2018 19:27:01 +0800 Subject: [PATCH] first commit --- README.md | 34 +++ _sidebar.md | 28 +++ cdn.md | 49 +++++ configuration.md | 465 ++++++++++++++++++++++++++++++++++++++++++ cover.md | 99 +++++++++ custom-navbar.md | 64 ++++++ deploy.md | 71 +++++++ embed-files.md | 63 ++++++ helpers.md | 82 ++++++++ language-highlight.md | 11 + markdown.md | 56 +++++ more-pages.md | 100 +++++++++ plugins.md | 179 ++++++++++++++++ pwa.md | 113 ++++++++++ quickstart.md | 90 ++++++++ ssr.md | 118 +++++++++++ themes.md | 61 ++++++ vue.md | 112 ++++++++++ write-a-plugin.md | 94 +++++++++ 19 files changed, 1889 insertions(+) create mode 100644 README.md create mode 100644 _sidebar.md create mode 100644 cdn.md create mode 100644 configuration.md create mode 100644 cover.md create mode 100644 custom-navbar.md create mode 100644 deploy.md create mode 100644 embed-files.md create mode 100644 helpers.md create mode 100644 language-highlight.md create mode 100644 markdown.md create mode 100644 more-pages.md create mode 100644 plugins.md create mode 100644 pwa.md create mode 100644 quickstart.md create mode 100644 ssr.md create mode 100644 themes.md create mode 100644 vue.md create mode 100644 write-a-plugin.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..1882d81 --- /dev/null +++ b/README.md @@ -0,0 +1,34 @@ +## docsify + +> 一个神奇的文档网站生成工具 + +## 是什么 + +docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 `.md` 转成 `.html` 文件，所有转换工作都是在运行时进行。 + +这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生成的一堆 `.html` 文件“污染” commit 记录，只需要创建一个 `index.html` 就可以开始写文档而且直接[部署在 GitHub Pages](zh-cn/deploy.md)。 + +查看[快速开始](zh-cn/quickstart.md)了解详情。 + +## 特性 + +- 无需构建，写完文档直接发布 +- 容易使用并且轻量 (~19kB gzipped) +- 智能的全文搜索 +- 提供多套主题 +- 丰富的 API +- 支持 Emoji +- 兼容 IE10+ +- 支持 SSR ([example](https://github.com/docsifyjs/docsify-ssr-demo)) + +## 例子 + +可以查看 [Showcase](https://github.com/docsifyjs/docsify/#showcase) 来了解使用 docsify 的文档项目。 + +## 捐赠 + +如果你觉得 docsify 对你有帮助，或者想对我微小的工作一点资瓷，欢迎给我[捐赠](https://github.com/QingWei-Li/donate)。 + +## Community + +Users and development team are in the [Gitter](https://gitter.im/docsifyjs/Lobby). diff --git a/_sidebar.md b/_sidebar.md new file mode 100644 index 0000000..84ab17e --- /dev/null +++ b/_sidebar.md @@ -0,0 +1,28 @@ +* 入门 + + * [快速开始](zh-cn/quickstart.md) + * [多页文档](zh-cn/more-pages.md) + * [定制导航栏](zh-cn/custom-navbar.md) + * [封面](zh-cn/cover.md) + +* 定制化 + + * [配置项](zh-cn/configuration.md) + * [主题](zh-cn/themes.md) + * [插件列表](zh-cn/plugins.md) + * [开发插件](zh-cn/write-a-plugin.md) + * [Markdown 配置](zh-cn/markdown.md) + * [代码高亮](zh-cn/language-highlight.md) + +* 指南 + + * [部署](zh-cn/deploy.md) + * [文档助手](zh-cn/helpers.md) + * [兼容 Vue](zh-cn/vue.md) + * [CDN](zh-cn/cdn.md) + * [离线模式(PWA)](zh-cn/pwa.md) + * [服务端渲染 (SSR)](zh-cn/ssr.md) + * [文件嵌入(new)](zh-cn/embed-files.md) + +* [Awesome docsify](zh-cn/awesome.md) +* [Changelog](zh-cn/changelog.md) diff --git a/cdn.md b/cdn.md new file mode 100644 index 0000000..5b98d68 --- /dev/null +++ b/cdn.md @@ -0,0 +1,49 @@ +# CDN + +推荐使用 [unpkg](//unpkg.com) —— 能及时获取到最新版。 + +## 获取最新版本 + +根据 UNPKG 的规则，不指定特定版本号时将引入最新版。 + +```html + + + + + +``` + +## 获取指定版本 + +如果担心频繁地版本更新又可能引入未知 Bug，我们也可以使用具体的版本。规则是 `//unpkg.com/docsify@VERSION/` + +```html + + + + + +``` + +!> 指定 *VERSION* 为 `latest` 可以强制每次都请求最新版本。 + +## 压缩版 + +CSS 的压缩文件位于 `/lib/themes/` 目录下 + +```html + +``` + +JS 的压缩文件是原有文件路径的基础上加 `.min`后缀 + +```html + +``` + +## 其他 CDN + +- http://www.bootcdn.cn/docsify (支持国内) +- https://cdn.jsdelivr.net/npm/docsify/ (国内外都支持) +- https://cdnjs.com/libraries/docsify diff --git a/configuration.md b/configuration.md new file mode 100644 index 0000000..5b947f8 --- /dev/null +++ b/configuration.md @@ -0,0 +1,465 @@ +# 配置项 + +你可以配置在 `window.$docsify` 里。 + +```html + +``` + +## 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: 'docsifyjs/docsify', + // or + repo: 'https://github.com/docsifyjs/docsify/' +}; +``` + +## maxLevel + +- 类型：`Number` +- 默认值: `6` + +默认情况下会抓取文档中所有标题渲染成目录，可配置最大支持渲染的标题层级。 + +```js +window.$docsify = { + maxLevel: 4 +}; +``` + +## loadNavbar + +- 类型：`Boolean|String` +- 默认值: `false` + +加载自定义导航栏，参考[定制导航栏](zh-cn/custom-navbar.md) 了解用法。设置为 `true` 后会加载 `_navbar.md` 文件，也可以自定义加载的文件名。 + +```js +window.$docsify = { + // 加载 _navbar.md + loadNavbar: true, + + // 加载 nav.md + loadNavbar: 'nav.md' +}; +``` + +## loadSidebar + +- 类型：`Boolean|String` +- 默认值: `false` + +加载自定义侧边栏，参考[多页文档](zh-cn/more-pages.md)。设置为 `true` 后会加载 `_sidebar.md` 文件，也可以自定义加载的文件名。 + +```js +window.$docsify = { + // 加载 _sidebar.md + loadSidebar: true, + + // 加载 summary.md + loadSidebar: 'summary.md' +}; +``` + +## subMaxLevel + +- 类型：`Number` +- 默认值: `0` + +自定义侧边栏后默认不会再生成目录，你也可以通过设置生成目录的最大层级开启这个功能。 + +```js +window.$docsify = { + subMaxLevel: 2 +}; +``` + +## 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/docsifyjs/docsify/master/README.md' +}; +``` + +## basePath + +- 类型：`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.md)。开启后是加载 `_coverpage.md` 文件，也可以自定义文件名。 + +```js +window.$docsify = { + coverpage: true, + + // 自定义文件名 + coverpage: 'cover.md', + + // mutiple covers + coverpage: ['/', '/zh-cn/'], + + // mutiple covers and custom file name + coverpage: { + '/': 'cover.md', + '/zh-cn/': 'cover.md' + } +}; +``` + +## logo + +- Type: `String` + +Website logo as it appears in the sidebar, you can resize by CSS. + +```js +window.$docsify = { + logo: '/_media/icon.svg' +}; +``` + +## name + +- 类型：`String` + +文档标题，会显示在侧边栏顶部。 + +```js +window.$docsify = { + name: 'docsify' +}; +``` + +## nameLink + +- 类型：`String` +- 默认值：`window.location.pathname` + +点击文档标题后跳转的链接地址。 + +```js +window.$docsify = { + nameLink: '/', + + // 按照路由切换 + nameLink: { + '/zh-cn/': '/zh-cn/', + '/': '/' + } +}; +``` + +## markdown + +- 类型: `Object|Function` + +参考 [Markdown 配置](zh-cn/markdown.md)。 + +```js +window.$docsify = { + // object + markdown: { + smartypants: true, + renderer: { + link: function() { + // ... + } + } + }, + + // function + markdown: function(marked, renderer) { + // ... + return marked; + } +}; +``` + +## themeColor + +- 类型：`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: { + '/foo/(+*)': '/bar/$1', // supports regexp + '/zh-cn/changelog': '/changelog', + '/changelog': + 'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG', + '/.*/_sidebar.md': '/_sidebar.md' // See #301 + } +}; +``` + +## autoHeader + +- 类型：`Boolean` + +同时设置 `loadSidebar` 和 `autoHeader` 后，可以根据 `_sidebar.md` 的内容自动为每个页面增加标题。[#78](https://github.com/docsifyjs/docsify/issues/78) + +```js +window.$docsify = { + loadSidebar: true, + autoHeader: true +}; +``` + +## executeScript + +- 类型：`Boolean` + +执行文档里的 script 标签里的脚本，只执行第一个 script ([demo](zh-cn/themes.md))。 如果 Vue 存在，则自动开启。 + +```js +window.$docsify = { + executeScript: true +}; +``` + +```markdown +## This is test + + +``` + +注意如果执行的是一个外链脚本，比如 jsfiddle 的内嵌 demo，请确保引入 [external-script](plugins.md?id=外链脚本-external-script) 插件。 + +## noEmoji + +- type: `Boolean` + +禁用 emoji 解析。 + +```js +window.$docsify = { + noEmoji: true +}; +``` + +## mergeNavbar + +- type: `Boolean` + +小屏设备下合并导航栏到侧边栏。 + +```js +window.$docsify = { + mergeNavbar: true +}; +``` + +## formatUpdated + +- type: `String|Function` + +我们可以显示文档更新日期通过 **{docsify-updated}** 变量. 并且格式化日期通过 `formatUpdated`。参考 https://github.com/lukeed/tinydate#patterns + +```js +window.$docsify = { + formatUpdated: '{MM}/{DD} {HH}:{mm}', + + formatUpdated: function(time) { + // ... + + return time; + } +}; +``` + +## externalLinkTarget + +- type: `String` +- default: `_blank` + +当前默认为 \_blank, 配置一下就可以： + +```js +window.$docsify = { + externalLinkTarget: '_self' // default: '_blank' +}; +``` + +## routerMode + +- type: `String` +- default: `history` + +```js +window.$docsify = { + routerMode: 'history' // default: 'hash' +}; +``` + +## noCompileLinks + +- 类型: `Array` + +有时我们不希望 docsify 处理我们的链接。 参考 [#203](https://github.com/docsifyjs/docsify/issues/203) + +```js +window.$docsify = { + noCompileLinks: ['/foo', '/bar/.*'] +}; +``` + +## requestHeaders + +- type: `Object` + +设置请求资源的请求头。 + +```js +window.$docsify = { + requestHeaders: { + 'x-token': 'xxx' + } +}; +``` + +## ext + +- type: `String` + +资源的文件扩展名。 + +```js +window.$docsify = { + ext: '.md' +}; +``` + +## fallbackLanguages + +- type: `Array` + +List of languages that will fallback to the default language when a page is request and didn't exists for the given local. + +Example: + +- try to fetch the page of `/de/overview`. If this page exists, it'll be displayed +- then try to fetch the default page `/overview` (depending on the default language). If this page exists, it'll be displayed +- then display 404 page. + +```js +window.$docsify = { + fallbackLanguages: ['fr', 'de'] +}; +``` + +## notFoundPage + +- type: `Boolean` | `String` | `Object` + +Load the `_404.md` file: + +```js +window.$docsify = { + notFoundPage: true +}; +``` + +Load the customised path of the 404 page: + +```js +window.$docsify = { + notFoundPage: 'my404.md' +}; +``` + +Load the right 404 page according to the localisation: + +```js +window.$docsify = { + notFoundPage: { + '/': '_404.md', + '/de': 'de/_404.md' + } +}; +``` + +> Note: The options with fallbackLanguages didn't work with the `notFoundPage` options. diff --git a/cover.md b/cover.md new file mode 100644 index 0000000..1577cfa --- /dev/null +++ b/cover.md @@ -0,0 +1,99 @@ +# 封面 + +通过设置 `coverpage` 参数，可以开启渲染封面的功能。具体用法见[配置项#coverpage](configuration.md#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/docsifyjs/docsify/) +[Get Started](#quick-start) +``` + +!> 一份文档只会在根目录下加载封面，其他页面或者二级目录下都不会加载。 + +## 自定义背景 + +目前的背景是随机生成的渐变色，我们自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。 + +_\_coverpage.md_ + +```markdown +# docsify + +[GitHub](https://github.com/docsifyjs/docsify/) +[Get Started](#quick-start) + + + +![](_media/bg.png) + + + +![color](#f0f0f0) +``` + +## 封面作为首页 + +通常封面和首页是同时出现的，当然你也是当封面独立出来通过设置[onlyCover 选项](zh-cn/configuration.md#onlycover)。 + +## 多个封面 + +如果你的文档网站是多语言的，或许你需要设置多个封面。 + +例如你的文档目录结构如下 + +```text +. +└── docs + ├── README.md + ├── guide.md + ├── _coverpage.md + └── zh-cn + ├── README.md + └── guide.md + └── _coverpage.md +``` + +那么你可以这么配置 + +```js +window.$docsify = { + coverpage: ['/', '/zh-cn/'] +}; +``` + +或者具体指名文件名 + +```js +window.$docsify = { + coverpage: { + '/': 'cover.md', + '/zh-cn/': 'cover.md' + } +}; +``` diff --git a/custom-navbar.md b/custom-navbar.md new file mode 100644 index 0000000..aac3e31 --- /dev/null +++ b/custom-navbar.md @@ -0,0 +1,64 @@ +# 自定义导航栏 + +我们可以直接在 HTML 里定义导航栏，要注意链接要以 `#/` 开头。 + +_index.html_ + +```html + + +
+ +``` + +## 配置文件 + +那我们可以通过 Markdown 文件来配置导航。首先配置 `loadNavbar`，默认加载的文件为 `_navbar.md`。具体配置规则见[配置项#loadNavbar](configuration.md#loadnavbar)。 + +_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.md) + * [多页文档](zh-cn/more-pages.md) + * [定制导航栏](zh-cn/custom-navbar.md) + * [封面](zh-cn/cover.md) + +* 配置 + * [配置项](zh-cn/configuration.md) + * [主题](zh-cn/themes.md) + * [使用插件](zh-cn/plugins.md) + * [Markdown 配置](zh-cn/markdown.md) + * [代码高亮](zh-cn/language-highlight.md) +``` + +效果图 + +![嵌套导航栏](../_images/zh-cn/nested-navbar.png '嵌套导航栏') diff --git a/deploy.md b/deploy.md new file mode 100644 index 0000000..b80cf22 --- /dev/null +++ b/deploy.md @@ -0,0 +1,71 @@ +# 部署 + +和 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 分支** 作为文档目录。 + +## GitLab Pages + +如果你正在部署你的主分支, 在 `.gitlab-ci.yml` 中包含以下脚本： + +?> `.public` 的解决方法是这样的，`cp` 不会无限循环的将 `public/` 复制到自身。 + +```YAML +pages: + stage: deploy + script: + - mkdir .public + - cp -r * .public + - mv .public public + artifacts: + paths: + - public + only: + - master +``` + +!> 你可以用 `- cp -r docs/. public` 替换脚本, 如果 `./docs` 是你的 docsify 子文件夹。 + +## VPS + +和部署所有静态网站一样，只需将服务器的访问根目录设定为 `index.html` 文件。 + +例如 nginx 的配置 + +```nginx +server { + listen 80; + server_name your.domain.com; + + location / { + alias /path/to/dir/of/docs; + index index.html; + } +} +``` + +## Netlify + +1. Login to your [Netlify](https://www.netlify.com/) account. +2. In the [dashboard](https://app.netlify.com/) page, click **New site from Git**. +3. Choose a repository where you store your docs, leave the **Build Command** area blank, fill in the Publish directory area with the directory of your `index.html`, for example it should be docs if you populated it at `docs/index.html`. + +### HTML5 router + +When using the HTML5 router, you need to set up redirect rules that redirect all requests to your `index.html`, it's pretty simple when you're using Netlify, populate a `\redirects` file in the docs directory and you're all set: + +```sh +/* /index.html 200 +``` diff --git a/embed-files.md b/embed-files.md new file mode 100644 index 0000000..429cc8e --- /dev/null +++ b/embed-files.md @@ -0,0 +1,63 @@ +# 文件嵌入 + +docsify 4.6 开始支持嵌入任何类型的文件到文档里。你可以将文件当成 `iframe`、`video`、`audio` 或者 `code block`，如果是 Markdown 文件，甚至可以直接插入到当前文档里。 + +这是一个嵌入 Markdown 文件的例子。 + +```markdown +[filename](../_media/example.md ':include') +``` + +`example.md` 文件的内容将会直接显示在这里 + +[filename](../_media/example.md ':include') + +你可以查看 [example.md](../_media/example.md ':ignore') 原始内容对比效果。 + +通常情况下，这样的语法将会被当作链接处理。但是在 docsify 里，如果你添加一个 `:include` 选项，它就会被当作文件嵌入。 + +## 嵌入的类型 + +当前，嵌入的类型是通过文件后缀自动识别的，这是目前支持的类型： + +* **iframe** `.html`, `.htm` +* **markdown** `.markdown`, `.md` +* **audio** `.mp3` +* **video** `.mp4`, `.ogg` +* **code** other file extension + +当然，你也可以强制设置嵌入类型。例如你想将 Markdown 文件当作一个 `code block` 嵌入。 + +```markdown +[filename](../_media/example.md ':include :type=code') +``` + +你将得到 + +[filename](../_media/example.md ':include :type=code') + +## 标签属性 + +如果你嵌入文件是一个 `iframe`、`audio` 或者 `video`，你可以给这些标签设置属性。 + +```markdown +[cinwell website](https://cinwell.com ':include :type=iframe width=100% height=400px') +``` + +[cinwell website](https://cinwell.com ':include :type=iframe width=100% height=400px') + +看见没？你只需要直接写属性就好了，每个标签有哪些属性建议你查看 [MDN 文档](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe)。 + +## 代码块高亮 + +如果是嵌入一个代码块，你可以设置高亮的语言，或者让它自动识别。这里是手动设置高亮语言 + +```markdown +[](../_media/example.html ':include :type=code text') +``` + +⬇️ + +[](../_media/example.html ':include :type=code text') + +?> 如何高亮代码？你可以查看[这份文档](language-highlight.md). diff --git a/helpers.md b/helpers.md new file mode 100644 index 0000000..eab5cbc --- /dev/null +++ b/helpers.md @@ -0,0 +1,82 @@ +# 文档助手 + +docsify 扩展了一些 Markdown 语法，可以让文档更易读。 + +## 强调内容 + +适合显示重要的提示信息，语法为 `!> 内容`。 + +```markdown +!> 一段重要的内容，可以和其他 **Markdown** 语法混用。 +``` + +!> 一段重要的内容，可以和其他 **Markdown** 语法混用。 + +## 普通提示 + +普通的提示信息，比如写 TODO 或者参考内容等。 + +```markdown +?> _TODO_ 完善示例 +``` + +?> _TODO_ 完善示例 + +## 忽略编译链接 + +有时候我们会把其他一些相对路径放到链接上，你必须告诉 docsify 你不需要编译这个链接。 例如： + +```md +[link](/demo/) +``` + +它将被编译为 `link` 并将加载 `/demo/README.md`. 可能你想跳转到 `/demo/index.html`。 + +现在你可以做到这一点 + +```md +[link](/demo/ ':ignore') +``` + +即将会得到 `link` html 代码。不要担心，你仍然可以为链接设置标题。 + +```md +[link](/demo/ ':ignore title') + +link +``` + +## 设置链接的 target 属性 + +```md +[link](/demo ':target=_blank') +[link](/demo2 ':target=_self') +``` + +## Github 任务列表 + +```md +- [ ] foo +- bar +- [x] baz +- [] bam <~ not working + - [ ] bim + - [ ] lim +``` + +- [ ] foo +- bar +- [x] baz +- [] bam <~ not working + - [ ] bim + - [ ] lim + +## Image resizing + +```md +![logo](https://docsify.js.org/_media/icon.svg ':size=50x100') +![logo](https://docsify.js.org/_media/icon.svg ':size=100') +``` + +![logo](https://docsify.js.org/_media/icon.svg ':size=50x100') +![logo](https://docsify.js.org/_media/icon.svg ':size=100') diff --git a/language-highlight.md b/language-highlight.md new file mode 100644 index 0000000..20e9f22 --- /dev/null +++ b/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)。 diff --git a/markdown.md b/markdown.md new file mode 100644 index 0000000..694698f --- /dev/null +++ b/markdown.md @@ -0,0 +1,56 @@ +# Markdown 配置 + +内置的 Markdown 解析器是 [marked](https://github.com/markedjs/marked)，可以修改它的配置。同时可以直接配置 `renderer`。 + +```js +window.$docsify = { + markdown: { + smartypants: true, + renderer: { + link: function() { + // ... + } + } + } +} +``` + +?> 完整配置参数参考 [marked 文档](https://github.com/markedjs/marked#options-1) + +当然也可以完全定制 Markdown 解析规则。 + +```js +window.$docsify = { + markdown: function(marked, renderer) { + // ... + + return marked + } +} +``` + + +## 支持 mermaid + +```js +// Import mermaid +// +// + +mermaid.initialize({ startOnLoad: false }); + +window.$docsify = { + markdown: { + renderer: { + code: function(code, lang) { + if (lang === "mermaid") { + return ( + '
' + mermaid.render(lang, code) + "
" + ); + } + return this.origin.code.apply(this, arguments); + } + } + } +} +``` diff --git a/more-pages.md b/more-pages.md new file mode 100644 index 0000000..ea0a8c0 --- /dev/null +++ b/more-pages.md @@ -0,0 +1,100 @@ +# 多页文档 + +如果需要创建多个页面，或者需要多级路由的网站，在 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` 选项，具体配置规则见[配置项#loadSidebar](zh-cn/configuration.md#loadsidebar)。 + +```html + + +``` + +接着创建 `_sidebar.md` 文件，内容如下 + +```markdown +* [首页](zh-cn/) +* [指南](zh-cn/guide) +``` + +!> 需要在文档根目录创建 `.nojekyll` 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。 + +`_sidebar.md` 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 `/zh-cn/more-pages` 则从 `/zh-cn/_sidebar.md` 获取文件，如果不存在则从 `/_sidebar.md` 获取。 + +当然你也可以配置 `alias` 避免不必要的回退过程。 + +```html + +``` + +## 显示目录 + +自定义侧边栏同时也可以开启目录功能。设置 `subMaxLevel` 配置项，具体介绍见 [配置项#sub-max-level](zh-cn/configuration#sub-max-level)。 + +```html + + +``` + +## 忽略副标题 + +当设置了 `subMaxLevel` 时，默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题，可以给它添加  `{docsify-ignore}` 。 + +```markdown +# Getting Started + +## Header {docsify-ignore} + +该标题不会出现在侧边栏的目录中。 +``` + +要忽略特定页面上的所有标题，你可以在页面的第一个标题上使用 `{docsify-ignore-all}` 。 + +```markdown +# Getting Started {docsify-ignore-all} + +## Header + +该标题不会出现在侧边栏的目录中。 +``` + +在使用时， `{docsify-ignore}` 和 `{docsify-ignore-all}` 都不会在页面上呈现。 diff --git a/plugins.md b/plugins.md new file mode 100644 index 0000000..545dcd8 --- /dev/null +++ b/plugins.md @@ -0,0 +1,179 @@ +# 插件列表 + +## 全文搜索 - Search + +全文搜索插件会根据当前页面上的超链接获取文档内容，在 `localStorage` 内建立文档索引。默认过期时间为一天，当然我们可以自己指定需要缓存的文件列表或者配置过期时间。 + +```html + + + +``` + +## 谷歌统计 - Google Analytics + +需要配置 track id 才能使用。 + +```html + + + +``` + +也可以通过 `data-ga` 配置 id。 + +```html + + +``` + +## emoji + +默认是提供 emoji 解析的，能将类似 `:100:` 解析成 :100:。但是它不是精准的，因为没有处理非 emoji 的字符串。如果你需要正确解析 emoji 字符串，你可以引入这个插件。 + +```html + +``` + +## 外链脚本 - External Script + +如果文档里的 script 是内联脚本，可以直接执行；而如果是外链脚本（即 js 文件内容由 `src` 属性引入），则需要使用此插件。 + +```html + +``` + +## Demo code with instant preview and jsfiddle integration + +With this plugin, sample code can be rendered on the page instantly, so that the readers can see the preview immediately. +When readers expand the demo box, the source code and description are shown there. if they click the button `Try in Jsfiddle`, +`jsfiddle.net` will be open with the code of this sample, which allow readers to revise the code and try on their own. + +[Vue](https://njleonzhang.github.io/docsify-demo-box-vue/) and [React](https://njleonzhang.github.io/docsify-demo-box-react/) are both supported. + +## 图片缩放 - Zoom image + +Medium's 风格的图片缩放插件. 基于 [medium-zoom](https://github.com/francoischalifour/medium-zoom)。 + +```html + +``` + +忽略某张图片 + +```markdown +![](image.png ':no-zoom') +``` + +## 在 Github 上编辑 + +在每一页上添加 `Edit on github` 按钮. 由第三方库提供, 查看 [document](https://github.com/njleonzhang/docsify-edit-on-github) + +## Copy to Clipboard + +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. + +## Disqus + +Disqus comments. https://disqus.com/ + +```html + + +``` + +## Gitalk + +[Gitalk](https://github.com/gitalk/gitalk) is a modern comment component based on Github Issue and Preact. + +```html + + + + + +``` + +## Pagination + +Pagination for docsify. By [@imyelo](https://github.com/imyelo) + +```html + + +``` + +## Code Fund + +帮你快速接入[Code Fund](https://codesponsor.io/)的[插件](https://github.com/njleonzhang/docsify-plugin-codefund), 由[@njleonzhang](https://github.com/njleonzhang)提供。 + +> Code Fund 以前叫 codesponsor + +``` + + +window.$docsify = { + plugins: [ + DocsifyCodefund.create('51d43327-eea3-4e27-bd44-e075e67a84fb') // 把这个id改成你的codefund id + ] +} +``` diff --git a/pwa.md b/pwa.md new file mode 100644 index 0000000..2337e9f --- /dev/null +++ b/pwa.md @@ -0,0 +1,113 @@ +# 离线模式 + +[Progressive Web Apps](https://developers.google.com/web/progressive-web-apps/)(PWA) 是一项融合 Web 和 Native 应用各项优点的解决方案。我们可以利用其支持离线功能的特点，让我们的网站可以在信号差或者离线状态下正常运行。 +要使用它也非常容易。 + +## 创建 serviceWorker +这里已经整理好了一份代码，你只需要在网站根目录下创建一个 `sw.js` 文件，并粘贴下面的代码。 + +*sw.js* + +```js +/* =========================================================== + * docsify sw.js + * =========================================================== + * Copyright 2016 @huxpro + * Licensed under Apache 2.0 + * Register service worker. + * ========================================================== */ + +const RUNTIME = 'docsify' +const HOSTNAME_WHITELIST = [ + self.location.hostname, + 'fonts.gstatic.com', + 'fonts.googleapis.com', + 'unpkg.com' +] + +// The Util Function to hack URLs of intercepted requests +const getFixedUrl = (req) => { + var now = Date.now() + var url = new URL(req.url) + + // 1. fixed http URL + // Just keep syncing with location.protocol + // fetch(httpURL) belongs to active mixed content. + // And fetch(httpRequest) is not supported yet. + url.protocol = self.location.protocol + + // 2. add query for caching-busting. + // Github Pages served with Cache-Control: max-age=600 + // max-age on mutable content is error-prone, with SW life of bugs can even extend. + // Until cache mode of Fetch API landed, we have to workaround cache-busting with query string. + // Cache-Control-Bug: https://bugs.chromium.org/p/chromium/issues/detail?id=453190 + if (url.hostname === self.location.hostname) { + url.search += (url.search ? '&' : '?') + 'cache-bust=' + now + } + return url.href +} + +/** + * @Lifecycle Activate + * New one activated when old isnt being used. + * + * waitUntil(): activating ====> activated + */ +self.addEventListener('activate', event => { + event.waitUntil(self.clients.claim()) +}) + +/** + * @Functional Fetch + * All network requests are being intercepted here. + * + * void respondWith(Promise r) + */ +self.addEventListener('fetch', event => { + // Skip some of cross-origin requests, like those for Google Analytics. + if (HOSTNAME_WHITELIST.indexOf(new URL(event.request.url).hostname) > -1) { + // Stale-while-revalidate + // similar to HTTP's stale-while-revalidate: https://www.mnot.net/blog/2007/12/12/stale + // Upgrade from Jake's to Surma's: https://gist.github.com/surma/eb441223daaedf880801ad80006389f1 + const cached = caches.match(event.request) + const fixedUrl = getFixedUrl(event.request) + const fetched = fetch(fixedUrl, { cache: 'no-store' }) + const fetchedCopy = fetched.then(resp => resp.clone()) + + // Call respondWith() with whatever we get first. + // If the fetch fails (e.g disconnected), wait for the cache. + // If there’s nothing in cache, wait for the fetch. + // If neither yields a response, return offline pages. + event.respondWith( + Promise.race([fetched.catch(_ => cached), cached]) + .then(resp => resp || fetched) + .catch(_ => { /* eat any errors */ }) + ) + + // Update the cache with the version we fetched (only for ok status) + event.waitUntil( + Promise.all([fetchedCopy, caches.open(RUNTIME)]) + .then(([response, cache]) => response.ok && cache.put(event.request, response)) + .catch(_ => { /* eat any errors */ }) + ) + } +}) +``` + +## 注册 + +现在，到 `index.html` 里注册它。这个功能只能工作在一些现代浏览器上，所以我们需要加个判断。 + +*index.html* + +```html + +``` + +## 体验一下 + +发布你的网站，并开始享受离线模式的魔力吧！:ghost: 当然你现在看到的 docsify 的文档网站已经支持离线模式了，你可以关掉 Wi-Fi 体验一下。 diff --git a/quickstart.md b/quickstart.md new file mode 100644 index 0000000..681fabf --- /dev/null +++ b/quickstart.md @@ -0,0 +1,90 @@ +# 快速开始 + +推荐安装 `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.md)。 + +## 本地预览网站 + +运行一个本地服务器通过 `docsify serve` 可以方便的预览效果，而且提供 LiveReload 功能，可以让实时的预览。默认访问 http://localhost:3000 。 + +```bash +docsify serve docs +``` + +?> 更多命令行工具用法，参考 [docsify-cli 文档](https://github.com/docsifyjs/docsify-cli)。 + +## 手动初始化 + +如果不喜欢 npm 或者觉得安装工具太麻烦，我们其实只需要直接创建一个 `index.html` 文件。 + +*index.html* + +```html + + + + + + + + + +
+ + + + +``` + +如果系统里安装 Python 的话，也可以很轻易的启动一个静态服务器。 + +```bash +cd docs && python -m SimpleHTTPServer 3000 +``` + +## Loading 提示 + +初始化时会显示 `Loading...` 内容，你可以自定义提示信息。 + +*index.html* +```html +
加载中
+``` + +如果更改了 `el` 的配置，需要将该元素加上 `data-app` 属性。 + +*index.html* +```html +
加载中
+ + +``` diff --git a/ssr.md b/ssr.md new file mode 100644 index 0000000..24d934d --- /dev/null +++ b/ssr.md @@ -0,0 +1,118 @@ +# 服务端渲染（SSR） + +先看例子 https://docsify.now.sh + +项目地址在 https://github.com/docsifyjs/docsify-ssr-demo + +![](https://dn-mhke0kuv.qbox.me/2bfef08c592706108055.png) + +文档依旧是部署在 GitHub Pages 上，Node 服务部署在 now.sh 里，渲染的内容是从 GitHub Pages 上同步过来的。所以静态部署文档的服务器和服务端渲染的 Node 服务器是分开的，也就是说你还是可以用之前的方式更新文档，并不需要每次都部署。 + + + +## 快速开始 + +如果你熟悉 `now` 的使用，接下来的介绍就很简单了。先创建一个新项目，并安装 `now` 和 `docsify-cli`。 + +```bash +mkdir my-ssr-demo && cd my-ssr-demo +npm init -y +npm i now docsify-cli -D +``` + +配置 `package.json` + +```json +{ + "scripts": { + "start": "docsify start .", + "deploy": "now -p" + }, + "docsify": { + "config": { + "basePath": "https://docsify.js.org/", + "loadSidebar": true, + "loadNavbar": true + } + } +} +``` + +如果你还没有创建文档，可以参考[之前的文章](https://zhuanlan.zhihu.com/p/24540753)。其中 `basePath` 为文档所在的路径，可以填你的 docsify 文档网站。 + +配置可以单独写在配置文件内，然后通过 `--config config.js` 加载。 + +渲染的基础模版也可以自定义，配置在 `template` 属性上，例如 + +```js +"docsify": { + "template": "./ssr.html", + "config": { + "basePath": "https://docsify.js.org/", + "loadSidebar": true, + "loadNavbar": true + } + } +``` + +*ssr.html* + +```html + + + + + docsify + + + + + + + + + + + + + + +``` + +其中 `` 和 `` 为占位符，会自动将渲染后的 html 和配置内容注入到页面上。 + +现在，你可以运行 `npm start` 预览效果，如果没有问题就通过 `npm run deploy` 部署服务。 + +```bash +npm start +# open http://localhost:4000 + +npm run deploy +# now ... +``` + + + +## 更多玩法 + +`docsify start` 其实是依赖了 [`docsify-server-renderer`](https://npmarket.surge.sh/?name=docsify-server-renderer) 模块，如果你感兴趣，你完全可以用它自己实现一个 server，可以加入缓存等功能。 + +```js +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' + } +}) + +renderer.renderToString(url) + .then(html => {}) + .catch(err => {}) +``` + +当然文档文件和 server 也是可以部署在一起的，`basePath` 不是一个 URL 的话就会当做文件路径处理，也就是从服务器上加载资源。 diff --git a/themes.md b/themes.md new file mode 100644 index 0000000..a7a56f6 --- /dev/null +++ b/themes.md @@ -0,0 +1,61 @@ +# 主题 + +目前提供三套主题可供选择，模仿 [Vue](//vuejs.org) 和 [buble](//buble.surge.sh) 官网订制的主题样式。还有 [@liril-net](https://github.com/liril-net) 贡献的黑色风格的主题。 + +```html + + + + +``` + +!> CSS 的压缩文件位于 `/lib/themes/` + +```html + + + + +``` + +如果你有其他想法或者想开发别的主题，欢迎提 [PR](https://github.com/docsifyjs/docsify/pulls)。 + +#### 点击切换主题 + + +
+ vue.css + buble.css + dark.css + pure.css +
+ + + + + + + +## Other themes + +- [docsify-themeable](https://jhildenbiddle.github.io/docsify-themeable/#/) A delightfully simple theme system for docsify. diff --git a/vue.md b/vue.md new file mode 100644 index 0000000..e0ecc59 --- /dev/null +++ b/vue.md @@ -0,0 +1,112 @@ +# 兼容 Vue + +你可以直接在 Markdown 文件里写 Vue 代码，它将被执行。我们可以用它写一些 Vue 的 Demo 或者示例代码。 + + +## 基础用法 + +在 `index.html` 里引入 Vue。 + +```html + + +``` + +接着就可以愉快地在 Markdown 里写 Vue 了。默认会执行 `new Vue({ el: '#main' })` 创建示例。 + +*README.md* + +```markdown +# Vue 介绍 + +`v-for` 的用法 + +```html +
    +
  • {{ i }}
    • +
+`` + +
    +
  • {{ i }}
    • +
+``` + +当然你也可以手动初始化 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/write-a-plugin.md b/write-a-plugin.md new file mode 100644 index 0000000..c83b107 --- /dev/null +++ b/write-a-plugin.md @@ -0,0 +1,94 @@ +# 自定义插件 + +docsify 提供了一套插件机制，其中提供的钩子（hook）支持处理异步逻辑，可以很方便的扩展功能。 + +## 完整功能 + +```js +window.$docsify = { + plugins: [ + function (hook, vm) { + hook.init(function() { + // 初始化时调用，只调用一次，没有参数。 + }) + + hook.beforeEach(function(content) { + // 每次开始解析 Markdown 内容时调用 + // ... + return content + }) + + hook.afterEach(function(html, next) { + // 解析成 html 后调用。beforeEach 和 afterEach 支持处理异步逻辑 + // ... + // 异步处理完成后调用 next(html) 返回结果 + next(html) + }) + + hook.doneEach(function() { + // 每次路由切换时数据全部加载完成后调用，没有参数。 + // ... + }) + + hook.mounted(function() { + // 初始化完成后调用 ，只调用一次，没有参数。 + }) + + hook.ready(function() { + // 初始化并第一次加完成数据后调用，没有参数。 + }) + } + ] +} +``` + +!> 如果需要用 docsify 的内部方法，可以通过 `window.Docsify` 获取，通过 `vm` 获取当前实例。 + +## 例子 + + +### footer + +给每个页面的末尾加上 `footer` + +```js +window.$docsify = { + plugins: [ + function (hook) { + var footer = [ + '
', + '' + ].join('') + + hook.afterEach(function (html) { + return html + footer + }) + } + ] +} +``` + + +### Edit Button + +```js +window.$docsify = { + plugins: [ + function(hook, vm) { + hook.beforeEach(function (html) { + var url = 'https://github.com/docsifyjs/docsify/blob/master/docs' + vm.route.file + var editHtml = '[📝 EDIT DOCUMENT](' + url + ')\n' + + return editHtml + + html + + '\n----\n' + + 'Last modified {docsify-updated} ' + + editHtml + }) + } + ] +} +```