无需构建快速生成文档页
## 特性 - 无需构建,写完 markdown 直接发布 - 支持自定义主题 - 容易使用并且轻量 (~12kb gzipped) ## 快速上手 ### 创建项目 新建一个空项目,接着创建一个 `docs` 目录并进入到 docs 目录下 ```shell mkdir my-project && cd my-project mkdir docs && cd docs ``` ### 创建入口文件 创建一个 `404.html` 文件,内容为 ```html ``` 新建 `README.md` 文件,作为主页面 ``` # Title ## balabala ``` ### 部署! 将项目 `push` 到 GitHub 仓库后到设置页面开启 **GitHub Pages** 功能,选择 `docs/` 选项 ![image](https://cloud.githubusercontent.com/assets/7565692/20639058/e65e6d22-b3f3-11e6-9b8b-6309c89826f2.png) ## 命令行工具 方便快速创建文档目录,会读取项目的 `package.json` 里的选项作为 docsify 的配置,支持本地预览。 ### 安装 ```shell npm i docsify-cli -g ``` ### 初始化文档 默认初始化在当前目录,推荐将文档放在 `docs` 目录下 ```shell docsify init docs ``` ### 启动本地服务 启动一个 server 方便预览,打开 http://localhost:3000 ```shell docsify serve docs ``` 更多选项参考 [docsify-cli](https://github.com/QingWei-Li/docsify-cli) ## 主题 目前提供 vue.css 和 buble.css,直接修改 `404.html` 里的 cdn 地址即可 ```html ``` 压缩版 ```html ``` ## 更多功能 ### 多页面 `README.md` 作为主页面,如果需要其他页面,直接在文档目录下创建对应的 `*.md` 文件,例如创建一个 `guide.md` 那么对应的路由就是 `/guide`。 ### 导航 导航需要自己写在 `404.html` 文件里,效果参考本文档 ```html ``` ### CDN - UNPKG [https://unpkg.com/docsify/](https://unpkg.com/docsify/) - jsDelivr [http://www.jsdelivr.com/projects/docsify](http://www.jsdelivr.com/projects/docsify) ### 配置参数 #### repo 参考本文档的右上角的 GitHub 图标,如果要开启的话,将 `404.html` 里的 script 改成 ```html ``` #### max-level 目录最大展开层级,默认值为 6 ```html ``` #### el 替换节点元素,默认为 `#app` ```html ``` #### sidebar-toggle Sidebar 开关按钮 ```html ``` #### sidebar 设置后 TOC 功能将不可用,适合导航较多的文档,`data-sidebar` 传入全局变量名。 ![image](https://cloud.githubusercontent.com/assets/7565692/20647425/de5ab1c2-b4ce-11e6-863a-135868f2f9b4.png) ```html ``` #### load-sidebar 读取侧边栏配置文件,如果配置,默认加载当前目录下的 `_sidebar.md`。如果文件不存在,会显示 TOC 作为侧边栏内容。如果你有二级目录,也应该放置一份配置文件。 **如果用 `_` 开头作为文件名,你应该在文档目录下添加 `.nojekyll`,阻止 GitHub Pages 忽略下划线开头的文件。** ```html ``` 你可以指定侧边栏文件名 ```html ``` `_sidebar.md` 的内容可以是这样的 ```markdown - [Home](/) - [Installation](/installation) - Essentials - [Getting Started](/getting-started) - [Dynamic Route Matching](/dynamic-matching) - [Nested Routes](/nested-routes) - [Programmatic Navigation](/navigation) - [Named Routes](/named-routes) - [Named Views](/named-views) - [Redirect and Alias](/redirect-and-alias) - [HTML5 History Mode](/history-mode) ``` #### load-navbar 读取导航配置文件,如果配置,默认加载当前目录下的 `_navbar.md`。如果文件不存在,会显示 html 里定义的导航栏。 ```html ``` 你可以指定导航栏文件名 ```html ``` `_navbar.md` 的内容可以是这样 ```markdown - [en](/) - [中文](/zh-cn) ``` 当然也支持二级列表,将生成一个下拉列表 ```markdown - [download](/download) - language - [en](/) - [中文](/zh-cn) ``` #### router 开启 hash router 功能,此时可以创建 `index.html` 作为入口文件,同时多页面切换不会重新加载资源。资源路径会被替换成 `/#/` 的形式。 ```html ``` #### auto2top 切换路由时自动跳转到页面顶部 ```html ``` #### homepage 默认情况下网站会将根目录下 `README.md` 作为首页渲染,但是有些时候我们想指定其他文件,甚至想直接将 repo 下的 README 作为首页。你可以这样做(需要设置 `data-router`): ```html ``` #### basePath 指定加载文档的路径,如果你的 HTML 入口文件和文档是放在不同地方,你可以设置: ```html ```