Config
Plugin Options
getInfo
Type:
(page: Page) => Record<string, unknown>
Reference:
Details:
Function to extract article information from pages.
Article info will be injected into route meta, making it available in client composables.
filter
Type:
(page: Page) => boolean
Default:
(page) => Boolean(page.filePathRelative) && !page.frontmatter.home
Reference:
Details:
Function to filter pages for blog articles.
By default, all pages generated from Markdown files except homepage are included.
category
- Type:
BlogCategoryOptions[]
- Reference:
- Details: Category configurations. See Category Config.
type
- Type:
BlogTypeOptions[]
- Reference:
- Details: Type configurations. See Type Config.
slugify
- Type:
(name: string) => string
- Default:
(name) => name.replace(/ _/g, '-').replace(/[:?*|\\/<>]/g, "").toLowerCase()
- Details: Function to convert strings to URL-friendly slugs for route registration.
excerpt
- Type:
boolean
- Default:
true
- Reference: Guide → Excerpt Generation
- Details: Whether to generate excerpt for pages.
excerptSeparator
- Type:
string
- Default:
<!-- more -->
- Reference:
- Details: Separator for manual excerpt in content.
excerptLength
Type:
number
Default:
300
Reference:
Details:
Target length for auto-generated excerpts.
Tips
Excerpt length will be the minimal possible length reaching this value.
Set to
0
to disable auto excerpt generation.
excerptFilter
Type:
(page: Page) => boolean
Default: Same as
filter
optionReference:
Details:
Function to filter pages for excerpt generation.
Tips
Use this to skip pages that don't need excerpt generation. For example, if users set
excerpt
ordescription
in frontmatter, you may want to use them directly.
isCustomElement
Type:
(tagName: string) => boolean
Default:
() => false
Reference:
Details:
Tags which is considered as custom elements.
This is used to determine whether a tag is a custom element since all unknown tags are removed in excerpt.
metaScope
Type:
string
Default:
"_blog"
Details:
Key used when injecting info to route meta.
Tips
Setting to an empty key will inject to route meta directly instead of a field.
hotReload
Type:
boolean
Default: Whether using
--debug
flagDetails:
Whether enable hotReload in devServer.
To theme developers
It's disabled by default because it does have performance impact in sites with a lot of categories and types. And it can slow down hotReload speed when editing Markdown.
If users are adding or organizing your categories or tags, you may tell them to enable this, for the rest it's better to keep it disabled.
Also, you can try to detect number of pages in users project and decide whether to enable it.
Blog Category Config
Blog category config should be an array, while each item is controlling a "category" rule.
interface BlogCategoryOptions {
/**
* Unique category name
*/
key: string
/**
* Function getting category from page
*/
getter: (page: Page) => string[]
/**
* A custom function to sort the pages
*/
sorter?: (pageA: Page, pageB: Page) => number
/**
* Path pattern of page to be registered
*
* @description `:key` will be replaced by the "slugify" result of the original key
*
* @default `/:key/`
*/
path?: string | false
/**
* Page layout name
*
* @default 'Layout'
*/
layout?: string
/**
* Frontmatter
*/
frontmatter?: (localePath: string) => Record<string, string>
/**
* Item page path pattern or custom function to be registered
*
* @description When filling in a string, `:key` and `:name` will be replaced by the "slugify" result of the original key and name
*
* @default `/:key/:name/`
*/
itemPath?: string | false | ((name: string) => string)
/**
* Item page layout name
*
* @default 'Layout'
*/
itemLayout?: string
/**
* Items Frontmatter
*/
itemFrontmatter?: (name: string, localePath: string) => Record<string, string>
}
Blog Type Config
Blog type config should be an array, while each item is controlling a "type" rule.
interface BlogTypeOptions {
/**
* Unique type name
*/
key: string
/**
* A filter function to determine whether a page should be the type
*/
filter: (page: Page) => boolean
/**
* A custom function to sort the pages
*/
sorter?: (pageA: Page, pageB: Page) => number
/**
* Page path to be registered
*
* @default '/:key/'
*/
path?: string
/**
* Layout name
*
* @default 'Layout'
*/
layout?: string
/**
* Frontmatter
*/
frontmatter?: (localePath: string) => Record<string, string>
}
Composition API
You can import the following API from @vuepress/plugin-blog/client
.
Blog category
const useBlogCategory: < T extends Record<string, unknown> = Record<string, unknown>, >( key?: string, ) => ComputedRef<BlogCategoryData<T>>
Argument
key
should be the category unique key.If no key is passed, the plugin will try to use the key in current path.
Blog category
const useBlogType: < T extends Record<string, unknown> = Record<string, unknown>, >( key?: string, ) => ComputedRef<BlogTypeData<T>>
Argument
key
should be the type unique key.If no key is passed, the plugin will try to use the key in current path.
Returning values are:
interface Article<T extends Record<string, unknown> = Record<string, unknown>> {
/** Article path */
path: string
/** Article info */
info: T
}
interface BlogCategoryData<
T extends Record<string, unknown> = Record<string, unknown>,
> {
/** Category path */
path: string
/**
* Only available when current route matches an item path
*/
currentItems?: Article<T>[]
/** Category map */
map: {
/** Unique key under current category */
[key: string]: {
/** Category path of the key */
path: string
/** Category items of the key */
items: Article<T>[]
}
}
}
interface BlogTypeData<
T extends Record<string, unknown> = Record<string, unknown>,
> {
/** Type path */
path: string
/** Items under current type */
items: Article<T>[]
}