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

content

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

content

` + +### 1.5.2 +#### Bug fixes +- Fixed number at the beginning of the slug + +### 1.5.1 +#### Bug fixes +- Remove HTML tag when handling slug + +### 1.5.0 + +#### Bug fixes +- Fix slugify. +- Fix nav highlight. + +#### Features +- Initialize the configuration by `window.$docsify`. +- Markdown parser is configurable. + +### 1.4.3 +#### Bug fixes +- Tweak style. + +### 1.4.2 + +#### Bug fixes +- Fix toggle button style. +- Support `mailto`, `tel`, etc. href type +- Fix scroll to top. + + +### 1.4.1 +#### Bug fixes +- Fix generate slug. + +### 1.4.0 Happly new year 🎉 +#### Features +- Display TOC in the custom sidebar, `data-sub-max-level`. +- Custom background in coverpage. + +#### Bug fixes +- Fix scroll highlight when Vue exist. + +### 1.3.5 +#### Bug fixes +- Fix vue + +### 1.3.4 +#### Bug fixes + +- Supports [vuep](https://github.com/QingWei-Li/vuep) + +### 1.3.3 +#### Bug fixes +- Fixed cover rendering timing + +### 1.3.2 + +#### Bug fixes +- Fixed render link + +### 1.3.1 + +#### Bug fixes +- Fixed cover page style +- Generate the correct link when rendering the article + +### 1.3.0 +#### Features +- Add cover page +- add `` style +- headling can be cliked + +#### Bug fixes +- sidebar highlight + + +#### break change +- Navbar no longer fixed at the top + +### 1.2.0 +#### Features +- custom basePath +- custom homepage + +### 1.1.7 +#### Bug fixes +- Optimize progress bar + +### 1.1.6 +#### Features +- Add logo 😂 + +#### Bug fixes +- Remove table background color +- Fixed highlight sidebar using chinese ids + +### 1.1.5 +#### Features +- Add table style + +#### Bug fixes +- Not fixed position of hte navbar in the mobile browser +- Correct calculation of whether the mobile browser + +### 1.1.4 +#### Bug fixes +- Fixed chinese auchor link + +### 1.1.3 +#### Bug fixes +- Optimize progress bar again + +### 1.1.2 +#### Bug fixes +- fix failed `auto2top` in mobile + + +### 1.1.1 +#### Bug fixes +- Optimize progress bar + +### 1.1.0 +#### Features +- Add progress bar +- Add `auto2top` option for hash router + +### 1.0.3 +#### Bug fixes +- Fix cache + +### 1.0.2 +#### Bug fixes +- Fix binding events bug, fixed #24 +- Fix regular expression, fixed #23 + +### 1.0.1 +#### Bug fixes +- `img` style + +### 1.0.0 +#### Features +- Support hash router + +#### Bug fixes +- Improved scrolling on mobile + +### 0.7.0 +#### Breaking change +- `themes/` was removed, only exists in the npm package. + +#### Bug fixes +- Fix style. +- Fix sidebar animation again. + +### 0.6.1 +#### Bug fixes +- In the mobile, it should collapse the sidebar when toggle is clicked. +- Fix the dropdown list style. +- Fix sidebar animation. + +### 0.6.0 +#### Features +- Navbar support dropdown list, #6 +- Sidebar with toggle + +#### Bug fixes +- Fix ineffective option, fixed #10 + +### 0.5.0 +#### Features +- Custom sidebars and navbars by markdown file + +### 0.4.2 +#### Bug fixes +- Correct catch ajax error + +### 0.4.1 +#### Bug fixes +- catch ajax error + +### 0.4.0 +#### Features +- Custom sidebar + +#### Bug fixes +- Fix undefined language + +### 0.3.1 +#### Bug fixes +- Strip HTML tag when rendering the headings + +### 0.3.0 +#### Features +- Add minified css files +- Add max level option +- Add pure.css + +### 0.2.1 +#### Bug fixes +- Fix vue.css + +### 0.2.0 +#### Bug fixes +- Fix route +- Remove dynamic title + +### 0.1.0 +#### Features +- Add buble.css \ No newline at end of file diff --git a/README.md b/README.md index 66cf9cd0..e813c9f5 100644 --- a/README.md +++ b/README.md @@ -82,14 +82,5 @@ npm i && npm run dev open http://localhost:3000 ``` -## More Language Highlight - -```html - - - -``` - ## License MIT - diff --git a/dev.html b/dev.html index f1c9abb5..5fb55eb7 100644 --- a/dev.html +++ b/dev.html @@ -2,21 +2,22 @@ + docsify
- diff --git a/docs/_images/deploy-github-pages.png b/docs/_images/deploy-github-pages.png new file mode 100644 index 00000000..278e40b3 Binary files /dev/null and b/docs/_images/deploy-github-pages.png differ diff --git a/docs/_images/zh-cn/nested-navbar.png b/docs/_images/zh-cn/nested-navbar.png new file mode 100644 index 00000000..3f4aa27f Binary files /dev/null and b/docs/_images/zh-cn/nested-navbar.png differ diff --git a/docs/favicon.ico b/docs/_media/favicon.ico similarity index 100% rename from docs/favicon.ico rename to docs/_media/favicon.ico diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 00000000..1c87b241 --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,20 @@ +- Basic + - [Quick start](/quickstart) + - [Writing more pages](/more-pages) + - [Custom nav](/custom-navbar) + - [Cover page](/cover) + +- Configuration + - [Configuration](/configuration) + - [Themes](/themes) + - [Using plugins](/plugins) + - [Markdown configuration](/markdown) + - [Lanuage highlight](/language-highlight) + +- Guide + - [Deploy](/deploy) + - [Doc helper](/helpers) + - [Compatible Vue](/vue) + - [CDN](/cdn) + +- [Changelog](/changelog) \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 19ea1d09..53738964 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2,8 +2,9 @@ - docsify - A magical documentation site generator. - + docsify + + @@ -11,24 +12,27 @@
- + + diff --git a/docs/zh-cn/README.md b/docs/zh-cn/README.md new file mode 100644 index 00000000..0d93c1b8 --- /dev/null +++ b/docs/zh-cn/README.md @@ -0,0 +1,26 @@ +## docsify + +> 一个神奇的文档网站生成工具 + +## 是什么 + +docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 `.md` 转成 `.html` 文件，所有转换工作都是在运行时进行。 + +这将非常实用，如果你只是需要快速的写一个小型的文档，或者不想因为生成的一堆 `.html` 文件“污染” commit 记录，只需要创建一个 `index.html` 就可以开始写文档而且直接部署。 + +可以查看[快速开始](zh-cn/quickstart)一章了解详情。 + +## 特性 +- 无需构建，写完 markdown 直接发布 +- 容易使用并且轻量 (~13Kb gzipped) +- 智能的全文检索 +- 提供多套主题 +- 丰富的 API + +## 例子 + +可以查看 [Showcase](https://github.com/QingWei-Li/docsify/#showcase) 来了解使用 docsify 的文档项目。 + +## 支持 + +有任何使用上的问题或者 Bug 欢迎提 [Issues](https://github.com/QingWei-Li/docsify/issues/)，祝你使用愉快! diff --git a/docs/zh-cn/_sidebar.md b/docs/zh-cn/_sidebar.md new file mode 100644 index 00000000..d2aa0bff --- /dev/null +++ b/docs/zh-cn/_sidebar.md @@ -0,0 +1,20 @@ +- 基础 + - [快速开始](zh-cn/quickstart) + - [多页文档](zh-cn/more-pages) + - [嵌套导航栏](zh-cn/custom-navbar) + - [封面](zh-cn/cover) + +- 配置 + - [配置项](zh-cn/configuration) + - [主题](zh-cn/themes) + - [使用插件](zh-cn/plugins) + - [Markdown 配置](zh-cn/markdown) + - [代码高亮](zh-cn/language-highlight) + +- 指南 + - [部署](zh-cn/deploy) + - [文档助手](zh-cn/helpers) + - [兼容 Vue](zh-cn/vue) + - [CDN](zh-cn/cdn) + +- [Changelog](zh-cn/changelog) \ No newline at end of file diff --git a/docs/zh-cn/cdn.md b/docs/zh-cn/cdn.md new file mode 100644 index 00000000..3e776698 --- /dev/null +++ b/docs/zh-cn/cdn.md @@ -0,0 +1,48 @@ +# CDN + +推荐使用 [UNPKG](//unpkg.com) —— 能及时获取到最新版。 + +## 获取最新版本 + +根据 UNPKG 的规则，不指定特定版本号时将引入最新版。 + +```html + + + + + +``` + +## 获取指定版本 + +如果你担心频繁地版本更新又可能引入未知 Bug，你也可以使用具体的版本。规则是 `//unpkg.com/docsify/VERSION/` + +```html + + + + + +``` + +!> 指定 *VERSION* 为 `latest` 可以强制每次都请求最新版本。 + +## 压缩版 + +CSS 的压缩文件位于 `/lib/themes/` 目录下 + +```html + +``` + +JS 的压缩文件是原有文件路径的基础上加 `.min`后缀 + +```html + +``` + +## 其他 CDN + +[jsDelivr](http://www.jsdelivr.com/projects/docsify) 也是可用的，具体用法参考其文档。 + diff --git a/docs/zh-cn/configuration.md b/docs/zh-cn/configuration.md new file mode 100644 index 00000000..930792ea --- /dev/null +++ b/docs/zh-cn/configuration.md @@ -0,0 +1,36 @@ +# 配置项 + +> TODO + +## el + +## repo + +## max-level + +## load-navbar + +## load-sidebar + +## sub-max-level + + +## load-navbar + +## auto2top + + +## homepage + + +## base-path + +## coverpage + +## name + +## name-link + +## theme-color + +## alias diff --git a/docs/zh-cn/cover.md b/docs/zh-cn/cover.md new file mode 100644 index 00000000..8d8da071 --- /dev/null +++ b/docs/zh-cn/cover.md @@ -0,0 +1,3 @@ +# 封面 + +> TODO \ No newline at end of file diff --git a/docs/zh-cn/custom-navbar.md b/docs/zh-cn/custom-navbar.md new file mode 100644 index 00000000..74bc20a3 --- /dev/null +++ b/docs/zh-cn/custom-navbar.md @@ -0,0 +1,60 @@ +# 自定义导航栏 + +> TODO + +*index.html* + +```html + + +
+ +``` + + + +## 配置文件 + +*index.html* + + +```html + + +``` + +*_navbar.md* + +```markdown +- [En](/) +- [中文](/zh-cn/) +``` + +## 嵌套 + +*_navbar.md* + + +```markdown +- 基础 + - [快速开始](zh-cn/quickstart) + - [多页文档](zh-cn/more-pages) + - [嵌套导航栏](zh-cn/custom-navbar) + - [封面](zh-cn/cover) + +- 配置 + - [配置项](zh-cn/configuration) + - [主题](zh-cn/themes) + - [使用插件](zh-cn/plugins) + - [Markdown 配置](zh-cn/markdown) + - [代码高亮](zh-cn/language-highlight) +``` + +![嵌套导航栏](_images/zh-cn/nested-navbar.png "嵌套导航栏") diff --git a/docs/zh-cn/deploy.md b/docs/zh-cn/deploy.md new file mode 100644 index 00000000..3e33d5e2 --- /dev/null +++ b/docs/zh-cn/deploy.md @@ -0,0 +1,34 @@ +# 部署 + +和 GitBook 生成的文档一样，我们可以直接把文档网站部署到 GitHub Pages 或者 VPS 上。 + +## 部署 GitHub Pages + +GitHub Pages 支持从三个地方读取文件 +- `docs/` 目录 +- master 分支 +- gh-pages 分支 + +我们推荐直接将文档放在 `docs/` 目录下，在设置页面开启 **GitHub Pages** 功能并选择 `master branch /docs folder` 选项。 + +![github pages](_images/deploy-github-pages.png) + +!> 你可以将文档放在根目录下，然后选择 **master 分支** 作为文档目录。 + +## 部署 VPS + +和部署所有静态网站一样，将服务器的访问根目录设定为 `index.html` 文件。 + +例如 nginx 的配置 + +```nginx +server { + listen 80; + server_name your.domain.com; + + location / { + alias /path/to/dir/of/docs; + index index.html; + } +} +``` diff --git a/docs/zh-cn/helpers.md b/docs/zh-cn/helpers.md new file mode 100644 index 00000000..fca6c595 --- /dev/null +++ b/docs/zh-cn/helpers.md @@ -0,0 +1,26 @@ +# 文档助手 + +docsify 扩展了一些 Markdown 语法，可以让你的文档更易读。 + + +## 强调内容 + +适合显示重要的提示信息，语法为 `!> 内容`。 + +```markdown +!> 一段重要的内容，可以和其他 **Markdown** 语法混用。 +``` + +!> 一段重要的内容，可以和其他 **Markdown** 语法混用。 + + +## 普通提示 + +不重要的提示信息，比如写 TODO 或者参考内容等。 + +```markdown +?> *TODO* 完善示例 +``` + +?> *TODO* 完善示例 + diff --git a/docs/zh-cn/language-highlight.md b/docs/zh-cn/language-highlight.md new file mode 100644 index 00000000..bb7029c4 --- /dev/null +++ b/docs/zh-cn/language-highlight.md @@ -0,0 +1,11 @@ +# 代码高亮 + +内置的代码高亮工具是 [Prism](https://github.com/PrismJS/prism)，默认支持 CSS、JavaScript 和 HTML。如果你需要高亮其语言——例如 PHP——你可以手动引入代码高亮插件。 + +```html + + + +``` + +其他的语言高亮插件可以查看[Prims 仓库](https://github.com/PrismJS/prism/tree/gh-pages/components)。 \ No newline at end of file diff --git a/docs/zh-cn/markdown.md b/docs/zh-cn/markdown.md new file mode 100644 index 00000000..51fe044a --- /dev/null +++ b/docs/zh-cn/markdown.md @@ -0,0 +1,26 @@ +# Markdown 配置 + +内置的 Markdown 解析插件是 [marked](https://github.com/chjj/marked)，你可以修改它的配置。 + +```js +window.$docsify = { + markdown: { + smartypants: true + // ... + } +} +``` + +?> 完整配置参数参考 [marked 文档](https://github.com/chjj/marked#options-1) + +当然你也可以完全定制 markdown 解析规则。 + +```js +window.$docsify = { + markdown: function(marked) { + // ... + + return marked + } +} +``` \ No newline at end of file diff --git a/docs/zh-cn/more-pages.md b/docs/zh-cn/more-pages.md new file mode 100644 index 00000000..0fcbaa6b --- /dev/null +++ b/docs/zh-cn/more-pages.md @@ -0,0 +1,62 @@ +# 多页文档 + +如果你的文档需要创建多个页面，或者需要提供多语言的文档。在 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 +``` + +## 定制侧边栏 + +默认情况下，侧边栏会根据当前文档的目录生成。你可以定制成文档链接，效果如当前的文档的侧边栏。 + +首先配置 docsify 的 `loadSidebar` 选项，具体配置规则见[配置项#load-sidebar](zh-cn/configuration#load-sidebar)一章。 + +```html + + +``` + +接着创建 `_sidebar.md` 文件，内容如下 + +```markdown +- [首页](zh-cn/) +- [指南](zh-cn/guide) +``` + +!> 需要在文档更目录创建 `.nojekyll` 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。 + + +## 显示目录 + +自定义侧边栏同时也可以开启目录功能。设置 `subMaxLevel` 配置项，具体介绍见 [配置项#sub-max-level](zh-cn/configuration#sub-max-level)。 + +```html + + +``` diff --git a/docs/zh-cn/plugins.md b/docs/zh-cn/plugins.md new file mode 100644 index 00000000..d2098ef3 --- /dev/null +++ b/docs/zh-cn/plugins.md @@ -0,0 +1,102 @@ +# 使用插件 + +## 内置插件 + +### 全文检索 - Search + +全文检索插件会根据当前页面上的超链接获取文档内容，在 `localStorage` 内建立文档索引。默认过期时间为一天，当然你可以自己指定需要缓存的文件列表或者配置过期时间。 + + +```html + + + +``` + +### 谷歌统计 - Google Analytics + +需要配置 track id 才能使用。 + +```html + + + +``` + +## 自定义插件 + +docsify 提供了一套插件注册机制，其中提供的钩子（hook）支持处理异步逻辑，可以很方便的扩展功能。 + +#### 完整功能 + +```js +window.$docsify = { + plugins: [ + function (hook) { + hook.init(function() { + // 初始化时调用，只调用一次 + }) + hook.beforeEach(function(content) { + // 每次开始解析 markdown 内容时调用 + // ... + return content + }) + hook.afterEach(function(html, next) { + // 解析成 html 后调用。beforeEach 和 afterEach 支持处理异步逻辑 + // ... + // 处理完成后调用 next(html) 返回结果 + next(html) + }) + hook.ready(function() { + // docsify 初始化完成后调用，只调用一次 + }) + } + ] +} +``` + +#### 例子 + +给每个页面的末尾加上 `footer` + +```js +window.$docsify = { + plugins: [ + function (hook) { + var footer = [ + '
', + '' + ].join('') + + hook.afterEach(function (html) { + return html + footer + }) + } + ] +} +``` diff --git a/docs/zh-cn/quickstart.md b/docs/zh-cn/quickstart.md new file mode 100644 index 00000000..442c626f --- /dev/null +++ b/docs/zh-cn/quickstart.md @@ -0,0 +1,59 @@ +# 快速开始 + +推荐安装 `docsify-cli` 工具，可以方便创建及本地预览文档网站。 + +```bash +npm i docsify-cli -g +``` + +## 初始化项目 + +如果你想在项目的 `./docs` 目录里写文档，直接通过 `init` 初始化项目。 + +```bash +docsify init ./docs +``` + +## 开始写文档 + +初始化成功后，可以看到 `./docs` 目录下创建的几个文件 + +- `index.html` 入口文件 +- `README.md` 会做为主页内容渲染 +- `.nojekyll` 用于阻止 GitHub Pages 会忽略掉下划线开头的文件 + +直接编辑 `docs/README.md` 就能更新网站内容，当然你可以[写多个页面](zh-cn/more-pages)。 + +## 本地预览网站 + +运行一个本地服务器通过 `docsify serve` 可以方便的预览效果，而且提供 LiveReload 功能，可以让实时的预览。默认访问 http://localhost:3000 。 + +```bash +docsify serve docs +``` + +?> 更多命令行工具用法，参考 [docsify-cli 文档](https://github.com/QingWei-Li/docsify-cli)。 + +## 手动初始化 + +如果你不喜欢 npm 安装工具，或者不需要本地预览文档功能，我们其实只需要直接创建一个 `index.html` 文件。 + +```html + + + + + + + +
+ + + +``` + +如果你设备里安装 Python 的话，也可以很轻易的启动一个静态服务器。 + +```bash +cd docs && python -m SimpleHTTPServer 3000 +``` diff --git a/docs/zh-cn/themes.md b/docs/zh-cn/themes.md new file mode 100644 index 00000000..34ff2e4a --- /dev/null +++ b/docs/zh-cn/themes.md @@ -0,0 +1,12 @@ +# 主题 + +目前提供两套主题可供选择，模仿 [vue](//vuejs.org) 和 [buble](//buble.surge.sh) 官网订制的主题样式。引入其中之一即可。 + +```html + + +``` + +!> CSS 的压缩文件位于 `/lib/themes/` + +如果你有其他想法或者想开发别的主题，欢迎提 PR。 \ No newline at end of file diff --git a/docs/zh-cn/vue.md b/docs/zh-cn/vue.md new file mode 100644 index 00000000..d603db1d --- /dev/null +++ b/docs/zh-cn/vue.md @@ -0,0 +1,86 @@ +# 兼容 Vue + +Docsify 的一大特色是可以配合 Vue 一起使用。你可以直接在 Markdown 文件里写 Vue 代码，它将被执行。我们可以用它写一些 Vue 的 Demo 或者示例代码。 + + +## 基础用法 + +用法很简单，首先在 `index.html` 里引入 Vue 脚本。 + +```html + + +``` + +接着就可以直接在 Markdown 里写 Vue 了。默认会自动执行 `new Vue({ el: 'main' })` 脚本。 + +*README.md* + +```markdown +# Vue 介绍 + +`v-for` 的用法 + +```html + +`` + + +``` + +当然你也可以手动初始化 Vue，这样你可以自定义一些配置。 + +*README.md* + +```markdown +# Vue 的基本用法 + +
hello {{ msg }}
+ +``` + +!> 一个 Markdown 文件里只有第一个 `script` 标签内的内容会被执行。 + +## 搭配 Vuep 写 Playground + +[Vuep](https://github.com/QingWei-Li/vuep) 是一个提供在线编辑和预览效果的 Vue 组件，搭配 docsify 可以直接在文档里写 Vue 的示例代码，支持 Vue component spec 和 JSX。 + +*index.html* + +```html + + + +``` + +*README.md* +```markdown +# Vuep 使用 + + + + + +``` + +?> 具体效果参考 [Vuep 文档](https://qingwei-li.github.io/vuep/)。