运行环境

1. vs code
2. node.js
3. pnpm（也可以换成 npm 或者 yarn等，但是 yarn 按照作者说法有些功能已经不再实现，因此推荐使用 npm 或者 pnpm）

创建项目

pnpm create vuepress-theme-hope my-docs
yarn create vuepress-theme-hope my-docs
npm init vuepress-theme-hope my-docs

三者任选一个即可。不能放在根目录上，建议使用全英文目录。

运行之后就需要进行配置，建议勾选上 Github Pages 工作流。Git 应该是默认的，博客的很多功能需要借助 Git 来进行实现，因此你现在不选初始化未来也需要进行初始化。

多语言未来可以自定义配置。

执行之后可以尝试运行。

项目结构

├── .github (可选的) → GitHub 配置文件存放路径
│    └── workflow → GitHub 工作流配置
│         └── docs-deploy.yml → 自动部署文档的工作流
│
├── src → 文档文件夹
│    │
│    ├── .vuepress (可选的) → VuePress 配置文件夹
│    │    │
│    │    ├── dist (默认的) → 构建输出目录
│    │    │
│    │    ├── public (可选的) → 静态资源目录
│    │    │
│    │    ├── styles (可选的) → 用于存放样式相关的文件
│    │    │
│    │    ├── config.{js,ts} (可选的) → 配置文件的入口文件
│    │    │
│    │    └── client.{js,ts} (可选的) → 客户端文件
│    │
│    ├── ... → 其他项目文档
│    │
│    └── README.md → 项目主页
│
└── package.json → Nodejs 配置文件

实际上并不仅仅是这些文件夹，运行时 .vuepress 目录会出现 .cache 和 .temp 这两个临时文件夹，根目录会出现 node_modules 和 pnpm_lock.yaml 两个和第三方模块的相关文件和文件夹，以及 .gitingore 文件。

项目命令

pnpm docs:dev
pnpm docs:build
pnpm docs:clean-dev
pnpm dlx vp-update

前两条会启动开发服务器，第二个会清空缓存，最后一个是升级 vuepress-theme-hope ，会升级到最新版本，第二个为构建项目，执行该项目会生成静态页面到 dist 文件夹中。

页面

页面主要分为两种，一种 README 为名的markdown 文件 ，一种是普通 markdown 文件。markdown 会转换成网页，打开开发服务器则会自动同步。

相对路径会转换成路由路径，将对应的 md 文件转换成 html页面，/ 表示 src 目录。以 /README.md 为例，会转换成 /，/demo/markdown.md 转换成 /demo/markdown.html。

README.md文件其实是转换为index.html文件，但是一般是作为主页，因此会省略，因此可以转换为/

markdown 文件中分为两个部分，一种是 Frontmatter ，一种是 Markdown 内容。

Frontmatter：

---
lang: zh-CN
title: 页面的标题
description: 页面的描述
---

部署到 GitHub

本地库和 Github 远程库建立连接，使用 main 作为主分支。Github 需要创建一个 <username>/<username>.github.io 和 一个 <repository> 仓库。

git remote add origin git@github.com:<username>/<repository>.git
git branch -M main

如果发不到 https://<username>.github.io/ ，需要将整个项目上传到 https://github.com/<username>/<username>.github.io 仓库，无需更改。仓库地址需要改成 https://<username>.github.io/<repository>/ ，则将 config.ts 中的 base 改为 /<repository>/ 。