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 (Dark)

Getting Started (Light)

Getting Started (Dark)

Installation

1. Add the gem to your Gemfile:

gem "jekyll-vitepress-theme"

2. Enable it in _config.yml:

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

3. Add theme behavior config in _config.yml:

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

4. 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:

• Getting Started
• Configuration Reference
• Frontmatter Reference
• VitePress Parity and Extensions

Release a gem

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

License

MIT