Docsify个人网站搭建详细教程

最新推荐文章于 2024-09-04 22:41:19 发布
最新推荐文章于 2024-09-04 22:41:19 发布
阅读量1w 收藏 54
点赞数 25
分类专栏： 博客搭建&图床配置 文章标签： npm 前端 node.js docsify
BaretH
本文链接：https://blog.csdn.net/qq_45173404/article/details/122683872
版权

目录

一、什么是 docsify

docsify是一个有魔法的文档网站生成器，它能够动态生成您的文档网站。与GitBook、Hexo不同，它不生成静态html文件，而是智能地加载和解析您的md文件，并将其显示为网站。要开始使用它，只需创建一个index.html并将其部署在GitHub Page/Gitee Page等第三方站点上即可。

官网：docsify

特点：

  • 无需构建静态的html文件
  • 轻量
  • 拥有智能的全文搜索插件
  • 支持多主题
  • 支持丰富的API插件
  • 支持表情符号
  • 兼容 IE11
  • 支持服务端的渲染

以前曾经折腾过一段时间 hexo 个人静态博客，总体来说还是比较满意的，hexo 也支持md渲染、一键部署、包括很多三方的插件和丰富的拓展性，唯一的不足可能就是相比 docify 配置比较麻烦，两者最大的区别就是当本地文件变更的时，hexo 需要首先通过hexo -c清空目前生成的静态网页文件，然后再通过hexo -g根据本地变更后的新文件构建出一个 public目录存放网站的静态文件，然后如果需要查看效果的话，还需通过hexo -s启动本地的hexo服务，而 Docsify 并不需要构建静态html文件，并且本地文件变更时网站会进行热部署，自动的变更到本地3000端口实时展示，极大的减轻了我们对于网站的管理，能让我们更加专注的进行文档编写或者知识的分享。


二、安装 docsify

安装 docsify 之前，我们需要安装npm包管理器，而安装了node.js就会自动安装npm，对于node.js，直接去Node.js官网选择合适的版本进行下载，然后一键安装即可。

zhongsiru@zhongsirudeAir ~ % npm -v
8.3.2

接着我们来全局安装 docsify-cli，这是一个 docsify 的命令行工具，可以帮助我们在本地进行 docsify 的初始化和网站的预览。

npm i docsify-cli -g

然后我们创建一个文件夹，用来存储 docsify 所有的文件，接着输入以下命令进行初始化

mkdir docsify
docsify init ./docsify

image-20220123195652774

可以看到初始化成功了，我们就可以在刚创建的 Docsify 文件夹中查看到README.md和index.html两个文件，此外还存在一个隐藏文件.nojekyll

zhongsiru@zhongsirudeAir Documents % cd Docsify 
zhongsiru@zhongsirudeAir Docsify % tree
.
├── README.md		# 会做为主页内容渲染
└── index.html	# 入口文件
└── .nojekyll		# 用于阻止 GitHub Pages 忽略掉下划线开头的文件

根据上述提示命令，我们便可启动 docsify 的网站，默认在本地的3000端口

image-20220123201250036

我们访问该网址，便可以看到内容

image-20220123201348559

这里渲染的内容就是上述 Docsify 文件夹中的 README.md，我们如果更改该文件中的内容，网站的内容会自动同步更新。


三、多页文档设置

我们可以轻松的在docsify 实现多级路由的网站，比如在前面创建的 Docsify 文件夹中创建guide.md、zh-cn/READEME.md、zh-cn/guide.md，结构如下所示：

.
├── README.md
├── guide.md
├── index.html
└── zh-cn
    ├── README.md
    └── guide.md

此时我们访问如下url即可以访问到对应的页面：

README.md					=> http://localhost:3000/#/
guide.md					=> http://localhost:3000/#/guide
/zh-cn/README.md  => http://localhost:3000/#/zh-cn/
/zh-cn/guide.md   => http://localhost:3000/#/zh-cn/guide

四、定制化配置

4.1、侧边栏

默认情况下，我们的侧边栏是根据 Markdown 文件自动生成，我们也可以定制化进行设定，首先修改Docsdify/index.html开启侧边栏的选项添加loadSiderbar: true，这样设置后就会加载 Docsify 目录下的 _sidebar.md 文件进行加载而渲染成我们定制的侧边栏。

<script>
  window.$docsify = {
    name: '',
    repo: '',
    // 开启侧边栏定制,加载_sidebar.md
    loadSidebar: true,
  }
