Jekyll VitePress Theme

Ruby deserves beautiful docs. Jekyll VitePress Theme brings VitePress-level polish to Jekyll, then goes beyond it.

---

Ruby projects should not need to leave Ruby just to get documentation that feels designed.

jekyll-vitepress-theme brings VitePress-level documentation polish to Jekyll: a product-like homepage, familiar navigation, sidebars, outlines, search, dark mode, code blocks, callouts, and doc footers, packaged as a Ruby gem. It targets VitePress parity for the core docs experience and adds extensions to VitePress for Jekyll-first workflows.

The unusual part is navigation. Jekyll VitePress uses Turbo Frames like a Rails app, swapping only the content frame while the nav, sidebar, and shell stay in place. Page changes feel instant, while the output remains plain Jekyll: Markdown, Liquid, YAML, Ruby, and static files.

Why Use It

• VitePress polish for Jekyll: match VitePress for the docs homepage, sidebar, outline, search, dark mode, callouts, code blocks, and doc footers.
• Jekyll-native setup: keep your Markdown, Liquid, YAML, and static hosting. Add the gem, set a few options, and publish.
• Fast docs navigation: Turbo Frames update the content area while the nav, sidebar, and shell stay mounted.
• More than VitePress: add GitHub Star and Sponsor buttons, RubyGems downloads, versions, labels, generated local search, and Copy Page/View as Markdown for LLM workflows.
• Static Ruby output: build with Jekyll and deploy the generated HTML to GitHub Pages, any CDN, or any static host.

Quick Start

Add the gem:

gem "jekyll-vitepress-theme"

Enable the theme and plugin:

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

Add basic theme config:

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

Define navigation and sidebar data:

# _data/navigation.yml
- title: Guide
  url: /getting-started/
  collections: [guides]

# _data/sidebar.yml
- title: Guide
  collection: guides

Run Jekyll:

bundle install
bundle exec jekyll serve --livereload

Metadata and jekyll-seo-tag

The theme writes the page description, canonical link, Open Graph, and Twitter card tags itself. Calling {% seo %} as well emits a second copy of each, so drop it when you switch to this theme, or drop the theme's tags if you prefer jekyll-seo-tag's. Its JSON-LD has no equivalent here, so keep that plugin if you want structured data.

Screenshots

Home	Docs

Docs

Read the full documentation at jekyll-vitepress.dev.

Start here:

• Getting Started
• Configuration
• Navigation and Layout
• Search and Outline
• Configuration Reference
• VitePress Parity
• Extensions to VitePress

Development

bundle install
npm install
bundle exec jekyll serve --livereload

Run the tests:

bundle exec rake test

Run the full local verification suite (tests, linters, build, smoke test, gem build):

bundle exec rake verify

License

MIT