使用 Vuepress 写笔记

vuepress 是一个简单的静态网站生成器，适合写作文档。

文档： https://vuepress.vuejs.org/

需要有 Node.js 环境

本文使用的 Vuepress 是 v1.x 版本， v2.x 现在还是 beta，主题使用默认主题。

开始上手

新建一个文件夹并初始化

yarn init 
# npm init

官网推荐安装为本地依赖

yarn add -D vuepress 
# npm install -D vuepress

不过我觉得全局安装挺好的

yarn global add vuepress
npm install -g vuepress

也可以使用 GitHub actions 部署： https://github.com/marketplace/actions/vuepress-1-x-compiler

在 project.js 文件中增加下面内容

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

创建一篇文档

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

即可在 http://localhost:8080 启动一个本地服务器预览

yarn docs:dev 
# npm run docs:dev

目录结构

.
├── docs
│   ├── .vuepress (可选的)
│   │   ├── dist (编译后的文件 可选的)
│   │   ├── config.js (可选的)
│   │   └── (其它配置文件)
│   │ 
│   ├── README.md
│   ├── guide
│   │   └── README.md
│   └── config.md
│ 
└── package.json

• docs/.vuepress: 用于存放全局的配置、组件、静态资源等。
• docs/.vuepress/config.js: 配置文件的入口文件，也可以是 YML 或 toml。
• docs/.vuepress/dist/: 编译后文件的默认位置

默认 docs 目录作为 targetDir （参考 命令行接口），下面所有的“文件的相对路径”都是相对于 docs 目录的

对于上述的目录结构，默认页面路由地址如下：

文件的相对路径	页面路由地址
/README.md	/
/guide/README.md	/guide/
/config.md	/config.html

有个小地方需要注意：使用 yanr docs:dev 预览的时候，超链接 /config 可以访问到 /config.html 文件，但编译后的文件不行，需要使用 /config.html

默认主题首页配置

使用默认主题时，通过根目录的 README.md 的 YAML front matter 来自定义首页

---
home: true
heroImage: /hero.png
heroText: Hero 标题
tagline: Hero 副标题
actionText: 快速上手 →
actionLink: /zh/guide/
features:
- title: 简洁至上
  details: 以 Markdown 为中心的项目结构，以最少的配置帮助你专注于写作。
- title: Vue驱动
  details: 享受 Vue + webpack 的开发体验，在 Markdown 中使用 Vue 组件，同时可以使用 Vue 来开发自定义主题。
- title: 高性能
  details: VuePress 为每个页面预渲染生成静态的 HTML，同时在页面被加载的时候，将作为 SPA 运行。
footer: MIT Licensed | Copyright © 2018-present Evan You
---

导航栏

默认主题的顶部导航栏配置如下

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'External', link: 'https://google.com' , target='_blank' },
    ]
  }
}

外部链接 <a> 标签的特性将默认包含target="_blank" rel="noopener noreferrer"，你可以提供 target 与 rel，它们将被作为特性被增加到 <a> 标签上：

导航栏下拉框设置如下

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Languages',
        ariaLabel: 'Language Menu',
        items: [
          { text: 'Chinese', link: '/language/chinese/' },
          { text: 'Japanese', link: '/language/japanese/' }
        ]
      }
    ]
  }
}

侧边栏

设置 themeConfig.sidebar 来定义侧边栏

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/page-a',
      ['/page-b', 'Explicit link text']
    ]
  }
}

每一个元素是一个侧边栏的链接，如果是数组，数组第一个元素是侧边栏的链接，第二个是自定义名称

当然，写复杂文档时不同路径下不同侧边栏是很重要的，

如果路径如下

.
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│  ├─ README.md
│  ├─ one.md
│  └─ two.md
└─ bar/
   ├─ README.md
   ├─ three.md
   └─ four.md

可以这样定义不同路径下的侧边栏

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: {
      '/foo/': [
        '',     /* /foo/ */
        'one',  /* /foo/one.html */
        'two'   /* /foo/two.html */
      ],

      '/bar/': [
        '',      /* /bar/ */
        'three', /* /bar/three.html */
        'four'   /* /bar/four.html */
      ],

      // fallback
      '/': [
        '',        /* / */
        'contact', /* /contact.html */
        'about'    /* /about.html */
      ]
    }
  }
}

如果内容过多，也可以把上面的内容放到一个单独的文件中，然后引用该文件

module.exports={
  themeConfig: {
    sidebar: require("./sidebar.js")
  }
}

流量统计

通过插件实现

安装：

yarn add -D @vuepress/plugin-google-analytics
# npm install -D @vuepress/plugin-google-analytics

配置：

module.exports = {
  plugins: [
    [
      '@vuepress/google-analytics',
      {
        'ga': '' // UA-00000000-0
      }
    ]
  ]
}

输出路径配置

配置方法：

dest: '../public'

默认为 docs/.vuepress/dist/