Ideas about sidebar

[Mister-Hope]

I want to share some ideas here, and if you like it I can build PRs for it.

Remain or at least support the old V1 logic on SidebarObjects

Here is the V1 logic:

https://v1.vuepress.vuejs.org/zh/theme/default-theme-config.html#%E5%A4%9A%E4%B8%AA%E4%BE%A7%E8%BE%B9%E6%A0%8F

So I think it's better for the official theme to both support:

module.exports = {
  themeConfig: {
    // 侧边栏对象
    // 不同子路径下的页面会使用不同的侧边栏
    sidebar: {
      '/guide/': [
        {
          isGroup: true,
          text: 'Guide',
          children: ['/guide/README.md', '/guide/getting-started.md'],
        },
      ],
      '/reference/': [
        {
          isGroup: true,
          text: 'Reference',
          children: ['/reference/cli.md', '/reference/config.md'],
        },
      ],
    },
  },
}

And

module.exports = {
  themeConfig: {
    // 侧边栏对象
    // 不同子路径下的页面会使用不同的侧边栏
    sidebar: {
      '/guide/': [
        {
          isGroup: true,
          text: 'Guide',
          children: ['README.md', 'getting-started.md'],
        },
      ],
      '/reference/': [
        {
          isGroup: true,
          text: 'Reference',
          children: ['cli.md', 'config.md'],
        },
      ],
    },
  },
}

Make the md suffix optional

People should be warned that xxx/README is expected instead of xxx/, but I don't think there are benefits for forcing people to type extra .md. Even if it's required to handle routes, it can be proceed by theme.

Remove isGroup

isGroup is used internal the theme to determin it's children are pages or headers in page. But I didnot see any difference between adding it or not( I tried in the docs). So please remove it. children property should be enough.

SidebarItem:

 {
    text: 'github',
    link: 'https://github.com',
},

SidebarGoupItem:

 {
    text: 'github',
    children: ['a.md','b.md'],
},

SidebarGroupItem with link in title:

 {
    text: 'github',
    link: 'https://github.com',
    children: ['a.md','b.md'],
},

The logic should be like this:

• Immediately work through users' config after getting it then add isGroup: true for every object containing children
• Behave like present.

Add prefix field as enhancement

This is something I had PR to V1 repo.

It's quite common for people to classify different type of contents with folders.So people will likely create sidebar same as their file structure.

E.g.:

.
├─ README.md
├─ contact.md
├─ about.md
├─ foo/
│   ├─ README.md
│   ├─ one.md
│   └─ two.md
└─ bar/
    ├─ README.md
    ├─ three.md
    └─ four.md

People would build their sidebar below in most cases

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      "/" /* / */,
      {
        title: "Foo",
        children: [
          "/foo/" /* /foo/ */,
          "/foo/one" /* /foo/one.html */,
          "/foo/two" /* /foo/two.html */,
        ],
      },
      {
        title: "Bar",
        children: [
          "/bar/" /* /bar/ */,
          "/bar/three" /* /bar/three.html */,
          "/bar/four" /* /bar/four.html */,
        ],
      },
      "/contact" /* /contact.html */,
      "/about" /* /about.html */,
    ],
  },
};

Adding prefix option could make more than a half cases easier in configuation:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      "/" /* / */,
      {
        title: "Foo",
        prefix: "/foo/",
        children: [
          "" /* /foo/ */,
          "one" /* /foo/one.html */,
          "two" /* /foo/two.html */,
        ],
      },
      {
        title: "Bar",
        prefix: "/bar/",
        children: [
          "" /* /bar/ */,
          "three" /* /bar/three.html */,
          "four" /* /bar/four.html */,
        ],
      },
      "/contact" /* /contact.html */,
      "/about" /* /about.html */,
    ],
  },
};

I saw many repo are handling prefix themselves like this way, so I think this enhancement is good:

children: [/* some items */].map(i => '/some-prefix/' +  i )

---

Why I want this?

The official theme should be treat as a paradigm and most of the 3rd-party theme will follow it to shorten migration costs.

[meteorlxy]

Most of those you mentioned are the legacy when migrating the sidebar of default theme. We can optimize them for sure.

• Implicit path prefix: It's OK to support it. The only problem is the types defs and documentation (I spent a lot of effort on them, which is definitely annoying lol)
• Implicit extension suffix: I personally decline to have too many implicit things like this.
• isGroup: As I remember, I decided to use it somehow to work together with the collapsable field as v1, but collapsable sidebar group has not been implemented in v2. 😅 So it looks redundant for now.
• A prefix field: Not sure if it's useful. I think the sidebar will not display well when mixing groups and links. Let's postpone it.

--- update

isGroup has special usage:

• If isGroup is not set to true, then the link is required
• We will render different DOM with isGroup or not

--- update

Now isGroup is removed in ea7c4bb

Then a special "sidebar sub group" is no longer supported (which should be rarely used).

[meteorlxy]

Anyway, contributions welcome, but try not to commit too many changes in a single PR 😄

[Mister-Hope]

I think my theme looks ok with nested sidebar. "布局" is mixed. check out here

And here and here are mixed one on first level. Not nice, but surely not bad.

[meteorlxy]

I mean it's might not display well in default theme. The group title and the normal link looks quite different

[Mister-Hope]

But the prefix is not built for mixing, pure groups could benifit from it. Like:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: "Foo",
        prefix: "/foo/",
        children: [
          "" /* /foo/ */,
          "one" /* /foo/one.html */,
          "two" /* /foo/two.html */,
        ],
      },
      {
        title: "Bar",
        prefix: "/bar/",
        children: [
          "" /* /bar/ */,
          "three" /* /bar/three.html */,
          "four" /* /bar/four.html */,
        ],
      },
    ],
  },
};

I really seen a lot of repos doing .map and add prefix for children. Even the default theme has a common prefix in every children in nesting groups.

[meteorlxy]

So with the help of prefix, we can avoid implicit path prefix.

[Mister-Hope]

Already supported