vuepress-theme-plume/docs/notes/theme/guide/安装与使用.md

title, author, icon, createTime, permalink, tags

title	author	icon	createTime	permalink	tags
安装/使用	pengzhanbo	grommet-icons:install	2024/03/04 09:50:07	/guide/quick-start/	指南 快速开始

依赖环境

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

命令行安装

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

::: code-tabs

@tab pnpm

pnpm create vuepress-theme-plume@latest

@tab yarn

yarn create vuepress-theme-plume@latest

@tab npm

npm init vuepress-theme-plume@latest

:::

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

::: details 怎么使用命令行工具？

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

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

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

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

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

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

手动安装

::: info 提示

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

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

:::: steps

• 新建文件夹并进入目录

  mkdir my-blog
  cd my-blog
  

• 初始化项目

  ::: code-tabs @tab pnpm

  git init
  pnpm init
  

  @tab yarn

  git init
  yarn init
  

  @tab npm

  git init
  npm init
  

  :::

• 安装相关依赖

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

  ::: code-tabs @tab pnpm

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

  @tab yarn

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

  @tab npm

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

  :::

  :::warning 主题当前版本 已适配至 vuepress@{{ vuepressVersion }}，你应该安装这个版本的 VuePress。 高于或低于这个版本，可能会存在潜在的兼容性问题。 :::

• 在 package.json 中添加 script

  ::: code-tabs @tab package.json

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

  :::

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

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

  ::: code-tabs @tab .gitignore

  node_modules
  .temp
  .cache
  

  @tab sh

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

  :::

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

  ::: code-tabs @tab 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(),
  })
  

  :::

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

• 在 docs 目录下新建 README.md 文件

  声明首页配置。 ::: code-tabs @tab README.md

  ---
  home: true
  ---
  

  :::

• 在本地服务器启动你的文档站点

  ::: code-tabs @tab pnpm

  pnpm docs:dev
  

  @tab yarn

  yarn docs:dev
  

  @tab npm

  npm docs:run dev
  

  :::

  Vuepress 会在 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
• package-lock.json
• .gitignore
• README.md :::

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