</script>

image-20220124102726357

然后我们在 Docsify 目录下创建一个 _sidebar.md 文件，里面可以对侧边栏进行配置，比如这里配置如下：

<!-- Docsify/_sidebar.md -->

* [首页](/) 
* [guide](/guide)
* [zh-cn](zh-cn/)
* [zh-cn guide](zh-cn/guide)

也就是 MarkDown 中的超链接语法，后面的路径也就对应着上述多页文档的路由路径

image-20220124103718738

这样设置以后，渲染出的侧边栏如下图所示，我们点击对应地方即可跳转到对应的多页文档

image-20220124103849853

image-20220124103930790

此外我们还可以指定页面的标题，比如这里指定首页的标题为home

<!-- Docsify/_sidebar.md -->

* [首页](/ "home") 
* [guide](/guide)
* [zh-cn](zh-cn/)
* [zh-cn guide](zh-cn/guide)

image-20220124110839892

📄 补充：嵌套的侧边栏

上述我们是在 Docsify 根目录下新建了一个 _sidebar.md表示网站根路径也就是默认3000端口路径下的侧边栏样式，但是 Docsify 是支持多页文档的，比如上述第3点中我们在根目录下创建了 zh-cn 目录，在这个目录下又有两个文件，我们也可以针对 zh-ch 这个目录对应的路径，定制化该目录下的侧边栏。

例如我们在 Docsify/zh-cn目录下创建一个 _sidebar.md，配置如下：

<!-- Docsify/zh-cn/_sidebar.md -->

* [zh-ch首页](/zh-cn) 
* [zh-cn guide](zh-cn/guide)

测试我们首先进入3000端口的首页

image-20220124104910592

然后点击 zh-cn 后，可以看到该目录下的侧边栏，也就是上述配置的 Docsify/zh-cn/_sidebar.md

image-20220124104937684

注意：_sidebar.md 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 /zh-cn 则从 /zh-cn/_sidebar.md 获取文件，如果不存在则从 /_sidebar.md 获取，我们也可以在 index.html 中如下配置表示默认都走根路径下的 _sidebar.md 文件

<script>
  window.$docsify = {
    loadSidebar: true,
    alias: {
      '/.*/_sidebar.md': '/_sidebar.md'
    }
  }
</script>

📄 开启侧边栏目录

自定义侧边栏后默认不会再生成目录，我们可以通过设置生成目录的最大层级开启这个功能：

<!-- index.html -->

