关于VuePress:手把手搭建VuePress文档

41次阅读

共计 8272 个字符，预计需要花费 21 分钟才能阅读完成。

你好，我悦创。

本来想用 gitbook 实现流沙团队文旦，奈何呈现一堆奇奇怪怪的 bug 后，我花了一天工夫写完文档，而后决定放弃它应用 VuePress。

1. 筹备条件（Prerequisites）

  1. Node.js v12+
  2. Yarn v1 classic (Optional)

1.1 Node.js 装置

大佬级别间接看上面这句话，就没啥问题：

这个装置很简略，只须要下载，而后一路 next 即可。下载链接：https://nodejs.org/en/

小白持续看看下来：

用于所有支流平台的官网软件包，可拜访 http://nodejs.cn/download/

装置 Node.js 的其中一种十分便捷的形式是通过软件包管理器。对于这种状况，每种操作系统都有其本身的软件包管理器。

在 macOS 上，Homebrew 是业界的规范，在装置之后能够十分轻松地装置 Node.js（通过在 CLI 中运行以下命令）：

brew install node

其余实用于 Linux 和 Windows 的软件包管理器列出在 https://nodejs.org/en/download/package-manager/。

nvm 是一种风行的运行 Node.js 的形式。例如，它能够轻松地切换 Node.js 版本，也能够装置新版本用以尝试并且当呈现问题时轻松地回滚。

这对于应用旧版本的 Node.js 来测试代码十分有用。

详见 https://github.com/creationix/nvm。

NVM 常用命令：https://www.aiyc.top/1946.html

倡议，如果刚入门并且还没有用过 Homebrew，则应用官网的安装程序，否则，Homebrew 是更好的解决方案。

无论如何，当装置 Node.js 之后，就能够在命令行中拜访 node 可执行程序。

1.2 装置 yarn（Optional）

npm install --global yarn
yarn --version

2. 疾速上手

本文会帮忙你从头搭建一个简略的 VuePress 文档。如果你想在一个现有我的项目中应用 VuePress 治理文档，从步骤 3 开始。

2.1 创立并进入一个新目录

我用的是 Windws 下应用 Linux 命令，Windows 间接界面创立文件夹，cmd 进入文件夹就能够了。

PS：买不起 MacBook，应用 Windows 10 配置 zsh 命令行做开发：https://www.aiyc.top/1976.html 有时候还不是很好用。

mkdir vuepress-starter && cd vuepress-starter

命令解析：

mkdir 我的项目文件夹名称 && cd 我的项目文件夹名称

我的操作：

# mkdir quicksand_vuepress && cd quicksand_vuepress
aiyc@aiyc:/mnt/d/gitee_all/quicksand_vuepress$

命令也能够离开：

mkdir vuepress-starter
cd vuepress-starter

2.2 应用你喜爱的包管理器进行初始化

git init
yarn init # npm init

我的操作：

clela@AIYC D:\gitee_all\quicksand_vuepress
# yarn init # npm init
yarn init v1.22.15
question name (quicksand_vuepress): quicksand_vuepress
question version (1.0.0): 1.0.0
question description: "流沙团队电子书 1.0"
question entry point (index.js): index.js
question repository url: https://github.com/QuicksandTeam/quicksandteam.github.io
question author (aiyc <1432803776@qq.com>):
question license (MIT):
question private:
success Saved package.json
Done in 132.92s.


2.3 将 VuePress 装置为本地依赖

咱们曾经不再举荐全局装置 VuePress

yarn add -D vuepress@next
# npm install -D vuepress@next
# yarn add -D vuepress
# npm install -D vuepress # next 意味着最新版。last 意味着旧版本

留神
如果你的现有我的项目依赖了 webpack 3.x，咱们举荐应用 Yarn (opens new window)而不是 npm 来装置 VuePress。因为在这种情景下，npm 会生成谬误的依赖树。

坑 1：最新版的 VuePress 须要大于 V12.13.0

