mirror of
https://github.com/pengzhanbo/vuepress-theme-plume.git
synced 2026-04-23 10:58:13 +08:00
docs: improve docs (#192)
This commit is contained in:
pengzhanbo
GitHub
parent
1c40b25cfa
commit
89b2601ec7
@ -1,4 +1,4 @@
|
||||
import { type ClientConfig, defineClientConfig } from 'vuepress/client'
|
||||
import { defineClientConfig } from 'vuepress/client'
|
||||
import CanIUseConfig from './themes/components/CanIUseConfig.vue'
|
||||
import Contributors from './themes/components/Contributors.vue'
|
||||
import Demos from './themes/components/Demos.vue'
|
||||
@ -17,4 +17,4 @@ export default defineClientConfig({
|
||||
setup() {
|
||||
setupThemeColors()
|
||||
},
|
||||
}) as ClientConfig
|
||||
})
|
||||
|
||||
@ -5,15 +5,16 @@ export const themeGuide = defineNoteConfig({
|
||||
link: '/guide/',
|
||||
sidebar: [
|
||||
{
|
||||
text: '快速开始',
|
||||
text: '从这里开始',
|
||||
collapsed: false,
|
||||
icon: 'carbon:idea',
|
||||
items: [
|
||||
'介绍',
|
||||
'安装与使用',
|
||||
'项目结构',
|
||||
'编写文章',
|
||||
'博客',
|
||||
'知识笔记',
|
||||
'编写文章',
|
||||
'国际化',
|
||||
'部署',
|
||||
'构建优化',
|
||||
|
||||
331
docs/4.教程/frontmatter.md
Normal file
331
docs/4.教程/frontmatter.md
Normal file
@ -0,0 +1,331 @@
|
||||
---
|
||||
title: 如何使用 frontmatter
|
||||
createTime: 2024/09/18 09:19:36
|
||||
permalink: /article/ecxnxxd0/
|
||||
---
|
||||
|
||||
::: info 说明
|
||||
本文 翻译 [Introduction to YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) 的部分内容。
|
||||
用于简单说明如何在 markdown 文件中使用 frontmatter。
|
||||
|
||||
如果您具有良好的英语阅读基础，为避免翻译可能存在的内容失真，建议您阅读原文。
|
||||
|
||||
原文地址： <https://dev.to/paulasantamaria/introduction-to-yaml-125f> 。
|
||||
:::
|
||||
|
||||
## 介绍
|
||||
|
||||
YAML 是一种数据序列化语言，通常用于配置文件，例如
|
||||
[Open API 规范](https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/yaml/api-with-examples.yaml) 或 [CI/CD 管道](https://docs.gitlab.com/ee/ci/yaml/)。
|
||||
|
||||
::: note 有趣的事实！🤓
|
||||
根据 [YAML 1.0 规范文档 （2001-05-26）](https://yaml.org/spec/history/2001-05-26.html) 首字母缩略词
|
||||
“YAML” 代表 “Yet Another Markup Language”，
|
||||
但后来在 [2002-04-07 规范](https://yaml.org/spec/history/2002-04-07.html) 中更改为递归首字母缩略词“YAML Ain't Markup Language”。
|
||||
:::
|
||||
|
||||
正如最新规范中所述，__YAML__ 旨在 __对处理数据的人友好__，并通过 __最大限度地减少结构字符的使用来实现“独特的干净度”__，
|
||||
允许数据以自然和有意义的方式显示。
|
||||
|
||||
最新规范还指出，YAML _1.2 作为官方子集符合 JSON_ ，这意味着大多数 JSON 文档都可以解析为 YAML。
|
||||
|
||||
YAML 通过使用基于缩进的范围界定（类似于 Python）轻松检查数据结构。
|
||||
|
||||
::: note 另一个有趣的事实！🤓
|
||||
DEV.to 文章使用 YAML 来定义自定义变量，如标题、描述、标签等。
|
||||
:::
|
||||
|
||||
## 基本语法
|
||||
|
||||
YAML 文档基本上是 __键值对的集合__，其中值可以像字符串一样简单，也可以像树一样复杂。
|
||||
|
||||
以下是有关 YAML 语法的一些说明：
|
||||
|
||||
- __缩进用于表示结构__。不允许使用制表符，只要子节点的缩进量比父节点大，空格的数量就无关紧要。
|
||||
- 允许使用 UTF-8、UTF-16 和 UTF-32 编码。
|
||||
|
||||
### 字符串
|
||||
|
||||
```md
|
||||
---
|
||||
# 字符串不需要引号：
|
||||
title: Introduction to YAML
|
||||
|
||||
# 但你仍可使用它们：
|
||||
title-w-quotes: 'Introduction to YAML'
|
||||
|
||||
# 多行字符串以 | 开头
|
||||
execute: |
|
||||
npm ci
|
||||
npm build
|
||||
npm test
|
||||
---
|
||||
```
|
||||
|
||||
上面的代码将转换为 JSON 为：
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Introduction to YAML",
|
||||
"title-w-quotes": "Introduction to YAML",
|
||||
"execute": "npm ci\nnpm build\nnpm test\n"
|
||||
}
|
||||
```
|
||||
|
||||
### 数字
|
||||
|
||||
```md
|
||||
---
|
||||
# 整数：
|
||||
age: 29
|
||||
|
||||
# 浮点数：
|
||||
price: 15.99
|
||||
|
||||
# 科学计数法：
|
||||
population: 2.89e+6
|
||||
---
|
||||
```
|
||||
|
||||
上面的代码将转换为 JSON 为：
|
||||
|
||||
```json
|
||||
{
|
||||
"age": 29,
|
||||
"price": 15.99,
|
||||
"population": 2890000
|
||||
}
|
||||
```
|
||||
|
||||
### 布尔值
|
||||
|
||||
```md
|
||||
---
|
||||
# 布尔值可以有不同的表示方式：
|
||||
published: false
|
||||
published: False
|
||||
published: FALSE
|
||||
---
|
||||
```
|
||||
|
||||
以上所有内容都将转换为 JSON，如下所示：
|
||||
|
||||
```json
|
||||
{
|
||||
"published": false
|
||||
}
|
||||
```
|
||||
|
||||
### Null 值
|
||||
|
||||
```md
|
||||
---
|
||||
# Null 值可以通过不设置值来表示：
|
||||
null-value:
|
||||
|
||||
# 或者更明确地说：
|
||||
null-value: null
|
||||
null-value: NULL
|
||||
null-value: Null
|
||||
---
|
||||
```
|
||||
|
||||
以上所有内容都将转换为 JSON，如下所示：
|
||||
|
||||
```json
|
||||
{
|
||||
"null-value": null
|
||||
}
|
||||
```
|
||||
|
||||
### 日期和时间戳
|
||||
|
||||
可以使用 ISO 格式的日期，如下所示：
|
||||
|
||||
```md
|
||||
---
|
||||
date: 2002-12-14
|
||||
canonical: 2001-12-15T02:59:43.1Z
|
||||
iso8601: 2001-12-14t21:59:43.10-05:00
|
||||
spaced: 2001-12-14 21:59:43.10 -5
|
||||
---
|
||||
```
|
||||
|
||||
### Sequences 序列
|
||||
|
||||
序列允许我们在 YAML 中定义列表：
|
||||
|
||||
```md
|
||||
---
|
||||
# 使用连字符的数字列表：
|
||||
numbers:
|
||||
- one
|
||||
- two
|
||||
- three
|
||||
|
||||
# 内联版本：
|
||||
numbers: [ one, two, three ]
|
||||
---
|
||||
```
|
||||
|
||||
上述两个序列都将解析为 JSON，如下所示：
|
||||
|
||||
```json
|
||||
{
|
||||
"numbers": [
|
||||
"one",
|
||||
"two",
|
||||
"three"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 嵌套值
|
||||
|
||||
我们可以使用上述所有类型来创建具有嵌套值的对象，如下所示：
|
||||
|
||||
```md
|
||||
---
|
||||
# 一九八四小说数据。
|
||||
nineteen-eighty-four:
|
||||
author: George Orwell
|
||||
published-at: 1949-06-08
|
||||
page-count: 328
|
||||
description: |
|
||||
A Novel, often published as 1984, is a dystopian novel by English novelist George Orwell.
|
||||
It was published in June 1949 by Secker & Warburg as Orwell's ninth and final book.
|
||||
---
|
||||
```
|
||||
|
||||
这将转换为 JSON ：
|
||||
|
||||
```json
|
||||
{
|
||||
"nineteen-eighty-four": {
|
||||
"author": "George Orwell",
|
||||
"published-at": "1949-06-08T00:00:00.000Z",
|
||||
"page-count": 328,
|
||||
"description": "A Novel, often published as 1984, is a dystopian novel by English novelist George Orwell.\nIt was published in June 1949 by Secker & Warburg as Orwell's ninth and final book.\n"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 对象列表
|
||||
|
||||
将序列和嵌套值组合在一起，我们可以创建一个对象列表。
|
||||
|
||||
```md
|
||||
---
|
||||
# Let's list books:
|
||||
- nineteen-eighty-four:
|
||||
author: George Orwell
|
||||
published-at: 1949-06-08
|
||||
page-count: 328
|
||||
description: |
|
||||
A Novel, often published as 1984, is a dystopian novel by English novelist George Orwell.
|
||||
|
||||
- the-hobbit:
|
||||
author: J. R. R. Tolkien
|
||||
published-at: 1937-09-21
|
||||
page-count: 310
|
||||
description: |
|
||||
The Hobbit, or There and Back Again is a children's fantasy novel by English author J. R. R. Tolkien.
|
||||
---
|
||||
```
|
||||
|
||||
## 独特特性
|
||||
|
||||
以下是一些引起我注意的 __更复杂的功能__ ，它们也使 YAML 与 JSON 区分开来。
|
||||
|
||||
### 注释
|
||||
|
||||
你可能已经在我前面的示例中注意到，YAML 允许以 `#` 开头的注释。
|
||||
|
||||
```md
|
||||
---
|
||||
# 这是一个非常有用的注释。
|
||||
---
|
||||
```
|
||||
|
||||
### 锚点的可重用性
|
||||
|
||||
节点锚点用于 __标记一个节点__ 以供将来引用，从而允许我们重复使用该节点。
|
||||
要标记一个节点，我们使用 `&` 字符，要引用它，我们使用 `*` ：
|
||||
|
||||
在下面的示例中，我们将定义一个书籍列表并重用作者数据，因此我们只需要定义一次：
|
||||
|
||||
```md
|
||||
---
|
||||
# 作者数据：
|
||||
author: &gOrwell
|
||||
name: George
|
||||
last-name: Orwell
|
||||
|
||||
# 一些书籍：
|
||||
books:
|
||||
- 1984:
|
||||
author: *gOrwell
|
||||
- animal-farm:
|
||||
author: *gOrwell
|
||||
---
|
||||
```
|
||||
|
||||
解析为 JSON 后，上面的代码将如下所示：
|
||||
|
||||
```json
|
||||
{
|
||||
"author": {
|
||||
"name": "George",
|
||||
"last-name": "Orwell"
|
||||
},
|
||||
"books": [
|
||||
{
|
||||
"1984": {
|
||||
"author": {
|
||||
"name": "George",
|
||||
"last-name": "Orwell"
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"animal-farm": {
|
||||
"author": {
|
||||
"name": "George",
|
||||
"last-name": "Orwell"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 带有标签的显式数据类型
|
||||
|
||||
正如我们在之前的示例中所见，YAML 会自动检测我们值的类型，但我们也可以 __指定所需的类型__ 。
|
||||
|
||||
我们通过在值前加上 `!!` 类型来指定它。
|
||||
|
||||
以下是一些示例：
|
||||
|
||||
```md
|
||||
---
|
||||
# 以下值应为整数，无论何种情况：
|
||||
should-be-int: !!int 3.2
|
||||
|
||||
# 解析任何值为字符串：
|
||||
should-be-string: !!str 30.25
|
||||
|
||||
# 我需要下一个值为布尔类型：
|
||||
should-be-boolean: !!bool yes
|
||||
---
|
||||
```
|
||||
|
||||
这将转换为 JSON：
|
||||
|
||||
```json
|
||||
{
|
||||
"should-be-int": 3,
|
||||
"should-be-string": "30.25",
|
||||
"should-be-boolean": true
|
||||
}
|
||||
```
|
||||
@ -8,7 +8,7 @@ config:
|
||||
hero:
|
||||
name: Theme Plume
|
||||
tagline: VuePress Next Theme
|
||||
text: 一个简约的，功能丰富的 vuepress 文档&博客 主题
|
||||
text: 一个简约易用的，功能丰富的 vuepress 文档&博客 主题
|
||||
actions:
|
||||
-
|
||||
theme: brand
|
||||
@ -23,39 +23,39 @@ config:
|
||||
features:
|
||||
-
|
||||
title: 响应式布局
|
||||
icon: 💻
|
||||
icon: twemoji:laptop-computer
|
||||
details: 适配移动设备，PC，平板
|
||||
-
|
||||
title: 博客 & 文档
|
||||
icon: 📖
|
||||
icon: twemoji:open-book
|
||||
details: 无论是想写博客，或想写产品文档，或者两者兼顾
|
||||
-
|
||||
title: 开箱即用
|
||||
icon: 🚀
|
||||
icon: twemoji:rocket
|
||||
details: 支持零配置开箱即用，也支持丰富的自定义配置
|
||||
-
|
||||
title: 多语言
|
||||
icon: ⚖
|
||||
icon: twemoji:balance-scale
|
||||
details: 内置 中文/英文支持，还可以自定义添加更多的语言支持
|
||||
-
|
||||
title: 双色主题
|
||||
icon: 👨💻
|
||||
icon: twemoji:cityscape
|
||||
details: 支持 浅色/深色 主题，包括代码高亮
|
||||
-
|
||||
title: 插件
|
||||
icon: 📦
|
||||
icon: twemoji:card-file-box
|
||||
details: 内置丰富的插件，一站式解决网站一般需求
|
||||
-
|
||||
title: 搜索、评论
|
||||
icon: 🔍
|
||||
icon: twemoji:magnifying-glass-tilted-right
|
||||
details: 支持多种评论系统，支持本地搜索、Algolia搜索
|
||||
-
|
||||
title: 加密
|
||||
icon: 🔒
|
||||
icon: twemoji:locked-with-key
|
||||
details: 支持全站加密、部分加密（加密目录、加密文章）
|
||||
-
|
||||
title: Markdown 增强
|
||||
icon: 📝
|
||||
icon: twemoji:writing-hand-light-skin-tone
|
||||
details: 支持 Markdown 语法，支持 代码块分组、提示容器、任务列表、数学公式、代码演示等
|
||||
-
|
||||
type: image-text
|
||||
@ -68,19 +68,19 @@ config:
|
||||
description: 为文章添加标签、分类、字数统计、阅读时间、写作日期等信息。
|
||||
-
|
||||
title: 评论
|
||||
description: 支持 4 种评论系统，你可以自由选择符合你的需求的评论系统。
|
||||
description: 支持 4 种评论系统：Giscus、Waline、Twikoo、Artalk<br>你可以自由选择符合你的需求的评论系统。
|
||||
-
|
||||
title: 搜索
|
||||
description: 支持基于 minisearch 的本地搜索， 支持 Algolia 搜索。
|
||||
description: 支持基于 minisearch 的本地搜索，还支持接入 Algolia 搜索。
|
||||
-
|
||||
title: 加密
|
||||
description: 支持全站加密、部分加密（加密目录、加密文章）。
|
||||
-
|
||||
title: 代码
|
||||
description: 代码复制，CodePen演示，Replit演示，JSFiddle演示，CodeSandbox演示，代码组，行高亮，行聚焦，行警告，差异对比等。
|
||||
description: 代码复制，CodePen演示，JSFiddle演示，CodeSandbox演示，代码组，行高亮，行聚焦，行警告，差异对比，代码块折叠等。
|
||||
-
|
||||
title: 资源嵌入
|
||||
description: 图表：chart.js/ECharts/Mermaid/flowchart，视频：Bilibili/Youtube，PDF
|
||||
description: 图表：chart.js/ECharts/Mermaid/flowchart<br>视频：Bilibili/Youtube<br>PDF，200K+ Iconify 图标
|
||||
-
|
||||
type: text-image
|
||||
title: 博客
|
||||
@ -94,8 +94,8 @@ config:
|
||||
title: 博主信息
|
||||
description: 自定义名称、座右铭、头像，社交媒体链接。
|
||||
-
|
||||
title: 标签、归档
|
||||
description: 自动生成标签页，为文章根据年份进行归档。
|
||||
title: 分类、标签、归档
|
||||
description: 自动生成分类页、标签页，为文章根据年份进行归档。
|
||||
-
|
||||
type: image-text
|
||||
title: 文档
|
||||
|
||||
@ -9,10 +9,11 @@ tags:
|
||||
- 快速开始
|
||||
---
|
||||
|
||||
==vuepress-theme-plume== 是一个基于 VuePress 的主题，适用于 博客、文档 和 知识笔记 。
|
||||
==vuepress-theme-plume== 是一个基于 VuePress 的主题，无论您是想写 **生活类博客**、**技术类博客**、
|
||||
或者是 **产品文档**、**知识库**、**系列文档** 等，主题都可以满足您的需求。
|
||||
|
||||
主题针对 文本内容、图片内容 的表现做了大量的优化，特别是针对 Markdown 内容的语法 做了 丰富的扩展，
|
||||
你可以很轻松的利用这些特性编写 漂亮、美观、易读、表现力丰富 的内容。
|
||||
你可以很轻松的利用这些特性编写 美观、易读、表现力丰富 的内容。
|
||||
|
||||
::: details 不了解 VuePress ？
|
||||
|
||||
|
||||
@ -17,7 +17,7 @@ import VPBlogProfile from 'vuepress-theme-plume/components/Blog/VPBlogProfile.vu
|
||||
|
||||
主题默认启用 博客功能，通常您无需进行额外的配置。
|
||||
|
||||
主题默认会将 `{sourceDir}` 目录下的，除了特定的目录（如 `notes` 目录将作为笔记所在目录），
|
||||
主题默认会将 [文档源目录](./项目结构.md#文档源目录) 下的，除了特定的目录（如 `notes` 目录将作为笔记所在目录），
|
||||
所有 md 文件作为博客文章。
|
||||
|
||||
主题还会根据 md 文件 所在的 文件目录结构，以 **目录名** 作为 博客文章所属的 **分类**。
|
||||
|
||||
@ -18,6 +18,28 @@ const vuepressVersion = __VUEPRESS_VERSION__
|
||||
- [Node.js v18.20.0+](https://nodejs.org/)
|
||||
- [pnpm 8+](https://pnpm.io/zh/) 或 [Yarn 2+](https://yarnpkg.com/)
|
||||
|
||||
:::: details 怎么安装依赖环境？
|
||||
::: steps
|
||||
|
||||
1. **请前往 [Node.js 官网](https://nodejs.org/zh-cn) 下载最新稳定版本**
|
||||
|
||||
请根据指引完成安装，一般而言，在安装过程中，您只需要保持其默认设置，直接选择下一步即可。
|
||||
|
||||
2. **安装 PNPM**
|
||||
|
||||
在您安装完成 node.js 后，请打开 终端，执行如下命令：
|
||||
|
||||
```sh
|
||||
corepack enable
|
||||
```
|
||||
|
||||
主题推荐您使用 pnpm 作为项目管理器。
|
||||
|
||||
3. **完成**
|
||||
|
||||
:::
|
||||
::::
|
||||
|
||||
## 命令行安装
|
||||
|
||||
主题提供了一个 命令行工具，帮助您构建一个基本项目。您可以通过运行以下命令，启动 安装向导。
|
||||
@ -213,7 +235,7 @@ cd open-source # 进入 D: 分区下的 open-source 目录
|
||||
:::
|
||||
|
||||
:::warning
|
||||
无论是否需要使用 __多语言__ ，你都应该为 VuePress 配置 正确 `lang` 选项值。
|
||||
无论是否需要使用 **多语言** ，你都应该为 VuePress 配置 正确 `lang` 选项值。
|
||||
主题需要根据 `lang` 选项来确定语言环境文本。
|
||||
:::
|
||||
|
||||
@ -249,7 +271,7 @@ cd open-source # 进入 D: 分区下的 open-source 目录
|
||||
@tab npm
|
||||
|
||||
``` sh :no-line-numbers
|
||||
npm docs:run dev
|
||||
npm run docs:dev
|
||||
```
|
||||
|
||||
:::
|
||||
@ -259,37 +281,3 @@ cd open-source # 进入 D: 分区下的 open-source 目录
|
||||
- ### 完成
|
||||
|
||||
::::
|
||||
|
||||
## 文件结构
|
||||
|
||||
使用命令行工具创建的项目，它的文件结构是这样的。（如果你是手动创建的，也可以参考此文件结构管理您的项目）
|
||||
|
||||
::: 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` 文件会被识别为 文档笔记。
|
||||
|
||||
@ -1,6 +1,7 @@
|
||||
---
|
||||
title: 构建优化
|
||||
icon: clarity:bundle-solid
|
||||
outline: 2
|
||||
createTime: 2024/09/10 01:50:20
|
||||
permalink: /guide/optimize-build/
|
||||
---
|
||||
@ -63,7 +64,7 @@ export default defineUserConfig({
|
||||
同时并发请求其他图片资源。这在一定程度上能够改善构建时间。
|
||||
:::
|
||||
|
||||
::: details 还有其他方案吗？
|
||||
<!-- ::: details 还有其他方案吗？
|
||||
事实上有的，当前的方案其实是一个折中的方案。
|
||||
|
||||
我考虑过使用 [thumbhash](https://github.com/evanw/thumbhash) 为图片生成缩略图，通过 占位图 和 懒加载
|
||||
@ -72,4 +73,14 @@ export default defineUserConfig({
|
||||
然而这是有代价的，这需要使用的 [sharp](https://github.com/lovell/sharp) 或 [canvaskit](https://github.com/google/skia/tree/main/modules/canvaskit) 等图片处理库，对图片进行处理分析，
|
||||
再通过 [thumbhash](https://github.com/evanw/thumbhash) 生成大概 `20byte` 大小的缩略图。这需要花费更多的时间，
|
||||
这可能对于用户而言是不可接受的。
|
||||
:::
|
||||
::: -->
|
||||
|
||||
## 图标优化
|
||||
|
||||
得益于 开源项目 [iconify](https://icon-sets.iconify.design/) 的强大，您可以在主题内使用大约 20 万 个图标。
|
||||
|
||||
当然，这并不意味着主题需要加载全部的图标。您可能已经注意到，主题推荐您在本地安装 `@iconify/json` 包，这需要
|
||||
下载大约 __70Mb__ 的资源包，如果加载全部的图标到文档站点中，这太大太大了。
|
||||
|
||||
但请放心，主题仅会加载您有使用到的图标资源，这包括 导航栏、侧边栏、首页 Features 等配置中的 iconify 图标，
|
||||
以及通过语法糖 `:[collect:name]:` 和 组件 `<Icon name="icon_name" />` 等各种方式使用的图标。
|
||||
|
||||
@ -9,60 +9,38 @@ tags:
|
||||
- 快速开始
|
||||
---
|
||||
|
||||
::: info 提示
|
||||
以下内容中，以 `sourceDir` 表示 项目中用于保存 `Markdown` 文件的目录。
|
||||
VuePress 支持完整的 [Markdown 语法](./markdown/基础.md),
|
||||
以及使用 [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f)
|
||||
定义 frontmatter 页面元数据，例如 标题和创建时间。
|
||||
|
||||
如 `package.json`的`scripts` 中配置的 `vuepress dev docs`，则表示 `sourceDir` 为 `docs` 目录
|
||||
:::
|
||||
主题还对 Markdown 语法进行了 [扩展](./markdown/扩展.md) 和 [更多](./markdown/进阶.md) 支持。你还可以直接在
|
||||
Markdown 中写 HTML ，或者使用 Vue 组件。
|
||||
|
||||
## 约定
|
||||
## Frontmatter
|
||||
|
||||
使用本主题编写文章是一件很轻松的事情，你可以在 `sourceDir`目录中按照你的个人命名喜好新建任意名字的`Markdown`文件。
|
||||
你可以通过设置 frontmatter 中的值来自定义 VuePress 里每个页面。
|
||||
Frontmatter 是你的文件顶部在 `---` 中间的部分。
|
||||
|
||||
### 文件夹命名约定
|
||||
::: code-tabs
|
||||
@tab post.md
|
||||
|
||||
对于 `sourceDir` 中的文件夹命名，主题有一套简单的约定。
|
||||
```md
|
||||
---
|
||||
title: 文章标题
|
||||
createTime: 2024/09/08 22:53:34
|
||||
permalink: /article/9eh4d6ao/
|
||||
---
|
||||
|
||||
- 文件夹的名称将作为 `category` 即 __分类__。
|
||||
- 允许多级目录，子级目录将作为父目录对应的分类的子项。
|
||||
- 如果目录名称 在 [主题配置 notes](../config/notes配置.md) 中声明用于 notes 文章管理，则默认不作为 分类目录。
|
||||
|
||||
由于文件夹名称将作为分类名称，且不在主题配置中进行排序配置，对于有排序需要的场景，使用以下规则进行命名：
|
||||
|
||||
``` ts :no-line-numbers
|
||||
const dir = /\d+\.[\s\S]+/
|
||||
// 即 数字 + . + 分类名称
|
||||
// 如： 1.前端
|
||||
页面内容在第二个 `---` 后面。
|
||||
```
|
||||
|
||||
数字将作为 __排序__ 的依据。 如果不带数字，则以默认的规则进行排序。
|
||||
|
||||
__example:__
|
||||
|
||||
::: file-tree
|
||||
|
||||
- \{sourceDir\}
|
||||
- 1.前端
|
||||
- 1.html/
|
||||
- 2.css/
|
||||
- 3.javascript/
|
||||
- 2.后端/
|
||||
- 运维/
|
||||
:::
|
||||
|
||||
主题将根据 目录结构，生成一个 分类页。
|
||||
::: details 什么是 frontmatter？
|
||||
frontmatter 是一个 [YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f) 格式的配置内容，被放置于 markdown 文件的顶部，通过 `---` 来分隔。
|
||||
|
||||
### 文件命名约定
|
||||
|
||||
- __博客文章__
|
||||
|
||||
对于 __博客文章__ 的名称，主题没有任何约定，你可以任意命名。博客文章默认排序规则仅根据文件创建时间进行排序。
|
||||
你还可以通过 [frontmatter > sticky](../config/frontmatter/post.md#sticky) 配置文章是否置顶。
|
||||
|
||||
- __notes__
|
||||
|
||||
对于 __notes__ 中的 markdown 文件名称，依然遵循 与 [文件夹命名约定](#文件夹命名约定) 相同的规则。
|
||||
这可以为 notes 的 [自动生成侧边栏](../config/notes配置.md#自动生成侧边栏) 提供排序依据。
|
||||
您可以阅读 [这篇文章](../../../4.教程/frontmatter.md) 了解如何正确书写 frontmatter。
|
||||
:::
|
||||
|
||||
## 自动生成 Frontmatter
|
||||
|
||||
@ -132,9 +110,62 @@ export default defineUserConfig({
|
||||
})
|
||||
```
|
||||
|
||||
## 约定
|
||||
|
||||
::: info 提示
|
||||
以下内容，以 [项目结构](./项目结构.md) 中的文件结构作为基准。
|
||||
:::
|
||||
|
||||
使用本主题编写文章是一件很轻松的事情，你可以在 `docs`目录中按照你的个人命名喜好新建任意名字的`Markdown`文件。
|
||||
|
||||
### 文件夹命名约定
|
||||
|
||||
对于 `docs` 中的文件夹命名，主题有一套简单的约定。
|
||||
|
||||
- 文件夹的名称将作为 `category` 即 __分类__。
|
||||
- 允许多级目录，子级目录将作为父目录对应的分类的子项。
|
||||
- 如果目录名称 在 [主题配置 notes](../config/notes配置.md) 中声明用于 notes 文章管理，则默认不作为 分类目录。
|
||||
|
||||
由于文件夹名称将作为分类名称，且不在主题配置中进行排序配置，对于有排序需要的场景，使用以下规则进行命名：
|
||||
|
||||
``` ts :no-line-numbers
|
||||
const dir = /\d+\.[\s\S]+/
|
||||
// 即 数字 + . + 分类名称
|
||||
// 如： 1.前端
|
||||
```
|
||||
|
||||
数字将作为 __排序__ 的依据。 如果不带数字，则以默认的规则进行排序。
|
||||
|
||||
__example:__
|
||||
|
||||
::: file-tree
|
||||
|
||||
- docs
|
||||
- 1.前端
|
||||
- 1.html/
|
||||
- 2.css/
|
||||
- 3.javascript/
|
||||
- 2.后端/
|
||||
- 运维/
|
||||
:::
|
||||
|
||||
主题将根据 目录结构，生成一个 分类页。
|
||||
|
||||
### 文件命名约定
|
||||
|
||||
- __博客文章__
|
||||
|
||||
对于 __博客文章__ 的名称，主题没有任何约定，你可以任意命名。博客文章默认排序规则仅根据文件创建时间进行排序。
|
||||
你还可以通过 [frontmatter > sticky](../config/frontmatter/post.md#sticky) 配置文章是否置顶。
|
||||
|
||||
- __notes__
|
||||
|
||||
对于 __notes__ 中的 markdown 文件名称，依然遵循 与 [文件夹命名约定](#文件夹命名约定) 相同的规则。
|
||||
这可以为 notes 的 [自动生成侧边栏](../config/notes配置.md#自动生成侧边栏) 提供排序依据。
|
||||
|
||||
## 文章写作
|
||||
|
||||
你可以使用 `markdown` 语法开始在 `sourceDir` 下新建 `Markdown` 文件，编写你自己的文章了，
|
||||
你可以使用 `markdown` 语法开始在 `docs` 下新建 `Markdown` 文件，编写你自己的文章了，
|
||||
关于 markdown 扩展的功能支持，请查看 [这个文档](./markdown/扩展.md)
|
||||
|
||||
由于主题默认会为文章 的 `frontmatter` 自动生成一个 `title`，因此，文章内容的主体部分的标题，起始应该从 `h2` 即
|
||||
|
||||
@ -280,6 +280,9 @@ interface PlumeThemeHomeFeatures extends PlumeHomeConfigBase {
|
||||
}
|
||||
|
||||
interface PlumeThemeHomeFeature {
|
||||
/**
|
||||
* 图标，也支持传入 iconify 图标名
|
||||
*/
|
||||
icon?: FeatureIcon
|
||||
title: string
|
||||
details?: string
|
||||
|
||||
227
docs/notes/theme/guide/项目结构.md
Normal file
227
docs/notes/theme/guide/项目结构.md
Normal file
@ -0,0 +1,227 @@
|
||||
---
|
||||
title: 项目结构
|
||||
icon: ph:tree-structure-bold
|
||||
createTime: 2024/09/16 21:59:30
|
||||
permalink: /guide/project-structure/
|
||||
---
|
||||
|
||||
本指南将向您说明 VuePress 和 Plume 创建的项目的文件结构，以及如何在项目中使用它们。
|
||||
|
||||
当您 [使用命令行工具创建](./安装与使用.md#命令行安装) 的项目，它的文件结构是这样的：
|
||||
|
||||
::: file-tree
|
||||
|
||||
- .git/
|
||||
- **docs** \# 文档源目录
|
||||
- .vuepress \# vuepress 配置文件夹
|
||||
- public/ \# 静态资源目录
|
||||
- client.ts \# 客户端配置 (可选)
|
||||
- config.ts \# vuepress 配值
|
||||
- navbar.ts \# 导航栏配置 (可选)
|
||||
- notes.ts \# notes 配置 (可选)
|
||||
- plume.config.ts \# 主题配置文件 (可选)
|
||||
- notes \# 系列文档、知识笔记
|
||||
- demo
|
||||
- foo.md
|
||||
- bar.md
|
||||
- preview \# 博客分类之一
|
||||
- markdown.md \# 分类下的博客文章
|
||||
- article.md \# 博客文章
|
||||
- README.md \# 首页
|
||||
- …
|
||||
- package.json
|
||||
- pnpm-lock.yaml
|
||||
- .gitignore
|
||||
- README.md
|
||||
:::
|
||||
|
||||
::: tip 如果你是手动创建的，也可以参考此文件结构管理您的项目
|
||||
:::
|
||||
|
||||
## 文档源目录
|
||||
|
||||
**文档源目录** 指的是，你的站点的所有 markdown 文件所在的目录。该目录一般在使用 命令行工具 启动 VuePress
|
||||
时指定：
|
||||
|
||||
```sh
|
||||
# [!code word:docs]
|
||||
vuepress dev docs
|
||||
# 这里声明了文档源目录为 docs
|
||||
```
|
||||
|
||||
```json title="package.json"
|
||||
{
|
||||
"scripts": {
|
||||
"docs:dev": "vuepress dev docs",
|
||||
// ^^^^
|
||||
"docs:build": "vuepress build docs"
|
||||
// ^^^^
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
一般而言，VuePress 仅会接管 该目录，非源目录下的其它文件会被忽略。
|
||||
|
||||
## `.vuepress` 目录
|
||||
|
||||
`.vuepress/` 目录是 VuePress 配置文件夹，你还可以在这里创建 自己的组件、自定义主题样式等。
|
||||
|
||||
**在此目录中：**
|
||||
|
||||
### `client.ts`
|
||||
|
||||
客户端配置文件，你可以在这里扩展 VuePress 的功能，比如声明新的全局组件等。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/client.ts
|
||||
|
||||
```ts
|
||||
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 配置文件，你需要在这里进行一个必要的配置，比如 主题、插件、构建工具等。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts
|
||||
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 服务，然而实际上大多数时候都不需要这么做。
|
||||
|
||||
主题将不需要重启服务的配置移动到了这里。在这里修改配置时，仅通过热更新的方式更新主题。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/plume.config.ts
|
||||
|
||||
```ts
|
||||
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
|
||||
})
|
||||
```
|
||||
|
||||
@tab .vuepress/navbar.ts
|
||||
|
||||
```ts
|
||||
import { defineNavbarConfig } from 'vuepress-theme-plume'
|
||||
|
||||
export default defineNavbarConfig([
|
||||
// ...
|
||||
])
|
||||
```
|
||||
|
||||
@tab .vuepress/notes.ts
|
||||
|
||||
```ts
|
||||
import { defineNotesConfig } from 'vuepress-theme-plume'
|
||||
|
||||
export default defineNotesConfig({
|
||||
// ...
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## notes 目录
|
||||
|
||||
**notes** 目录用于存放你的 知识笔记、系列文档等。
|
||||
|
||||
### 如何理解知识笔记/系列文档 ？
|
||||
|
||||
一种很常见的场景是，您正在学习某项技能，并打算把学习心得、重点内容、疑难点等记录在笔记中，这一场景下，
|
||||
您可能会写多篇文档进行记录。
|
||||
|
||||
或者是，您正在准备面试，想要提前准备好 面试题目和答案，这时候可能会把 每个题目和答案都单独作为一篇文档。
|
||||
|
||||
你很容易就会希望把它们都单独放在一个目录下进行管理，与此同时，还希望在生成的文档站点中，能够快速的在
|
||||
这项技能笔记 的不同文档之间导航，或者在不同的面试题目之间导航。
|
||||
|
||||
这是博客类型的文档满足不了的诉求，而这恰恰是 `notes` 所要解决的一个痛点。
|
||||
|
||||
上述的内容，很容易产生以下目录结构：
|
||||
|
||||
::: file-tree
|
||||
|
||||
- notes
|
||||
- interview \# 面试题
|
||||
- 自我介绍.md
|
||||
- 我的技能.md
|
||||
- 做过的项目.md
|
||||
- …
|
||||
- typescript \# 学习笔记
|
||||
- 基础
|
||||
- 基本类型.md
|
||||
- 泛型.md
|
||||
- …
|
||||
- 进阶
|
||||
- 函数.md
|
||||
- …
|
||||
:::
|
||||
|
||||
这可以很方面的管理多个系列文档，每个系列文档都可以有自己的目录结构。
|
||||
|
||||
## 其它目录/文件
|
||||
|
||||
在 ==文档源目录== 中的 其它目录、文件，除了 `README.md` 被识别为 `主页` 之外，都会被识别为 博客文章。
|
||||
而 目录结构 则将被识别为 博客分类。
|
||||
|
||||
::: file-tree
|
||||
|
||||
- docs
|
||||
- 生活
|
||||
- 旅游日记.md
|
||||
- …
|
||||
- 学习
|
||||
- 考试笔记.md
|
||||
- …
|
||||
- 工作
|
||||
- 番茄时间.md
|
||||
- …
|
||||
- 杂事.md \# 无分类的文章
|
||||
- README.md \# 主页
|
||||
- …
|
||||
|
||||
:::
|
||||
Loading…
x
Reference in New Issue
Block a user