使用docsify快速生成文档网站

1. 概述
2. 安装 docsify-cli 工具
3. 初始化项目
4. 本地预览
5. 多页文档
6. 定制导航栏
- 6.1 在index.html中添加导航栏
- 6.2 添加导航栏配置文件
- 6.3 下拉导航栏
7. 封面设置
- 7.1 设置封面参数
- 7.2 自定义封面背景
- 7.3 将封面设置为首页
配置项
- el
- repo
- maxLevel
- loadNavbar
- homepage

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 -vdocsify-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目录文件结构如下：

文件结构介绍：

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

更多命令行工具用法，参考 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.mdloadNavbar: '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',// orrepo: 'https://github.com/docsifyjs/docsify/',
};

maxLevel

类型：Number
默认值: 6

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

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

loadNavbar

类型：Boolean|String
默认值: false

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

window.$docsify = {// 加载 _navbar.mdloadNavbar: true,// 加载 nav.mdloadNavbar: 'nav.md',
};

homepage

类型：String
默认值: README.md

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

window.$docsify = {// 入口文件改为 /home.mdhomepage: 'home.md',// 文档和仓库根目录下的 README.md 内容一致homepage:'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
};

更多配置项请自行查阅官方文档。

—— END ——

使用Docsify搭建Markdown文件服务器相关推荐

本地 MarkDown 怎么部署到服务器上？教你使用 Docsify 搭建个人博客
使用Docsify搭建文档类型网站 docsify 可以快速帮你生成文档网站.不同于 GitBook.Hexo 的地方是,它不会生成静态的 .html 文件,所有转换工作都是在运行时.如果你想要开始使 ...
docsify安装,docsify搭建,docsify使用教程
docsify安装,docsify搭建,docsify使用教程首先安装docsify-cli脚手架,用于初始化docsify文档项目 npm i docsify-cli -g 然后初始化 docsi ...
docsify搭建个人博客
预览 fearless's blog fearless's puzzle game fearless's github 使用工具一个神奇的文档网站生成器 docsify 安装doocsify npm ...
atom搭建markdown环境
1. 搭建markdown环境 > 禁用atom自带的markdown-preview插件(功能简单) > 安装插件:markdown-preview-plus@2.4.16(在markd ...
nginx搭建文件服务器脚本,基于docker搭建nginx文件服务器的方法步骤
1.在本机新建配置文件docker_nginx.conf server { listen 7070; server_name localhost; charset utf-8; location /f ...
Windows搭建SFTP文件服务器
Windows搭建SFTP文件服务器自己搭建一个SFTP文件服务器,来实现不同IP服务器之间文件的传输: 应用的场景:由于需要缓解服务器的压力,需要对服务进分离,分别放置在不同IP服务器上: 首先提 ...
vps文件服务器,vps搭建媒体文件服务器
vps搭建媒体文件服务器内容精选换一换在高可用部署场景下需要创建SFS Turbo提供文件共享功能.请参考表1在公有云平台创建SFS Turbo. 域名认证时,需要将下载的认证文件上传到网站根目 ...
Ubuntu 搭建FTP文件服务器
最近公司项目中需要搭建FTP文件服务器,主要是用来解决大文件上传问题. 注:以下命令都是在已经关闭防火墙的前提下进行的 1.安装vsftpd $ sudo apt install vsftpd 2.开 ...
nodejs搭建静态文件服务器
用NodeJS搭建静态文件服务器引言之前用lamp和wamp搭建过网站,集成的软件套装对于建站十分方便.apache的autoindex功能我非常喜欢,有时候想要分享一些文件给同学,但是又懒得用U ...

使用Docsify搭建Markdown文件服务器