diff --git a/docs/notes/theme/config/frontmatter/post.md b/docs/notes/theme/config/frontmatter/post.md index c6ef64fb..ac7ec15e 100644 --- a/docs/notes/theme/config/frontmatter/post.md +++ b/docs/notes/theme/config/frontmatter/post.md @@ -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 +} +``` diff --git "a/docs/notes/theme/config/\344\270\273\351\242\230\351\205\215\347\275\256.md" "b/docs/notes/theme/config/\344\270\273\351\242\230\351\205\215\347\275\256.md" index 72ac01fb..d942608d 100644 --- "a/docs/notes/theme/config/\344\270\273\351\242\230\351\205\215\347\275\256.md" +++ "b/docs/notes/theme/config/\344\270\273\351\242\230\351\205\215\347\275\256.md" @@ -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 +} + +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 } ``` diff --git "a/docs/notes/theme/guide/\345\215\232\345\256\242.md" "b/docs/notes/theme/guide/\345\215\232\345\256\242.md" index 07c52047..f14a7066 100644 --- "a/docs/notes/theme/guide/\345\215\232\345\256\242.md" +++ "b/docs/notes/theme/guide/\345\215\232\345\256\242.md" @@ -11,12 +11,11 @@ tags: ## 概述 -主题默认启用 博客功能，通常您无需进行额外的配置。 - 主题默认会将 [文档源目录](./项目结构.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: 如果你想要为文章添加摘要，你可以使用 `` 注释来标记它。任何在此注释之前的内容会被视为摘要。 -***示例：** +**示例：** ```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 +- … +::: + +默认效果如下： + +
+ +
+ +还可以为 封面图 调整 布局位置，以及 尺寸比例： + +```md +--- +title: 文章标题 +cover: # [!code ++:5] + url: /images/cover.jpg + layout: left + ratio: 16:9 + width: 300 +--- +``` + +效果如下: + +
+ +
+ +当文章没有摘要时，可能会显得比较空，为此你还可以通过 `compact: true` 使 封面图 贴合容器边缘，使整体变得更紧凑： + +```md +--- +title: 文章标题 +cover: # [!code ++:6] + url: /images/cover.jpg + layout: left + ratio: 16:9 + width: 300 + compact: true +--- +``` + +效果如下: + +
+ +
+ +::: warning compact: true 仅在文章没有摘要时生效 +::: + +还可以设置 封面图在 标题上方，此时变为 大图风格： + +```md +--- +title: 文章标题 +cover: # [!code ++:5] + url: /images/cover.jpg + layout: top + ratio: 16:9 + width: 300 +--- +``` + +效果如下: + +
+ +
+ +### 预设配置 + +虽然主题支持为每个文章的封面图使用不同的配置，出于整体布局风格的考虑，以及简化配置的目的， +主题还支持为封面图预设配置： + +```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` 效果如下： + +
+ + + +
+ +::: warning 注意 +当在 移动设备窄屏 上时，出于视觉效果考虑，`layout` 配置强制重置为 `top`。 +::: + ## 标签页，分类页和归档页 主题除了自动生成 **博客文章列表页** 以外，还会自动生成 **标签页**，**分类页** 和 **归档页**。 @@ -128,6 +368,24 @@ title: 标题 归档页根据文章的创建时间进行归, 默认地址为 `/blog/archives/` +## 国际化支持 + +如果启用了 国际化，那么博客列表页将会 根据 不同的语言，展示对应语言目录下的博客列表。 +即 每个语言下的 文章列表 都是保持独立的。 + +特别的，如果您的 一篇博客文章 拥有不同的语言版本，请保持在 不同的语言目录下，都有相同的 +目录文件结构和文件名。当切换语言时，主题能够正确的切换到对应语言的文章。 + +::: file-tree + +- docs + - en + - my-article.md + - fr + - my-article.md + - my-article.md +::: + ## 设置博客为主页 默认情况下，主题 将 **首页** 与 **博客页** 分离。 diff --git "a/docs/notes/theme/guide/\347\237\245\350\257\206\347\254\224\350\256\260.md" "b/docs/notes/theme/guide/\347\237\245\350\257\206\347\254\224\350\256\260.md" index fece9165..32c9883a 100644 --- "a/docs/notes/theme/guide/\347\237\245\350\257\206\347\254\224\350\256\260.md" +++ "b/docs/notes/theme/guide/\347\237\245\350\257\206\347\254\224\350\256\260.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 效果。 :::