clela@AIYC D:\gitee_all\quicksand_vuepress
# yarn add -D vuepress@next
yarn add v1.22.15
info No lockfile found.
[1/4] Resolving packages...
warning vuepress > @vuepress/bundler-webpack > webpack-dev-server > url > querystring@0.2.0: The querystring API is considered Legacy. new code should use the URLSearchParams API instead.
warning vuepress > @vuepress/bundler-webpack > webpack-dev-server > sockjs > uuid@3.4.0: Please upgrade  to version 7 or higher.  Older versions may use Math.random() in certain circumstances, which is known to be problematic.  See https://v8.dev/blog/math-random for details.
[2/4] Fetching packages...
error copy-webpack-plugin@9.0.1: The engine "node" is incompatible with this module. Expected version ">= 12.13.0". Got "10.12.0"
error Found incompatible module.
info Visit https://yarnpkg.com/en/docs/cli/add for documentation about this command

须要切换 nodejs 的版本，这里还是举荐应用 nvm：https://www.aiyc.top/1946.html

2.4 在 package.json 中增加一些 scripts

这一步骤是可选的，但咱们举荐你实现它。在下文中，咱们会默认这些 scripts 曾经被增加。

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

其实，这个文件，在我初始化的时候就创立了。不过我再补充一下下面的内容。

为了，避免你真的是零根底小白。我这里把外面的全部内容 copy 进去，间接批改也能够。

