VitePress Routing

VitePress uses a file-based routing system, which means your URL structure is determined by your source file directory structure. Understanding this is key to organizing your documentation site.

Basic Principle

Each .md file in the docs directory (or your specified root directory) will be compiled into an .html page and mapped to a corresponding route.

• A file named guide.md will generate a guide.html page, accessible via /guide.html or more simply /guide.
• A file located at guide/getting-started.md will generate guide/getting-started.html, accessible via /guide/getting-started.

This approach is very intuitive: your directory structure is your site structure.

Index Pages

If a filename is index.md, it will be treated as the "home page" of that directory.

• docs/index.md will become the site's root home page, accessible by visiting /.
• docs/guide/index.md will become the home page of the /guide/ directory, accessible by visiting /guide/.

Clean URLs

VitePress automatically generates "clean URLs" for your pages. This means users don't need to include the .html extension in the URL when accessing pages. The server will automatically resolve /page to /page.html.

Linking to Other Pages

In your Markdown files, you can use relative paths to link to other pages.

<!-- Assuming current file is at docs/guide/getting-started.md -->

<!-- Link to another file in the same directory -->
[View Configuration](./configuration.md)

<!-- Link to the home page of the parent directory -->
[Back to Guide Home](../guide/)

<!-- Link to API examples in the site root -->
[View API Examples](/api-examples.md)

Best Practices:

• Always use the .md extension when linking to Markdown files. VitePress will automatically convert it to .html during the build process.
• Using relative paths ensures your links work correctly in different environments (such as local development and after deployment).

Navigation via Sidebar and Navbar

While you can manually create links within pages, the main navigation for a documentation site is typically implemented through Sidebar and Navbar.

These navigation elements are configured in the .vitepress/config.js file. By defining themeConfig.nav and themeConfig.sidebar, you can provide users with a clear, consistent site navigation structure.

For example, a simple sidebar configuration might look like this:

// .vitepress/config.js
export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' }
        ]
      }
    ]
  }
}

This way, VitePress will automatically generate navigation links based on your configuration, and users don't need to worry about the underlying URL structure.