Overview

The theme provides a notes feature, which is used to aggregate articles from the same series or serve as the site's sub-documentation.

"Notes" are organized based on the file structure. By default, the notes/ directory is used as the root directory. Documents stored under the notes directory will not be treated as blog posts and will not appear on the blog post list page.

File Structure and Configuration

In one of our projects, we have the following file structure:

• docs
  • notes
    • typescript# Typescript notes
      • basic.md
      • types.md
    • rust# Rust notes
      • tuple.md
      • struct.md
  • blog-post.md# Blog post
  • README.md# Site home page

Under the docs/notes directory, there are two subdirectories for storing the series content of typescript and rust, respectively.

Next, configure notes in the configuration file:

.vuepress/config.ts

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

export default defineUserConfig({
  theme: plumeTheme({
    notes: {
      // Declare the directory for all notes, (default configuration, usually you don't need to declare it)
      dir: '/notes/',
      link: '/', // Declare the default link prefix for all notes, default is '/' (default configuration, usually you don't need to declare it)
      notes: [
        // Each note is an object in the `notes` array
        {
          // Declare the note's directory, relative to `notes.dir`, here it represents the `notes/typescript` directory
          dir: 'typescript',
          // Declare the note's link prefix, concatenated with `notes.link`, here it represents `/typescript/`
          // All articles within the note will use `/typescript/` as the access link prefix.
          link: '/typescript/',
          // Configure the note's sidebar navigation, used to navigate all documents within the note
          // Declared as `auto`, the sidebar navigation will be automatically generated based on the directory structure
          sidebar: 'auto'
        },
        {
          dir: 'rust',
          link: '/rust/',
          sidebar: [
            { text: 'Introduction', items: ['foo'] }
          ]
        }
      ]
    }
  })
})

Tips

It is recommended to configure the note's directory and link prefix before creating files. The theme has enabled auto-frontmatter by default, which needs to generate permanent links and sidebars for md files in the directory based on the configuration.

Writing Notes Configuration

Since writing all notes configurations inside plumeTheme({ }) may cause the code nesting to be too deep, it is more recommended to use the defineNotesConfig() and defineNoteConfig() provided by the theme to extract the notes configuration to the outside. They can also help you get better type hints, making it more readable and easier to maintain.

.vuepress/notes.ts

import { defineNoteConfig, defineNotesConfig } from 'vuepress-theme-plume'

/**
 * Configure a single note
 */
const typescript = defineNoteConfig({
  dir: 'typescript',
  link: '/typescript/',
  sidebar: [
    '/guide/intro.md',
    '/guide/getting-start.md',
    '/config/config-file.md',
  ]
})

/**
 * Configure notes
 */
export default defineNotesConfig({
  // Declare the directory for all notes, (default configuration, usually you don't need to declare it)
  dir: '/notes/',
  link: '/',
  // Add note configurations here
  notes: [typescript] 
})

.vuepress/config.ts

import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
import notes from './notes'

export default defineUserConfig({
  theme: plumeTheme({
    notes
  }),
})

How to configure when there are many notes?

If you have a large number of notes and putting them all in one notes.ts file may make the file too large and difficult to maintain, you can split the files, using the .vuepress/notes/ directory as the directory for note configurations.

• docs
  • .vuepress
    • notes
      • typescript.ts
      • rust.ts
      • index.ts
      • …
  • notes
    • typescript
      • …
    • rust
      • …

The code is as follows:

.vuepress/config.ts

import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'
import notes from './notes/index.ts'

export default defineUserConfig({
  theme: plumeTheme({
    notes
  }),
})

.vuepress/notes/index.ts

import { defineNotesConfig } from 'vuepress-theme-plume'
import rust from './rust'
import typescript from './typescript'

export default defineNotesConfig({
  // Declare the directory for all notes, (default configuration, usually you don't need to declare it)
  dir: '/notes/',
  link: '/',
  // Add note configurations here
  notes: [ 
    typescript,
    rust,
  ]
})

.vuepress/notes/typescript.ts

import { defineNoteConfig } from 'vuepress-theme-plume'

export default defineNoteConfig({
  dir: 'typescript',
  link: '/typescript/',
  sidebar: [
    '/guide/intro.md',
    '/guide/getting-start.md',
    '/config/config-file.md',
  ]
})

.vuepress/notes/rust.ts

import { defineNoteConfig } from 'vuepress-theme-plume'

