前言

在开始之前，请先确保你已经满足以下两个前提条件：

  • 自己的电脑上安装了 Node.js ；
  • 拥有自己的 Github/Gitee 账号；

快速安装并开始

安装

首先使用如下命令在自己的电脑上安装 docsify-cli 工具，方便后续的创建和预览自己的文档网站；

  1. npm i docsify-cli -g

快速搭建属于自己的文档型博客 - 图1

项目初始化

在自己的电脑上创建一个项目文件夹，比如我的是 Docsify，然后进入该文件夹并打开命令行工具，通过如下命令来初始化项目；

  1. docsify init ./

快速搭建属于自己的文档型博客 - 图2

项目目录结构

经过初始化后，可以发现项目文件夹的目录结构如下，主要有三个文件，其功能如下：

  1. .
  2.     .nojekyll
  3.     index.html
  4.     README.md
  • index.html : 入口文件，也叫配置文件，相关配置均在其中；
  • README.md : 作为主页内容渲染；
  • .nojekyll : 防止 Github Pages 忽略下划线开头的文件；

本地预览

当我们编辑好文档后，想要在本地预览时，可通过如下命令运行本地服务器，然后在浏览器中访问 http://localhost:3000 进行实时预览（其中 3000 端口是 docsify 默认访问端口）；

  1. docsify serve ./

快速搭建属于自己的文档型博客 - 图3

快速搭建属于自己的文档型博客 - 图4

项目配置

配置文件 index.html

该文件中主要配置了文档网站的名字以及开启一些配置选项，比如我修改后的配置如下：

  1. <!DOCTYPE html>
  2. <html lang="en">
  4. <head>
  5.   <meta charset="UTF-8">
  6.   <title>村雨遥</title>
  7.   <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
  8.   <meta name="description" content="Description">
  9.   <meta name="viewport"
  10.     content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
  11.   <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/dark.css">
  12. </head>
  14. <body>
  15.   <div id="app"></div>
  16.   <!-- docsify-edit-on-github -->
  17.   <script src="//unpkg.com/docsify-edit-on-github/index.js"></script>
  18.   <script>
  19.     window.$docsify = {
  20.       name: '村雨遥',
  21.       repo: 'https://gitub.com/cunyu1943/cunyu1943',
  22.       maxLevel: 5,//最大支持渲染的标题层级
  23.       subMaxLevel: 3,
  24.       homepage: 'README.md',
  25.       coverpage: true, // 封面
  26.       loadSidebar: true, // 侧边栏
  27.       autoHeader: true,
  28.       notFoundPage: true, // 找不到页面时
  29.       auto2top: true,//切换页面后是否自动跳转到页面顶部
  30.       //全文搜索
  31.       search: {
  32.         //maxAge: 86400000, // 过期时间，单位毫秒，默认一天
  33.         paths: 'auto',
  34.         placeholder: '搜索',
  35.         noData: '未找到结果',
  36.         // 搜索标题的最大程级, 1 - 6
  37.         depth: 3,
  38.       },
  39.       plugins: [
  40.         EditOnGithubPlugin.create('https://githee.com/cunyu1943/cunyu1943/')
  41.       ],
  42.     }
  43.   </script>
  44.   <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
  45.   <!--Java代码高亮-->
  46.   <script src="//unpkg.com/prismjs/components/prism-java.js"></script>
  47.   <script src="//unpkg.com/prismjs/components/prism-python.js"></script>
  48.   <!--全文搜索-->
  49.   <script src="https://cdn.bootcss.com/docsify/4.5.9/plugins/search.min.js"></script>
  50.   <!-- 复制到剪贴板 -->
  51.   <script src="//unpkg.com/docsify-copy-code"></script>
  52.   <!-- emoji -->
  53.   <script src="//unpkg.com/docsify/lib/plugins/emoji.js"></script>
  54.   <!-- 图片缩放 -->
  55.   <script src="//unpkg.com/docsify/lib/plugins/zoom-image.js"></script>
  56.   <!-- 字数统计 -->
  57.   <script src="//unpkg.com/docsify-count/dist/countable.js"></script>
  58. </body>
  60. </html>

侧边栏

上述配置中侧边栏已经打开，在配置文件中加入如下代码:

  1. loadSidebar: true

然后在目录下新建一个 _sidebar.md 文件，在其中加入你所要显示的内容；

快速搭建属于自己的文档型博客 - 图5

封面

上述配置中封面已经打开，即 coverpage: true，此时新建一个 _coverpage.md 文件，在其中加入你所要显示的内容，比如我的封面；

快速搭建属于自己的文档型博客 - 图6

主页内容

即 README.md 的内容，比如我的最终结果显示如下；

快速搭建属于自己的文档型博客 - 图7

Loading 提示

初始化时会显示 Loading...，但是我们可以自定义要提示的信息，只需要在配置文件index.html中，修改如下配置即可；

  1. <div id="app">🏃💨💨💨 Loading...</div>

部署

进行上述操作之后，如果想要让别人都能访问到我们的网站，可以将其部署到 GitHub Pages，然后供别人访问了是不是很激动，部署详情如下：

新建仓库

即和平常创建的步骤一样，但是要注意打开 Github Pages 功能；

快速搭建属于自己的文档型博客 - 图8

提交项目

将本地的项目提交到远程；

快速搭建属于自己的文档型博客 - 图9

预览

在浏览器中访问创建仓库时的给的网址即可在线预览我们的网站了，比如我的是：`https://cunyu1943.github.io/，默认会显示封面页；

快速搭建属于自己的文档型博客 - 图10

总结

经过上述的配置之后，我们就成功利用 docsify 成功搭建自己的文档类型网站了，赶紧去试试吧！😎😎😎