mirror of
https://github.com/pengzhanbo/vuepress-theme-plume.git
synced 2026-04-23 10:58:13 +08:00
docs: update blog and notes docs (#199)
This commit is contained in:
pengzhanbo
GitHub
parent
ef34b915b0
commit
1d7233d44c
@ -53,3 +53,45 @@ tags:
|
||||
- 默认值： `[]`
|
||||
|
||||
文章标签。
|
||||
|
||||
### cover
|
||||
|
||||
- 类型： `string \| BlogPostCover`
|
||||
- 默认值： `''`
|
||||
|
||||
文章封面图。 封面图仅显示在 文章列表页。
|
||||
|
||||
当传入为 `string` 时，表示 封面图链接地址。仅支持 绝对路径 以及 远程图片地址。
|
||||
|
||||
当传入为 `BlogPostCover` 时，表示 封面图配置。
|
||||
|
||||
```ts
|
||||
interface BlogPostCover {
|
||||
/**
|
||||
* 封面图链接地址，只能使用 绝对路径 以及 远程图片地址
|
||||
*/
|
||||
url: string
|
||||
/**
|
||||
* 博客文章封面图的位置
|
||||
*/
|
||||
layout?: 'left' | 'right' | 'odd-left' | 'odd-right' | 'top'
|
||||
/**
|
||||
* 博客文章封面图的比例
|
||||
*
|
||||
* @default '4:3'
|
||||
*/
|
||||
ratio?: number | `${number}:${number}`
|
||||
|
||||
/**
|
||||
* 封面图的宽度, 仅在 layout 为 'left' 或 'right' 时生效
|
||||
*
|
||||
* @default 240
|
||||
*/
|
||||
width?: number
|
||||
/**
|
||||
* 是否使用紧凑模式，紧凑模式下，封面图紧贴容器边缘
|
||||
* @default false
|
||||
*/
|
||||
compact?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
@ -79,8 +79,11 @@ interface BlogOptions {
|
||||
|
||||
/**
|
||||
* 分页配置
|
||||
*
|
||||
* - `false` - 不启用分页
|
||||
* - `number` - 每页显示的文章数量
|
||||
*/
|
||||
pagination?: false | {
|
||||
pagination?: false | number | {
|
||||
/**
|
||||
* 每页显示的文章数量
|
||||
* @default 10
|
||||
@ -104,6 +107,46 @@ interface BlogOptions {
|
||||
* @default true
|
||||
*/
|
||||
categories?: boolean
|
||||
|
||||
/**
|
||||
* 博客文章封面图
|
||||
*
|
||||
* 配置封面图的位置，支持 `'left'`、`'right'`、`'top'`、`'top-inside'`
|
||||
*
|
||||
* @default 'right'
|
||||
*/
|
||||
postCover?: BlogPostCoverLayout | Omit<BlogPostCover, 'url'>
|
||||
}
|
||||
|
||||
type BlogPostCoverLayout = 'left' | 'right' | 'odd-left' | 'odd-right' | 'top'
|
||||
|
||||
interface BlogPostCover {
|
||||
/**
|
||||
* 封面图链接地址，只能使用 绝对路径 以及 远程图片地址
|
||||
*/
|
||||
url: string
|
||||
/**
|
||||
* 博客文章封面图的位置
|
||||
*/
|
||||
layout?: BlogPostCoverLayout
|
||||
/**
|
||||
* 博客文章封面图的比例
|
||||
*
|
||||
* @default '4:3'
|
||||
*/
|
||||
ratio?: number | `${number}:${number}`
|
||||
|
||||
/**
|
||||
* 封面图的宽度, 仅在 layout 为 'left' 或 'right' 时生效
|
||||
*
|
||||
* @default 240
|
||||
*/
|
||||
width?: number
|
||||
/**
|
||||
* 是否使用紧凑模式，紧凑模式下，封面图紧贴容器边缘
|
||||
* @default false
|
||||
*/
|
||||
compact?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
@ -11,12 +11,11 @@ tags:
|
||||
|
||||
<script setup lang="ts">
|
||||
import VPBlogProfile from 'vuepress-theme-plume/components/Blog/VPBlogProfile.vue'
|
||||
import VPPostItem from 'vuepress-theme-plume/components/Blog/VPPostItem.vue'
|
||||
</script>
|
||||
|
||||
## 概述
|
||||
|
||||
主题默认启用 博客功能，通常您无需进行额外的配置。
|
||||
|
||||
主题默认会将 [文档源目录](./项目结构.md#文档源目录) 下的，除了特定的目录（如 `notes` 目录将作为笔记所在目录），
|
||||
所有 md 文件作为博客文章。
|
||||
|
||||
@ -25,10 +24,43 @@ import VPBlogProfile from 'vuepress-theme-plume/components/Blog/VPBlogProfile.vu
|
||||
主题默认会生成一个 链接地址为 `/blog/` 的 博客文章列表页。
|
||||
展示所有的博客文章，以及 博主的相关信息。
|
||||
|
||||
## 国际化支持
|
||||
## 配置
|
||||
|
||||
如果启用了 国际化，那么博客列表页将会 根据 不同的语言，展示对应语言目录下的博客列表。
|
||||
即 每个语言下的 文章列表 都是保持独立的。
|
||||
主题默认启用 博客功能，通常您无需进行额外的配置。
|
||||
|
||||
::: code-tabs
|
||||
@tab .vuepress/config.ts
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
// 禁用博客功能
|
||||
// blog: false,
|
||||
|
||||
blog: {
|
||||
/**
|
||||
* 通过 glob string 配置包含文件，
|
||||
* 默认读取 源目录中的所有 `.md` 文件，但会排除 `notes` 配置中用于笔记的目录。
|
||||
*/
|
||||
include: ['**/*.md'],
|
||||
// 如果希望只将源目录下某个目录下的文章读取为博客文章，比如 `blog` 目录，可以配置为：
|
||||
// include: ['blog/**/*.md'],
|
||||
|
||||
/**
|
||||
* 通过 glob string 配置排除的文件，相对于 源目录
|
||||
*/
|
||||
exclude: ['.vuepress/', '**/README.md'],
|
||||
|
||||
// 禁用分页
|
||||
// pagination: false,
|
||||
// 每页显示的文章数量
|
||||
pagination: 15,
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
## 博主信息
|
||||
|
||||
@ -96,6 +128,7 @@ tags:
|
||||
| tags | `string[]` | `[]` | 文章标签 |
|
||||
| sticky | `boolean \| number` | false | 是否置顶, 如果为数字，则数字越大，置顶越靠前 |
|
||||
| draft | `boolean` | false | 是否为草稿，草稿文章不会被展示 |
|
||||
| cover | `string` \| `BlogPostCover` | `''` | 文章封面 |
|
||||
|
||||
除了以上的字段，你还可以使用 [通用 frontmatter 配置](../config/frontmatter/basic.md) 中的字段，
|
||||
灵活的控制当前页面的行为。
|
||||
@ -104,7 +137,7 @@ tags:
|
||||
|
||||
如果你想要为文章添加摘要，你可以使用 `<!-- more -->` 注释来标记它。任何在此注释之前的内容会被视为摘要。
|
||||
|
||||
***示例：**
|
||||
**示例：**
|
||||
|
||||
```md
|
||||
---
|
||||
@ -118,6 +151,213 @@ title: 标题
|
||||
这里的内容不会被作为摘要
|
||||
```
|
||||
|
||||
## 文章封面图
|
||||
|
||||
在博客文章列表页，主题支持为 文章添加封面图，并支持不同的 排版 和 灵活的尺寸配置。
|
||||
|
||||
为博客文章添加 封面图，可以在 `frontmatter` 中配置 `cover`:
|
||||
|
||||
```md
|
||||
---
|
||||
title: 标题
|
||||
cover: /images/cover.jpg # [!code ++]
|
||||
---
|
||||
```
|
||||
|
||||
**封面图** 仅支持 绝对路径 或 远程路径。当使用 绝对路径时，从 `.vuepress/public` 目录中加载图片。
|
||||
|
||||
::: file-tree
|
||||
|
||||
- docs
|
||||
- .vuepress
|
||||
- public
|
||||
- images
|
||||
- cover.jpg
|
||||
- config.ts
|
||||
- article.md
|
||||
- …
|
||||
:::
|
||||
|
||||
默认效果如下：
|
||||
|
||||
<div style="background-color: var(--vp-c-bg-alt); padding: 20px 24px;transition: var(--t-color)">
|
||||
<VPPostItem
|
||||
:post="{ path: '/article/ecxnxxd0/', title: '文章标题',
|
||||
categoryList: [{id:'65f30c',sort:4,name:'教程'}], createTime: '2024/09/18 09:19:36',
|
||||
lang:'zh-CN', excerpt:'', cover: 'https://api.pengzhanbo.cn/wallpaper/bing' }"
|
||||
:index="1"
|
||||
/>
|
||||
</div>
|
||||
|
||||
还可以为 封面图 调整 布局位置，以及 尺寸比例：
|
||||
|
||||
```md
|
||||
---
|
||||
title: 文章标题
|
||||
cover: # [!code ++:5]
|
||||
url: /images/cover.jpg
|
||||
layout: left
|
||||
ratio: 16:9
|
||||
width: 300
|
||||
---
|
||||
```
|
||||
|
||||
效果如下:
|
||||
|
||||
<div style="background-color: var(--vp-c-bg-alt); padding: 20px 24px;transition: var(--t-color)">
|
||||
<VPPostItem
|
||||
:post="{ path: '/article/ecxnxxd0/', title: '文章标题',
|
||||
categoryList: [{id:'65f30c',sort:4,name:'教程'}], createTime: '2024/09/18 09:19:36',
|
||||
lang:'zh-CN', excerpt:'', cover: { url: 'https://api.pengzhanbo.cn/wallpaper/bing', layout: 'left', ratio: '16:9', width: 300 } }"
|
||||
:index="1"
|
||||
/>
|
||||
</div>
|
||||
|
||||
当文章没有摘要时，可能会显得比较空，为此你还可以通过 `compact: true` 使 封面图 贴合容器边缘，使整体变得更紧凑：
|
||||
|
||||
```md
|
||||
---
|
||||
title: 文章标题
|
||||
cover: # [!code ++:6]
|
||||
url: /images/cover.jpg
|
||||
layout: left
|
||||
ratio: 16:9
|
||||
width: 300
|
||||
compact: true
|
||||
---
|
||||
```
|
||||
|
||||
效果如下:
|
||||
|
||||
<div style="background-color: var(--vp-c-bg-alt); padding: 20px 24px;transition: var(--t-color)">
|
||||
<VPPostItem
|
||||
:post="{ path: '/article/ecxnxxd0/', title: '文章标题',
|
||||
categoryList: [{id:'65f30c',sort:4,name:'教程'}], createTime: '2024/09/18 09:19:36',
|
||||
lang:'zh-CN', excerpt:'',
|
||||
cover: { url: 'https://api.pengzhanbo.cn/wallpaper/bing', layout: 'left', ratio: '16:9', width: 300, compact: true } }"
|
||||
:index="1"
|
||||
/>
|
||||
</div>
|
||||
|
||||
::: warning compact: true 仅在文章没有摘要时生效
|
||||
:::
|
||||
|
||||
还可以设置 封面图在 标题上方，此时变为 大图风格：
|
||||
|
||||
```md
|
||||
---
|
||||
title: 文章标题
|
||||
cover: # [!code ++:5]
|
||||
url: /images/cover.jpg
|
||||
layout: top
|
||||
ratio: 16:9
|
||||
width: 300
|
||||
---
|
||||
```
|
||||
|
||||
效果如下:
|
||||
|
||||
<div style="background-color: var(--vp-c-bg-alt); padding: 20px 24px;transition: var(--t-color)">
|
||||
<VPPostItem
|
||||
:post="{ path: '/article/ecxnxxd0/', title: '文章标题',
|
||||
categoryList: [{id:'65f30c',sort:4,name:'教程'}], createTime: '2024/09/18 09:19:36',
|
||||
lang:'zh-CN', excerpt:'',
|
||||
cover: { url: 'https://api.pengzhanbo.cn/wallpaper/bing', layout: 'top', ratio: '16:9', width: 300 } }"
|
||||
:index="1"
|
||||
/>
|
||||
</div>
|
||||
|
||||
### 预设配置
|
||||
|
||||
虽然主题支持为每个文章的封面图使用不同的配置，出于整体布局风格的考虑，以及简化配置的目的，
|
||||
主题还支持为封面图预设配置：
|
||||
|
||||
```ts
|
||||
export default defineUserConfig({
|
||||
theme: plumeTheme({
|
||||
|
||||
blog: {
|
||||
// 配置 封面图 布局位置
|
||||
// postCover: 'left', // 'left' | 'right' | 'odd-left' | 'odd-right' | 'top'
|
||||
postCover: {
|
||||
layout: 'left',
|
||||
ratio: '16:9',
|
||||
width: 300,
|
||||
compact: true
|
||||
}
|
||||
}
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
```ts
|
||||
type BlogPostCoverLayout = 'left' | 'right' | 'odd-left' | 'odd-right' | 'top'
|
||||
|
||||
interface BlogPostCover {
|
||||
/**
|
||||
* 封面图链接地址，只能使用 绝对路径 以及 远程图片地址
|
||||
*/
|
||||
url: string
|
||||
/**
|
||||
* 博客文章封面图的位置
|
||||
*/
|
||||
layout?: BlogPostCoverLayout
|
||||
/**
|
||||
* 博客文章封面图的比例
|
||||
*
|
||||
* @default '4:3'
|
||||
*/
|
||||
ratio?: number | `${number}:${number}`
|
||||
|
||||
/**
|
||||
* 封面图的宽度, 仅在 layout 为 'left' 或 'right' 时生效
|
||||
*
|
||||
* @default 240
|
||||
*/
|
||||
width?: number
|
||||
/**
|
||||
* 是否使用紧凑模式，紧凑模式下，封面图紧贴容器边缘
|
||||
* @default false
|
||||
*/
|
||||
compact?: boolean
|
||||
}
|
||||
```
|
||||
|
||||
你可能已经注意到，在预设配置的 `layout` 中，还支持 `odd-left` 和 `odd-right` 两种配置。
|
||||
|
||||
- `odd-left`: 表示 单数项在左侧，偶数项在右侧
|
||||
- `odd-right`: 表示 单数项在右侧，偶数项在左侧
|
||||
|
||||
比如 `odd-left` 效果如下：
|
||||
|
||||
<div style="background-color: var(--vp-c-bg-alt); padding: 20px 24px;display: flex;flex-direction: column;gap: 24px;transition: var(--t-color)">
|
||||
<VPPostItem
|
||||
:post="{ path: '/article/ecxnxxd0/', title: '文章标题',
|
||||
categoryList: [{id:'65f30c',sort:4,name:'教程'}], createTime: '2024/09/18 09:19:36',
|
||||
lang:'zh-CN', excerpt:'',
|
||||
cover: { url: 'https://api.pengzhanbo.cn/wallpaper/bing', layout: 'odd-left', ratio: '16:9', width: 300, compact: true } }"
|
||||
:index="0"
|
||||
/>
|
||||
<VPPostItem
|
||||
:post="{ path: '/article/ecxnxxd0/', title: '文章标题',
|
||||
categoryList: [{id:'65f30c',sort:4,name:'教程'}], createTime: '2024/09/18 09:19:36',
|
||||
lang:'zh-CN', excerpt:'',
|
||||
cover: { url: 'https://api.pengzhanbo.cn/wallpaper/bing', layout: 'odd-left', ratio: '16:9', width: 300,compact: true } }"
|
||||
:index="1"
|
||||
/>
|
||||
<VPPostItem
|
||||
:post="{ path: '/article/ecxnxxd0/', title: '文章标题',
|
||||
categoryList: [{id:'65f30c',sort:4,name:'教程'}], createTime: '2024/09/18 09:19:36',
|
||||
lang:'zh-CN', excerpt:'',
|
||||
cover: { url: 'https://api.pengzhanbo.cn/wallpaper/bing', layout: 'odd-left', ratio: '16:9', width: 300, compact: true } }"
|
||||
:index="2"
|
||||
/>
|
||||
</div>
|
||||
|
||||
::: warning 注意
|
||||
当在 移动设备窄屏 上时，出于视觉效果考虑，`layout` 配置强制重置为 `top`。
|
||||
:::
|
||||
|
||||
## 标签页，分类页和归档页
|
||||
|
||||
主题除了自动生成 **博客文章列表页** 以外，还会自动生成 **标签页**，**分类页** 和 **归档页**。
|
||||
@ -128,6 +368,24 @@ title: 标题
|
||||
|
||||
归档页根据文章的创建时间进行归, 默认地址为 `/blog/archives/`
|
||||
|
||||
## 国际化支持
|
||||
|
||||
如果启用了 国际化，那么博客列表页将会 根据 不同的语言，展示对应语言目录下的博客列表。
|
||||
即 每个语言下的 文章列表 都是保持独立的。
|
||||
|
||||
特别的，如果您的 一篇博客文章 拥有不同的语言版本，请保持在 不同的语言目录下，都有相同的
|
||||
目录文件结构和文件名。当切换语言时，主题能够正确的切换到对应语言的文章。
|
||||
|
||||
::: file-tree
|
||||
|
||||
- docs
|
||||
- en
|
||||
- my-article.md
|
||||
- fr
|
||||
- my-article.md
|
||||
- my-article.md
|
||||
:::
|
||||
|
||||
## 设置博客为主页
|
||||
|
||||
默认情况下，主题 将 **首页** 与 **博客页** 分离。
|
||||
|
||||
@ -222,6 +222,64 @@ const sidebar: Sidebar = [
|
||||
]
|
||||
```
|
||||
|
||||
### 关于 `prefix`
|
||||
|
||||
`prefix` 的目的是为了简写与其同层级的 `items` 项内的 链接，它允许你将这些链接的相同的前缀提取到
|
||||
`prefix` 中，由主题帮您完成完整链接的拼接。
|
||||
|
||||
需要注意的是，`items` 中的链接 仅有 相对路径的链接才会与 `prefix` 拼接，而绝对路径则不进行处理。
|
||||
|
||||
```ts
|
||||
const sidebar: Sidebar = [
|
||||
{
|
||||
prefix: '/guide',
|
||||
items: [
|
||||
'intro', // 相对路径, 最终拼接为 /guide/intro
|
||||
'/config/config-file', // 绝对路径，不拼接
|
||||
{
|
||||
text: '博客',
|
||||
link: 'blog', // 相对路径, 最终拼接为 /guide/blog
|
||||
},
|
||||
{
|
||||
text: '配置',
|
||||
link: '/config', // 绝对路径，不拼接
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
同时，`items` 内还支持 深层嵌套，内部还依然支持 `prefix`，这里也遵循相同的规则，`prefix` 如果是相对路径，
|
||||
则会与 上一层的 `prefix` 拼接，再与 当前层级 `items` 内的 `link` 拼接，如果 `prefix` 是绝对路径，则不与
|
||||
上一层级 `prefix` 拼接。
|
||||
|
||||
```ts
|
||||
const sidebar: sidebar = [
|
||||
{
|
||||
prefix: '/guide',
|
||||
items: [
|
||||
'intro', // 相对路径, 最终拼接为 /guide/intro
|
||||
{
|
||||
prefix: '/config',
|
||||
items: [
|
||||
'config-file', // 相对路径, 最终拼接为 /config/config-file
|
||||
'configuration', // 相对路径, 最终拼接为 /config/configuration
|
||||
]
|
||||
},
|
||||
{
|
||||
prefix: 'blog',
|
||||
items: [
|
||||
'intro', // 相对路径, 最终拼接为 /guide/blog/intro
|
||||
'getting-start', // 相对路径, 最终拼接为 /guide/blog/getting-start
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**是否是绝对路径的判断标准是，如果以 `/` 开头，则为绝对路径，否则为相对路径**
|
||||
|
||||
:::warning
|
||||
不建议 侧边栏的层级过深，超过 3 层的侧边栏 可能会导致 糟糕的 UI 效果。
|
||||
:::
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user