{
  "name": "quicksand_vuepress",
  "version": "1.0.0",
  "description": "流沙团队电子书",
  "main": "index.js",
  "repository": "https://github.com/QuicksandTeam/quicksandteam.github.io",
  "author": "aiyc <1432803776@qq.com>",
  "license": "MIT",
  "devDependencies": {"vuepress": "^2.0.0-beta.26"},
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

2.5 将默认的长期目录和缓存目录增加到 .gitignore 文件中

Linxu or Mac：

echo 'node_modules' >> .gitignore
echo '.temp' >> .gitignore
echo '.cache' >> .gitignore

Windows 间接创立文件 .gitignore 写入如下内容：

node_modules
.temp
.cache

2.6 创立你的第一篇文档

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

Windows 的话，间接创立就好啦。把创立的文档放在 docs 文件夹下（这个文件夹本人创立）。

2.7 在本地启动服务器

yarn docs:dev # npm run docs:dev

当咱们运行 yarn docs:dev 就相当于运行 vuepress dev docs

VuePress 会在 http://localhost:8080 在新窗口关上 启动一个热重载的开发服务器。当你批改你的 Markdown 文件时，浏览器中的内容也会自动更新。

当初，你应该曾经有了一个简略可用的 VuePress 文档网站。接下来，理解一下 VuePress 配置 相干的内容。

3. 配置

3.1 配置文件

如果没有任何配置，你的 VuePress 站点仅有一些最根底的性能。为了更好地自定义你的网站，让咱们首先在你的文档目录（docs）下创立一个 .vuepress 目录，所有 VuePress 相干的文件都将会被放在这里。你的我的项目构造可能是这样：

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

VuePress 站点必要的配置文件是 .vuepress/config.js，它应该导出一个 JavaScript 对象。如果你应用 TypeScript，你能够将其替换为 .vuepress/config.ts，以便让 VuePress 配置失去更好的类型提醒。

如果你是 JavaScript：

module.exports = {
  lang: 'zh-CN',
  title: '你好，流沙团队！',
  description: '这是团队的第一个 VuePress 站点',

  themeConfig: {logo: 'https://vuejs.org/images/logo.png',},
}

如果你是 TypeScript：

import {defineUserConfig} from 'vuepress'
import type {DefaultThemeOptions} from 'vuepress'

export default defineUserConfig<DefaultThemeOptions>({
  lang: 'en-US',
  title: 'Hello quicksandTeam',
  description: 'Just playing around',

  themeConfig: {logo: 'https://vuejs.org/images/logo.png',},
})

提醒
咱们接下来会把这个配置对象称为 VuePress 配置.

3.2 配置作用域

你可能曾经留神到了，在 VuePress 配置中有一项 themeConfig 配置项。

在 themeConfig 内部的配置项属于 站点配置 ，而在 themeConfig 外部的配置项则属于 主题配置。

3.2.1 站点配置

站点配置的意思是，无论你应用什么主题，这些配置项都能够失效。

咱们晓得，每一个站点都应该有它的 lang, title 和 description 等属性，因而 VuePress 内置反对了这些属性的配置。

提醒： 返回 配置参考 查看所有站点配置。

这里我做一些我本人的配置。

VuePress 配置的参考文档，能够通过配置文件来设置这些配置。VuePress 约定的配置文件为（依照优先程序）：

  • 当前工作目录 cwd 下：

    • vuepress.config.ts
    • vuepress.config.js

  • 源文件目录 sourceDir 下：

    • .vuepress/config.ts
    • .vuepress/config.js

你也能够通过 命令行接口 的 --config 选项来指定配置文件。

1. base

  • 类型：string
  • 默认值：/

详情：

如果你想让你的网站部署到一个子门路下，你将须要设置它。 它的值该当总是以斜杠开始，并以斜杠完结。

举例来说，如果你想将你的网站部署到 https://quicksandteam.github.io/aiyc/，那么 base 应该被设置成 "/aiyc/"。

base 将会作为前缀主动地插入到所有以 / 开始的其余选项的链接中，所以你只须要指定一次。

参考：

  • 指南 > 动态资源 > Base Helper
  • 指南 > 部署

2. lang

  • 类型：string
  • 默认值：en-US

详情：

站点的语言。

它将会在最终渲染出的 HTML 中作为 <html> 标签的 lang 属性。

它能够设置在不同语言的 locales 中。中文：zh-CN

参考：

  • 配置 > locales

3. title

  • 类型：string
  • 默认值：''

详情：

站点的题目。

它将会作为所有页面题目的后缀，并且在默认主题的导航栏中显示。

它能够设置在不同语言的 locales 中。

参考：

  • 配置 > locales

4. description

  • 类型：string
  • 默认值：''

详情：

站点的形容。

它将会在最终渲染出的 HTML 中作为 <meta name="description" /> 标签的 content 属性。它会被每个页面的 Frontmatter 中的 description 字段笼罩。

它能够设置在不同语言的 locales 中。

参考：

  • 配置 > locales
  • Frontmatter > description

5. head

  • 类型：HeadConfig[]
  • 默认值：[]

详情：

在最终渲染出的 HTML 的 <head> 标签内退出的额定标签。

你能够通过 [tagName, { attrName: attrValue}, innerHTML?] 的格局来增加标签。

它能够设置在不同语言的 locales 中。

示例：

减少一个自定义的 favicon：

module.exports = {head: [['link', { rel: 'icon', href: '/images/logo.png'}]],
}

渲染为：

<head>
  <link rel="icon" href="/images/logo.png" />
</head>

尽管，前面我会放上我写的配置，然而当初我还是放一下这个 head 的多个 html 写法：

head: [['link', { rel: 'icon', type: "image/png", href: 'images/favicon.ico',}],
            ['meta', { name: "keywords", content: "流沙团队：AI 悦创、长远, 编程一对一教学,Python, 爬虫, 深度学习, 机器学习, 数据分析, 网络,IT, 技术, 博客, 算法与数据结构"}]
            ],

那我对应的文件夹以及图片的构造呢？


参考： https://v2.vuepress.vuejs.org/zh/guide/assets.html

参考：

  • 配置 > locales
  • Frontmatter > head

6. locales

  • 类型：{[path: string]: Partial<SiteLocaleData> }
  • 默认值：{}

详情：

多语言反对的各个语言 locales。

  • lang
  • title
  • description
  • head

参考：

指南 > I18n

写到 6 这个点呢，就不得不说怎么配置了。不过不是当初，是前面的站点配置。

不过写到这里，也就开始了主题的配置了。

3.2.2 主题配置

主题配置将会被 VuePress 主题来解决，所以它取决于你应用的主题是什么。

如果你没有设置 VuePress 配置的 theme 配置项，则代表应用的是默认主题。至于其余主题，等我有工夫，我肯定安顿。如果你们焦急就分享和关注公众号：AI 悦创，并私信我哈。

提醒： 返回 默认主题 > 配置参考 查看默认主题的配置。

1. home

  • 类型：string
  • 默认值：/

详情：

首页的门路。

它将被用于：

  • 导航栏中 Logo 的链接
  • 404 页面的 返回首页 链接

2. navbar

  • 类型：false | (NavbarItem | NavbarGroup | string)[]
  • 默认值：[]

详情：

导航栏配置。

设置为 false 能够禁用导航栏。

为了配置导航栏元素，你能够将其设置为 导航栏数组，其中的每个元素是 NavbarItem 对象、NavbarGroup 对象、或者字符串：

  • NavbarItem 对象应该有一个 text 字段和一个 link 字段，还有一个可选的 activeMatch 字段。
  • NavbarGroup 对象应该有一个 text 字段和一个 children 字段。children 字段同样是一个 导航栏数组。
  • 字符串应为指标页面文件的门路。它将会被转换为 NavbarItem 对象，将页面题目作为 text，将页面路由门路作为 link。

写到这里的时候，我发现文档很强很全，所以我间接待会把配置好的文件内容贴出来。

接下来，我配置一下，目前须要的导航栏：

目前构想，我须要：

  • 专栏
  • Github
  • 对于团队
  • 资源分享
  • 技术杂谈
  • 付费教学
  • 数据结构与算法
  • Java 入门
  • Python 入门
  • Go 入门
  • 源码剖析
  • 广告
  • 期末不挂科

3. 站点多语言配置

要启用 VuePress 的多语言反对，首先须要应用如下的文件目录构造：

docs
├─ README.md
├─ foo.md
├─ nested
│  └─ README.md
└─ zh
   ├─ README.md
   ├─ foo.md
   └─ nested
      └─ README.md

那下面是官网给的构造，我是中国人，所以呢。我就把 zh 改成 en 吧。


而后，在你的 配置文件 中设置 locales 选项：

module.exports = {
  locales: {
    // 键名是该语言所属的子门路
    // 作为特例，默认语言能够应用 '/' 作为其门路。'/': {
      lang: 'en-US',
      title: 'VuePress',
      description: 'Vue-powered Static Site Generator',
    },
    '/zh/': {
      lang: 'zh-CN',
      title: 'VuePress',
      description: 'Vue 驱动的动态网站生成器',
    },
  },
}

