### Run Jekyll Locally
Source: https://jekyll-vitepress.dev/getting-started
Start the Jekyll development server with live reloading enabled.
```sh
bundle exec jekyll serve --livereload
```
--------------------------------
### Install Jekyll VitePress Theme
Source: https://jekyll-vitepress.dev/getting-started
Add the theme to your project's Gemfile and install the dependencies using Bundler.
```ruby
gem "jekyll-vitepress-theme"
```
```sh
bundle install
```
--------------------------------
### Create Documentation Page
Source: https://jekyll-vitepress.dev/getting-started
Create a Markdown file within a collection folder using frontmatter to define the title and navigation order.
```markdown
---
title: Introduction
nav_order: 1
---
Welcome to My Project! This is your first documentation page.
```
--------------------------------
### Define Jekyll Collections
Source: https://jekyll-vitepress.dev/getting-started
Set up documentation collections in _config.yml to organize content into groups with custom permalinks.
```yaml
collections:
guides:
output: true
permalink: "/:name/"
reference:
output: true
permalink: "/:name/"
defaults:
- scope:
path: ""
values:
layout: default
```
--------------------------------
### Define Navigation and Sidebar
Source: https://jekyll-vitepress.dev/getting-started
Configure top-level navigation and sidebar groupings using YAML files in the _data directory.
```yaml
# _data/navigation.yml
- title: Guide
url: /getting-started/
collections: [guides]
- title: Reference
url: /api-reference/
collections: [reference]
# _data/sidebar.yml
- title: Guides
collection: guides
- title: Reference
collection: reference
```
--------------------------------
### Configure Jekyll Theme and Plugins
Source: https://jekyll-vitepress.dev/getting-started
Enable the theme and plugin functionality within your _config.yml file.
```yaml
theme: jekyll-vitepress-theme
plugins:
- jekyll-vitepress-theme
```
--------------------------------
### Configure Minimal Jekyll VitePress Setup
Source: https://jekyll-vitepress.dev/configuration-reference
Defines the basic site title in _config.yml and sets up initial navigation and sidebar structures in the _data directory.
```yaml
# _config.yml
jekyll_vitepress:
branding:
site_title: My Docs
```
```yaml
# _data/navigation.yml
- title: Guide
url: /getting-started/
collections: [introduction, core_features, advanced]
```
```yaml
# _data/sidebar.yml
- title: Getting Started
collection: introduction
```
--------------------------------
### Configure Theme Branding and Syntax
Source: https://jekyll-vitepress.dev/getting-started
Customize site branding and syntax highlighting themes in the jekyll_vitepress configuration block.
```yaml
jekyll_vitepress:
branding:
site_title: My Project
syntax:
light_theme: github
dark_theme: github.dark
```
--------------------------------
### Example Code Blocks with Title Bars
Source: https://jekyll-vitepress.dev/code-blocks
Provides examples of code blocks with title bars, showcasing different programming languages and their inferred file types. This utilizes the Kramdown IAL syntax for specifying the title.
```ruby
class WeatherTool
def call(city:)
"sunny in #{city}"
end
end
```
```typescript
export function formatDate(input: string): string {
return new Date(input).toISOString()
}
```
```yaml
jekyll_vitepress:
branding:
site_title: My Docs
```
--------------------------------
### Internal Link Examples (Markdown)
Source: https://jekyll-vitepress.dev/markdown-extensions
Shows two methods for creating internal links in Markdown: using standard relative or absolute paths, and using Jekyll's `{% link %}` tag. The `{% link %}` tag provides build-time validation for link existence.
```markdown
[Getting Started](/getting-started/)
[Configuration]({% link _reference/configuration-reference.md %})
```
--------------------------------
### Basic Markdown Fenced Code Block Example
Source: https://jekyll-vitepress.dev/code-blocks
Demonstrates a standard Markdown fenced code block with a language specifier. VitePress automatically adds a copy button and a language label to such blocks.
```markdown
```ruby
puts "Hello, world!"
```
```
--------------------------------
### Inject custom content via hook includes
Source: https://jekyll-vitepress.dev/extending-behavior
Demonstrates how to add custom markup to specific theme injection points like the document footer. This example adds a feedback prompt by creating a file at _includes/jekyll_vitepress/doc_footer_end.html.
```html
```
--------------------------------
### Markdown Table with Column Alignment (Markdown)
Source: https://jekyll-vitepress.dev/markdown-extensions
Provides an example of a Markdown table demonstrating column alignment using the standard colon syntax. This allows for left, center, or right alignment of text within table columns.
```markdown
| Left | Center | Right |
|:-----|:------:|------:|
| a | b | c |
```
--------------------------------
### Inject Custom Markup in Footer (_includes/jekyll_vitepress/doc_footer_end.html)
Source: https://jekyll-vitepress.dev/configuration-reference
An example of a theme hook that allows injecting custom HTML markup at the end of the documentation footer. This file can be overridden to add site-specific content like support links.
```html
```
--------------------------------
### Deploy Jekyll site with GitHub Actions
Source: https://jekyll-vitepress.dev/deployment
A minimal GitHub Actions workflow configuration to build and deploy a Jekyll site to GitHub Pages. It utilizes official actions to handle the build process and deployment to the gh-pages branch.
```yaml
- uses: actions/jekyll-build-pages@v1
- uses: actions/deploy-pages@v4
```
--------------------------------
### Configure Home Layout with Hero and Features (YAML)
Source: https://jekyll-vitepress.dev/frontmatter-reference
Defines the frontmatter for a home page using the 'home' layout. It includes configuration for a hero section with text, images, and action buttons, as well as a list of features with icons, titles, and optional links. This configuration is specific to the VitePress-style landing page.
```yaml
layout: home
hero:
name: Project Name
text: Project Tagline
tagline: Supporting sentence
image:
src: /path/to/image.svg
alt: Logo
width: 320
height: 320
actions:
- theme: brand
text: Get Started
link: /getting-started/
- theme: alt
text: GitHub
link: https://github.com/you/project
features:
- icon: ⚡
title: Fast
details: Feature description
link_text: Learn more
link: /getting-started/
```
--------------------------------
### Configure Footer and Doc Footer
Source: https://jekyll-vitepress.dev/configuration-reference
Controls the visibility and content of the global footer and the navigation footer on documentation pages.
```yaml
jekyll_vitepress:
footer:
enabled: true
message: Released under the MIT License.
copyright: © 2026-present You
show_on_docs: false
doc_footer:
enabled: true
previous_label: Previous page
next_label: Next page
```
--------------------------------
### Configure Branding and Syntax Highlighting
Source: https://jekyll-vitepress.dev/configuration
Set the site title, logo for different modes, and syntax highlighting themes. The theme automatically generates scoped CSS for light and dark modes using Rouge themes.
```yaml
jekyll_vitepress:
branding:
site_title: Your Project
logo:
default: /assets/images/logo.svg
light: /assets/images/logo-light.svg
dark: /assets/images/logo-dark.svg
alt: Your Project
width: 24
height: 24
syntax:
light_theme: github
dark_theme: github.dark
```
--------------------------------
### Configure Syntax Highlighting Themes in `_config.yml`
Source: https://jekyll-vitepress.dev/code-blocks
Shows how to configure light and dark syntax highlighting themes for code blocks in the `_config.yml` file. The plugin uses Rouge themes and falls back to 'github'/'github.dark' if an invalid theme is specified.
```yaml
jekyll_vitepress:
syntax:
light_theme: github
dark_theme: github.dark
```
--------------------------------
### Enable Edit Link
Source: https://jekyll-vitepress.dev/configuration
Configure an edit link in the doc footer to point users to the source file on GitHub. The `:path` placeholder is replaced with the source file’s path at build time. This is configured in `_config.yml`.
```yaml
jekyll_vitepress:
edit_link:
enabled: true
pattern: "https://github.com/you/project/edit/main/:path"
text: Edit this page on GitHub
```
--------------------------------
### Enable GitHub Star Button
Source: https://jekyll-vitepress.dev/configuration
Display a GitHub star button with a live count in the navbar. Configure the repository and text. This is enabled in `_config.yml`.
```yaml
jekyll_vitepress:
github_star:
enabled: true
repository: you/project
text: Star
show_count: true
```
--------------------------------
### Configure Typography and CSS Tokens
Source: https://jekyll-vitepress.dev/configuration-reference
Customizes font families and CSS variables for light and dark themes to match brand identity.
```yaml
jekyll_vitepress:
typography:
body_font_family: "'Inter', ui-sans-serif, system-ui, sans-serif"
code_font_family: "'JetBrains Mono', ui-monospace, monospace"
google_fonts_url: "https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap"
tokens:
light:
--vp-c-brand-1: "#3451b2"
--vp-c-brand-2: "#3a5ccc"
dark:
--vp-c-brand-1: "#a8b1ff"
--vp-c-brand-2: "#bac2ff"
```
--------------------------------
### Define Navigation Links
Source: https://jekyll-vitepress.dev/configuration
Configure navigation links for the top navbar. Each link includes a title, URL, and a list of collections it represents, which controls sidebar highlighting. Navigation links are defined in `_data/navigation.yml`.
```yaml
- title: Guide
url: /what-is-jekyll-vitepress-theme/
collections: [introduction, core_features, advanced]
- title: Reference
url: /configuration-reference/
collections: [reference]
```
--------------------------------
### Configure Version Selector
Source: https://jekyll-vitepress.dev/configuration
If `_data/versions.yml` exists, a version selector dropdown is rendered in the navbar. Set `current: auto` to automatically resolve to the gem version. External links can also be specified.
```yaml
current: auto
items:
- title: v1.0.0 (current)
url: /
- title: Changelog
url: https://github.com/you/project/releases
external: true
```
--------------------------------
### Configure Labels and UI Behavior
Source: https://jekyll-vitepress.dev/configuration-reference
Customizes UI labels for navigation elements and defines scroll behavior offsets.
```yaml
jekyll_vitepress:
labels:
outline: On this page
sidebar_menu: Menu
return_to_top: Return to top
skip_to_content: Skip to content
appearance_menu: Appearance
switch_to_dark: Switch to dark theme
switch_to_light: Switch to light theme
behavior:
scroll_offset: 134
```
--------------------------------
### Configure Edit Link, Last Updated, and GitHub Star
Source: https://jekyll-vitepress.dev/configuration-reference
Enables social and maintenance features including GitHub edit links, timestamps, and repository star counts.
```yaml
jekyll_vitepress:
edit_link:
enabled: true
pattern: "https://github.com/you/project/edit/main/docs/:path"
text: Edit this page on GitHub
last_updated:
enabled: true
text: Last updated
format: "%-d %b %Y, %H:%M"
github_star:
enabled: true
repository: you/project
text: Star
show_count: true
```
--------------------------------
### Jekyll VitePress: Basic Alert Block Syntax (Liquid)
Source: https://jekyll-vitepress.dev/custom-blocks
Demonstrates the basic syntax for including an alert block using the `alert.html` include. The `type` parameter controls the block's appearance and default title, while the `content` parameter accepts Markdown for rich text formatting. This is a core feature for creating styled callouts.
```liquid
{% include alert.html type="tip" content="This is a helpful tip." %}
```
--------------------------------
### Top Navigation Configuration (_data/navigation.yml)
Source: https://jekyll-vitepress.dev/navigation-layout
Configures the top navigation bar links, including their titles, URLs, and associated collections for highlighting active links. The 'collections' array determines which nav link remains active for pages within those collections.
```yaml
- title: Guide
url: /introduction/
collections: [introduction, core_features, advanced]
- title: Reference
url: /configuration-reference/
collections: [reference]
```
--------------------------------
### GitHub-Flavored Markdown Table with Styling (Markdown)
Source: https://jekyll-vitepress.dev/markdown-extensions
Illustrates the creation of a standard GitHub-flavored Markdown table. These tables are automatically styled by the theme with striped rows, borders, and horizontal scrolling on smaller screens.
```markdown
| Feature | Status | Notes |
|----------------|-----------|-------------------|
| Header anchors | Automatic | No config needed |
| External links | Automatic | Arrow icon added |
| Tables | Automatic | Striped rows |
```
--------------------------------
### Sidebar Configuration (_data/sidebar.yml)
Source: https://jekyll-vitepress.dev/navigation-layout
Defines the structure of the sidebar navigation by specifying titles and corresponding Jekyll collections. Documents within each collection are sorted by 'nav_order'.
```yaml
- title: Introduction
collection: introduction
- title: Core Features
collection: core_features
```
--------------------------------
### Inject Custom Head Tags
Source: https://jekyll-vitepress.dev/configuration
Inject custom markup into the `` section of your site using include files. This is useful for analytics, verification meta tags, or extra fonts. Create `_includes/jekyll_vitepress/head_end.html`.
```html
```
--------------------------------
### Inject Custom Doc Footer Content
Source: https://jekyll-vitepress.dev/configuration
Append custom markup after the documentation footer. Create the `_includes/jekyll_vitepress/doc_footer_end.html` file to add content like custom links or notes.
```html
```
--------------------------------
### Configure Sidebar Navigation (_data/sidebar.yml)
Source: https://jekyll-vitepress.dev/configuration-reference
Defines the structure and content of the sidebar navigation in the Jekyll VitePress theme. It uses a collection-driven approach, where each item links to a specific collection for content.
```yaml
- title: Introduction
collection: introduction
- title: Core Features
collection: core_features
- title: Advanced
collection: advanced
- title: Reference
collection: reference
```
--------------------------------
### Jekyll Page Frontmatter Configuration (YAML)
Source: https://jekyll-vitepress.dev/markdown-extensions
Shows the essential YAML frontmatter required for a Jekyll page, including `title`, `nav_order`, and `description`. These metadata fields are used for page titles, navigation ordering, and search/meta descriptions.
```yaml
---
title: My Page
nav_order: 1
description: A brief description for search and meta tags.
---
```
--------------------------------
### Add Social Links
Source: https://jekyll-vitepress.dev/configuration
Add social icons to the top navbar. Use built-in icon slugs or provide custom inline SVG. Social links are defined in `_data/social_links.yml`.
```yaml
- icon: github
url: https://github.com/you/project
label: GitHub
- icon: x
url: https://x.com/you
label: X
```
--------------------------------
### Inject Custom Layout End Content
Source: https://jekyll-vitepress.dev/configuration
Inject custom markup just before the closing `` tag. Create the `_includes/jekyll_vitepress/layout_end.html` file for scripts or other end-of-body elements.
```html
```
--------------------------------
### Add custom CSS and JS via head_end hook
Source: https://jekyll-vitepress.dev/extending-behavior
Shows how to include site-specific stylesheets and scripts by overriding the _includes/jekyll_vitepress/head_end.html file. This ensures assets are loaded within the document head.
```html