VuePress 快速踩坑小结

VuePress 快速踩坑小结

VuePress 是一个基于 Vue.js 的静态网站生成器，它和传统的静态网站生成器不同的是，采用了 Vue.js 的单文件组件来编写页面。

在使用 VuePress 的过程中，可能会遇到一些坑点，下面就一些常见的坑点进行总结，希望能对初次使用 VuePress 的同学有所帮助。

一、安装操作

在安装 VuePress 之前，需要先确认本地环境是否安装了 Node.js 和 npm，如果没有安装，需要先手动安装 Node.js 和 npm。

接着，可以通过在终端输入以下命令来安装 VuePress：

npm install -g vuepress

如果您用的是 Yarn，可以使用如下命令：

yarn global add vuepress

二、创建新项目

使用 VuePress 可以快速的生成一个静态网站，可以通过以下命令来创建一个新的 VuePress 项目：

mkdir my-project
cd my-project
yarn init -y
yarn add -D vuepress # 或者：npm install -D vuepress

三、配置文件

在项目的根目录下需要配置 config.js 文件，该文件可以对 VuePress 的静态资源输出路径、站点基础路径、markdown 配置等进行配置。

以下是一个示例：

// .vuepress/config.js

module.exports = {
  title: 'VuePress',
  description: 'VuePress 是一个基于 Vue.js 的静态网站生成器，以及一个以 Markdown 为中心的文档编写和发布工具。',
  port: 8080,
  dest: 'dist',
  locales: {
    '/': {
      lang: 'en-US',
      title: 'VuePress',
      description: 'Vue-powered Static Site Generator'
    },
    '/zh/': {
      lang: 'zh-CN',
      title: 'VuePress 中文文档',
      description: 'Vue 驱动的静态网站生成器'
    }
  },
  markdown: {
    lineNumbers: true,
    toc: {
      includeLevel: [1, 2]
    }
  },
  themeConfig: {
    sidebar: 'auto',
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
      { text: 'About', link: '/about.html' },
      {
        text: 'Languages',
        ariaLabel: 'Language Menu',
        items: [
          { text: 'Chinese', link: '/zh/' },
          { text: 'English', link: '/' }
        ]
      }
    ]
  }
}

需要注意的是，如果我们配置了多语言支持，VuePress 会根据浏览器的语言偏好来自动切换。

四、编写页面

在 VuePress 中，页面主要通过 Markdown 文件编写。每个页面都可以使用 YAML 头信息来设置一些页面的元数据。以下是一个页面的示例：

---
title: Example Page
---

# Example Page

This is an example page.

页面的文件名也需要遵循一定的规则，比如，首页必须命名为 README.md，其它页面的文件名必须以 .md 结尾。

五、快速示例

以下是两个快速示例：

1. 创建一个 VuePress 项目并运行

mkdir vuepress-demo
cd vuepress-demo
yarn init -y
yarn add -D vuepress
mkdir docs
echo '# Hello VuePress' > docs/README.md
echo '' > .vuepress/config.js
npx vuepress dev docs

执行完成后，打开浏览器访问 http://localhost:8080，可以看到生成的首页。

2. 集成 GitLab CI/CD

# .gitlab-ci.yml

image: node:16.7.0

before_script:
  - yarn install

build:
  script:
    - yarn run docs:build

deploy:
  stage: deploy
  script:
    - mv .vuepress/dist/ public/
    - echo "$PRIVATE_SSH_KEY" > id_rsa
    - chmod 600 id_rsa
    - rsync -e 'ssh -i id_rsa' -r --delete-after --quiet public/ [e-mail]:/var/www/vuepress-demo
  only:
    - main

将上述代码加入 .gitlab-ci.yml 文件中，这样每次代码提交到 GitLab 时，GitLab CI/CD 会自动执行构建和部署操作。

总结

以上就是 VuePress 快速踩坑小结的攻略，希望可以为初学者带来一些帮助。如果还有任何疑问或困惑，可以在评论区留言，我将尽快回复。