Getting Started

This guide walks you through installing the theme and getting a working documentation site running locally. By the end, you’ll have a Jekyll site with VitePress-style navigation, sidebar, and styling.

Add the gem

Add the theme to your Gemfile:

gem "jekyll-vitepress-theme"

Then install it:

bundle install

Enable theme and plugin

The gem serves double duty — it provides layouts and assets as a theme, and registers Jekyll hooks as a plugin. You need to enable both:

theme: jekyll-vitepress-theme
plugins:
  - jekyll-vitepress-theme

Define your collections

Jekyll VitePress Theme uses collections to organize your documentation into groups. Define them in _config.yml:

collections:
  guides:
    output: true
    permalink: "/:name/"
  reference:
    output: true
    permalink: "/:name/"

defaults:
  - scope:
      path: ""
    values:
      layout: default

Each collection becomes a folder (e.g., _guides/, _reference/) where you place your Markdown files. The permalink: "/:name/" setting gives each document a clean URL based on its filename.

Configure branding and data files

Theme behavior lives in _config.yml under jekyll_vitepress:

jekyll_vitepress:
  branding:
    site_title: My Project
  syntax:
    light_theme: github
    dark_theme: github.dark

Navigation and sidebar structure live in _data/ files. The navigation defines your top navbar links and maps them to collections (so the correct nav item highlights when viewing pages from those collections):

- title: Guide
  url: /getting-started/
  collections: [guides]
- title: Reference
  url: /api-reference/
  collections: [reference]

The sidebar defines the left-hand navigation groups. Each group pulls its entries from a collection, sorted by nav_order frontmatter:

- title: Guides
  collection: guides
- title: Reference
  collection: reference

Create your first page

Create a document inside one of your collection folders:

---
title: Introduction
nav_order: 1
---

Welcome to My Project! This is your first documentation page.

The nav_order value controls the sort order in the sidebar. Lower numbers appear first.

Run locally

bundle exec jekyll serve --livereload

Open http://127.0.0.1:4000 and you should see your site with the VitePress layout — top nav, sidebar, and your content in the center.