安装/使用

1086字约4分钟

2024-03-04

依赖环境

Node.js v18.20.0+
pnpm 8+ 或 Yarn 2+

命令行安装

主题提供了一个命令行工具，帮助您构建一个基本项目。您可以通过运行以下命令，启动安装向导。

pnpm

pnpm create vuepress-theme-plume@latest

yarn

yarn create vuepress-theme-plume@latest

npm

npm init vuepress-theme-plume@latest

启动向导后，您只需要回答几个简单的问题：

┌  Welcome to VuePress and vuepress-theme-plume !
│
◇  Select a language to display / 选择显示语言
│  简体中文
│
◇  您想在哪里初始化 VuePress？
│  ./my-project
│
◇  站点名称：
│  My Vuepress Site
│
◇  站点描述信息：
│  My Vuepress Site Description
│
◇  是否使用多语言？
│  No
│
◇  请选择站点默认语言
│  简体中文
│
◇  是否使用 TypeScript？
│  Yes
│
◇  请选择打包工具
│  Vite
│
◇  部署方式：
│  Custom
│
◇  是否初始化 git 仓库？
│  Yes
│
◇  是否安装依赖？
│  Yes
│
◇   🎉 创建成功!
│
└  🔨 执行以下命令即可启动：
      cd ./my-project
      pnpm run docs:dev

怎么使用命令行工具？

以 Windows 系统为例，你可以使用以下方法来启动 CMD 命令行工具：

按下 Win + R 键打开 “运行” 对话框。
输入 cmd 并按下 Enter 键。（也可以输入 powershell 来打开 PowerShell）

注意此时 cmd 可能不在你期望的目录位置，你可以使用如下命令来切换到正确的目录：

D: # 此命令将切换到 D: 分区，进入其他分区请按照实际情况修改
cd open-source # 进入 D: 分区下的 open-source 目录

此时，你就可以在这里输入 pnpm create vuepress-theme-plume@latest 来创建一个基本的项目了。

创建的项目将位于 D:\open-source\my-project 目录下。

手动安装

提示

使用 pnpm 时，你需要安装 vue 作为 peer-dependencies 。
使用 Yarn 2+ 时，你需要在 .yarnrc.yml 文件中设置 nodeLinker: 'node-modules' 。

使用本主题，你需要首先新建一个项目，并安装vuepress@next以及本主题

新建文件夹并进入目录
```
mkdir my-blog
cd my-blog
```

初始化项目

pnpm

git init
pnpm init

yarn

git init
yarn init

npm

git init
npm init

安装相关依赖

安装 vuepress@next 和 vuepress-theme-plume 作为本地依赖。

pnpm

# 安装 vuepress
pnpm add -D vuepress@next vue
# 安装 主题和打包工具
pnpm add -D vuepress-theme-plume @vuepress/bundler-vite@next

yarn

# 安装 vuepress
yarn add -D vuepress@next
# 安装 主题和打包工具
yarn add -D vuepress-theme-plume @vuepress/bundler-vite@next

npm

# 安装 vuepress
npm i -D vuepress@next
# 安装 主题和打包工具
npm i -D vuepress-theme-plume @vuepress/bundler-vite@next

注意

主题当前版本已适配至 vuepress@2.0.0-rc.15，你应该安装这个版本的 VuePress。高于或低于这个版本，可能会存在潜在的兼容性问题。

在 `package.json` 中添加 `script`

package.json

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

vuepress 默认将文档源码放在 docs 目录下。

将默认的临时目录和缓存目录添加到`.gitignore` 文件中

.gitignore

node_modules
.temp
.cache

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

在 `docs/.vuepress/config.{js,ts}` 中配置主题

docs/.vuepress/config.js

import { defineUserConfig } from 'vuepress'
import { viteBundler } from '@vuepress/bundler-vite'
import { plumeTheme } from 'vuepress-theme-plume'

export default defineUserConfig({
  // 请不要忘记设置默认语言
  lang: 'zh-CN',
  theme: plumeTheme({
    // more...
  }),
  bundler: viteBundler(),
})

注意

无论是否需要使用 多语言 ，你都应该为 VuePress 配置正确 lang 选项值。主题需要根据 lang 选项来确定语言环境文本。

在 docs 目录下新建 README.md 文件
声明首页配置。
README.md
```
---
home: true
---
```
在本地服务器启动你的文档站点
pnpm
```
pnpm docs:dev
```
yarn
```
yarn docs:dev
```
npm
```
npm docs:run dev
```
Vuepress 会在 http://localhost:8080 。启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。
完成

文件结构

使用命令行工具创建的项目，它的文件结构是这样的。（如果你是手动创建的，也可以参考此文件结构管理您的项目）

.git/
- …
docs# 文档源目录
- .vuepress
  - public/# 静态资源目录
    - …
  - client.ts
  - config.ts# vuepress 配值文件
  - navbar.ts# 导航栏配置
  - notes.ts# notes 配置
  - plume.config.ts# 主题配置文件
- notes
  - demo
    - foo.md
    - bar.md
- preview
  - markdown.md
- README.md# 首页
package.json
package-lock.json
.gitignore
README.md

在 docs 目录中，除 .vuepress 目录外，目录中的所有 markdown 文件都会被识别为文档。其中，除 notes 目录外的 markdown 文件会被识别为博客文章，而 notes 目录下 markdown 文件会被识别为文档笔记。