jekyll-vitepress-theme

KO | EN

gitlite — search

#python #react #java #golang #android #javascript #library #mysql #php #nodejs #aws #rust

jekyll-vitepress-theme

★ 60 Open GitHub ↗

Ruby deserves beautiful documentation. Jekyll VitePress Theme brings VitePress-level polish to Jekyll.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Jekyll VitePress Theme

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

[![Gem Version](https://img.shields.io/gem/v/jekyll-vitepress-theme.svg)](https://rubygems.org/gems/jekyll-vitepress-theme)
[![CI](https://github.com/crmne/jekyll-vitepress-theme/actions/workflows/main.yml/badge.svg)](https://github.com/crmne/jekyll-vitepress-theme/actions/workflows/main.yml)
[![Docs](https://img.shields.io/badge/docs-jekyll--vitepress.dev-blue)](https://jekyll-vitepress.dev)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/crmne/jekyll-vitepress-theme/master/LICENSE)

</div>

---

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](https://jekyll-vitepress.dev/vitepress-parity/) for the core docs experience and adds [extensions to VitePress](https://jekyll-vitepress.dev/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](https://jekyll-vitepress.dev/vitepress-parity/):** 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](https://jekyll-vitepress.dev/extensions-to-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:

```rb
gem "jekyll-vitepress-theme"
```

Enable the theme and plugin:

```yaml
theme: jekyll-vitepress-theme
plugins:
  - jekyll-vitepress-theme
```

Add basic theme config:

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

Define navigation and sidebar data:

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

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

Run Jekyll:

```sh
bundle install
bundle exec jekyll serve --livereload
```

## Screenshots

| Home | Docs |
| --- | --- |
| ![Home page in light mode](https://raw.githubusercontent.com/crmne/jekyll-vitepress-theme/master/assets/images/screenshots/home-light.png) | ![Docs page in light mode](https://raw.githubusercontent.com/crmne/jekyll-vitepress-theme/master/assets/images/screenshots/getting-started-light.png) |

## Docs

Read the full documentation at **[jekyll-vitepress.dev](https://jekyll-vitepress.dev)**.

Start here:

- [Getting Started](https://jekyll-vitepress.dev/getting-started/)
- [Configuration](https://jekyll-vitepress.dev/configuration/)
- [Navigation and Layout](https://jekyll-vitepress.dev/navigation-layout/)
- [Search and Outline](https://jekyll-vitepress.dev/search-and-outline/)
- [Configuration Reference](https://jekyll-vitepress.dev/configuration-reference/)
- [VitePress Parity](https://jekyll-vitepress.dev/vitepress-parity/)
- [Extensions to VitePress](https://jekyll-vitepress.dev/extensions-to-vitepress/)

## Development

```sh
bundle install
npm install
bundle exec jekyll serve --livereload
```

Run the tests:

```sh
bundle exec rake test
```

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

```sh
bundle exec rake verify
```

## License

MIT

jekyll-vitepress-theme

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README