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

你好，我悦创。

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

Node.js v12+
Yarn v1 classic (Optional)

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

这个装置很简略，只须要下载，而后一路 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 可执行程序。

npm install --global yarn
yarn --version

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

我用的是 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

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.

咱们曾经不再举荐全局装置 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 会生成谬误的依赖树。

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

这一步骤是可选的，但咱们举荐你实现它。在下文中，咱们会默认这些 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

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

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

yarn docs:dev # npm run docs:dev

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

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

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

如果没有任何配置，你的 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 配置.

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

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

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

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

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

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

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

当前工作目录 cwd 下：
- vuepress.config.ts
- vuepress.config.js

源文件目录 sourceDir 下：
- .vuepress/config.ts
- .vuepress/config.js

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

类型：string
默认值：/

详情：

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

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

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

参考：

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

类型：string
默认值：en-US

详情：

站点的语言。

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

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

参考：

配置 > locales

类型：string
默认值：''

详情：

站点的题目。

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

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

参考：

配置 > locales

类型：string
默认值：''

详情：

站点的形容。

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

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

参考：

配置 > locales
Frontmatter > description

类型：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

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

详情：

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

lang
title
description
head

参考：

指南 > I18n

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

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

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

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

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

类型：string
默认值：/

详情：

首页的门路。

它将被用于：

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

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

详情：

导航栏配置。

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

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

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

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

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

目前构想，我须要：

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

要启用 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文档

1. 筹备条件（Prerequisites）

1.1 Node.js 装置

1.2 装置 yarn（Optional）

2. 疾速上手

2.1 创立并进入一个新目录

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

2.3 将 VuePress 装置为本地依赖

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

2.4 在 package.json 中增加一些 scripts

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

2.6 创立你的第一篇文档

2.7 在本地启动服务器

3. 配置

3.1 配置文件

3.2 配置作用域

3.2.1 站点配置

1. base

2. lang

3. title

4. description

5. head

6. locales

3.2.2 主题配置

1. home

2. navbar

3. 站点多语言配置

1. 筹备条件（Prerequisites）

1.1 Node.js 装置

1.2 装置 yarn（Optional）

2. 疾速上手

2.1 创立并进入一个新目录

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

2.3 将 VuePress 装置为本地依赖

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

2.4 在 package.json 中增加一些 scripts

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

2.6 创立你的第一篇文档

2.7 在本地启动服务器

3. 配置

3.1 配置文件

3.2 配置作用域

3.2.1 站点配置

1. base

2. lang

3. title

4. description

5. head

6. locales

3.2.2 主题配置

1. home

2. navbar

3. 站点多语言配置

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