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

软件发布|下载排行|最新软件

当前位置:首页IT学院IT技术

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

xhemj   2020-04-01 我要评论
# 使用Docsify做文档网站的详细配置教程 > 作者:xhemj 没错,它叫Docsify。
![logo](https:/https://img.qb5200.com/download-x/docsify.js.org/_media/icon.svg)
[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
Please wait...
``` ### 自定义侧边栏 只需在`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 ``` 效果就是点击一下图片可以放大
如:
![logo](https:/https://img.qb5200.com/download-x/docsify.js.org/_media/icon.svg)
如果不想缩放可以设置:
```markdown ![](image.png ":no-zoom") ``` ### 复制代码插件 ```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)哦!
好看就分享一下吧!

Copyright 2022 版权所有 软件发布 访问手机版

声明:所有软件和文章来自软件开发商或者作者 如有异议 请与本站联系 联系我们