<script>
  window.$docsify = {
    loadSidebar: true,
    // 开启目录,最大层级为2
    subMaxLevel: 2
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

当设置了 subMaxLevel 时，默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题，可以给它添加 <!-- {docsify-ignore} --> 。

# Getting Started

## Header <!-- {docsify-ignore} -->

该标题不会出现在侧边栏的目录中。

要忽略特定页面上的所有标题，你可以在页面的第一个标题上使用 <!-- {docsify-ignore-all} --> 。

# Getting Started <!-- {docsify-ignore-all} -->

## Header

该标题不会出现在侧边栏的目录中。

在使用时， <!-- {docsify-ignore} --> 和 <!-- {docsify-ignore-all} --> 都不会在页面上呈现。

4.2、导航栏

添加导航栏有两种方式，一是直接到 index.html 中添加，二是和侧边栏类似，通过 md 文件的形式来添加：

1️⃣ html中添加nav标签

<!-- index.html -->

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

image-20220124112843635

2️⃣ 通过md文件来添加

首先在 index.html 中配置 loadNavbar，默认加载的文件为 _navbar.md

  <script>
    window.$docsify = {
      name: '',
      repo: '',
      loadSidebar: true,
      subMaxLevel: 3,
      // 开启导航栏,加载_navbar.md
      loadNavbar: true
    }
  </script>

然后在 Docsify 目录下创建 _navbar.md，这样设置与上述通过html的效果一致

<!-- _navbar.md -->

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

image-20220124113251307

此外，如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式：

<!-- _navbar.md -->

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


* 配置
  * [配置项](zh-cn/configuration.md)
  * [主题](zh-cn/themes.md)
  * [使用插件](zh-cn/plugins.md)
  * [Markdown 配置](zh-cn/markdown.md)
  * [代码高亮](zh-cn/language-highlight.md)

image-20220124113412160

注意：_navbar.md 加载逻辑和 sidebar 文件一致，从每层目录下获取。例如当前路由为 /zh-cn 那么是从 /zh-cn/_navbar.md 获取导航栏。

📄 整合自定义导航栏与 emoji 插件

如果你使用 emoji 插件:

<!-- index.html -->

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

例如，你可以在自定义导航栏 Markdown 文件中使用旗帜表情：

<!-- _navbar.md -->

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


* 配置
  * [配置项](zh-cn/configuration.md)
  * [主题](zh-cn/themes.md)
  * [使用插件](zh-cn/plugins.md)
  * [Markdown 配置](zh-cn/markdown.md)
  * [代码高亮](

image-20220124113707960

4.3、封面

同侧边栏和导航栏一样，我们手下在 index.html 中设置 coverpage 参数开启封面功能

<script>
  window.$docsify = {
    name: '',
    repo: '',
    loadSidebar: true,
    subMaxLevel: 3,
    loadNavbar: true,
    // 开启封面,加载_coverpage.md
    coverpage: true,
  }
</script>

然后在文档根目录创建 _coverpage.md 文件，用于配置封面内容

# docsify <small>3.5</small>

> 一个神奇的文档网站生成器。

- 简单、轻便 (压缩后 ~21kB)
- 无需生成 html 文件
- 众多主题

[GitHub](https://github.com/docsifyjs/docsify/)

image-20220124121435384

📄 自定义背景

目前的背景是随机生成的渐变色，我们自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。

<!-- 网站图标 -->
![logo](_media/icon.jpg)

# docsify <small>3.5</small>

> 一个神奇的文档网站生成器。

- 简单、轻便 (压缩后 ~21kB)
- 无需生成 html 文件
- 众多主题

[GitHub](https://github.com/docsifyjs/docsify/)

<!-- 背景图片 -->
![](_media/玩家.png)

<!-- 背景色 -->
![color](#f0f0f0)

在这里插入图片描述

📄 多封面

如果你的文档网站是多语言的，或许你需要设置多个封面，例如你的文档目录结构如下

.
└── docs
    ├── README.md
    ├── guide.md
    ├── _coverpage.md
    └── zh-cn
        ├── README.md
        └── guide.md
        └── _coverpage.md

那么可以这样配置

window.$docsify = {
  coverpage: ['/', '/zh-cn/']
};

4.4、主题

目前支持的主题如下所示，我们只需要在 index.html 中引入想要的主题即可

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dolphin.css">

五、部署

以上就是 docsify 的一个基本的配置，更多的配置可以查看docsify官方文档根据自己的情况作出定制化修改，接下来我们将这个网站部署上线使得所有人都可以进行访问，以下分别介绍了部署到 Gitee Page 和部署到云服务两种方式。

5.1、部署到Gitee

我们在gitee上新建一个仓库Docsify

image-20220124162553129

然后 git clone 到本地，然后在其中创建一个docs目录，然后把本地的 Docsify 目录拷贝到该目录中

# 1.克隆仓库
git clone https://gitee.com/bareth/docsify.git

# 2.进入仓库
cd docsify 

# 3.创建docs目录并进入
mkdir docs&cd docs 

# 4.将本地docsify文件拷贝到docs目录
mv ~/Documents/Docsify .

然后我们重新将本地变更推送到 gitee 远程仓库中

git add .
git commit -m "add docsify files"
git push

image-20220124163917265

然后我们填写要部署的目录

image-20220125133556225

最后就生成了一个网站地址，我们点击直接可以访问了

在这里插入图片描述

5.2、部署到云服务器

这里我们采用 Nginx 反向代理服务器来部署，首先在云服务器上安装好 Nginx：Nginx最新版安装教程（Windows+Linux）

Nginx 安装完成后，我们访问服务器的公网ip即可进入nginx页面

image-20220124160627116

接下来我们在 Nginx 安装目录也就是 /usr/local/nginx 下新建一个文件夹专门用来存放 Docsify 的文件

image-20220124160805862

接下来我们将本地存放docsify文件的 Docsify 文件夹上传到服务器的 Docsify 文件夹即可

scp -r Docsify root@139.198.40.248:/usr/local/nginx/Docsify

此时 docsify 相关文件已经上传到 nginx 的 Docsify 目录中，接下来我们将该路径配置到 nginx 配置文件中即可

vim /usr/local/nginx/conf/nginx.conf

将 location/root 地址更改为存放 docsify 文件的 Docsify 目录的地址即可，更改完保存退出

image-20220124161345342

然后我们重启 nginx 服务器

/usr/local/nginx/sbin/nginx -s reload

完成后我们再次访问服务器的公网ip即可看到 docsify 的网站

在这里插入图片描述

Baret-H
关注
专栏目录
docsify搭建个人极简知识仓库
2401_84048034的博客
05-04 1058
自我介绍一下，小编13年上海交大毕业，曾经在小公司待过，也去过华为、OPPO等大厂，18年进入阿里一直到现在。深知大多数Java工程师，想要提升技能，往往是自己摸索成长，自己不成体系的自学效果低效漫长且无助。因此收集整理了一份《2024年Java开发全套学习资料》，初衷也很简单，就是希望能够帮助到想自学提升又不知道该从何学起的朋友，同时减轻大家的负担。
docsify安装手册
05-02
markdown渲染引擎安装手册
Docsify搭建
Bkhole的博客
05-07 807
Docsify搭建 官网：https://docsify.js.org/#/zh-cn/ 前提 要配置好 nodeJs 、npm 安装 Docsify 插件 自己创建一个要下载到本地的文件夹，然后在这里直接利用命令下载 推荐全局安装 docsify-cli 工具，可以方便地创建及在本地预览生成的文档。 npm i docsify-cli -g ​ 下载完成之后，进入 ./node_modules/.bin 使用终端查看安装是否成功 docsify -v 出现版本号，表明安装成功，自己再将该路径
docsify快速部署搭建个人知识库（支持本地、服务器、虚拟机运行）
最新发布
2401_86402635的博客
09-04 998
登录阿里云后，打开阿里云的容器镜像服务页面 https://cr.console.aliyun.com ，然后找到如下页面，可以查看到你的。国内镜像中心常用的为阿里云与网易云，选择其中一个加速器进行配置即可。在本地 Docker 中指定要使用的国内加速器地址后，就可以直接从国内镜像中心下载镜像了。注意，该 json 数据中的 URL 地址是与用户登录账号绑定的，不同的用户所生成的地址是不同的。点击这个 开启阅读 链接后，会跳转到 README.md 内容路径，想要再次回到上图的主意，在。
docsify 教程
dreamwhigh的博客
07-13 1万+
docsify 教程 参考 docsify 前期准备 安装 git git 国内镜像下载地址 安装 npm 参照 npm 安装教程，安装 node ，建议选择 Long Term Support (LTS) 长期支持版本。 全局安装 docsify-cli 工具，可以方便创建及本地预览文档网站。 npm i docsify-cli -g 安装 notepad++ 文本编辑器推荐安装 notepa...
Docsify使用指南（打造最快捷、最轻量级的个人&团队文档）
专注于C#/.NET/.NET Core学习、工作、面试干货和实战教程分享。这里聚焦了大量的C#/.NET/.NET Core优质文章、开源项目、实用工具和学习、工作、面试心得。
05-05 1299
网上关于动态文档生成工具有很多如：Docsify、 VuePress、Docute 、Hexo这些都是一些非常优秀的文档生成工具，本章主要介绍如何快速使用Docsify搭建一个快捷、轻量级的个人&团队文档。一个神奇的文档网站生成器。docsify 可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是它不会生成静态的 .html 文件，所有转换工作都是在运行时。如果你想要开始使用它，只需要创建一个 index.html 就可以开始编写文档。
手把手教你从0开始搭建个人博客，东半球最详细的保姆级博客搭建部署教程 | 程序员人手必备个人博客网站
华科硕士，大厂打工中。编程问题咨询，请私我
12-07 1959
Hello 小伙伴们大家好，我是雷小帅！ 想象一下你有一个技术博客，然后把网址写在了简历上，面试官点击鼠标打开了这个网站，然后被惊艳了，最后面试的结果你懂得…… 好了，今天的主题就是手把手教大家从零开始搭建一个个人博客，整个搭建过程我保证一分钱都不用花，全部白嫖！ 赶紧开始吧，有点迫不及待了。 目录 环境准备 安装 node.js 安装 docsify-cli 初始化工程目录 本地预览博客网站 定制化 多页文档 添加封面 更换主题 自定义插件 搜索框 字数统计 效果展示
Docsify快速搭建个人博客
weixin_44829437的博客
05-26 1420
平常写一些文档或者个人笔记时，Markdown 是我的第一个选择，因为它用起来真的很方便、简洁。那么今天要讲的 Docsify 是什么呢？ Docsify简介 Docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件，所有转换工作都是在运行时进行。 这将非常实用，如果只是需要快速的搭建一个小型的文档网站，或者不想因为生...
Node.js开发-docsify
08-09
没有静态构建的html文件 简单轻巧（~19kB gzipped） 智能全文搜索插件 多个主题 有用的插件API 兼容IE10 支持SSR（示例） 支持嵌入文件
Docsify保姆级教程
ybb_ymm的专栏
12-29 1056
动态生成文档网站的一款热门工具！网上很多关于动态生成文档的工具！今天我们的主角是Docsify！
Docsify快速上手与进阶指南
笔记中的日常，分享编程建站
04-30 1100
Docsify 是一个基于JavaScript的文档网站生成器，可以速轻松地搭建基于文本文档的静态网站。它没有预设的主题，所有的网站样式都由Markdown文件生成，可以自由定制。docsify的优点是简单易用，不需要复杂的配置，文档可以直接写在Markdown文件中，支持插件扩展和多语言支持。基础配置：在index.html文件的标签内，通过设置对象来定制Docsify的行为。例如，你可以设置网站标题、是否启用侧边栏、指定加载的CSS或JS文件等。
docsify教程|个人博客搭建
weixin_45517132的博客
02-11 649
docsify教程|个人博客搭建 准备： nodejs git docsify 1.1nodejs官网下载nodejs 的Windows installer(.msi) 64-bit版本 nodejs 官网 1.2默认安装Nodejs即可 1.3在控制台输入nodejs查验是否安装成功 2.1准备markdown文件（这步可不按教程准备） 徽章查询：https://badgen.net 自定义徽章：https://img.shields.io 2.2更换镜像源 输入：npm config s
Docsify 快速入门与配置指南
gitblog_01190的博客
08-08 448
Docsify 快速入门与配置指南 docsify???? A magical documentation site generator.项目地址:https://gitcode.com/gh_mirrors/do/docsify 1. 项目目录结构及介绍 典型的 docsify 项目目录可能如下： ├── 404.html # 自定义404页面 ├── assets # ...
使用Docsify做文档网站详细教程解决方案
gradfly的博客
01-29 1273
docsify安装使用及无法启动问题解决办法
工具--docsify详解
热门推荐
李宥的博客
04-29 2万+
docsify详解 一、docsify入门 1、简介 docsify 可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是它不会生成静态的 .html 文件，所有转换工作都是在运行时。如果你想要开始使用它，只需要创建一个 index.html 就可以开始编写文档并直接部署。 官网地址：https://docsify.js.org/#/zh-cn/ 2、特性 无需构建，写完文档直接发布 容易使用并且轻量 (压缩后 ~21kB) 智能的全文搜索 提供多套主题 丰富的 API 支持 Emoji
VuePress搭建个人技术文档网站教程
weixin_34026484的博客
11-19 1199
VuePress 由两部分组成：一部分是支持用 Vue 开发主题的极简静态网站生成器，另一个部分是为书写技术文档而优化的默认主题。它的诞生初衷是为了支持 Vue 及其子项目的文档需求。 每一个由 VuePress 生成的页面都带有预渲染好的 HTML，也因此具有非常好的加载性能和搜索引擎优化（SEO）。同时，一旦页面被加载，Vue 将接管...
mac终端搭建docsify
03-24
非常好的问题！搭建 Docsify 的过程需要几个简单的步骤，步骤如下： 1. 首先，确定你的 Mac 上是否安装了 Node.js，如果没有，请先安装 Node.js。 2. 打开终端，运行以下命令安装 Docsify CLI： ``` npm i docsify-cli -g ``` 3. 选择一个目录作为 Docsify 的根目录，运行以下命令： ``` docsify init ./docs ``` 该命令会在当前目录下创建一个 docs 目录，并生成一个 `index.html` 文件和一个 `README.md` 文件。 4. 进入到 docs 目录，启动 Docsify 服务器，并在浏览器中查看网站： ``` cd docs docsify serve ``` 该命令会启动 Docsify 服务器，并在浏览器中打开 http://localhost:3000 查看网站。 完成上述步骤后，你就成功地搭建了 Docsify 站点！
评论 18
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

Baret-H

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值