catalog

This plugin automatically generates catalog pages and provides catalog components.

Usage

npm i -D @vuepress/plugin-catalog@next

.vuepress/config.ts
import { catalogPlugin } from '@vuepress/plugin-catalog'

export default {
  plugins: [
    catalogPlugin({
      // Your options
    }),
  ],
}

Guide

Catalog Info

First, you should set catalog info in routeMeta:

.vuepress/config.ts
import { catalogPlugin } from '@vuepress/plugin-catalog'

export default {
  extendsPage: (page) => {
    // Set catalog info in routeMeta
    page.routeMeta = {
      // Catalog title
      title: page.title,
      // ... other information
    }
  },
}

You can then import defineCatalogInfoGetter from @vuepress/plugin-catalog/client and use it in client config file to extract catalog info from route meta.

.vuepress/client.ts
import { defineCatalogInfoGetter } from '@vuepress/plugin-catalog/client'

defineCatalogInfoGetter((meta) => (meta.title ? { title: meta.title } : null))

Catalog info should contain:

title: Catalog title
order: Catalog order (optional)
content: Catalog content component (optional)

Sorting with Order

The plugin sorts pages by order in the following sequence:

// Positive numbers from small to large
Project with order 1
Project with order 2
...
Project with order 10
...
// Projects without order
Project without order
Project without order
...
// Negative numbers from small to large
Project with order -10
// ...
Project with order -2
Project with order -1

Options

levelbuilt-in: Component only1 | 2 | 3

Default3

Maximum depth of catalog items.

indexbuilt-in: Component onlyboolean

Whether to show index numbers for catalog items.

frontmatter(path: string, app: App) => PageFrontmatter

Frontmatter getter for generated pages, where app is the VuePress app instance.

.vuepress/config.ts
import { catalogPlugin } from '@vuepress/plugin-catalog'

export default {
  plugins: [
    catalogPlugin({
      frontmatter: (path, app) => ({
        // Frontmatter you want
        // You may customize title, author, time, etc.
      }),
    }),
  ],
}

exclude(RegExp | string)[]

Default[]

Catalog page path to be excluded during generation.

"/foo/" means only exclude catalog page generation at the /foo/ folder.
/^\/foo\// means exclude catalog page generation at the /foo/ folder and its subfolders.

404 pages will be automatically excluded.

componentstring

Component name to use as the catalog component.

By default the plugin registers and uses a <Catalog /> component.

localesCatalogPluginLocaleConfig

Locale config of the catalog component.

Client Options

defineCatalogInfoGetter

interface CatalogInfo {
  /** Catalog title */
  title: string
  /** Catalog order */
  order?: number
  /** Catalog content */
  content?: Component
}

type CatalogInfoGetter = (meta: Record<string, unknown>) => CatalogInfo | null

const defineCatalogInfoGetter: (options: CatalogInfoGetter) => void

Customizes how to extract catalog info from route meta.

Components

Catalog

Details:
This plugin globally registers a <Catalog /> component by default (unless you set the component option).
You can use <Catalog /> in theme layouts or directly in Markdown files.
The component supports four props:
- level: Changes the display depth (maximum 3 levels), default is 3.
- base: Displays catalog of the specified folder, default is the current folder.
- index: Adds index numbers to catalog items, default is no numbers.
- hideHeading: Hides the component title, default is to display the Catalog title.

Styles

You can customize catalog styles via CSS variables:

:root {
  --catalog-c-accent: var(--vp-c-accent);
  --catalog-c-accent-text: var(--vp-c-accent-text);
  --catalog-c-control: var(--vp-c-bg-alt);
  --catalog-c-control-hover: var(--vp-c-bg-alt);
  --catalog-c-divider: var(--vp-c-divider);
  --catalog-header-offset: var(--header-offset, 3.6rem);
}