VitePress Parity and Extensions

This theme targets high visual and interaction parity with VitePress, while keeping configuration and authoring idiomatic to Jekyll. Here’s what maps directly, what’s intentionally different, and what’s been added on top.

VitePress parity targets

The theme intentionally mirrors these VitePress features:

  • Top nav, mobile nav screen, and social links
  • Left sidebar + right outline behavior
  • Home layout structure (hero + feature cards)
  • Doc footer behavior (edit link, previous/next pager, last-updated label)
  • Appearance switcher (auto → dark → light)
  • Search trigger UX (/, Ctrl/Cmd+K)
  • Code block UX (copy buttons, language labels, file title bars with icons)
  • Header anchors on all headings
  • External link icons (arrow indicator on outbound links)
  • Table styling (striped rows, bordered cells, responsive scroll)
  • Custom containers (tip, warning, danger, info, note, important, caution, details)
  • Automatic page title injection

Jekyll-first differences (intentional)

These are deliberate departures from VitePress internals. The functionality is equivalent, but the implementation uses Jekyll conventions:

  • Configuration lives in _config.yml under jekyll_vitepress instead of a .vitepress/config.js file
  • Nav, sidebar, social, and version data live in _data/*.yml instead of being defined in JavaScript
  • Syntax highlighting uses Rouge themes instead of Shiki
  • Last-updated timestamps are populated via Jekyll plugin hooks instead of Git history
  • Extension points are include hooks (_includes/jekyll_vitepress/*.html) instead of Vue slots

Extras added on top

These features are not part of baseline VitePress but are included as optional extras:

  • GitHub star widget — a navbar button showing live star count from the GitHub API, configured via jekyll_vitepress.github_star
  • Local search index — a simple client-side search built from search.json, generated at build time from sidebar collection content
  • Version selector — a data-driven dropdown from _data/versions.yml with current: auto support for automatic version label resolution

Practical guidance

If you want output that looks as close to VitePress as possible, keep the optional extras disabled and rely on the default structure and styling.

If you want productized docs behavior beyond what VitePress ships out of the box, enable extras case by case in _config.yml. Each extra is independent — you can use the GitHub star widget without the version selector, or the search without either.