export default defineNoteConfig({
  dir: 'rust',
  link: '/rust/',
  sidebar: [
    '/guide/intro.md',
    '/guide/getting-start.md',
    '/config/config-file.md',
  ]
})

Sidebar Configuration

Taking the typescript directory as an example, it has the following file structure:

• typescript
  • guide
    • intro.md
    • getting-start.md
  • config
    • config-file.md
    • configuration.md
  • reference
    • basic.md
    • syntax.md
    • modules.md
  • built-in
    • types
      • Required.md
      • Omit.md
  • README.md

Automatically Generating Sidebar

The simplest configuration method is sidebar: 'auto', the theme will automatically generate the sidebar based on the file structure and sort it according to the encoding of the first character.

If you want to modify the order of the automatically generated sidebar, you can add prefixes such as 1. or 2. before the directory name or file name.

• typescript
  • 1.guide
    • 1.intro.md
    • 2.getting-start.md
  • 2.config
    • 1.config-file.md
    • 2.configuration.md
  • …

The theme will sort based on the numbers in these prefixes, and the prefix part will not be displayed in the sidebar.

Customizing the Sidebar

Sometimes, automatically generating the sidebar may not fully meet the requirements, and you can customize the sidebar.

Here is the type definition for the sidebar:

type Sidebar = (string | SidebarItem)[]

interface SidebarItem {
  /**
   * Sidebar text
   */
  text?: string

  /**
   * Sidebar link
   */
  link?: string

  /**
   * Sidebar icon
   */
  icon?: ThemeIcon

  /**
   * The link prefix for the current group, the link prefix will be concatenated before the `link` in `items`
   * It will only be concatenated when the `link` in `items` is a relative path
   */
  prefix?: string
  /**
   * Subordinate sidebar groups
   */
  items?: 'auto' | (string | SidebarItem)[]

  /**
   * If not specified, the group is not collapsible.
   * If `true`, the group is collapsible and defaults to collapsed.
   * If `false`, the group is collapsible but defaults to expanded.
   */
  collapsed?: boolean
}

When the type passed in is string, it represents the path to a markdown file:

.vuepress/notes.ts

import { defineNoteConfig } from 'vuepress-theme-plume'

const typescript = defineNoteConfig({
  dir: 'typescript',
  link: '/typescript/',
  sidebar: [
    '/guide/intro.md',
    '/guide/getting-start.md',
    '/config/config-file.md',
    // …
  ]
})

// … other code

You can also omit the .md file suffix and abbreviate it to /guide/intro. The theme will parse the corresponding file, obtain the title and page link address, and convert it into the data format of { text: string, link: string }.

When the type passed in is SidebarItem:

.vuepress/notes.ts

import { defineNoteConfig } from 'vuepress-theme-plume'

const typescript = defineNoteConfig({
  dir: 'typescript',
  link: '/typescript/',
  sidebar: [
    { text: 'Introduction', link: '/guide/intro' },
    { text: 'Quick Start', link: '/guide/getting-start' },
  // …
  ]
})

// … other code

You can also nest multiple levels:

.vuepress/notes.ts

import { defineNoteConfig } from 'vuepress-theme-plume'

const typescript = defineNoteConfig({
  dir: 'typescript',
  link: '/typescript/',
  sidebar: [
    {
      text: 'Guide',
      prefix: '/guide', // Use prefix to concatenate, you can abbreviate the link in the items below to a relative path
      items: [
      // You can mix string and SidebarItem
        { text: 'Introduction', link: 'intro' },
        'getting-start',
      ],
    },
    {
      text: 'Configuration',
      prefix: '/config',
      items: 'auto', // items is 'auto', the sidebar will be automatically generated based on the file structure of prefix
    },
  ]
})

// … other code

About prefix

The purpose of prefix is to abbreviate the links in the same level items by extracting the common prefix to prefix, allowing the theme to complete the full link concatenation for you.

It should be noted that only relative path links in items will be concatenated with prefix, while absolute paths will not be processed.

.vuepress/notes.ts

import { defineNoteConfig } from 'vuepress-theme-plume'

const typescript = defineNoteConfig({
  dir: 'typescript',
  link: '/typescript/',
  sidebar: [
    {
      prefix: '/guide',
      items: [
        'intro', // Relative path, finally concatenated to /guide/intro
        '/config/config-file', // Absolute path, not concatenated
        {
          text: 'Blog',
          link: 'blog', // Relative path, finally concatenated to /guide/blog
        },
        {
          text: 'Configuration',
          link: '/config', // Absolute path, not concatenated
        }
      ]
    }
  ]
})

