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.
Search and AI discovery by default: ship canonical metadata, social cards, JSON-LD, nested breadcrumbs, sitemap, robots controls, llms.txt, and llms-full.txt without another discovery plugin.
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

SEO is built in

Every site using the theme gets one consistent set of search and social metadata, JSON-LD (WebSite, WebPage or Article, Organization/Person, image, and nested breadcrumbs), sitemap.xml, and robots.txt. Canonical overrides, noindex, language alternates, social images, authors, publishers, and webmaster verification tokens are configurable without another plugin.

Set at least title, description, and an absolute production url in _config.yml. The build warns about missing and duplicate metadata. Do not also render {% seo %} or enable another sitemap/robots generator; that creates duplicated or contradictory signals.

LLM discovery is built in

The theme also creates /llms.txt, a concise canonical documentation index, and /llms-full.txt, a single Markdown bundle containing every eligible page and collection document. Redirects, 404 pages, noindex pages, and external-canonical duplicates are excluded. Both files understand baseurl and can be configured or disabled without jekyll-ai-visible-content.

Screenshots

Home	Docs

Docs

Read the full documentation at jekyll-vitepress.dev.

Start here:

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