Make Nav URL customisable for home page and subpages

[air3ijai]

trafficstars

Is your feature request related to a problem? Please describe.

We would like to have a way to easy navigate between home page and subpages.

Describe the solution you'd like

Now, when we press on Nav element it points to the home page. It would be useful to have a way to set a link to that element

• Add nav-link to be used when you are on home page
• Add nav-sub-link to be used when you are on subpage, and if not defined is equal to nav-link

In that way, we can easy navigate between home and subpages by press on same element. For example

export default {
  themeConfig: {
    nav: [
      { nav-link: '/markdown-examples'},
      { nav-sub-link: '/'},
      { text: 'Markdown Examples', link: '/markdown-examples' }
    ]
  }
}

Describe alternatives you've considered

No alternatives right now?

Additional context

And example about how it works now

https://github.com/user-attachments/assets/df4e051b-242c-4cbe-a3bd-8fa39ba25848

Validations

• [X] Follow our Code of Conduct
• [X] Read the docs.
• [X] Read the Contributing Guidelines.
• [X] Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[brc-dd]

  themeConfig: {
    logoLink: '/foo',
  }

[ghost]

Thanks, direct link works fine - do we have a way to set a "back-link", when we located on the subpage?

We need a way to navigate easy back.

[brc-dd]

Ah, currently no 👀

[brc-dd]

Can you explain again what was the requirement? Did you mean you want to go back to /foo/ when you're at /foo/bar and to /baz/ when you're at /baz/bar? This is possible in v2-alpha with directory based configs.

[ghost]

We need an easy way to navigate back to the docs Home Page.

1. We can navigate from HP to different sub-pages
   • docs.domain.tld --> docs.domain.tld/foo ✅
2. We have no way to press any visible link to navigate back to the HP
   • docs.domain.tld/foo --> docs.domain.tld :x:

logoLink is a perfect location for that, but it works only for p.1 and when we are on sub-pages, we should be able to specify logoLinkSubpages: '/' and in that way have an active area to return back to HP.

For example

1. Go to https://vitepress.dev - press the logo and nothing is happening, probably because logoLink is not set?
2. On sub-page https://vitepress.dev/guide/getting-started - press the logo and it will return you back to the HP.

The idea is to have an active and all the time visible area which should permit us to switch between HP and Main sub-page.

[brc-dd]

Please check if https://stackblitz.com/edit/vite-krajaenw?file=docs/.vitepress/config.ts works for you.

---

probably because logoLink is not set?

It defaults to base (/ in this case). You're on same page as the link (home page), so there won't be any navigation.

[ghost]

Please check if https://stackblitz.com/edit/vite-krajaenw?file=docs/.vitepress/config.ts works for you.

It looks exactly what we need - can you please point to the documentation?

    if (relativePath === 'index.md') {
      return [{ themeConfig: { logoLink: '/example' } }];
    }

In that case we set logoLink: '/example' only for HP and for all other pages it will point back to HP?

[brc-dd]

Ah, the docs aren't there yet. It's a new API, added last month - #4660.

In that case we set logoLink: '/example' only for HP and for all other pages it will point back to HP?

Yeah. It will override whatever the earlier layer has. Here, by default the logoLink is /, then we are overriding it for index.md (the home page).

So, when the home page is open that overloaded logoLink (/example) will be shown. For other pages, it won't be overloaded, so the default logoLink (/) will be shown.

You can customize the behavior to however you want, but the loader function should be pure (you cannot use external variables in it). You can open console in browser devtools and change the log level there to include verbose logs. That will show you which layers are being loaded.

Unfortunately, when you add custom additionalConfig in your main vitepress config, the default behavior of auto-loading directory-level config files will stop. We can probably support both.

[ghost]

Unfortunately, when you add custom additionalConfig in your main vitepress config, the default behavior of auto-loading directory-level config files will stop. We can probably support both.

Does it affect language specific configs as well?

I'm asking because in #4660 there are some related changes and we need to check how to upgrade to v2 in general.

[brc-dd]

Does it affect language specific configs as well?

No, those should work fine.

I'm asking because in #4660 there are some related changes

Ah, if you're referring to changes where we moved things like - docs/.vitepress/config/es.ts → docs/es/config.ts - then those aren't necessary. We did it just to check out the things and for better colocation. But yeah the newer docs/es/config.ts style won't work for you (yet) if you specify custom additionalConfig. v1 style config inside locales key (the one documented here - https://vitepress.dev/guide/i18n) will keep working fine.

You can refer the changelog for list of breaking changes. There aren't many, and they are mostly if you're customizing theme too much.

[ghost]

Thank you for the solution and clarification. Hopefully next month will find a time for more experiments.

[its-miroma]

I believe this has been resolved by #4963. You can now do:

nav: [
  {
    text: 'Sub Page',
    link: ({ relativePath }) =>
      relativePath === 'index.md' ? '/sub-page' : '/',
  },
],

[its-miroma]

@brc-dd https://github.com/vuejs/vitepress/issues/4232#issuecomment-3346744774