---
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` 文件会被识别为 文档笔记。