使用Docsify搭建Markdown文件服务器

清晨-阳光zx

已于 2022-04-10 10:13:55 修改

阅读量1.8k

点赞数 1

分类专栏： TypeScript Node.js 文章标签： node.js docsify Markdown

于 2022-01-10 12:55:31 首次发布

本文链接：https://blog.youkuaiyun.com/pro_fan/article/details/122407631

版权

TypeScript 同时被 2 个专栏收录

6 篇文章

订阅专栏

Node.js

4 篇文章

订阅专栏

使用Docsify快速生成文档网站

1. 概述
2. 安装 docsify-cli 工具
3. 初始化项目
4. 本地预览
5. 多页文档
6. 定制导航栏
7. 封面设置
配置项

1. 概述

docsify网站：https://docsify.js.org/#/zh-cn/

docsify 可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是它不会生成静态的 .html 文件，所有转换工作都是在运行时。如果你想要开始使用它，只需要创建一个 index.html 就可以开始编写文档并直接部署在 GitHub Pages。

2. 安装 docsify-cli 工具

推荐使用如下命令全局安装 docsify-cli 工具，可以方便地创建及在本地预览生成的文档。

npm i docsify-cli -g

安装完成后使用docsify -v命令检查一下版本号

F:\PersonalProject>docsify -v

docsify-cli version:
  4.4.3

下面进行文档项目的创建与开发。

3. 初始化项目

使用 docsify init 命令初始化项目。命令语法如下：

docsify init <path> [--local false] [--theme vue] [--plugins false]

简写形式如下：

docsify i <path> [-l false] [-t vue] [--plugins false]

命令配置项含义请查阅 docsify-cli 文档。

如果想在项目的 ./docs 目录里写文档，可以使用如下命令：

docsify init ./docs

初始化后./docs目录文件结构如下：
./docs目录结构
文件结构介绍：

index.html 入口文件，在该文件中可以设置docsify配置项，配置项信息请查阅 docsify 配置项。
README.md 会做为主页内容渲染。
.nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件。

直接编辑 docs/README.md 就能更新文档内容，当然也可以添加更多页面。

4. 本地预览

终端运行 docsify serve命令启动一个本地服务器，可以方便地实时预览效果。默认访问地址 http://localhost:3000。

docsify serve docs

如果需要执行端口，可在命令上增加-p选项：

docsify serve docs -p 4000

!](https://img-blog.csdnimg.cn/0010e7961ce34fd79fe8c2d6fd0b596a.png?x-oss-process=image/watermark,type_d3F5LXplbmhlaQ,shadow_50,text_Q1NETiBA5riF5pmoLemYs-WFiXp4,size_20,color_FFFFFF,t_70,g_se,x_16)

更多命令行工具用法，参考 docsify-cli 文档。

5. 多页文档

docsify支持设置多页文档，多页文档之间的跳转设置和Markdown文档与文档之间的跳转方式一致。

格式： [显示的文本内容](跳转地址)

6. 定制导航栏

docsify默认是没有导航栏的，可以通过修改index.html和添加导航栏配置两种方式来显示导航栏。

注意： 文档的链接都要以 #/ 开头。

6.1 在index.html中添加导航栏

如果导航项较少的话，可以使用这种方式。

<!-- index.html -->

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

6.2 添加导航栏配置文件

在index.html中配置loadNavbar属性值，如果其值为true，则默认加载的文件为 _navbar.md；也可以将其值指定为具体的配置文件名。

<!-- index.html -->

<script>
  window.$docsify = {
  	loadNavbar: true,  // 默认加载配置文件 _navbar.md
  	loadNavbar: 'nav.md', 	// 自定义加载的配置文件 nav.md
  }
</script>

<!-- _navbar.md -->

* [En](/)
* [中文](/zh-cn/)

在这里插入图片描述

6.3 下拉导航栏

当导航项过多时，或者希望将导航栏显示为下拉列表的形式可以在导航配置文件中使用如下写法。

<!-- _navbar.md -->

* 入门

  * [快速开始](zh-cn/quickstart.md)
  * [多页文档](zh-cn/more-pages.md)
  * [定制导航栏](zh-cn/custom-navbar.md)
  * [封面](zh-cn/cover.md)

在这里插入图片描述

具体配置规则见 配置项#loadNavbar

7. 封面设置

7.1 设置封面参数

通过设置 coverpage 参数，可以开启渲染封面的功能。

封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 _coverpage.md 文件。

<!-- index.html -->

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

注意：

目前封面的背景是随机生成的渐变色，想修改封面背景继续往下看。
通常封面和首页是同时出现的，如果希望只在访问主页时加载封面可以通过设置onlyCover 选项来实现。

7.2 自定义封面背景

可以在文档末尾用添加图片的 Markdown 语法设置自定义背景（背景色/背景图）。

<!-- _coverpage.md -->

# docsify <small>3.5</small>

[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#quick-start)

<!-- 背景图片 -->

![](_media/bg.png)

<!-- 背景色 -->

![color](#f0f0f0)

7.3 将封面设置为首页

只在访问主页时加载封面。解决封面和首页同时出现的问题。

window.$docsify = {
  onlyCover: false,
};

配置项

可以在window.$docsify中设置配置项信息。

el

类型：string
默认值：#app

docsify 初始化的挂载元素，可以是一个 CSS 选择器，默认为 #app 如果不存在就直接绑定在 body 上。

window.$docsify = {
  el: '#app',
};

repo

类型：String
默认值: null

配置仓库地址或者 username/repo 的字符串，会在页面右上角渲染一个 GitHub Corner 挂件。

window.$docsify = {
  repo: 'docsifyjs/docsify',
  // or
  repo: 'https://github.com/docsifyjs/docsify/',
};

maxLevel

类型：Number
默认值: 6

默认情况下会抓取文档中所有标题渲染成目录，可配置最大支持渲染的标题层级。

window.$docsify = {
  maxLevel: 4,
};

loadNavbar

类型：Boolean|String
默认值: false

加载自定义导航栏，参考定制导航栏了解用法。设置为 true 后会加载 _navbar.md 文件，也可以自定义加载的文件名。

window.$docsify = {
  // 加载 _navbar.md
  loadNavbar: true,

  // 加载 nav.md
  loadNavbar: 'nav.md',
};

homepage

类型：String
默认值: README.md

设置首页文件加载路径。适合不想将 README.md 作为入口文件渲染，或者是文档存放在其他位置的情况使用。

window.$docsify = {
  // 入口文件改为 /home.md
  homepage: 'home.md',

  // 文档和仓库根目录下的 README.md 内容一致
  homepage:
    'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
};