【工具】10分钟快速搭建属于自己的文档网站

GopalFeng

发布于 2022-08-01 19:41:17

1.6K0

发布于 2022-08-01 19:41:17

文章被收录于专栏：前端杂货铺-Gopal

前言

很多同学都希望能够拥有自己的一个文档系统，去记录/总结自己所学到的知识。

本文就来介绍一下 Docsify[1] + Github Page 的方式，旨在快速搭建属于自己的文档网站

本文的 Demo 代码可以通过 https://github.com/GpingFeng/docsify-demo 查看，演示看 https://gpingfeng.github.io/docsify-demo/#/

准备工作

全局安装 docsify-cli 工具，并创建文档项目目录

npm i docsify-cli -g
mkdir my-docs
cd my-docs

初始化项目

docsify init ./docs

成功后会生成一个 docs 的文件夹，并且里面有三个文件

index.html 入口文件。后面我们的配置很多都是在这里配置
README.md 会做为主页内容渲染
.nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件

启动项目

docsify serve docs

通过运行 docsify serve 启动一个本地服务器，可以方便地实时预览效果。默认访问地址 http://localhost:3000[2] 。下面的内容时间上是 README.md 中的内容

简单的配置

接下来就是配置我们的文档了

配置侧边栏

在 index.html 中，新增配置 loadSidebar: true

window.$docsify = {
  name: '',
  repo: '',
+  loadSidebar: true
}

在 docs 中新建一个文件 _sidebar.md，写入

- JavaScript
  - [闭包](closure.md "闭包")
  - [原型](prototype.md "原型")

- CSS
  - [布局](layout.md "布局")

同时在 docs 中新建 closure.md 、prototype.md和 layout.md三个 Markdown 文件

可以在 closure.md 中写入如下，查看效果

# 介绍闭包
## 什么是闭包
哈哈哈哈

## 闭包的作用是什么

自动生成目录

可以根据标题生成目录，这个在文章很长的时候很有用，直接演示配置和效果

window.$docsify = {
  name: '',
  repo: '',
  loadSidebar: true,
+ subMaxLevel: 2
}

插件的使用

基础的配置已经完成了，当然还有其他更多的功能配置，这里不再细说。Docsify 还提供了丰富的插件，接下来我们看看

全文搜索

配置非常简单

<script>
  window.$docsify = {
    name: '',
    repo: '',
    loadSidebar: true,
    subMaxLevel: 2,
+   search: 'auto'
  }
</script>
<!-- Docsify v4 -->
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

查看效果

图片缩放

Docsify 是需要插件才能实现图片缩放的，但其实也很简单，如下

    <script>
      window.$docsify = {
        name: '',
        repo: '',
        loadSidebar: true,
        subMaxLevel: 2,
        search: 'auto'
      }
    </script>
    <!-- Docsify v4 -->
    <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
+   <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>