Customize Sidebar on VitePress Sites

Quick Reference

We have to add Objects here.

/.vitepress/config.mjs

import { defineConfig } from "vitepress";

export default defineConfig({
  themeConfig: {
    sidebar: [
      // ==> Inside Here <==
    ],
  },
});

Adding a Single Link

Just add a signle Object if you want to add a normal link here.

/.vitepress/config.mjs

import { defineConfig } from "vitepress";

export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: "Getting Started",    // The text shown for the Sidebar UI
        link: "/getting-started",   // Markdown Files link
      },
    ],
  },
});

The text prop is simple. It will show the Text on the UI. But, About the link prop. link prop for the actual markdown files adress. Assuming your file structure will be like this:

Terminal

$ tree -a --dirsfirst --gitignore
.
├── docs    # This is the "source directory" which will be `/`
│   ├── public
│   │   └── icon.svg
│   ├── api-examples.md
│   ├── getting-started.md  # And, This will become `/getting-started`
│   ├── index.md
│   └── markdown-examples.md
├── .vitepress
│   └── config.js
├── .gitignore
├── package.json
└── package-lock.json

4 directories, 9 files

And Thats how you link an internal file without the .md extention.

Adding a Section

/.vitepress/config.mjs

import { defineConfig } from "vitepress";

export default defineConfig({
  themeConfig: {
    sidebar: [
      // ==> Inside here <==
    ],
  },
});

A Section is just one object. Give it at least two keys:

• text (string) – the heading of the section
• items (array of objects) – the links

If you want the block to start collapsed, also add:

• collapsed (boolean, set to true)

For Example:

/.vitepress/config.mjs

import { defineConfig } from "vitepress";

export default defineConfig({
  themeConfig: {
    sidebar: [
      { text: "Markdown Examples", link: "/markdown-examples" }, // Single Link
      { text: "Runtime API Examples", link: "/api-examples" },   // Single Link
      {
        text: "Docker",
        items: [    
          { text: "Get Started", link: "/examples/get-started" },
          { text: "Docker Fundamentls", link: "/examples/docker-fundamentals" },
        ],
      },
    ],
  },
});

This will add in a Section with Its dedicated links.

TIP

You can add as much single links or section with links as you want.

Reference

Official Link 🚀