VuePress 搭建站点

本文最后更新于：2024年5月7日下午

VuePress 是静态站点生成框架之一，界面简介优雅，本文记录使用方法。

简介

VuePress 是尤雨溪（vue.js 框架作者）发布的一个全新的基于 vue 的静态网站生成器，实际上就是一个 vue 的 spa 应用，内置 webpack，可以用来写文档。
VuePress 有很多优点：
- 界面简洁优雅，不同于 Hexo，个人觉得更适合作为说明文档页
- 容易上手（半小时能搭好整个项目）
- 更好的兼容、扩展 Markdown 语法
- 响应式布局，PC端、手机端
- Google Analytics 集成
- 支持 PWA
中文官网：https://vuepress.docschina.org/

安装

nodejs

VuePress 需要安装 Node.js，且版本要求 >= 8。

vuepress

在 nodejs 平台下安装 vuepress

1
2
3

npm install -g vuepress
# 或
yarn global add vuepress

使用方法

创建框架

以 Cellink 项目的说明文档为例，创建 cellink-docs 文件夹

1	`mkdir cellink-docs`

初始化项目

1	`npm init -y`

在 VueDemo 文件夹中创建 docs 文件夹，在其中加入 README.md 文件，写入 hello world!
在 docs 中创建 .vuepress 文件夹，在.vuepress中创建 public 文件夹和 config.js 文件，最终项目结构如下所示：

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

添加 vue-template-compiler 模块

1	`npm install vue-template-compiler`

配置站点信息

在 config.js 文件中配置网站标题、描述、主题等信息

module.exports = {
  locales: {
    // 键名是该语言所属的子路径
    // 作为特例，默认语言可以使用 '/' 作为其路径。
    '/': {
      lang: 'zh-CN', // 将会被设置为 <html> 的 lang 属性
      title: 'Cellink 用户手册',
      description: '一款可视化代码流程管理框架',
    },
  },
  title: 'Cellink',
  base: '/cellink-docs/',
  head: [
    ['link', { rel: 'icon', href: '/imgs/icon.png' }],
    ['meta', { name: 'keywords', content: 'cellink,可视化,流程管理,cellink文档,用户文档'}]
  ],
  themeConfig: {
    locales: {
      '/': {
        // 多语言下拉菜单的标题
        selectText: 'Languages',
        // 该语言在下拉菜单中的标签
        label: '🇨🇳 简体中文',
        // 编辑链接文字
        editLinkText: '帮助我们完善文档',
        // 最后更新的描述
        lastUpdated: '文档更新于',
        // Service Worker 的配置
        serviceWorker: {
          updatePopup: {
            message: '发现新内容可用.',
            buttonText: '刷新',
          },
        },
        nav: [
          { text: '开始使用', link: '/start/' },
          { text: '配置指南', link: '/guide/' },
          { text: '进阶用法', link: '/advance/' },
		  { text: 'Cellink 实践', link: '/practice/' },
          { text: 'GitHub', link: 'https://github.com/viibridges/cellink' },
        ],
      },
    },
    sidebar: 'auto',
    // 假如你的文档仓库和项目本身不在一个仓库：
    docsRepo: 'zywvvd/cellink-docs',
    // 假如文档不是放在仓库的根目录下：
    docsDir: 'docs',
    // 假如文档放在一个特定的分支下：
    docsBranch: 'source',
    // 默认是 false, 设置为 true 来启用
    editLinks: true,
  }
};

此时站点框架完成，已经可以进行初步测试，执行命令：

1	`npm run dev`

正常情况下 VuePress 会建立本地 Web 服务器，监听 http://localhost:8080/
访问 http://localhost:8080/

填充内容

按照导航配置的 link 我们分别创建文件夹和对应的 markdown 文件

│  package.json
│  README.md
│
└─docs
    │  README.md
    ├─.vuepress
    │  │  config.js
    │  └─public
    ├─advance
    │      README.md
    ├─guide
    │      README.md
    ├─practice
    │      README.md
    └─start
           README.md

如果需要图像资源，需要放在 public 文件夹下：

│  package.json
│  README.md
│
└─docs
    │  README.md
    ├─.vuepress
    │  │  config.js
    │  ├─public
    │  │  │  .nojekyll
    │  │  │
    │  │  └─imgs
    │  │          adc-graph.png
    │  │          bearing-graph.png
    │  │          demo-graph.png
    │  │          icon.png
    │  │          node-types.png
    │  │          nozzle-graph.png
    │  │          quantum-graph.png
    │  └───────── slogan.png
    ├─advance
    │      README.md
    ├─guide
    │      README.md
    ├─practice
    │      README.md
    └─start
           README.md