diff --git a/docs/.vuepress/client.ts b/docs/.vuepress/client.ts index 71f2aeba..d95666c8 100644 --- a/docs/.vuepress/client.ts +++ b/docs/.vuepress/client.ts @@ -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 +}) diff --git a/docs/.vuepress/notes/zh/theme-guide.ts b/docs/.vuepress/notes/zh/theme-guide.ts index f87b55c3..4c86d5e0 100644 --- a/docs/.vuepress/notes/zh/theme-guide.ts +++ b/docs/.vuepress/notes/zh/theme-guide.ts @@ -5,15 +5,16 @@ export const themeGuide = defineNoteConfig({ link: '/guide/', sidebar: [ { - text: '快速开始', + text: '从这里开始', collapsed: false, icon: 'carbon:idea', items: [ '介绍', '安装与使用', + '项目结构', + '编写文章', '博客', '知识笔记', - '编写文章', '国际化', '部署', '构建优化', diff --git a/docs/4.教程/frontmatter.md b/docs/4.教程/frontmatter.md new file mode 100644 index 00000000..8f15c1ad --- /dev/null +++ b/docs/4.教程/frontmatter.md @@ -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。 + +如果您具有良好的英语阅读基础，为避免翻译可能存在的内容失真，建议您阅读原文。 + +原文地址： 。 +::: + +## 介绍 + +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 +} +``` diff --git a/docs/README.md b/docs/README.md index ba6300ed..176cc0e9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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
你可以自由选择符合你的需求的评论系统。 - 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
视频：Bilibili/Youtube
PDF，200K+ Iconify 图标 - type: text-image title: 博客 @@ -94,8 +94,8 @@ config: title: 博主信息 description: 自定义名称、座右铭、头像，社交媒体链接。 - - title: 标签、归档 - description: 自动生成标签页，为文章根据年份进行归档。 + title: 分类、标签、归档 + description: 自动生成分类页、标签页，为文章根据年份进行归档。 - type: image-text title: 文档 diff --git a/docs/notes/theme/guide/介绍.md b/docs/notes/theme/guide/介绍.md index 7e68f774..de1fa023 100644 --- a/docs/notes/theme/guide/介绍.md +++ b/docs/notes/theme/guide/介绍.md @@ -9,10 +9,11 @@ tags: - 快速开始 --- -==vuepress-theme-plume== 是一个基于 VuePress 的主题，适用于 博客、文档 和 知识笔记 。 +==vuepress-theme-plume== 是一个基于 VuePress 的主题，无论您是想写 **生活类博客**、**技术类博客**、 +或者是 **产品文档**、**知识库**、**系列文档** 等，主题都可以满足您的需求。 主题针对 文本内容、图片内容 的表现做了大量的优化，特别是针对 Markdown 内容的语法 做了 丰富的扩展， -你可以很轻松的利用这些特性编写 漂亮、美观、易读、表现力丰富 的内容。 +你可以很轻松的利用这些特性编写 美观、易读、表现力丰富 的内容。 ::: details 不了解 VuePress ？ diff --git a/docs/notes/theme/guide/博客.md b/docs/notes/theme/guide/博客.md index 46e6c8e2..07c52047 100644 --- a/docs/notes/theme/guide/博客.md +++ b/docs/notes/theme/guide/博客.md @@ -17,7 +17,7 @@ import VPBlogProfile from 'vuepress-theme-plume/components/Blog/VPBlogProfile.vu 主题默认启用 博客功能，通常您无需进行额外的配置。 -主题默认会将 `{sourceDir}` 目录下的，除了特定的目录（如 `notes` 目录将作为笔记所在目录）， +主题默认会将 [文档源目录](./项目结构.md#文档源目录) 下的，除了特定的目录（如 `notes` 目录将作为笔记所在目录）， 所有 md 文件作为博客文章。 主题还会根据 md 文件 所在的 文件目录结构，以 **目录名** 作为 博客文章所属的 **分类**。 diff --git a/docs/notes/theme/guide/安装与使用.md b/docs/notes/theme/guide/安装与使用.md index bb2dd9be..066af1b2 100644 --- a/docs/notes/theme/guide/安装与使用.md +++ b/docs/notes/theme/guide/安装与使用.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` 文件会被识别为 文档笔记。 diff --git a/docs/notes/theme/guide/构建优化.md b/docs/notes/theme/guide/构建优化.md index e5185cd0..cb38b7ca 100644 --- a/docs/notes/theme/guide/构建优化.md +++ b/docs/notes/theme/guide/构建优化.md @@ -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 还有其他方案吗？ + + +## 图标优化 + +得益于 开源项目 [iconify](https://icon-sets.iconify.design/) 的强大，您可以在主题内使用大约 20 万 个图标。 + +当然，这并不意味着主题需要加载全部的图标。您可能已经注意到，主题推荐您在本地安装 `@iconify/json` 包，这需要 +下载大约 __70Mb__ 的资源包，如果加载全部的图标到文档站点中，这太大太大了。 + +但请放心，主题仅会加载您有使用到的图标资源，这包括 导航栏、侧边栏、首页 Features 等配置中的 iconify 图标， +以及通过语法糖 `:[collect:name]:` 和 组件 `` 等各种方式使用的图标。 diff --git a/docs/notes/theme/guide/编写文章.md b/docs/notes/theme/guide/编写文章.md index 910091c6..b968f847 100644 --- a/docs/notes/theme/guide/编写文章.md +++ b/docs/notes/theme/guide/编写文章.md @@ -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` 即 diff --git a/docs/notes/theme/guide/自定义首页.md b/docs/notes/theme/guide/自定义首页.md index 0cb4a140..047ebf94 100644 --- a/docs/notes/theme/guide/自定义首页.md +++ b/docs/notes/theme/guide/自定义首页.md @@ -280,6 +280,9 @@ interface PlumeThemeHomeFeatures extends PlumeHomeConfigBase { } interface PlumeThemeHomeFeature { + /** + * 图标，也支持传入 iconify 图标名 + */ icon?: FeatureIcon title: string details?: string diff --git a/docs/notes/theme/guide/项目结构.md b/docs/notes/theme/guide/项目结构.md new file mode 100644 index 00000000..e11729f4 --- /dev/null +++ b/docs/notes/theme/guide/项目结构.md @@ -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 \# 主页 + - … + +:::