项目结构
1085字约4分钟
2024-09-16
本指南将向您说明 VuePress 和 Plume 创建的项目的文件结构,以及如何在项目中使用它们。
当您 使用命令行工具创建 的项目,它的文件结构是这样的:
- .git
- …
- docs # 文档源目录
- .vuepress # vuepress 配置文件夹
- public# 静态资源目录
- …
- client.ts# 客户端配置 (可选)
- config.ts# vuepress 配值
- navbar.ts# 导航栏配置 (可选)
- notes.ts# notes 配置 (可选)
- plume.config.ts# 主题配置文件 (可选)
- public# 静态资源目录
- notes# 系列文档、知识笔记
- demo
- foo.md
- bar.md
- demo
- preview# 博客分类之一
- markdown.md# 分类下的博客文章
- article.md# 博客文章
- README.md# 首页
- …
- .vuepress # vuepress 配置文件夹
- package.json
- pnpm-lock.yaml
- .gitignore
- README.md
如果你是手动创建的,也可以参考此文件结构管理您的项目
文档源目录
文档源目录 指的是,你的站点的所有 markdown 文件所在的目录。该目录一般在使用 命令行工具 启动 VuePress 时指定:
vuepress dev docs
# 这里声明了文档源目录为 docs
{
"scripts": {
"docs:dev": "vuepress dev docs",
// ^^^^
"docs:build": "vuepress build docs"
// ^^^^
}
}
一般而言,VuePress 仅会接管 该目录,非源目录下的其它文件会被忽略。
.vuepress
目录
.vuepress/
目录是 VuePress 配置文件夹,你还可以在这里创建 自己的组件、自定义主题样式等。
在此目录中:
client.ts
客户端配置文件,你可以在这里扩展 VuePress 的功能,比如声明新的全局组件等。
import { defineClientConfig } from 'vuepress/client'
export default defineClientConfig({
enhance({ app, router, siteData }) {
// app: vue app 实例
// router: vue router 实例
// siteData: vuepress 站点配置
// 注册全局组件
app.component('MyComponent', MyComponent)
},
setup() {
// 等同于 vue 根组件 上的 setup 方法
}
})
config.ts
为 VuePress 配置文件,你需要在这里进行一个必要的配置,比如 主题、插件、构建工具等。
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(),
})
plume.config.ts
主题配置文件,由于每次修改 .vuepress/config.ts
,都需要重启 VuePress 服务,然而实际上大多数时候都不需要这么做。
主题将不需要重启服务的配置移动到了这里。在这里修改配置时,仅通过热更新的方式更新主题。
import { definePlumeConfig } from 'vuepress-theme-plume'
import navbar from './navbar'
import notes from './notes'
export default definePlumeConfig({
logo: '/logo.svg',
profile: {
name: 'Theme Plume',
},
navbar,
notes,
// ... more
})
import { defineNavbarConfig } from 'vuepress-theme-plume'
export default defineNavbarConfig([
// ...
])
import { defineNotesConfig } from 'vuepress-theme-plume'
export default defineNotesConfig({
// ...
})
notes 目录
notes 目录用于存放你的 知识笔记、系列文档等。
如何理解知识笔记/系列文档 ?
一种很常见的场景是,您正在学习某项技能,并打算把学习心得、重点内容、疑难点等记录在笔记中,这一场景下, 您可能会写多篇文档进行记录。
或者是,您正在准备面试,想要提前准备好 面试题目和答案,这时候可能会把 每个题目和答案都单独作为一篇文档。
你很容易就会希望把它们都单独放在一个目录下进行管理,与此同时,还希望在生成的文档站点中,能够快速的在 这项技能笔记 的不同文档之间导航,或者在不同的面试题目之间导航。
这是博客类型的文档满足不了的诉求,而这恰恰是 notes
所要解决的一个痛点。
上述的内容,很容易产生以下目录结构:
- notes
- interview # 面试题
- 自我介绍.md
- 我的技能.md
- 做过的项目.md
- …
- typescript# 学习笔记
- 基础
- 基本类型.md
- 泛型.md
- …
- 进阶
- 函数.md
- …
- 基础
- interview # 面试题
这可以很方便的管理多个系列文档,每个系列文档都可以有自己的目录结构。
其它目录/文件
在 文档源目录 中的 其它目录、文件,除了 README.md
被识别为 主页
之外,都会被识别为 博客文章。 而 目录结构 则将被识别为 博客分类。
- docs
- 生活
- 旅游日记.md
- …
- 学习
- 考试笔记.md
- …
- 工作
- 番茄时间.md
- …
- 杂事.md # 无分类的文章
- README.md # 主页
- …
- 生活