快速上手

最近更新：2024-7-29

注意

本人已转用 Vitepress ，可能不会再更新了

在线体验

免安装体验及调试 StackBlitz：https://stackblitz.com/fork/vuepress

前期工作

说明

已经安装 或者 熟练了，可以不用看此步骤

必备工具
pnpm

安装好nodejs后，通过 npm 安装 pnpm 或 yarn

#安装pnpm
npm install -g pnpm
#查看版本号
pnpm -v
#安装yarn
npm install -g yarn
#查看版本号
yarn -v

创建文件目录

win键+R键，调出命令运行框，输入 cmd

先进入任意盘符，比如 F 盘

#盘符可以自定义 回车进入
f:

再创建文件夹名

#创建目录并进入，也可以自定义目录名
mkdir vuepress && cd vuepress

说明

这样我的目录路径为 F:\vuepress

不习惯的，也可以直接电脑创建

安装

说明

如果你是首次接触，推荐你使用 一键安装

你已经够熟练了，直接使用 手动安装

一键安装

通过 create-vuepress 直接创建项目模板

pnpm create vuepress vuepress-starter
yarn create vuepress vuepress-starter
npm init vuepress vuepress-starter

用键盘 方向键↓ 选择 简体中文，回车

包管理器就选择你安装时的包，我是pnpm，回车

打包器用默认的vite即可，回车

项目类型，我用文档演示，用键盘 方向键↓ 选择 docs

应用名称、版本号、描述也可以之后再改，直接回车

默认协议MIT，默认创建工作流，回车

等下载安装完成，问是否启动，输入 y 回车

WARN  Issues with peer dependencies found

这里提示依赖关系需要不对等，不急，我们等会处理

这里自动生成了一个本地8080端口的网页，复制到浏览器打开

打开网页一片空白，什么都没有

这就是刚才提示依赖不对等造成的，我们ctrl+c ，输入 y 回车结束终端

进入自动创建的vuepress-starter文件夹

cd vuepress-starter

使用 pnpm dlx 升级vuepress

pnpm dlx vp-update
yarn dlx vp-update
npx vp-update

最后手动启动看看，已经可以查看网页了

pnpm docs:dev
yarn dlx vp-update
npx vp-update

手动安装

cmd不小心关了，在目录上方的地址栏输入 cmd 回车，可以快捷打开

初始化

pnpm init
yarn init
npm init

安装依赖

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

创建目录

# 创建 docs 目录和 docs/.vuepress 目录
mkdir docs
mkdir docs\.vuepress

创建配置文件

在 docs/.vuepress/ 目录中，创建一个空的配置文件

echo >docs/.vuepress/config.ts

右键记事本打开，复制下面代码，粘贴到 config.ts 中保存

import { viteBundler } from '@vuepress/bundler-vite'
import { defaultTheme } from '@vuepress/theme-default'
import { defineUserConfig } from 'vuepress'

export default defineUserConfig({
  bundler: viteBundler(),
  theme: defaultTheme(),
})

脚本命令

在 package.json 中更改 scripts 命令，保存

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

命令讲解

执行命令 docs:dev，就会运行 vuepress dev docs

执行命令 docs:build，就会运行 vuepress build docs

git忽略项

添加 .gitignore 文件，主要用于上传到gitee/github的忽略项

注意

分别将 依赖文件 / 临时目录 / 缓存目录 / 静态目录 添加到.gitignore文件中

建议先使用cmd，使用vscode有可能会出现乱码

echo node_modules >> .gitignore

echo .temp >> .gitignore

echo .cache >> .gitignore

echo dist >> .gitignore

Github上传未忽略dist文件夹

原因：vscode输入命令导致编码错误

解决：Github Desktop - Repository settings - ignored files

输入我们忽略的dist文件即可，save保存即可

node_modules
.temp
.cache
dist

创建文档

注意

建议先使用cmd，使用vscode有可能会出现乱码

创建你的第一篇文档

echo # Hello VuePress > docs/README.md

本地启动

执行在 脚本命令 中的命令，进入开发环境来搭建文档网站

pnpm docs:dev
yarn docs:dev
npm docs:dev

如何退出

ctrl+c 即可退出开发模式

本地启动了一个 8080 端口的热重载开发服务器

复制 http://localhost:8080 网址到浏览器打开，看到页面就说明vuepress就搭建完成了

注意

接下来我们可以关闭cmd，全程用vscode了