Blog

About 2054 wordsAbout 7 min

GuideQuick Start

2025-03-04

Overview

By default, the theme will treat all md files in the documentation source directory as blog posts, except for specific directories (e.g., the notes directory, which is used for notes).

The theme will also categorize blog posts based on the directory structure of the md files, using the directory name as the category of the blog post.

The theme will automatically generate a blog post list page with the link address /blog/, displaying all blog posts and relevant information about the blogger.

Configuration

The blog feature is enabled by default in the theme, and you usually do not need to perform additional configurations.

.vuepress/config.ts

export default defineUserConfig({
  theme: plumeTheme({
    // Disable the blog feature
    // blog: false,

    blog: {
      /**
       * Configure included files via glob string,
       * by default, it reads all `.md` files in the source directory, but excludes directories used for notes in the `notes` configuration.
       */
      include: ['**/*.md'],
      // If you want to only read articles from a specific directory in the source directory, such as the `blog` directory, you can configure it as:
      // include: ['blog/**/*.md'],

      /**
       * Configure excluded files via glob string, relative to the source directory
       */
      exclude: ['.vuepress/', '**/README.md'],

      // Disable pagination
      // pagination: false,
      // Number of articles displayed per page
      pagination: 15,
    }
  })
})

Blogger Information

The theme supports displaying basic information about the blogger.

Plume Theme

The Theme for Vuepress 2.0

GuangZhou, China

pengzhanbo

Configuration

You can set the blogger's avatar and other related information through the profile attribute.

.vuepress/config.ts

export default defineUserConfig({
  theme: plumeTheme({
    profile: {
      name: 'Your Name',
      description: 'Description text, motto/signature',
      avatar: '/blogger.png',
      location: 'Your Location',
      organization: 'Your Organization',
      circle: true, // Whether the avatar is circular
      layout: 'right', // Whether the personal information is on the left or right, 'left' | 'right'
    },
    // Social links
    social: [
      { icon: 'github', link: 'https://github.com/vuepress-theme-plume  ' },
      // ... more
    ]
  })
})

Article Metadata

You can configure the display of blog post metadata, such as title, author, date, tags, etc. This data is configured through frontmatter.

---
title: Article Title
createTime: 2024/01/01 00:00:00
tags:
  - tag1
  - tag2
---

Among them, title / createTime will be automatically filled in by the theme when creating a new md file, and you can modify them at will.

The following are the available frontmatter properties in blog posts.

Property	Type	Default Value	Description
title	`string`	Automatically filled in with the filename	Article title
createTime	`string`	Current time	Article creation time
tags	`string[]`	`[]`	Article tags
sticky	`boolean \| number`	false	Whether to pin the article, if it's a number, the larger the number, the higher the pinning priority
draft	`boolean`	false	Whether it's a draft, draft articles will not be displayed
cover	`string`	`''`	Article cover image
coverStyle	`BlogPostCoverStyle`	`null`	Article cover image style
excerpt	`boolean \| string`	''	Article excerpt, by default generated via `<!-- more -->` comment, passing a string indicates custom content, and it will no longer be extracted from the main text

In addition to the above fields, you can also use the fields in the general frontmatter configuration to flexibly control the behavior of the current page.

Article Excerpt

If you want to add an excerpt to an article, you can use the  comment to mark it. Any content before this comment will be considered as the excerpt.

Example:

---
title: Title
---

This content will be used as the excerpt

<!-- more -->

This content will not be used as the excerpt

You can also use frontmatter.excerpt to control whether the article displays an excerpt and to customize the excerpt content.

frontmatter.excerpt defaults to false, indicating that the excerpt is not displayed, and the  comment will be ignored.
When frontmatter.excerpt is of type string, it indicates custom excerpt content, and the  comment will be ignored.

Example:

---
title: Title
excerpt: Custom excerpt content
---

You can use different methods to control the excerpt of the article as needed.

The theme more strongly recommends using the  comment to add excerpts

Although the theme supports using different configurations for each article's cover image, for the sake of overall layout style and to simplify configuration, the theme also supports preset configurations for cover images:

