Jekyll VitePress Theme

A reusable Jekyll theme gem that reproduces the VitePress default docs experience.

What it includes

  • VitePress-style layout structure (top nav, sidebar, outline, doc footer)
  • Appearance toggle with auto -> dark -> light
  • Local search modal (/, Ctrl/Cmd+K, Cmd+K)
  • Automatic /search.json generation for the home page and sidebar collections
  • Optional GitHub star button with live count (jekyll_vitepress.github_star)
  • Code block copy button, language labels, file-title bars and icons
  • Page-level "Copy page" split button with raw Markdown copy + plain .md view (jekyll_vitepress.copy_page, enabled by default)
  • Rouge-native syntax theme config (jekyll_vitepress.syntax.light_theme/dark_theme)
  • Last-updated hook via plugin
  • Jekyll-native extension hooks (_includes/jekyll_vitepress/head_end.html, doc_footer_end.html, layout_end.html)

Screenshots

Home (Light)

Home light mode

Home (Dark)

Home dark mode

Getting Started (Light)

Getting Started light mode

Getting Started (Dark)

Getting Started dark mode

Installation

  1. Add the gem to your Gemfile:
gem "jekyll-vitepress-theme"
  1. Enable it in _config.yml:
theme: jekyll-vitepress-theme
plugins:
  - jekyll-vitepress-theme
  1. Add theme behavior config in _config.yml:
jekyll_vitepress:
  branding:
    site_title: My Docs
  syntax:
    light_theme: github
    dark_theme: github.dark
  1. Add navigation and sidebar data files:
# _data/navigation.yml
- title: Guide
  url: /getting-started/
  collections: [introduction, core_features, advanced]

# _data/sidebar.yml
- title: Getting Started
  collection: introduction

Local development (this repo)

bundle install
npm install
bundle exec jekyll serve --livereload

Open http://127.0.0.1:4000.

Local Quality Gates

# one-shot verification
bundle exec rake verify

# regenerate built-in social icon assets after changing icon list
npm run build:social-icons

# install and run git hooks
bundle exec overcommit --install
bundle exec overcommit --sign pre-commit
bundle exec overcommit --sign pre-push
bundle exec overcommit --run

Docs deployment (this repo)

  • master deploys a single docs site at /
  • No secondary version paths are published in default mode (/latest/, /v/*, /next/)
  • Optional multi-version deployment is documented in _advanced/deployment.md

Theme configuration

See docs pages:

Release a gem

gem build jekyll-vitepress-theme.gemspec
gem push jekyll-vitepress-theme-<version>.gem

License

MIT