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

news/2024/5/13 1:19:03/文章来源:https://blog.csdn.net/qq_41026919/article/details/105812751

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

作者：xhemj

没错，它叫Docsify。
logo
xhemj的文档中心就是用这个写的

开源地址：https://github.com/docsifyjs/docsify/
官方Demo：https://docsify.js.org/

目录

  • 官方说明
  • 安装
  • 如何写文章
  • 个性化
  • 插件
  • 结尾

官方说明

Docsify
A magical documentation site generator.
Simple and lightweight (~21kB gzipped)
No statically built html files
Multiple themes

Docsify
一个神奇的文档站点生成器。
简单轻巧（~21kB）
没有生成静态的html文件
主题丰富

安装

本地搭建

如果你想在本地搭建：
npm安装：

npm i docsify-cli -g

初始化：

docsify init ./docs

本地预览：

docsify serve docs

进入http://localhost:3000就能看到效果咯！

托管在网上

如果你想在托管在网上：
新建一个index.html内容为：

<!DOCTYPE html>
<html>
<head><meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"><meta name="viewport" content="width=device-width,initial-scale=1"><meta charset="UTF-8"><link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
</head>
<body><div id="app"></div><script>window.$docsify = {//...}</script><script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
</body>
</html>

CDN的选择

CDN可以选择：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/docsify/4.11.2/docsify.min.js"></script>
<script src="//unpkg.com/docsify/lib/docsify.min.js"></script>

这样就可以看到一个最基本的网页啦！

如何写文章

只需用Markdown语法写好一个.md的文章放在根目录或子目录后就会自动识别了。
我自己测试好像用html的也可以，直接把后缀名改成.md，但效果可能不太好。
文章链接对应：

/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://xhemj.gitee.io/books/#/p/How-to-Use-Docsify

个性化

自定义加载文字

只需在index.html中新增：

<div id="app">Please wait...</div>

自定义侧边栏

只需在index.html中新增：

<script>window.$docsify = {loadSidebar: true}
</script>

后创建一个文件叫做_sidebar.md，将你的文件输入进去：

* [Home](/)
* [Guide](guide.md)

_sidebar.md的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。
例如当前路径为/zh-cn/more-pages则从/zh-cn/_sidebar.md获取文件，如果不存在则从/_sidebar.md获取。

注意，如果是托管在网上，请在文件根目录新增名叫.nojekyll的空文件。

为了更好地SEO，您可以在每个文件后面自定义标题：

* [Home](/)
* [Guide](guide.md "The greatest guide in the world")

默认情况下会自动根据文章标题生成目录，如果不想要，可以再index.html中新增：

<script>window.$docsify = {loadSidebar: true,subMaxLevel: 2}
</script>

subMaxLevel: 2表示只显示h1~h2的标题，对应#和##。
如果你想忽略某个标题，则可以在文章中新增{docsify-ignore}：

# Getting Started
## Header {docsify-ignore}

如果想忽略全部的标题，则可以新增{docsify-ignore-all}：

# Getting Started {docsify-ignore-all}
## Header

表示忽略{docsify-ignore-all}下的全部标题

{docsify-ignore-all}和{docsify-ignore}在正文中都不会显示

自定义导航栏

写法一：
在index.html中新增：

<body><nav><a href="#/">EN</a><a href="#/zh-cn/">中文</a></nav><div id="app"></div>
</body>

所有路径都必须用#/来书写

写法二：
在根目录新增_navbar.md文件：
写法同_sidebar.md

* [En](/)
* [chinese](/zh-cn/)

你也可以按照如下来写多级导航栏：

* 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获取。

封面

设置：

window.$docsify = {coverpage: true,
}

后再根目录创建_coverpage.md
输入内容就可以显示在封面了
效果见https://xhemj.gitee.io/books/

主题颜色

设置：

window.$docsify = {themeColor: '#c30aff',
}

#c30aff就是主题的颜色了

外链打开方式

设置：

window.$docsify = {externalLinkTarget: '_blank',
}

_blank表示在新标签页中打开

插件

表情插件

先在在index.html中新增：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>

我自己测试是我上面推荐的三个CDN都可以使用

即可输入
:100: => 💯

搜索插件

新增index.html：

<script>window.$docsify = {search: 'auto', search : ['/',            // => /README.md'/guide',       // => /guide.md'/get-started', // => /get-started.md'/zh-cn/',      // => /zh-cn/README.md],search: {maxAge: 86400000, paths: [], placeholder: 'Type to search',placeholder: {'/zh-cn/': '搜索','/': 'Type to search'},noData: 'No Results!',noData: {'/zh-cn/': '找不到结果','/': 'No Results'},depth: 2,hideOtherSidebarContent: false,namespace: 'website-1',}}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

那我们来解释一下：
1.指定搜索路径
search: 'auto',表示是否搜索，默认是auto
或：

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',
或：

placeholder: {'/zh-cn/': '搜索','/': 'Type to search'},

这样可以设置中英文目录的搜索框的提示
noData: 'No Results!',表示无结果时显示的文字
或：

noData: {'/zh-cn/': '找不到结果','/': 'No Results'},

分别设置中英文
5.标题深度
depth: 2,（官方这么解释）可以设置为1-6
6.隐藏其他侧边栏内容
hideOtherSidebarContent: false,（官方这么解释）默认为false
7.避免搜索索引冲突
namespace: 'website-1',可以自己设置
同一域下的多个网站之间可以设置名称
避免搜索索引冲突
其实有很多参数都不用设置
比如我的配置是：

search: 'auto',
search: {
maxAge: 86400000,
paths: '/',
placeholder: '搜索...',
noData: '未找到结果，换个搜索词试试？',
namespace: 'XhemjBlog',},

Google Analytics

就是谷歌统计
直接新增：

<script>window.$docsify = {ga: 'UA-XXXXX-Y'}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>

ga: 'UA-XXXXX-Y'就是谷歌统计的编号
或：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js" data-ga="UA-XXXXX-Y"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>

ga: 'UA-XXXXX-Y'=data-ga="UA-XXXXX-Y"

外链脚本插件

如果你需要在.md文件中引用如：

<script src="https://domain.com/xxx.js" ></script>

安装：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script>

照这样看来是可以在.md中写.html的……

图片缩放插件

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>

效果就是点击一下图片可以放大
如：
logo
如果不想缩放可以设置：

![](image.png ":no-zoom")

复制代码插件

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code"></script>

效果可以自己看上面的所有代码

Disqus评论插件

<script>window.$docsify = {disqus: 'shortname'}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/disqus.min.js"></script>

详见：https://disqus.com/

Gitalk评论插件

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/gitalk/dist/gitalk.css"><script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/gitalk.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/gitalk/dist/gitalk.min.js"></script>
<script>var gitalk = new Gitalk({clientID: 'Github Application Client ID',clientSecret: 'Github Application Client Secret',repo: 'Github repo',owner: 'Github repo owner',admin: ['Github repo collaborators, only these guys can initialize github issues'],// facebook-like distraction free modedistractionFreeMode: false})
</script>

可以使文章实现评论效果，教程详见：https://github.com/gitalk/gitalk/

链接下一篇文章插件

可以再文章底部显示“下一篇”和“上一篇”
效果见https://xhemj.gitee.io/books/#/p/How-to-Use-Docsify.md

<script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>

也可以自定义：

window.$docsify = {
pagination: {previousText: '上一篇',nextText: '下一篇',crossChapter: true,crossChapterText: true,},}

更多插件可以见https://docsify.js.org/#/awesome?id=plugins

以下是我自己使用的插件

Social Share分享插件

经过测试，无法直接在index.html中嵌入代码
需要先安装上面的外链脚本插件

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/external-script.min.js"></script>

后在.md文件中写下：

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/social-share.js/1.0.16/css/share.min.css">
<div class="social-share"></div>
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/social-share.js/1.0.16/js/social-share.min.js"></script>

即可在文件中嵌入分享插件
详细自定义教程可见：https://github.com/overtrue/share.js

嵌入Markdown文件插件

<script src="https://unpkg.com/docsify-remote-markdown/dist/docsify-remote-markdown.min.js">

可以自定义：

window.$docsify = {
remoteMarkdown: {tag: 'md',},}

使用方法：

[你设置的tag，如：md](https://domain.com/markdown.md)

效果如上方的分享插件就可以直接链接：
而不用写分享代码

<script src="https://unpkg.com/docsify-footer-enh/dist/docsify-footer-enh.min.js"></script>

自定义：

window.$docsify = {
footer: {copy: '',auth: '',pre: '<hr>',style:'text-align: center;'},}

实测copy和auth可以随便写
写什么文字代码都可以
pre是正文和Footer的分割线，默认<hr>
效果可以见https://xhemj.gitee.io/books/#/p/How-to-Use-Docsify.md

结尾

基本上配置就是这样了！本文当基于官方文档书写
要是有什么说不到位的欢迎私信我或者发邮件到xhemj2680@163.com哦！
好看就分享一下吧！

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.luyixian.cn/news_show_899187.aspx

如若内容造成侵权/违法违规/事实不符，请联系dt猫网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

IronPython 个人网站样例宝藏挖掘

IronPython 个人网站样例宝藏挖掘

IronPython for ASP.NET 的 CTP 已经发布两个多星期了&#xff0c;惭愧的是&#xff0c;因为工作繁忙&#xff0c;一直没有太多时间来学习。居然忽略了 Personal Web Site Starter Kit 的 IronPython 样例。幸亏了 Scott Guthrie 这篇博客: http://blog.joycode.com/scottgu/ar…
阅读更多...
php网站压测(ab)

php网站压测(ab)

一般来说核心页面都需要进行压测&#xff0c;特别是秒杀页面&#xff0c;从而知道网站的承受能力&#xff0c;方便暴露一些问题&#xff0c;更好的把控网站。压测工具有很多种&#xff0c;最简单、方便的可以使用ApacheBench&#xff0c;也就是我们熟悉的ab工具&#xff0c;不过…
阅读更多...
在构建社交网站中，MySQL 和 MongoDB优缺点大比拼

在构建社交网站中，MySQL 和 MongoDB优缺点大比拼

在项目的规划和发展过程中&#xff0c;最关键的一步是要选择合适的数据库。如果选择错误的话&#xff0c;将会花费你大量时间和金钱&#xff0c;并且在这过程中还会惹毛很多的客户。当在他们预期方式中使用时&#xff0c;MongoDB和MySQL都是非常优秀的数据库&#xff0c;但究竟…
阅读更多...
大型网站架构演化历程

大型网站架构演化历程

大型网站的挑战主要来自庞大的用户&#xff0c;高并发的访问和海量数据&#xff0c;任何简单的业务一旦需要处理数以P计的数据和面对数以亿计的用户&#xff0c;问题就会变得棘手。大型网站架构主要就是解决这类问题。 本文内容大部分来自《大型网站技术架构》,这本书很值得一看…
阅读更多...
强烈推荐几个比较好的Java代码查询网站

强烈推荐几个比较好的Java代码查询网站

这些是我经常使用的一些Java代码查询网站&#xff0c;希望在这里能起到抛砖引玉的效果&#xff0c;大家群策群力&#xff0c;一起分享Java快乐。 1. java2s http://www.java2s.com/ 这个网站非常好&#xff0c;分成三大类&#xff0c;分别是 Example、 Products、 Articles&a…
阅读更多...
今天在做网站中..........

今天在做网站中..........

程序员协会的网站已经拖了半年了&#xff0c;呵呵&#xff0c;一直想做 在听蓝色生死恋&#xff0c;嗯嗯&#xff0c;过去只是在街上听过&#xff0c;昨天晚上到Baidu找了半天&#xff0c;上传上来&#xff0c;大家共享一下&#xff01; 心情不咋样&#xff0c;早上抓了几个学…
阅读更多...
如何用初级的JavaWeb知识写一个较简单的网站(一)

如何用初级的JavaWeb知识写一个较简单的网站(一)

本人JavaWeb初学者&#xff0c;这是学校一门课程的期末作业&#xff0c;之前已经写了不少了&#xff0c;但是由于一点误操作&#xff0c;导致项目有点崩盘&#xff0c;加上心态不是很好&#xff0c;所以把整个项目全部删除重做&#xff0c;这里记录一下我写整个项目的全过程。 …
阅读更多...
如何用初级的JavaWeb知识写一个较简单的网站(二)

如何用初级的JavaWeb知识写一个较简单的网站(二)

好了&#xff0c;废话不多说&#xff0c;我们接着上次的项目继续开发 我们现在先暂时开发用户登录注册界面&#xff0c;上次我们已经完成了项目的初期准备&#xff0c;完成了建表、User实体类和UserDao的书写&#xff0c;下面我们开始套页 这里的前台页面是由一名前端程序员写…
阅读更多...
影响网站打开速度的9大因素

影响网站打开速度的9大因素

再好的网站&#xff0c;如果打开速度慢&#xff0c;10个人会有9个人选择离开&#xff0c;我归纳了大约9大影响网站打开速度的因素&#xff0c;但网站页面显示的速度取决于众多的因素&#xff0c;包括服务器性能、网络传输质量、网站的带宽、DNS解析、网页内容包括涉及到的JS代码…
阅读更多...
提高网站打开速度的7大秘籍

提高网站打开速度的7大秘籍

很多站长使用虚拟主机来做网站&#xff0c;网页内容一旦很多&#xff0c;网站打开速度就会特别慢&#xff0c;如果说服务器、带宽、CDN这类硬指标我们没有经济实力去做&#xff0c;不妨通过网页代码优化的方式来提高速度&#xff0c;卢松松总结了一些可行性的方法。 1: 缩小Jav…
阅读更多...
12个在线网站测速工具——web性能

12个在线网站测速工具——web性能

网站的访问速度对于一个网站非常重要&#xff0c;没有一个人会喜欢速度慢的网站。下面是12款在线测试网站的访问速度和性能的工具&#xff0c;在优化网站的时候很有用。 Pingdom 测试网站每个元素的加载速度&#xff0c;比如html、图片、JS文件等等。 GTmetrix GTmetrix集合…
阅读更多...
谷歌搜索将衡量网站速度

谷歌搜索将衡量网站速度

据国外媒体报道&#xff0c;Google搜索结果排名将考量网页加载速度因素&#xff0c;网页加载速度慢的网站的Google搜索结果排名很可能会下滑。 Google的两位首席搜索工程师阿米特‧辛格哈尔&#xff08;Amit Singhal&#xff09;和马特•卡茨&#xff08;Matt Cutts&#xff09…
阅读更多...
怎样让网站的文章(内页)快速收录和发外链的方法

怎样让网站的文章(内页)快速收录和发外链的方法

做网站的站长们都知道&#xff0c;网站的文章的收录数量往往决定着网站的权重和网站的排名&#xff0c;所以一些站长对于网站的索引量看的极其重要。而最让人头疼的是&#xff0c;有时候当你费尽心思的写出一篇高质量的原创文章发表到网站以后&#xff0c;却迟迟不被收录&#…
阅读更多...
构建一个网站流程

构建一个网站流程

阅读更多...
实验室网站图片

实验室网站图片

阅读更多...
windows server服务器上部署java+tomcat网站域名配置

windows server服务器上部署java+tomcat网站域名配置

windows server服务器上部署javatomcat网站域名配置 如果只是部署java项目的话&#xff0c;可以把IIS删除&#xff0c;然后在服务器上安装jdk tomcat 配置好环境变量&#xff0c;就和你在自己计算机上开发一样&#xff0c;把你的项目war包拷到tomcat下的webapps里&#xff08;…
阅读更多...
python使用selenium爬取网站流程 适用于抓取使用了js等异步加载技术的网站

python使用selenium爬取网站流程 适用于抓取使用了js等异步加载技术的网站

Python使用urllib.open再配合BeautifulSoup解析是最快的网页抓取方式&#xff0c;但部分网站做了反爬&#xff0c;用这种抓取方法会出错&#xff0c;就是浏览器里看网页内容是有的&#xff0c;但Python里抓出来的是空架子无数据。这种时候可以F12观察网站是否有直接的数据接口返…
阅读更多...
应用程序和网站中创建几乎任何类型的工业条码控件BarcodeX.NET

应用程序和网站中创建几乎任何类型的工业条码控件BarcodeX.NET

BarcodeX.NET条形码控件是一种.NET WinForms组件和ASP.NET服务器控件&#xff0c;它可以在您的应用程序和网站中创建几乎任何类型的工业条形码。 具体功能&#xff1a; 100% C#托管代码适用于.NET框架2.0&#xff0c;3.0和3.5支持的条码包括&#xff1a;DataMatrix, PDF-417, …
阅读更多...
轻量级设计，让网站灵敏轻便的6个技巧

轻量级设计，让网站灵敏轻便的6个技巧

在网站或软件的策划和设计过程中&#xff0c;我们经常听到这样的讨论&#xff1a;“这个功能设计得太重了”又或“我们希望能够处理得轻一些”。似乎轻设计是时下炙手可热的话题&#xff0c;也是方兴未艾的Web2.0大浪下设计师们的最爱&#xff08;看看那些在全世界遍地开花的SN…
阅读更多...
做网站用UTF-8还是GB2312？

做网站用UTF-8还是GB2312？

经常我们打开外国网站的时候出现乱码&#xff0c;又或者打开很多非英语的外国网站的时候&#xff0c;显示的都是口口口口口的字符&#xff0c; WordPress程序是用的UTF-8&#xff0c;很多cms用的是GB2312。 ● 为什么有这么多编码&#xff1f; ● UTF-8和GB2312有什么区别&…
阅读更多...
推荐文章
最新文章

Copyright @ 2022~2023

友情链接： 我的编程经验分享 一条长河网 尧图网站开发 尧图建网站 广利置业