基于Vuepress搭建文档式博客

效果预览 moyokoo

Vuepress官网

快速搭建

安装工具

yarn , npm

请确保你的 Node.js 版本 >= 8。

新建项目

在自己喜欢的目录下建立一个文件夹,然后进入该文件夹下,接下来使用如下命令

一定要使用 yarn add vuepress@next 而不是官网的命令,官网的命令是老版本

# 将 VuePress 作为一个本地依赖安装
yarn add vuepress@next

# 新建一个 docs 文件夹
mkdir docs

# 新建一个 markdown 文件
echo '# Hello VuePress!' > docs/README.md

# 开始写作
npx vuepress dev docs
复制代码

刚才新建的 README.md 是作为首页,你可以进行修改,也可以进行自定义

接着，在 package.json 里加一些脚本

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}
复制代码

然后执行下面的命令

yarn docs:dev
复制代码

就会出现一个和Vuepress一样的网站了

替换主题

最新版的默认主题有一个bug没有解决,因此有必要将主题掌握自己手中

首先在docs下的 .vuepress 目录下新建 theme文件夹

然后找到该目录 /node_modules/@vuepress/theme-default

把 theme-default 中的所有文件复制到刚才的 theme中,注意不是把 theme-default文件夹复制过去

现在,你可以自己修改主题了

加入第三方UI框架

我添加的框架是 vuetify

进入项目根目录,使用命令 yarn add vuetify

然后在 .vuepress文件夹下的 enhanceApp.js 进行配置,如果没有 enhanceApp.js 文件则新建这个文件

import Vuetify from 'vuetify'
import '../../node_modules/vuetify/dist/vuetify.min.css'
export default ({
  Vue, // the version of Vue being used in the VuePress app
  options, // the options for the root Vue instance
  router, // the router instance for the app
  siteData // site metadata
}) => {
  Vue.use(Vuetify);
}
复制代码

现在,你可以使用这个框架了,比如我的首页是这样的

    

      
Hello

      
专注自己的创作
      
        fas fa-paper-plane
      
    

复制代码

使用 fontawesome 图标

如果你想使用图标,可以使用 fontawesome ,需要进行配置

在 .vuepress文件夹下的 config.js 中配置head

  head: [
    ['link', { rel: 'stylesheet', href: `https://fonts.cat.net/css?family=Roboto:100,300,400,500,700,900|Material+Icons` }],
    ['link', { rel: 'stylesheet', href: `https://use.fontawesome.com/releases/v5.1.0/css/all.css` }],
  ],
复制代码

侧边栏配置

我的侧边栏是将所有的博客放在一块,当然你也可以分开,侧边栏的数据是放在 config.js 中的

themeConfig: {
    sidebarDepth: 2,
    lastUpdated: 'Last Updated',
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Github', link: 'https://github.com/moyokoo' },
    ],
    sidebar: {
      '/blog/': getBlogSidebar('你的侧边栏item的名称', '你的侧边栏item的名称', '你的侧边栏item的名称'),
    }
  },

function getBlogSidebar(groupA, groupB, groupC) {
  return [
    {
      title: groupA,
      collapsable: true,
      children: [
        '',
        '你的md文件名.md',
      ]
    },
    {
      title: groupB,
      collapsable: true,
      children: [
        '你的md文件名.md',
        '你的md文件名.md',
      ]
    },
  ]
}
复制代码

主题自定义

之前我们已经把主题的所有文件都放到 theme 文件夹下,因此,如果你想要修改你的页面,可以直接修改该文件夹下的文件,使用的都是 vue 语法

插件自定义

有些插件你想做修改,可以这样做,这里以back-to-top为例

首先去 node_modules/@vuepress 下的 back-to-top 插件整个复制到 .vuepress/theme 下

然后在 config.js 中修改

  plugins: [
    [require('../.vuepress/theme/plugin-back-to-top')],
    ['@vuepress/medium-zoom', {
      selector: '.content .p img'
    }],
  ],
复制代码

这样,你就可以直接修改插件了

可以参考我修改的 back-to-top

.go-to-top {
  cursor: pointer;
  position: fixed;
  bottom: 1rem;
  right: 1rem;
  z-index: 999;
}
复制代码