296 lines
6.0 KiB
Markdown
296 lines
6.0 KiB
Markdown
---
|
||
title: 安装/使用
|
||
author: pengzhanbo
|
||
icon: grommet-icons:install
|
||
createTime: 2024/03/04 09:50:07
|
||
permalink: /guide/quick-start/
|
||
tags:
|
||
- 指南
|
||
- 快速开始
|
||
---
|
||
|
||
<script setup>
|
||
const vuepressVersion = __VUEPRESS_VERSION__
|
||
</script>
|
||
|
||
## 依赖环境
|
||
|
||
- [Node.js v18.20.0+](https://nodejs.org/)
|
||
- [pnpm 8+](https://pnpm.io/zh/) 或 [Yarn 2+](https://yarnpkg.com/)
|
||
|
||
## 命令行安装
|
||
|
||
主题提供了一个 命令行工具，帮助您构建一个基本项目。您可以通过运行以下命令，启动 安装向导。
|
||
|
||
::: code-tabs
|
||
|
||
@tab pnpm
|
||
|
||
```sh
|
||
pnpm create vuepress-theme-plume@latest
|
||
```
|
||
|
||
@tab yarn
|
||
|
||
```sh
|
||
yarn create vuepress-theme-plume@latest
|
||
```
|
||
|
||
@tab npm
|
||
|
||
```sh
|
||
npm init vuepress-theme-plume@latest
|
||
```
|
||
|
||
:::
|
||
|
||
启动向导后，您只需要回答几个简单的问题：
|
||
|
||
<!-- @include: ../snippet/create.snippet.md ---->
|
||
|
||
::: details 怎么使用命令行工具？
|
||
|
||
以 Windows 系统为例，你可以使用以下方法来启动 CMD 命令行工具：
|
||
|
||
1. 按下 `Win + R` 键打开 “运行” 对话框。
|
||
2. 输入 `cmd` 并按下 Enter 键。 （也可以输入 `powershell` 来打开 PowerShell）
|
||
|
||
注意此时 `cmd` 可能不在你期望的目录位置，你可以使用如下命令来切换到正确的目录：
|
||
|
||
```sh
|
||
D: # 此命令将切换到 D: 分区，进入其他分区请按照实际情况修改
|
||
cd open-source # 进入 D: 分区下的 open-source 目录
|
||
```
|
||
|
||
此时，你就可以在这里输入 `pnpm create vuepress-theme-plume@latest` 来创建一个基本的项目了。
|
||
|
||
创建的项目将位于 `D:\open-source\my-project` 目录下。
|
||
:::
|
||
|
||
## 手动安装
|
||
|
||
::: info 提示
|
||
|
||
- 使用 [pnpm](https://pnpm.io/zh/) 时，你需要安装 `vue` 作为 peer-dependencies 。
|
||
- 使用 [Yarn 2+](https://yarnpkg.com/) 时，你需要在 `.yarnrc.yml` 文件中设置 `nodeLinker: 'node-modules'` 。
|
||
:::
|
||
|
||
使用本主题，你需要首先新建一个项目，并安装`vuepress@next`以及本主题
|
||
|
||
:::: steps
|
||
|
||
- ### 新建文件夹并进入目录
|
||
|
||
``` sh :no-line-numbers
|
||
mkdir my-blog
|
||
cd my-blog
|
||
```
|
||
|
||
- ### 初始化项目
|
||
|
||
::: code-tabs
|
||
@tab pnpm
|
||
|
||
``` sh :no-line-numbers
|
||
git init
|
||
pnpm init
|
||
```
|
||
|
||
@tab yarn
|
||
|
||
``` sh :no-line-numbers
|
||
git init
|
||
yarn init
|
||
```
|
||
|
||
@tab npm
|
||
|
||
``` sh :no-line-numbers
|
||
git init
|
||
npm init
|
||
```
|
||
|
||
:::
|
||
|
||
- ### 安装相关依赖
|
||
|
||
安装 `vuepress@next` 和 `vuepress-theme-plume` 作为本地依赖。
|
||
|
||
::: code-tabs
|
||
@tab pnpm
|
||
|
||
```sh :no-line-numbers
|
||
# 安装 vuepress
|
||
pnpm add -D vuepress@next vue
|
||
# 安装 主题和打包工具
|
||
pnpm add -D vuepress-theme-plume @vuepress/bundler-vite@next
|
||
```
|
||
|
||
@tab yarn
|
||
|
||
``` sh :no-line-numbers
|
||
# 安装 vuepress
|
||
yarn add -D vuepress@next
|
||
# 安装 主题和打包工具
|
||
yarn add -D vuepress-theme-plume @vuepress/bundler-vite@next
|
||
```
|
||
|
||
@tab npm
|
||
|
||
``` sh :no-line-numbers
|
||
# 安装 vuepress
|
||
npm i -D vuepress@next
|
||
# 安装 主题和打包工具
|
||
npm i -D vuepress-theme-plume @vuepress/bundler-vite@next
|
||
```
|
||
|
||
:::
|
||
|
||
:::warning
|
||
主题当前版本 已适配至 <code>vuepress@{{ vuepressVersion }}</code>，你应该安装这个版本的 VuePress。
|
||
高于或低于这个版本，可能会存在潜在的兼容性问题。
|
||
:::
|
||
|
||
- ### 在 `package.json` 中添加 `script`
|
||
|
||
::: code-tabs
|
||
@tab package.json
|
||
|
||
``` json :no-line-numbers
|
||
{
|
||
"scripts": {
|
||
"docs:dev": "vuepress dev docs",
|
||
"docs:build": "vuepress build docs"
|
||
}
|
||
}
|
||
```
|
||
|
||
:::
|
||
|
||
`vuepress` 默认将文档源码放在 `docs` 目录下。
|
||
|
||
- ### 将默认的临时目录和缓存目录添加到`.gitignore` 文件中
|
||
|
||
::: code-tabs
|
||
@tab .gitignore
|
||
|
||
``` txt :no-line-numbers
|
||
node_modules
|
||
.temp
|
||
.cache
|
||
```
|
||
|
||
@tab sh
|
||
|
||
``` sh :no-line-numbers
|
||
echo 'node_modules' >> .gitignore
|
||
echo '.temp' >> .gitignore
|
||
echo '.cache' >> .gitignore
|
||
```
|
||
|
||
:::
|
||
|
||
- ### 在 `docs/.vuepress/config.{js,ts}` 中配置主题
|
||
|
||
::: code-tabs
|
||
@tab docs/.vuepress/config.js
|
||
|
||
``` ts :no-line-numbers
|
||
import { viteBundler } from '@vuepress/bundler-vite'
|
||
import { defineUserConfig } from 'vuepress'
|
||
import { plumeTheme } from 'vuepress-theme-plume'
|
||
|
||
export default defineUserConfig({
|
||
// 请不要忘记设置默认语言
|
||
lang: 'zh-CN',
|
||
theme: plumeTheme({
|
||
// more...
|
||
}),
|
||
bundler: viteBundler(),
|
||
})
|
||
```
|
||
|
||
:::
|
||
|
||
:::warning
|
||
无论是否需要使用 __多语言__ ，你都应该为 VuePress 配置 正确 `lang` 选项值。
|
||
主题需要根据 `lang` 选项来确定语言环境文本。
|
||
:::
|
||
|
||
- ### 在 `docs` 目录下新建 `README.md` 文件
|
||
|
||
声明首页配置。
|
||
::: code-tabs
|
||
@tab README.md
|
||
|
||
``` md :no-line-numbers
|
||
---
|
||
home: true
|
||
---
|
||
```
|
||
|
||
:::
|
||
|
||
- ### 在本地服务器启动你的文档站点
|
||
|
||
::: code-tabs
|
||
@tab pnpm
|
||
|
||
```sh :no-line-numbers
|
||
pnpm docs:dev
|
||
```
|
||
|
||
@tab yarn
|
||
|
||
``` sh :no-line-numbers
|
||
yarn docs:dev
|
||
```
|
||
|
||
@tab npm
|
||
|
||
``` sh :no-line-numbers
|
||
npm docs:run dev
|
||
```
|
||
|
||
:::
|
||
|
||
Vuepress 会在 [http://localhost:8080](http://localhost:8080) 。启动一个热重载的开发服务器。当你修改你的 Markdown 文件时，浏览器中的内容也会自动更新。
|
||
|
||
- ### 完成
|
||
|
||
::::
|
||
|
||
## 文件结构
|
||
|
||
使用命令行工具创建的项目，它的文件结构是这样的。（如果你是手动创建的，也可以参考此文件结构管理您的项目）
|
||
|
||
::: file-tree
|
||
|
||
- .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
|
||
- pnpm-lock.yaml
|
||
- .gitignore
|
||
- README.md
|
||
:::
|
||
|
||
在 `docs` 目录中， 除 `.vuepress` 目录外，目录中的 所有 markdown 文件都会被识别为文档。
|
||
|
||
- 除 `notes` 目录外的 `markdown` 文件会被识别为 博客文章，并根据其所在的目录结构，作为 文章分类。
|
||
|
||
- `notes` 目录下 `markdown` 文件会被识别为 文档笔记。
|