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, a persistent sidebar, Turbo-powered internal page changes, polished default styling, and optional features beyond baseline VitePress. See VitePress Parity and Extensions to VitePress for the full scope.

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. You should see the VitePress-style layout: top nav, sidebar, content area, right outline, local search, and fast doc-to-doc navigation. From there, enable the Jekyll-first extras documented in Extensions to VitePress as needed.