From bf9ef6372a7c1ffa8a378b81e60ed05cf2623caa Mon Sep 17 00:00:00 2001 From: pengzhanbo Date: Mon, 2 Sep 2024 00:03:15 +0800 Subject: [PATCH] docs: update docs --- docs/notes/theme/guide/markdown/进阶.md | 67 +++++++++++++++ docs/notes/theme/guide/介绍.md | 55 ++++++++----- docs/notes/theme/guide/国际化.md | 17 ++-- docs/notes/theme/guide/安装与使用.md | 94 ++++++++++++++++++++-- docs/notes/theme/guide/知识笔记.md | 18 +++-- docs/notes/theme/guide/编写文章.md | 19 ++--- docs/notes/theme/guide/部署.md | 5 +- docs/notes/theme/snippet/create.snippet.md | 42 ++++++++++ docs/sponsor.md | 1 + 9 files changed, 263 insertions(+), 55 deletions(-) create mode 100644 docs/notes/theme/snippet/create.snippet.md diff --git a/docs/notes/theme/guide/markdown/进阶.md b/docs/notes/theme/guide/markdown/进阶.md index 766bacc1..6a5b30b8 100644 --- a/docs/notes/theme/guide/markdown/进阶.md +++ b/docs/notes/theme/guide/markdown/进阶.md @@ -166,6 +166,73 @@ tags: 4. 结束 :::: +## 文件树 + +在 Markdown 中，你可以使用 `file-tree` 容器 来显示带有文件图标和可折叠子目录的目录结构。 + +在 `::: file-tree` 容器，使用内置的 **Markdown 无序列表语法** 指定文件和目录的组织结构。 +使用嵌套的列表项创建子目录；若希望某个目录不显示具体内容，只需在列表项末尾添加斜杠 `/` 即可。 + +以下语法可用于自定义文件树的外观： + +- 通过加粗文件名或目录名来突出显示，例如 `**README.md**` +- 通过在名称后添加更多文本来为文件或目录添加注释 +- 使用 `...` 或 `…` 作为名称来添加占位符文件和目录。 + +**输入：** + +```md +::: file-tree + +- docs + - .vuepress + - config.ts + - page1.md + - README.md +- theme 一个 **主题** 目录 + - client + - components + - **Navbar.vue** + - composables + - useNavbar.ts + - styles + - navbar.css + - config.ts + - node/ +- package.json +- pnpm-lock.yaml +- .gitignore +- README.md +- … +::: +``` + +**输出：** + +::: file-tree + +- docs + - .vuepress + - config.ts + - page1.md + - README.md +- theme 一个 **主题** 目录 + - client + - components + - **Navbar.vue** + - composables + - useNavbar.ts + - styles + - navbar.css + - config.ts + - node/ +- package.json +- pnpm-lock.yaml +- .gitignore +- README.md +- … +::: + ## 选项组 在 Markdown 中支持选项卡。 diff --git a/docs/notes/theme/guide/介绍.md b/docs/notes/theme/guide/介绍.md index 01c99b04..e9b5585b 100644 --- a/docs/notes/theme/guide/介绍.md +++ b/docs/notes/theme/guide/介绍.md @@ -9,36 +9,39 @@ tags: - 快速开始 --- -## 介绍 - ==vuepress-theme-plume== 是一个基于 VuePress 的主题，适用于 博客、文档 和 知识笔记 。 +主题针对 文本内容、图片内容 的表现做了大量的优化，特别是针对 Markdown 内容的语法 做了 丰富的扩展， +你可以很轻松的利用这些特性编写 漂亮、美观、易读、表现力丰富 的内容。 + +::: details 不了解 VuePress ？ + VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) 。 专为构建快速、以内容为中心的站点而设计。 简而言之，VuePress 获取用 Markdown 编写的内容，对其应用主题，并生成可以轻松部署到任何地方的静态 HTML 页面。 - -::: tip - -本主题 基于 [vuepress-next](https://github.com/vuepress/vuepress-next), 目前处于 RC 阶段。 - -当前主题 功能和 API 趋于稳定，但在未来的更新中仍有小概率出现破坏更改。 - -如果您在使用过程中遇到问题，或者有新的想法， -请在 [Issues](https://github.com/pengzhanbo/vuepress-theme-plume/issues) 里提出， -也欢迎 通过 [PR](https://github.com/pengzhanbo/vuepress-theme-plume/pulls) 帮助完善主题。 - ::: ## 优势 与 vuepress 默认主题相比： -- 大幅度优化了界面、交互，更具美观度，更好的用户体验。 -- 同时，还添加了大量的丰富实用的功能，如 代码分组、提示容器、任务列表、数学公式、代码演示、 -内容搜索、文章评论、加密 等。 -- 新增编译缓存，加快启动速度。 -- 支持使用单独的主题配置文件，避免修改配置导致频繁重启 VuePress 服务。 -- 大幅度简化了配置，更易于使用，同时还保留了丰富灵活的配置项，满足个性化的需求。 +- **更好的用户体验** + + 大幅度优化了界面、交互，更为美观、简洁，易用。 + +- **更多的功能** + + 代码分组、提示容器、任务列表、数学公式、代码演示、内容搜索、文章评论、加密、文件树 等。 + +- **更好的开发体验** + + 增加编译缓存，缓存 markdown 文件编译、缓存 复杂 代码块 内容解析结果。 + +- **更好的配置** + + 支持使用单独的主题配置文件，避免修改配置导致频繁重启 VuePress 服务。 + + 大幅度简化了配置，更易于使用，同时还保留了丰富灵活的配置项，满足个性化的需求。 ==plume 主题== 尽可能的内置你可能需要的功能，以及搭建站点所需要的一般性配置，您无需关注这些细节。 目的是，让您更专注于 内容的创作，更好的表达你的想法，享受 Markdown 增强语法带来的便利。 @@ -52,7 +55,19 @@ VuePress 是一个 [静态站点生成器](https://en.wikipedia.org/wiki/Static_ - 🔑 支持 全站加密、部分加密 - 👀 支持 搜索、文章评论 - 👨‍💻‍ 支持 浅色/深色 主题 （包括代码高亮） -- 📠 markdown 增强，支持 代码块分组、提示容器、任务列表、数学公式、代码演示 等 +- 📠 markdown 增强，支持 代码块分组、提示容器、任务列表、数学公式、代码演示、文件树 等 - 📚 代码演示，支持 CodePen, Replit, JSFiddle, CodeSandbox - 📊 嵌入图标，支持 chart.js，Echarts，Mermaid，flowchart 等 - 🎛 资源嵌入，支持 PDF, bilibili视频，youtube视频等 + +::: tip + +本主题 基于 [vuepress-next](https://github.com/vuepress/vuepress-next), 目前处于 RC 阶段。 + +当前主题 功能和 API 趋于稳定，但在未来的更新中仍有小概率出现破坏更改。 + +如果您在使用过程中遇到问题，或者有新的想法， +请在 [Issues](https://github.com/pengzhanbo/vuepress-theme-plume/issues) 里提出， +也欢迎 通过 [PR](https://github.com/pengzhanbo/vuepress-theme-plume/pulls) 帮助完善主题。 + +::: diff --git a/docs/notes/theme/guide/国际化.md b/docs/notes/theme/guide/国际化.md index 6992c0cd..2c70d03b 100644 --- a/docs/notes/theme/guide/国际化.md +++ b/docs/notes/theme/guide/国际化.md @@ -13,14 +13,15 @@ tags: 要使用内置的 i18n (国际化) 功能，需要创建类似于下面的目录结构： -``` -docs/ -├─ es/ -│ ├─ foo.md -├─ fr/ -│ ├─ foo.md -├─ foo.md -``` +::: file-tree + +- docs + - en + - foo.md + - fr + - foo.md + - foo.md +::: ## vuepress 配置 diff --git a/docs/notes/theme/guide/安装与使用.md b/docs/notes/theme/guide/安装与使用.md index 7ac4ba46..7056aeaf 100644 --- a/docs/notes/theme/guide/安装与使用.md +++ b/docs/notes/theme/guide/安装与使用.md @@ -18,14 +18,63 @@ const vuepressVersion = __VUEPRESS_VERSION__ - [Node.js v18.20.0+](https://nodejs.org/) - [pnpm 8+](https://pnpm.io/zh/) 或 [Yarn 2+](https://yarnpkg.com/) +## 命令行安装 + +主题提供了一个 命令行工具，帮助您构建一个基本项目。您可以通过运行以下命令，启动 安装向导。 + +::: code-tabs + +@tab pnpm + +```sh +pnpm create vuepress-theme-plume@latest +``` + +@tab yarn + +```sh +yarn create vuepress-theme-plume@latest +``` + +@tab npm + +```sh +npm init vuepress-theme-plume@latest +``` + +::: + +启动向导后，您只需要回答几个简单的问题： + + + +::: details 怎么使用命令行工具？ + +以 Windows 系统为例，你可以使用以下方法来启动 CMD 命令行工具： + +1. 按下 `Win + R` 键打开 “运行” 对话框。 +2. 输入 `cmd` 并按下 Enter 键。 （也可以输入 `powershell` 来打开 PowerShell） + +注意此时 `cmd` 可能不在你期望的目录位置，你可以使用如下命令来切换到正确的目录： + +```sh +D: # 此命令将切换到 D: 分区，进入其他分区请按照实际情况修改 +cd open-source # 进入 D: 分区下的 open-source 目录 +``` + +此时，你就可以在这里输入 `pnpm create vuepress-theme-plume@latest` 来创建一个基本的项目了。 + +创建的项目将位于 `D:\open-source\my-project` 目录下。 +::: + +## 手动安装 + ::: info 提示 - 使用 [pnpm](https://pnpm.io/zh/) 时，你需要安装 `vue` 作为 peer-dependencies 。 - 使用 [Yarn 2+](https://yarnpkg.com/) 时，你需要在 `.yarnrc.yml` 文件中设置 `nodeLinker: 'node-modules'` 。 ::: -## 安装 - 使用本主题，你需要首先新建一个项目，并安装`vuepress@next`以及本主题 :::: steps @@ -110,8 +159,8 @@ const vuepressVersion = __VUEPRESS_VERSION__ ``` json :no-line-numbers { "scripts": { - "dev": "vuepress dev docs", - "build": "vuepress build docs" + "docs:dev": "vuepress dev docs", + "docs:build": "vuepress build docs" } } ``` @@ -188,19 +237,19 @@ const vuepressVersion = __VUEPRESS_VERSION__ @tab pnpm ```sh :no-line-numbers - pnpm dev + pnpm docs:dev ``` @tab yarn ``` sh :no-line-numbers - yarn dev + yarn docs:dev ``` @tab npm ``` sh :no-line-numbers - npm run dev + npm docs:run dev ``` ::: @@ -210,3 +259,34 @@ const vuepressVersion = __VUEPRESS_VERSION__ - ### 完成 :::: + +## 文件结构 + +使用命令行工具创建的项目，它的文件结构是这样的。（如果你是手动创建的，也可以参考此文件结构管理您的项目） + +::: 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 +- package-lock.json +- .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 1c845026..8a68fd73 100644 --- a/docs/notes/theme/guide/知识笔记.md +++ b/docs/notes/theme/guide/知识笔记.md @@ -22,14 +22,16 @@ tags: 示例： -``` :no-line-numbers -{sourceDir}/ -├─ notes/ -│ ├─ typescript/ -│ │ └─ foo.md -│ └─ rust/ -│ └─ foo.md -``` +::: file-tree + +- \{sourceDir\} + - notes + - typescript + - foo.md + - rust + - foo.md + +::: 其中，`typescript` 和 `rust` 为目录名，各自独立保存与之相关的 markdown 文件。 diff --git a/docs/notes/theme/guide/编写文章.md b/docs/notes/theme/guide/编写文章.md index b33e6ce4..0c81521f 100644 --- a/docs/notes/theme/guide/编写文章.md +++ b/docs/notes/theme/guide/编写文章.md @@ -40,15 +40,16 @@ const dir = /\d+\.[\s\S]+/ __example:__ -``` txt :no-line-numbers - .{sourceDir} - - 1.前端 - - 1.html - - 2.css - - 3.javascript - - 2.后端 - - 运维 -``` +::: file-tree + +- \{sourceDir\} + - 1.前端/ + - 1.html/ + - 2.css/ + - 3.javascript/ + - 2.后端/ + - 运维/ +::: ## 文章写作 diff --git a/docs/notes/theme/guide/部署.md b/docs/notes/theme/guide/部署.md index 52cd3d8c..0ab84ba2 100644 --- a/docs/notes/theme/guide/部署.md +++ b/docs/notes/theme/guide/部署.md @@ -10,8 +10,7 @@ tags: --- ::: tip -此文档 fork 自 [vuepress official doc](https://v2.vuepress.vuejs.org/zh/guide/deployment.html)， -仅为了方便阅读。 +此文档 fork 自 [vuepress official doc](https://v2.vuepress.vuejs.org/zh/guide/deployment.html)。 ::: 下述的指南基于以下条件： @@ -64,7 +63,7 @@ jobs: fetch-depth: 0 - name: Setup pnpm - uses: pnpm/action-setup@v2 + uses: pnpm/action-setup@v4 with: # 选择要使用的 pnpm 版本 version: 8 diff --git a/docs/notes/theme/snippet/create.snippet.md b/docs/notes/theme/snippet/create.snippet.md new file mode 100644 index 00000000..9cfe10b0 --- /dev/null +++ b/docs/notes/theme/snippet/create.snippet.md @@ -0,0 +1,42 @@ +```ansi :no-line-numbers :collapsed-lines +┌ Welcome to VuePress and vuepress-theme-plume ! +│ +◇ Select a language to display / 选择显示语言 +│ 简体中文 +│ +◇ 您想在哪里初始化 VuePress？ +│ ./my-project +│ +◇ 站点名称： +│ My Vuepress Site +│ +◇ 站点描述信息： +│ My Vuepress Site Description +│ +◇ 是否使用多语言？ +│ No +│ +◇ 请选择站点默认语言 +│ 简体中文 +│ +◇ 是否使用 TypeScript？ +│ Yes +│ +◇ 请选择打包工具 +│ Vite +│ +◇ 部署方式： +│ Custom +│ +◇ 是否初始化 git 仓库？ +│ Yes +│ +◇ 是否安装依赖？ +│ Yes +│ +◇ 🎉 创建成功! +│ +└ 🔨 执行以下命令即可启动： + cd ./my-project + pnpm run docs:dev +``` diff --git a/docs/sponsor.md b/docs/sponsor.md index d0d3ce78..f16059b8 100644 --- a/docs/sponsor.md +++ b/docs/sponsor.md @@ -30,3 +30,4 @@ readingTime: false | ---- | ---------- | ------ | ------------------ | | **锋 | 2024-04-18 | 6.88 | 支持下作者，加油！ | | *杰 | 2024-05-25 | 6.00 | 请你喝杯茶，加油 | +| **党 | 2024-08-22 | 8.80 | 感谢开源，加油 |