一、docsify

准备工作

全局安装 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 (opens new window) 。下面的内容实际上是 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 还提供了 Gitalk (opens new window) 评论插件等。更多请看官方文档 (opens new window)。

二、VuePress

准备工作

注意 VuePress基于node 8.0+

官方推荐使用yarn代替npm，使用npm后续会出错。

安装yarn

npm install -g yarn

查看版本

yarn --version

初始化项目

创建一个新目录

mkdir vuepress-docs

进入目录

cd vuepress-docs

初始化

yarn init

启动项目

本地安装VuePress

VuePress 可以不用全局安装。

yarn add -D vuepress

创建你的第一篇文档

mkdir docs && echo '# Hello VuePress' > docs/README.md

**在package.json**中添加一些scripts

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

在本地启动服务器

yarn docs:dev

通过yarn docs:dev启动一个本地服务器，方便预览效果。默认访问地址是 http://localhost:8080 (opens new window)。

简单配置

在docs下新建一个.vuepress目录，所有VuePress相关的文件都会放在这里。最后目录结构可能如下：

.
├─ docs
│  ├─ README.md
│  └─ .vuepress
│     └─ config.js
└─ package.json

在.vuepress/config.js中添加配置：

module.exports = {
    title: '我的文档', // 设置网站标题
    description: 'a document', // 描述
    base: '/v1/web-frontend/learn/', // 基础路径
    // 默认主题配置
    themeConfig: {
        logo: './public/001.png',
        smoothScroll: true, // 启用滚动
        // 导航栏配置
        nav: [{
                text: '首页',
                link: '/'
            },
            {
                text: '前端相关知识',
                link: '/study/html'
            },
            {
                text: '个人文章',
                items: [{
                        text: '掘金',
                        link: 'https://juejin.cn/user/3113457361639054'
                    },
                ]
            }
        ],
        // 侧边栏配置
        sidebar: {
            '/': [
                "/study/html", // 根目录创建 .md文件
                "/study/css",
                "/study/js",
            ]
        },
        // 侧边栏标题层级
        sidebarDepth: 2
    }
}

部署到github pages或者gitee pages

新建仓库

不需要添加README文件。注意！仓库名要与.vuepress/config.js中的相同。

打包文件

在项目中运行下面代码

npm run build

将打包后的文件上传到仓库中

cd到dist文件夹中

git init
git add .
git commit -m 'init'
git branch -M main
git remote add origin 仓库地址
git push -u origin main

配置github pages

找到项目中的settings

向下拉，找到pages，选择主分支和根文件夹，因为我们上传的代码index.html在根文件夹。

最后访问https://ctrlwin.github.io/仓库名/，就可以看到我们的网站了。

插件

vuepress官方提供了丰富的插件，如果需要添加插件可以参考官方文档 (opens new window)。

与docsify的区别

VuePress 的话，具有以下的特点

• 灵活性更高，自己自定义组件，直接在 Markdown 中使用组件
• 性能 vuepress > docsify。docsify 是运行时解析，vuepress 是预先渲染 HTML
• 更好的 SEO
• 但是配置上，docsify 更加简单一些