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

作者:xhemj

没错,它叫Docsify。



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: =>

使用Docsify做文档网站的详细配置教程的更多相关文章

  1. 使用 Hexo 创建项目文档网站

    当我们发布一个开源项目的时候,最重要的事情之一就是要创建项目文档.对使用项目的用户来说,文档是非常有必要的,通常我们可以使用下面这些方式来创建文档: GitHub Wiki:在 Github 上我们可 ...

  2. 无需编译、快速生成 Vue 风格的文档网站

    无需编译.快速生成 Vue 风格的文档网站 https://docsify.js.org/#/#coverpage https://github.com/QingWei-Li/docsify/

  3. 本号讯 | 永不消失的协作“空间站”开课;微软推出微软云Azure文档网站

    8月29日,针对企业常面临的“协同办公”困难,开展以“还有这种操作?永不消失的协作'空间站'”为主题的协同办公培训课. 课程内容包含:在Office 365环境中,如何利用Teams与Groups等功 ...

  4. GIT+云盘作 做 文档管理工具

    GIT+云盘作 做 文档管理工具 在工作中, 会遇到公司的文档 和 自己家里的 文档进行同步的问题, 通常我们使用U盘作为传输节制, 但是不是非常好,文档的改动都不能发现, 导致回家同步的时候, 出各 ...

  5. 为什么不使用github的wiki而是使用mkdocs做文档管理?

    为什么不使用github的wiki而是使用mkdocs做文档管理? 目前 KSFramework 是使用mkdocs来做在线文档 而非使用github的wiki,这是为什么呢? 在windows下搭建 ...

  6. VUE3.0发布,自己搞个文档网站

    9月19日,尤大神发表了VUE3.0版本的演说,强大且震撼,这两天一直在找网站文档,可能还未被百度收录,未找到文档网站.后来在github上面找到了中文代码. 地址为:https://github.c ...

  7. 如何使用 VuePress 搭建一个 element-ui 风格的文档网站

    如何使用 VuePress 搭建一个 element-ui 风格的文档网站 { "devDependencies": { "vuepress": "1 ...

  8. 百度在线编辑器UEditor(v1.3.6) .net环境下详细配置教程之更改图片和附件上传路径

    本文是接上一篇博客,如果有疑问请先阅读上一篇:百度在线编辑器UEditor(v1.3.6) .net环境下详细配置教程 默认UEditor上传图片的路径是,编辑器包目录里面的net目录下 下面就演示如 ...

  9. 使用ghpage(github服务)搭建文档网站几种方式

    可以通过github提供的ghpage服务来搭建网站,有以下三种方式来实现: 1.文档放在master分支,作为一个子目录. 仓库:https://github.com/Ourpalm/ILRunti ...

随机推荐

  1. sphinx + mysql 全文索引配置

    参考地址 http://v9.help.phpcms.cn/html/2010/search_0919/35.html http://blog.sina.com.cn/s/blog_705e4fdc0 ...

  2. MHRD_Guide

    @(Steam蒸汽动力)[MHRD|Game|How To] [CH]游戏解决方案 1.解决方案将作为完整的代码呈现,部分结决方案将有理论分析或图解. 2.根据记录板判断,解决方案远非理想. 3.慎重 ...

  3. Java登录界面的实现(注册、登录、背景图片)

    */ * Copyright (c) 2016,烟台大学计算机与控制工程学院 * All rights reserved. * 文件名:text.java * 作者:常轩 * 微信公众号:Worldh ...

  4. 零基础JavaScript编码(一)

    任务目的 JavaScript初体验 初步明白JavaScript的简单基本语法,如变量.函数 初步了解JavaScript的事件是什么 初步了解JavaScript中的DOM是什么 任务描述 参考以 ...

  5. [LeetCode] 面试题 10.01.合并排序的数组

    题目: 这道题有多种实现的思路,这里使用双指针结合数组有序的特点进行解决 思路: m代表A初始时有效元素的个数,n代表B中元素的个数,那么n+m才是A的总长度 从A的最后一个位置开始,设为cur,分别 ...

  6. spring boot整合memcache

    1.导入memcached客户端jar包 <dependency> <groupId>com.whalin</groupId> <artifactId> ...

  7. 由世界坐标系转换到摄像机坐标系的lookAt()函数

    在学习图形学和opengl的时候,都涉及到坐标转化,从物体坐标转换为世界的坐标,从世界的坐标转换为摄像机的坐标. 在世界坐标到摄像机转换的过程中常用lookAt函数得到转化矩阵.GLM官方文档对它的解 ...

  8. C++ for循环练习

    #include <stdio.h> //题目:现有公鸡5元一只,母鸡3元一只,小鸡1元3只(小鸡不能单买 最少3只起卖),此时顾客有100元,请问有多少种购买方案. int main() ...

  9. (转)协议森林07 傀儡 (UDP协议)

    协议森林07 傀儡 (UDP协议) 作者:Vamei 出处:http://www.cnblogs.com/vamei 欢迎转载,也请保留这段声明.谢谢! 我们已经讲解了物理层.连接层和网络层.最开始的 ...

  10. 微信小程序修改request合法域名不生效及解决方法

    在小程序微信公众平台修改后请求,依然在console中显示修改前的域名. 解决:在小程序开发者工具中点击“详情”后点击“域名信息”,就会自动刷新