使用Docsify做文档网站的详细配置教程

# 使用Docsify做文档网站的详细配置教程 > 作者：xhemj 没错，它叫Docsify。
[xhemj的文档中心](https://xhemj.gitee.io/books)就是用这个写的
> 开源地址：[https://github.comhttps://img.qb5200.com/download-x/docsifyjshttps://img.qb5200.com/download-x/docsify/](https://github.comhttps://img.qb5200.com/download-x/docsifyjshttps://img.qb5200.com/download-x/docsify/)
> 官方Demo：[https:/https://img.qb5200.com/download-x/docsify.js.org/](https:/https://img.qb5200.com/download-x/docsify.js.org/)
## 目录 - [官方说明](#官方说明) - [安装](#安装) - [如何写文章](#如何写文章) - [个性化](#个性化) - [插件](#插件) - [结尾](#结尾) ## 官方说明 ```text Docsify A magical documentation site generator. Simple and lightweight (~21kB gzipped) No statically built html files Multiple themes ``` Docsify
一个神奇的文档站点生成器。
简单轻巧（~21kB）
没有生成静态的html文件
主题丰富
## 安装 ### 本地搭建 如果你想在本地搭建：
npm安装：
```bash npm i docsify-cli -g ``` 初始化：
```bash docsify init .https://img.qb5200.com/download-x/docs ``` 本地预览：
```bash docsify serve docs ``` 进入`http://localhost:3000`就能看到效果咯！
### 托管在网上 如果你想在托管在网上：
新建一个`index.html`内容为：
```html ``` ### CDN的选择 CDN可以选择：
```html ``` 这样就可以看到一个最基本的网页啦！
## 如何写文章 只需用Markdown语法写好一个`.md`的文章放在根目录或子目录后就会自动识别了。
我自己测试好像用html的也可以，直接把后缀名改成`.md`，但效果可能不太好。
文章链接对应：
```text /README.md => domain.com/#/ /hello.md => domain.com/#/hello /hello/hi.md => domain.com/#/hello/hi ``` 如本教程文章Markdown文件为：[https://gitee.com/xhemj/books/raw/master/p/How-to-Use-Docsify.md](https://gitee.com/xhemj/books/raw/master/p/How-to-Use-Docsify.md)
渲染成：[https://xhemj.gitee.io/books/#/p/How-to-Use-Docsify](https://xhemj.gitee.io/books/#/p/How-to-Use-Docsify)
## 个性化 ### 自定义加载文字 只需在`index.html`中新增：
```html ``` ### 自定义侧边栏 只需在`index.html`中新增：
```html ``` 后创建一个文件叫做`_sidebar.md`，将你的文件输入进去： ``` * [Home](/) * [Guide](guide.md) ``` `_sidebar.md`的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。
例如当前路径为`/zh-cn/more-pages`则从`/zh-cn/_sidebar.md`获取文件，如果不存在则从`/_sidebar.md`获取。
!> 注意，如果是托管在网上，请在文件根目录新增名叫`.nojekyll`的空文件。
为了更好地SEO，您可以在每个文件后面自定义标题：
```markdown * [Home](/) * [Guide](guide.md "The greatest guide in the world") ``` 默认情况下会自动根据文章标题生成目录，如果不想要，可以再`index.html`中新增：
```html ``` `subMaxLevel: 2`表示只显示`h1~h2`的标题，对应`#`和`##`。
如果你想忽略某个标题，则可以在文章中新增`{docsify-ignore}`：
```markdown # Getting Started ## Header {docsify-ignore} ``` 如果想忽略全部的标题，则可以新增`{docsify-ignore-all}`：
```markdown # Getting Started {docsify-ignore-all} ## Header ``` 表示忽略`{docsify-ignore-all}`下的全部标题
!> `{docsify-ignore-all}`和`{docsify-ignore}`在正文中都不会显示 ### 自定义导航栏
写法一：
在`index.html`中新增：
```html ``` !> 所有路径都必须用`#/`来书写 写法二：
在根目录新增`_navbar.md`文件：
写法同`_sidebar.md`
```markdown * [En](/) * [chinese](/zh-cn/) ``` 你也可以按照如下来写多级导航栏：
```markdown * Getting started * [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) ``` `_navbar.md`的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。
例如当前路径为`/zh-cn/more-pages`则从`/zh-cn/_navbar.md`获取文件，如果不存在则从`_navbar.md`获取。
### 封面 设置： ```html window.$docsify = { coverpage: true, } ``` 后再根目录创建`_coverpage.md` 输入内容就可以显示在封面了 效果见[https://xhemj.gitee.io/books/](https://xhemj.gitee.io/books/) ### 主题颜色 设置： ```html window.$docsify = { themeColor: '#c30aff', } ``` `#c30aff`就是主题的颜色了 ### 外链打开方式 设置： ```html window.$docsify = { externalLinkTarget: '_blank', } ``` `_blank`表示在新标签页中打开 ## 插件 ### 表情插件 先在在`index.html`中新增：
```html ``` !> 我自己测试是我上面推荐的三个CDN都可以使用 即可输入
`:100:` => :100: ### 搜索插件 新增`index.html`：
```html ``` 那我们来解释一下：
1.指定搜索路径
`search: 'auto',`表示是否搜索，默认是`auto`
或：
```html search : [ '/', // => /README.md '/guide', // => /guide.md '/get-started', // => /get-started.md '/zh-cn/', // => /zh-cn/README.md ], ``` 如：`/`就表示`README.md`
`guide`表示`/guide.md`
设置后就表示只搜索这几个目录
2.`maxAge: 86400000,`到期时间（官方这么说），不用改动
3.`paths: [], `可以设置搜索的目录，或设置`auto`或`/`，貌似和`search:[]`一样？
4.搜索框的提示
`placeholder: 'Type to search',`
或：
```html placeholder: { '/zh-cn/': '搜索', '/': 'Type to search' }, ``` 这样可以设置中英文目录的搜索框的提示
`noData: 'No Results!',`表示无结果时显示的文字
或：
```html noData: { '/zh-cn/': '找不到结果', '/': 'No Results' }, ``` 分别设置中英文
5.标题深度
`depth: 2,`（官方这么解释）可以设置为`1-6`
6.隐藏其他侧边栏内容
`hideOtherSidebarContent: false,`（官方这么解释）默认为`false`
7.避免搜索索引冲突
`namespace: 'website-1',`可以自己设置
同一域下的多个网站之间可以设置名称
避免搜索索引冲突
其实有很多参数都不用设置
比如我的配置是：
```html search: 'auto', search: { maxAge: 86400000, paths: '/', placeholder: '搜索...', noData: '未找到结果，换个搜索词试试？', namespace: 'XhemjBlog', }, ``` ### Google Analytics 就是谷歌统计
直接新增：
```html ``` `ga: 'UA-XXXXX-Y'`就是谷歌统计的编号
或：
```html ``` `ga: 'UA-XXXXX-Y'`=`data-ga="UA-XXXXX-Y"` ### 外链脚本插件 如果你需要在`.md`文件中引用如：
```html ``` 安装：
``` ``` > 照这样看来是可以在`.md`中写`.html`的…… ### 图片缩放插件 ```html ``` 效果就是点击一下图片可以放大
如：
如果不想缩放可以设置：
```markdown  ``` ### 复制代码插件 ```html ``` 效果可以自己看上面的所有代码
### Disqus评论插件 ```html ``` 详见：[https:/https://img.qb5200.com/download-x/disqus.com/](https:/https://img.qb5200.com/download-x/disqus.com/)
### Gitalk评论插件 ```html ``` 可以使文章实现评论效果，教程详见：[https://github.com/gitalk/gitalk/](https://github.com/gitalk/gitalk/)
### 链接下一篇文章插件 可以再文章底部显示“下一篇”和“上一篇”
效果见[https://xhemj.gitee.io/books/#/p/how-to-use-Docsify.md](https://xhemj.gitee.io/books/#/p/how-to-use-Docsify)
```html ``` 也可以自定义：
```html window.$docsify = { pagination: { previousText: '上一篇', nextText: '下一篇', crossChapter: true, crossChapterText: true, }, } ``` 更多插件可以见[https:/https://img.qb5200.com/download-x/docsify.js.org/#/awesome?id=plugins](https:/https://img.qb5200.com/download-x/docsify.js.org/#/awesome?id=plugins)
!> 以下是我自己使用的插件 ### Social Share分享插件 经过测试，无法直接在`index.html`中嵌入代码
需要先安装上面的外链脚本插件
```html ``` 后在`.md`文件中写下：
```markdown ``` 即可在文件中嵌入分享插件
详细自定义教程可见：[https://github.com/overtrue/share.js](https://github.com/overtrue/share.js)
### 嵌入Markdown文件插件 ```html ``` 自定义：
```html window.$docsify = { footer: { copy: '', auth: '', pre: '

---

', style:'text-align: center;' }, } ``` 实测`copy`和`auth`可以随便写
写什么文字代码都可以
`pre`是正文和Footer的分割线，默认`

---

`
效果可以见[https://xhemj.gitee.io/books/#/p/how-to-use-Docsify.md](https://xhemj.gitee.io/books/#/p/how-to-use-Docsify)
## 结尾 基本上配置就是这样了！本文当基于[官方文档](https:/https://img.qb5200.com/download-x/docsify.js.org/)书写
要是有什么说不到位的欢迎私信我或者发邮件到[xhemj2680@163.com](mailto:xhemj2680@163.com)哦！
好看就分享一下吧！