Jekyll VitePress

https://jekyll-vitepress.dev
Admin
Jekyll VitePress is a Jekyll theme and plugin that brings VitePress's polished documentation...
Tokens:10,871
Snippets:122
Trust Score:2.5
Update:7 months ago
Show doc for...
Tokens:
Raw
### 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
<div class="my-feedback">
  Was this page helpful?
  <a href="/feedback/">Let us know</a>.
</div>
```

--------------------------------

### 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
<!-- _includes/jekyll_vitepress/doc_footer_end.html -->
<div class="my-doc-footer">
  Need help? <a href="/support/">Contact support</a>.
</div>
```

--------------------------------

### 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 `<head>` 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
<!-- _includes/jekyll_vitepress/head_end.html -->
<!-- Add your custom head content here -->
```

--------------------------------

### 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
<!-- _includes/jekyll_vitepress/doc_footer_end.html -->
<!-- Add your custom doc footer content here -->
```

--------------------------------

### 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 `</body>` tag. Create the `_includes/jekyll_vitepress/layout_end.html` file for scripts or other end-of-body elements.

```html
<!-- _includes/jekyll_vitepress/layout_end.html -->
<!-- Add your custom layout end content here -->
```

--------------------------------

### 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
<link rel="stylesheet" href="/assets/css/custom.css">
<script src="/assets/js/custom.js" defer></script>
```

--------------------------------

### Jekyll VitePress: Markdown in Alert Block Content (Liquid)

Source: https://jekyll-vitepress.dev/custom-blocks

Illustrates the support for inline Markdown within the `content` parameter of the `alert.html` include. This enables the use of code snippets, links, bold text, and other Markdown features directly within the callout block, enhancing readability and detail.

```liquid
{% include alert.html type="tip" content="Set `layout: home` in your frontmatter. See the [Frontmatter Reference](/frontmatter-reference/) for details." %}

```

--------------------------------

### Define Social Links (_data/social_links.yml)

Source: https://jekyll-vitepress.dev/configuration-reference

Specifies social media links to be displayed, including an icon (either built-in or custom SVG), the URL, and an ARIA label for accessibility. Supports various built-in icon slugs.

```yaml
- icon: github
  url: https://github.com/you/project
  label: GitHub
- icon: x
  url: https://x.com/you
  label: X
- icon: custom
  url: https://bsky.app/profile/you
  label: Bluesky
  icon_svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path d="M12 11.388c0-.756 1.676-3.35 3.43-4.594 2.296-1.627 3.726-1.348 4.3-.225.672 1.316-.53 4.77-2.257 6.48-.958.949-1.786 1.433-2.84 1.356-.67-.05-1.167-.35-1.586-.824-.49-.554-.732-1.346-1.047-2.193-.315.847-.557 1.64-1.047 2.193-.419.474-.916.775-1.586.824-1.054.077-1.882-.407-2.84-1.356C5.8 11.339 4.6 7.885 5.271 6.57c.574-1.124 2.004-1.402 4.3.225 1.754 1.243 3.43 3.838 3.43 4.594Z"/></svg>'
```

--------------------------------

### Customize Typography and CSS Tokens

Source: https://jekyll-vitepress.dev/configuration

Customize fonts by providing a Google Fonts URL and font family names. Override VitePress CSS variables for branding in light and dark modes. Set `google_fonts_url: false` to disable external font loading.

```yaml
jekyll_vitepress:
  typography:
    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"
    body_font_family: "'Inter', ui-sans-serif, system-ui, sans-serif"
    code_font_family: "'JetBrains Mono', ui-monospace, monospace"

  tokens:
    light:
      --vp-c-brand-1: "#3451b2"
    dark:
      --vp-c-brand-1: "#a8b1ff"
```

--------------------------------

### Customize Previous and Next Links (YAML)

Source: https://jekyll-vitepress.dev/frontmatter-reference

Overrides the default previous and next navigation links in Jekyll VitePress. This frontmatter allows you to specify custom text and URLs for the pager, providing more control over user navigation between pages. This is useful for creating non-sequential or specially linked content.

```yaml
jekyll_vitepress:
  prev:
    text: Custom previous title
    link: /some/page/
  next:
    text: Custom next title
    link: /another/page/

```

--------------------------------

### Configure Fonts in Jekyll VitePress

Source: https://jekyll-vitepress.dev/customizing-styles

Set custom font stacks for body and code text, and specify a Google Fonts URL for loading external fonts in Jekyll VitePress. Set `google_fonts_url` to `false` to disable external font loading and rely on system fonts or self-hosted fonts.

```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"

```

--------------------------------

### Jekyll VitePress: Customizing Alert Block Titles (Liquid)

Source: https://jekyll-vitepress.dev/custom-blocks

Shows how to override the default title of an alert block using the `title` parameter. This allows for more specific and context-aware labeling of warnings, tips, or other important information. The `content` parameter still processes Markdown.

```liquid
{% include alert.html type="warning" title="Breaking Change" content="The `foo` option was removed in v2.0." %}

```

--------------------------------

### Custom Heading ID with Anchor Link (Markdown)

Source: https://jekyll-vitepress.dev/markdown-extensions

Demonstrates how to assign a custom ID to a Markdown heading, which automatically generates a clickable anchor link. This allows users to link directly to specific sections of a page.

```markdown
## My Custom Section {#custom-id}

```

--------------------------------

### Add Title Bar to Code Block with Kramdown IAL

Source: https://jekyll-vitepress.dev/code-blocks

Illustrates how to add a title bar to a code block using Kramdown's Inline Attribute List (IAL) syntax. The `data-title` attribute specifies the filename to be displayed in the title bar.

```markdown
```ruby
class WeatherTool
  def call(city:)
    "sunny in #{city}"
  end
end
```
{: data-title="app/tools/weather_tool.rb"}
```

--------------------------------

### Override Brand Colors in Jekyll VitePress

Source: https://jekyll-vitepress.dev/customizing-styles

Customize brand colors for both light and dark modes by overriding VitePress CSS variables in the `_config.yml` file. These tokens affect various accent elements like links and buttons. The numbered variants control different states such as primary, hover, and active.

```yaml
jekyll_vitepress:
  tokens:
    light:
      --vp-c-brand-1: "#3451b2"
      --vp-c-brand-2: "#3a5ccc"
      --vp-c-brand-3: "#2f4bab"
    dark:
      --vp-c-brand-1: "#a8b1ff"
      --vp-c-brand-2: "#bac2ff"
      --vp-c-brand-3: "#939eff"

```
Tokens:
Raw