At the same time, deep nesting is also supported within items, and prefix is still supported inside, following the same rules. If prefix is a relative path, it will be concatenated with the prefix of the upper level, and then with the link in the current level items. If prefix is an absolute path, it will not be concatenated with the prefix of the upper level.

.vuepress/notes.ts

import { defineNoteConfig } from 'vuepress-theme-plume'

const typescript = defineNoteConfig({
  dir: 'typescript',
  link: '/typescript/',
  sidebar: [
    {
      prefix: '/guide',
      items: [
        'intro', // Relative path, finally concatenated to /guide/intro
        {
          prefix: '/config',
          items: [
            'config-file', // Relative path, finally concatenated to /config/config-file
            'configuration', // Relative path, finally concatenated to /config/configuration
          ]
        },
        {
          prefix: 'blog',
          items: [
            'intro', // Relative path, finally concatenated to /guide/blog/intro
            'getting-start', // Relative path, finally concatenated to /guide/blog/getting-start
          ]
        }
      ]
    }
  ]
})

The criterion for whether it is an absolute path is that if it starts with /, it is an absolute path; otherwise, it is a relative path.

Warning

It is not recommended to have too many levels in the sidebar. Sidebars with more than 3 levels may lead to poor UI effects.

Sidebar Icons

Adding icons to the sidebar helps to better present the sidebar. Thanks to the powerful open-source icon library iconify, you can use over 200k icons by simply adding the icon configuration.

.vuepress/notes.ts

import { defineNoteConfig } from 'vuepress-theme-plume'

const typescript = defineNoteConfig({
  dir: 'typescript',
  link: '/typescript/',
  sidebar: [
    {
      text: 'Guide',
      prefix: '/guide',
      icon: 'ep:guide', // iconify icon name
      items: [
        { text: 'Introduction', link: 'intro', icon: 'ph:info-light' }, 
      ],
    },
  ]
})

You can also use local icons or local images:

.vuepress/notes.ts

import { defineNoteConfig } from 'vuepress-theme-plume'

const typescript = defineNoteConfig({
  dir: 'typescript',
  link: '/typescript/',
  sidebar: [
    {
      text: 'Guide',
      prefix: '/guide',
      icon: '/images/guide.png', // iconify icon name
      items: [
        { text: 'Introduction', link: 'intro', icon: '/images/info.png' }, 
        // It can also be a remote image
        { text: 'Quick Start', link: 'getting-start', icon: 'https://cn.vuejs.org/images/logo.png  ' },
      ],
    },
  ]
})

Please note that using local images must start with /, indicating a static resource path, which will be loaded from the .vuepress/public/ directory.

• docs
  • .vuepress
    • public# Save static resources in this location
      • images
        • guide.png
        • info.png
  • …

You may have noticed how to configure sidebar icons when sidebar: auto. In fact, it's very simple. Just add an icon field in the frontmatter section of the file.

typescript/guide/intro.md

---
title: Introduction
icon: ep:guide
---

Sidebar Group Internal Separation

Separating items within a group is a relatively niche requirement. It may be more applicable when there are many items in a group, but it is not suitable to split them into multiple groups, or when it is not suitable to split the group into multiple subgroups. It provides a way to use auxiliary text color to display a separator item name at the same level, for simple separation of items.

.vuepress/notes.ts

import { defineNoteConfig } from 'vuepress-theme-plume'

const typescript = defineNoteConfig({
  dir: 'typescript',
  link: '/typescript/',
  sidebar: [
    {
      text: 'Guide',
      items: [
        'Project 1',
        'Project 2',
        'Project 3',
        { text: 'Separator', link: '---' }, 
        'Project 4',
        'Project 5',
        // …
      ],
    },
  ]
})

It is very simple to complete the separation within a group. You just need to insert a { text: 'xxxx', link: '---' } at the appropriate position. The key is to set the link to consecutive ---, at least three -. You can define the text arbitrarily and also add icons.

Note Home Page

You may have noticed that there is a README.md file in the typescript directory, which will be displayed as the note home page.

• typescript
  • README.md
  • …
• …

By default, it is no different from ordinary documentation pages because the theme sets pageLayout: docs for all pages by default.

But you can directly configure pageLayout: 'home', just like configuring the site home page, to customize a home page for the note!

typescript/README.md

---
pageLayout: home
config:
  - type: hero
  - type: features
---

Contributors

zhenghaoyang24pengzhanbo

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