那和下面也是一样的，我要设置一个英文站点，然而显然下面的官网提供样例的配置是不够的，还须要看这个连贯的文档：

所以我也一起配置一波：

module.exports = {
  locales: {
    // 键名是该语言所属的子门路
    // 作为特例，默认语言能够应用 '/' 作为其门路。'/': {
      lang: 'zh-CN',
      title: '流沙团队',
      description: '一股有形的力量——流沙',
    },
    '/en/': {
      lang: 'en-US',
      title: 'QuickSandTeam',
      description: 'An invisible force -- quicksandteam',
    },
  },
}

如果一个语言没有申明 lang, title, description 或者 head，VuePress 将会尝试应用顶层配置的对应值。如果每个语言都申明了这些值，那么顶层配置中的对应值能够被省略。

提醒： 配置参考：locales

然而，下面的配置我发现显示的和我工夫的语言有区别。

第一个应该是中文，却上图那样显示。第二个也是：


第二个还算好一点，所以进行优化批改：

themeConfig: {
  logo: 'https://vuejs.org/images/logo.png',

  locales: {
    '/': {
      selectLanguageText: "抉择语言",
          selectLanguageName: '简体中文',
          selectLanguageText: '抉择语言',
          selectLanguageAriaLabel: '抉择语言',
    },
    '/en/': {
      selectLanguageText: "Languages",
      selectLanguageName: 'English',
    }
  },

待更新！

AI 悦创·推出辅导班啦，包含「Python 语言辅导班、C++ 辅导班、算法 / 数据结构辅导班、少儿编程、pygame 游戏开发」，全部都是一对一教学：一对一辅导 + 一对一答疑 + 安排作业 + 我的项目实际等。QQ、微信在线，随时响应！V：Jiabcdefh

正文完
vuepress
发表至： vuepress
2021-10-16
 0
关于vuepress:VuePress-博客之-SEO-优化六站长工具
关于vuepress:vuepress-插件原理-以及-如何实现一个博客访问验证插件
关于vuepress:搭建-VuePress-站点必做的-10-个优化
关于VuePress:从01实践VuePress搭建组件库文档一