博客

指南快速开始

2024-03-04

概述

主题默认会将文档源目录下的，除了特定的目录（如 notes 目录将作为笔记所在目录），所有 md 文件作为博客文章。

主题还会根据 md 文件所在的文件目录结构，以 目录名 作为博客文章所属的分类。

主题默认会生成一个链接地址为 /blog/ 的博客文章列表页。展示所有的博客文章，以及博主的相关信息。

配置

主题默认启用博客功能，通常您无需进行额外的配置。

.vuepress/config.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,
    }
  })
})

博主信息

主题支持展示博主的基本信息。

Jin Gao

Jin Gao's Homepage

Cambridge, MA, USA

srcJin

配置

你可以通过 profile 属性来设置博主头像等相关信息。

.vuepress/config.ts

export default defineUserConfig({
  theme: plumeTheme({
    profile: {
      name: '您的名字',
      description: '描述文字，座右铭/签名',
      avatar: '/blogger.png',
      location: '您的位置',
      organization: '您的组织',
      circle: true, // 是否为圆形头像
      layout: 'right', // 个人信息在左侧还是右侧，'left' | 'right'
    },
    // 社交链接
    social: [
      { icon: 'github', link: 'https://github.com/vuepress-theme-plume' },
      // ... more
    ]
  })
})

文章元数据

你可以配置展示博客文章的元数据，如标题、作者、日期、标签等。这些数据通过 frontmatter 配置。

---
title: 文章标题
createTime: 2024/01/01 00:00:00
tags:
  - tag1
  - tag2
---

其中，title / createTime 会在新建 md 文件时由主题自动填充，你可以随意修改它们。

以下是在博客文章中可用的 frontmatter 属性。

属性	类型	默认值	说明
title	`string`	默认自动填入文件名	文章标题
createTime	`string`	当前时间	文章创建时间
tags	`string[]`	`[]`	文章标签
sticky	`boolean \| number`	false	是否置顶, 如果为数字，则数字越大，置顶越靠前
draft	`boolean`	false	是否为草稿，草稿文章不会被展示
cover	`string \| BlogPostCover`	`''`	文章封面
excerpt	`boolean \| string`	''	文章摘要，默认通过 `<!-- more -->` 注释生成, 传入字符串表示自定义内容，不再从正文提取

除了以上的字段，你还可以使用通用 frontmatter 配置中的字段，灵活的控制当前页面的行为。

文章摘要

如果你想要为文章添加摘要，你可以使用  注释来标记它。任何在此注释之前的内容会被视为摘要。

示例：

---
title: 标题
---

这里的内容会被作为摘要

<!-- more -->

这里的内容不会被作为摘要

还可以使用 frontmatter.excerpt 来控制文章是否显示摘要，以及自定义摘要内容。

frontmatter.excerpt 默认为 false，表示不显示摘要，此时  注释会被忽略。
frontmatter.excerpt 为 string 类型时，表示自定义摘要内容，此时  注释会被忽略。

示例：

---
title: 标题
excerpt: 自定义摘要内容
---

您可以根据需要使用不同的方式来控制文章的摘要。

主题更建议使用  注释来添加摘要

文章封面图

在博客文章列表页，主题支持为文章添加封面图，并支持不同的排版和灵活的尺寸配置。

为博客文章添加封面图，可以在 frontmatter 中配置 cover:

---
title: 标题
cover: /images/cover.jpg
---

封面图 仅支持绝对路径或远程路径。当使用绝对路径时，从 .vuepress/public 目录中加载图片。

docs
- .vuepress
  - public
    - images
      - cover.jpg
  - config.ts
- article.md
…

默认效果如下：

文章标题

2024-09-18

还可以为封面图调整布局位置，以及尺寸比例：

---
title: 文章标题
cover:
  url: /images/cover.jpg
  layout: left
  ratio: 16:9
  width: 300
---

效果如下:

文章标题

2024-09-18

当文章没有摘要时，可能会显得比较空，为此你还可以通过 compact: true 使封面图贴合容器边缘，使整体变得更紧凑：

---
title: 文章标题
cover:
  url: /images/cover.jpg
  layout: left
  ratio: 16:9
  width: 300
  compact: true
---

效果如下:

文章标题

2024-09-18

compact: true 仅在文章没有摘要时生效

还可以设置封面图在标题上方，此时变为大图风格：

---
title: 文章标题
cover:
  url: /images/cover.jpg
  layout: top
  ratio: 16:9
  width: 300
---

效果如下:

文章标题

2024-09-18

预设配置

虽然主题支持为每个文章的封面图使用不同的配置，出于整体布局风格的考虑，以及简化配置的目的，主题还支持为封面图预设配置：

.vuepress/config.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
      }
    }
  })
})

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 效果如下：

文章标题

2024-09-18

文章标题

2024-09-18

文章标题

2024-09-18

注意

当在移动设备窄屏上时，出于视觉效果考虑，layout 配置强制重置为 top。

标签页，分类页和归档页

主题除了自动生成 博客文章列表页 以外，还会自动生成 标签页，分类页 和 归档页。

标签页可以根据标签筛选并展示博客文章，默认地址为 /blog/tags/

分类页可以根据原始目录结构分类展示博客文章, 默认地址为 /blog/categories/

归档页根据文章的创建时间进行归, 默认地址为 /blog/archives/

国际化支持

如果启用了国际化，那么博客列表页将会根据不同的语言，展示对应语言目录下的博客列表。即每个语言下的文章列表都是保持独立的。

特别的，如果您的一篇博客文章拥有不同的语言版本，请保持在不同的语言目录下，都有相同的目录文件结构和文件名。当切换语言时，主题能够正确的切换到对应语言的文章。

docs
- en
  - my-article.md
- fr
  - my-article.md
- my-article.md

设置博客为主页

默认情况下，主题将首页与 博客页 分离。

但对于希望只建立一个博客站点的用户而言，可能直接将博客页作为首页是个更好的选择。

主题提供了两种方式来设置博客为主页，满足不同的需求场景：

方式一：配置主页的 pageLayout 属性为 blog

docs/README.md

---
pageLayout: blog
---

此配置会直接将页面应用博客布局，显示博客文章列表。

这是将主页修改为博客页的最简单的方式，但缺点是缺少灵活性。

方式二：配置主页的 pageLayout 属性为 home, 添加 type: blog 的首页区域类型

docs/README.md

---
pageLayout: home
config:
  - type: blog
---

使用这种方式，你不仅可以在首页中添加博客文章列表，还可以灵活的在页面的其他区域添加不同的内容。

比如，配置首屏为 banner，然后紧跟着博客文章列表：

docs/README.md

---
pageLayout: home
config:
  - type: banner
  - type: blog
---

更多自定义配置，请参考自定义首页。

当使用以上两种方式将首页配置为博客页后，由于主题默认依然会生成地址为/blog/ 的博客文章列表页，这导致存在了重复功能的页面，为此，你需要主题配置 > 博客配置中， 关闭自动生成博客文章列表页：

（还可以在重新修改分类页/标签页/归档页的链接地址）

.vuepress/config.ts

import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'

export default defineUserConfig({
  theme: plumeTheme({
    blog: {
      postList: false, // 禁止生成博客文章列表页
      // tagsLink: '/blog/tags/',
      // categoriesLink: '/blog/categories/',
      // archiveLink: '/blog/archives/',
    }
  })
})