docs: update docs
This commit is contained in:
pengzhanbo
parent
29326ec381
commit
bf9ef6372a
@ -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 中支持选项卡。
|
||||
|
||||
@ -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) 帮助完善主题。
|
||||
|
||||
:::
|
||||
|
||||
@ -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 配置
|
||||
|
||||
|
||||
@ -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
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
启动向导后，您只需要回答几个简单的问题：
|
||||
|
||||
<!-- @include: ../snippet/create.snippet.md ---->
|
||||
|
||||
::: 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` 文件会被识别为 文档笔记。
|
||||
|
||||
@ -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 文件。
|
||||
|
||||
|
||||
@ -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.后端/
|
||||
- 运维/
|
||||
:::
|
||||
|
||||
## 文章写作
|
||||
|
||||
|
||||
@ -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
|
||||
|
||||
42
docs/notes/theme/snippet/create.snippet.md
Normal file
42
docs/notes/theme/snippet/create.snippet.md
Normal file
@ -0,0 +1,42 @@
|
||||
```ansi :no-line-numbers :collapsed-lines
|
||||
[0;90m┌[0m [0;36;1mWelcome to VuePress and vuepress-theme-plume ![0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m Select a language to display / 选择显示语言[0m
|
||||
[0;90m│[0m[0m [0;2m简体中文[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 您想在哪里初始化 VuePress？[0m
|
||||
[0;90m│[0m[0m [0;2m./my-project[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 站点名称：[0m
|
||||
[0;90m│[0m[0m [0;2mMy Vuepress Site[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 站点描述信息：[0m
|
||||
[0;90m│[0m[0m [0;2mMy Vuepress Site Description[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 是否使用多语言？[0m
|
||||
[0;90m│[0m[0m [0;2mNo[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 请选择站点默认语言[0m
|
||||
[0;90m│[0m[0m [0;2m简体中文[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 是否使用 TypeScript？[0m
|
||||
[0;90m│[0m[0m [0;2mYes[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 请选择打包工具[0m
|
||||
[0;90m│[0m[0m [0;2mVite[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 部署方式：[0m
|
||||
[0;90m│[0m[0m [0;2mCustom[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 是否初始化 git 仓库？[0m
|
||||
[0;90m│[0m[0m [0;2mYes[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 是否安装依赖？[0m
|
||||
[0;90m│[0m[0m [0;2mYes[0m[0m
|
||||
[0;90m│[0m[0m
|
||||
[0;32m◇[0m 🎉 创建成功![0m
|
||||
[0;90m│[0m[0m
|
||||
[0;90m└[0m[0m 🔨 执行以下命令即可启动：[0m
|
||||
[0;32mcd ./my-project[0m
|
||||
[0;32mpnpm run docs:dev[0m
|
||||
```
|
||||
@ -30,3 +30,4 @@ readingTime: false
|
||||
| ---- | ---------- | ------ | ------------------ |
|
||||
| **锋 | 2024-04-18 | 6.88 | 支持下作者，加油！ |
|
||||
| *杰 | 2024-05-25 | 6.00 | 请你喝杯茶，加油 |
|
||||
| **党 | 2024-08-22 | 8.80 | 感谢开源，加油 |
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user