.vuepress/config.ts

export default defineUserConfig({
  theme: plumeTheme({

    blog: {
      // Configure the layout position of the cover image
      // 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 BlogPostCoverStyle {
  /**
   * The position of the blog post cover image
   */
  layout?: BlogPostCoverLayout
  /**
   * The aspect ratio of the blog post cover image
   *
   * @default '4:3'
   */
  ratio?: number | `${number}:${number}`

  /**
   * The width of the cover image, only effective when layout is 'left' or 'right'
   *
   * @default 240
   */
  width?: number
  /**
   * Whether to use compact mode, in compact mode, the cover image fits the container edges
   * @default false
   */
  compact?: boolean
}

You may have noticed that in the preset configuration's layout, there are also two configurations supported: odd-left and odd-right.

odd-left: Indicates that odd items are on the left and even items are on the right
odd-right: Indicates that odd items are on the right and even items are on the left

For example, the effect of odd-left is as follows:

Article Title

2024-09-18

Article Title

2024-09-18

Article Title

2024-09-18

Note

When on narrow screens of mobile devices, for visual effect considerations, the layout configuration is forcibly reset to top.

Tag Page, Category Page, and Archive Page

In addition to automatically generating the blog post list page, the theme will also automatically generate tag pages, category pages, and archive pages.

The tag page can filter and display blog posts based on tags, with the default address being /blog/tags/

The category page can display blog posts based on the original directory structure, with the default address being /blog/categories/

The archive page archives articles based on their creation time, with the default address being /blog/archives/

Internationalization Support

If internationalization is enabled, the blog list page will display the blog list of the corresponding language directory based on different languages. That is, the article list of each language is kept independent.

Specifically, if one of your blog posts has different language versions, ensure that the same directory file structure and filename exist under different language directories. When switching languages, the theme can correctly switch to the corresponding language article.

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

Setting the Blog as the Homepage

By default, the theme separates the homepage and the blog page.

However, for users who want to build only a blog site, it might be a better choice to directly set the blog page as the homepage.

The theme provides two ways to set the blog as the homepage to meet different scenario needs:

Method One: Configure the pageLayout attribute of the homepage to blog

docs/README.md

---
pageLayout: blog
---

This configuration will directly apply the blog layout to the page, displaying the blog post list.

This is the simplest way to modify the homepage to a blog page, but the downside is the lack of flexibility.

Method Two: Configure the pageLayout attribute of the homepage to home, and add a homepage area type of type: blog

docs/README.md

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

With this method, you can not only add a blog post list to the homepage but also flexibly add different content to other areas of the page.

For example, configure the first screen as banner, followed by the blog post list:

docs/README.md

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

For more customization configurations, please refer to Customize the Homepage.

After using the above two methods to configure the homepage as the blog page, since the theme still generates the blog post list page with the address /blog/ by default, this results in duplicate functional pages. Therefore, you need to Theme Configuration > Blog Configuration to disable the automatic generation of the blog post list page:

(You can also modify the link addresses of the category page/tag page/archive page)

.vuepress/config.ts

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

export default defineUserConfig({
  theme: plumeTheme({
    blog: {
      postList: false, // Prevent the generation of the blog post list page
      // tagsLink: '/blog/tags/',
      // categoriesLink: '/blog/categories/',
      // archiveLink: '/blog/archives/',
    }
  })
})

Contributors

zhenghaoyang24

pengzhanbo

Changelog

3/27/25, 1:06 PM

View All Changelog

9f99a-docs: add en markdown doc (#538)on 3/27/25
a4ac3-docs: add en-US docs (#514)on 3/9/25

markdown

Blog

Overview

Configuration

Blogger Information

Plume Theme

Configuration

Article Metadata

Article Excerpt

Article Cover Image

Article Title

Article Title

Article Title

Article Title

Preset Configuration

Article Title

Article Title

Article Title

Tag Page, Category Page, and Archive Page

Internationalization Support

Setting the Blog as the Homepage

Contributors

Changelog