Overview

Jekyll VitePress Theme is distributed as a single gem with two jobs: it is a theme that provides layouts, includes, and assets, and it is a plugin that registers Jekyll hooks for build-time behavior.

That split keeps the runtime simple. Jekyll renders static HTML. The theme adds a small amount of JavaScript for UI behavior, including Turbo Frame navigation for doc-to-doc page changes.

Theme assets

The gem ships everything needed to render a VitePress-like site and then adds Jekyll-first features beyond baseline VitePress. See VitePress Parity and Extensions to VitePress for the full split:

  • Layouts (_layouts/default.html, _layouts/home.html) that compose the page structure: navbar, sidebar, content area, outline, and footer.
  • Includes for each UI component: navigation, search modal, sidebar, doc footer, and more.
  • Stylesheets (assets/css/) split into core layout styles, component styles, and token overrides.
  • JavaScript (assets/js/vitepress-theme.js) for interactive behavior: sidebar toggle, scroll-tracked outline, search modal, appearance switcher, code block copy buttons, page-level “Copy page”, and Turbo Frame refresh hooks.
  • Turbo runtime (assets/vendor/turbo.js) for fast internal docs navigation without a full page reload.

There is no app bundle to build. The shipped assets are plain HTML, CSS, JavaScript, and a vendored Turbo runtime.

Plugin behavior

The plugin side registers Jekyll hooks that run automatically at build time:

  • Last-updated timestamps: before each page renders, the plugin sets last_updated_at to the date of the last Git commit that touched the page’s source file, read from one git log pass per build. Untracked and locally edited files, and sites outside a Git repository, use the file’s modification time. This means your doc footers can show “Last updated” dates without you touching frontmatter manually.
  • Rouge syntax theme generation: after reading site config, the plugin validates your configured Rouge theme names and generates scoped CSS for light and dark modes. Invalid theme names fall back to defaults with a warning.
  • Version label resolution: if _data/versions.yml sets current: auto, the plugin replaces it with the gem’s version string (e.g., v1.0.0) at build time.
  • Copy page markdown export: before doc pages render, the plugin captures their raw Markdown for the “Copy page” button. After the site is written, it emits a plain .md sibling for each generated HTML doc page so “View as Markdown” works without external hosting assumptions. HTML in the page source, written inline or produced by includes, is converted to Markdown, and fenced code stays exactly as written. Disable this with jekyll_vitepress.copy_page.enabled: false.
  • SEO and discovery: each HTML page gets normalized search/social metadata and JSON-LD from the same canonical URL model used to generate sitemap.xml and robots.txt. The build excludes redirects, 404 pages, external-canonical duplicates, and noindex pages from the sitemap, and warns about missing or duplicate metadata.
  • LLM discovery: the plugin generates a concise llms.txt index and a complete llms-full.txt Markdown bundle from eligible pages and output collections. Both are theme-native and require no additional plugin.

VitePress parity scope

The project targets high visual and interaction parity with VitePress for the features that matter most in documentation:

  • Top nav, sidebar, local nav, and right outline
  • Fast internal page navigation with a persistent docs shell
  • Header anchors and scroll tracking
  • External link icons
  • Styled tables (striped rows, responsive scroll)
  • Custom containers (tip, warning, danger, info, and more)
  • Doc footer pager and edit-link support
  • Appearance switcher (auto, dark, light)
  • Code block copy buttons, language labels, title bars, and file icons
  • Rouge-native light/dark syntax themes
  • Automatic page title injection

It intentionally stays Jekyll-first for configuration and page authoring: no .vue files, no Vite config, and no frontmatter DSL that only exists in another toolchain.

For a detailed feature checklist, see VitePress Parity. For optional features added on top of baseline VitePress, see Extensions to VitePress.