jekyll-vitepress-theme 0.9.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b16443ae3825807e971321a1c4492381c0f87e0e45e990c71189ab42dfed67ec
+  data.tar.gz: 87acf037fa7f85bbfda93cee166d5788f0c4a1e82c4183acbbfc4bd8c65c90ab
+SHA512:
+  metadata.gz: a745075f8f8ce30ab015f96eb5acf3fa2f82a5860f311e6775fadf9078b170698592687c52913753192b0be4bcc9ad5ad1d795b09e895bad2b513a7654b53b10
+  data.tar.gz: b5288a28f63ca4725bdbb0e1f3334db18bdb96f8588f6504436daca4bcb596ab45ec53e66656853ab112c0b0dbb08830c53da0868212a8081107644bc90d514d

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carmine Paolino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,93 @@
+# Jekyll VitePress Theme
+
+A reusable Jekyll theme gem that reproduces the VitePress default docs experience.
+
+## What it includes
+
+- VitePress-style layout structure (top nav, sidebar, outline, doc footer)
+- Appearance toggle with `auto -> dark -> light`
+- Local search modal (`/`, `Ctrl/Cmd+K`, `Cmd+K`)
+- Code block copy button, language labels, file-title bars and icons
+- Rouge-native syntax theme config (`vp_theme.rouge_theme.light/dark`)
+- Last-updated hook via plugin
+- Slot includes for lightweight theme extension (`_includes/vp_slots/head.html`, `doc_footer.html`, `layout_bottom.html`)
+
+## Installation
+
+1. Add the gem to your `Gemfile`:
+
+```ruby
+gem "jekyll-vitepress-theme"
+```
+
+2. Enable it in `_config.yml`:
+
+```yaml
+theme: jekyll-vitepress-theme
+plugins:
+  - jekyll-vitepress-theme
+```
+
+3. Add `vp_theme` configuration:
+
+```yaml
+vp_theme:
+  nav:
+    - text: Guide
+      link: /what-is-jekyll-vitepress-theme/
+      collections: [getting_started, core_features, advanced]
+  sidebar_collections:
+    - id: getting_started
+      text: Introduction
+```
+
+## Local development (this repo)
+
+```bash
+bundle install
+npm install
+bundle exec jekyll serve --livereload
+```
+
+Open `http://127.0.0.1:4000`.
+
+## Local Quality Gates
+
+```bash
+# one-shot verification
+bundle exec rake verify
+
+# regenerate built-in social icon assets after changing icon list
+npm run build:social-icons
+
+# install and run git hooks
+bundle exec overcommit --install
+bundle exec overcommit --sign pre-commit
+bundle exec overcommit --sign pre-push
+bundle exec overcommit --run
+```
+
+## Docs versioning (this repo)
+
+- `main` deploys unreleased docs to `/next/`
+- `main` runs a release gate; when the gem version is unpublished, release docs deploy to `/v/x.y.z/` and refresh `/latest/`
+- `gh-pages/versions.yml` is the single source of truth for the version selector
+
+## Theme configuration
+
+See docs pages:
+
+- [Getting Started](/getting-started/)
+- [Configuration Reference](/configuration-reference/)
+- [Frontmatter Reference](/frontmatter-reference/)
+
+## Release a gem
+
+```bash
+gem build jekyll-vitepress-theme.gemspec
+gem push jekyll-vitepress-theme-<version>.gem
+```
+
+## License
+
+MIT

data/_includes/doc_footer.html

@@ -0,0 +1,184 @@
+{% assign edit_link_enabled = true %}
+{% if site.vp_theme.edit_link == false or page.edit_link == false %}
+  {% assign edit_link_enabled = false %}
+{% endif %}
+
+{% assign edit_link = nil %}
+{% if edit_link_enabled and site.vp_theme.edit_link and site.vp_theme.edit_link.pattern and page.path %}
+  {% assign edit_link = site.vp_theme.edit_link.pattern | replace: ':path', page.path %}
+{% endif %}
+
+{% assign edit_link_text = 'Edit this page on GitHub' %}
+{% if site.vp_theme.edit_link and site.vp_theme.edit_link.text %}
+  {% assign edit_link_text = site.vp_theme.edit_link.text %}
+{% endif %}
+
+{% assign last_updated_enabled = true %}
+{% if site.vp_theme.last_updated == false or page.last_updated == false %}
+  {% assign last_updated_enabled = false %}
+{% endif %}
+
+{% assign last_updated_text = 'Last updated' %}
+{% if site.vp_theme.last_updated and site.vp_theme.last_updated.text %}
+  {% assign last_updated_text = site.vp_theme.last_updated.text %}
+{% endif %}
+
+{% assign last_updated_format = '%-d %b %Y, %H:%M' %}
+{% if site.vp_theme.last_updated and site.vp_theme.last_updated.format %}
+  {% assign last_updated_format = site.vp_theme.last_updated.format %}
+{% endif %}
+
+{% assign last_updated_at = page.last_updated_at | default: page.last_updated | default: nil %}
+{% assign show_last_updated = false %}
+{% if last_updated_enabled and last_updated_at %}
+  {% assign show_last_updated = true %}
+{% endif %}
+
+{% assign prev_doc = nil %}
+{% assign next_doc = nil %}
+{% if page.collection %}
+  {% assign docs = site[page.collection] | sort: 'nav_order' %}
+  {% assign found_current = false %}
+  {% for doc in docs %}
+    {% if found_current and next_doc == nil %}
+      {% assign next_doc = doc %}
+    {% endif %}
+
+    {% if doc.url == page.url %}
+      {% assign found_current = true %}
+    {% elsif found_current == false %}
+      {% assign prev_doc = doc %}
+    {% endif %}
+  {% endfor %}
+{% endif %}
+
+{% assign doc_footer_enabled = true %}
+{% if site.vp_theme.doc_footer == false or page.doc_footer == false %}
+  {% assign doc_footer_enabled = false %}
+{% endif %}
+
+{% assign prev_enabled = doc_footer_enabled %}
+{% assign next_enabled = doc_footer_enabled %}
+{% assign prev_desc = 'Previous page' %}
+{% assign next_desc = 'Next page' %}
+
+{% if site.vp_theme.doc_footer and site.vp_theme.doc_footer != false %}
+  {% if site.vp_theme.doc_footer.prev == false %}
+    {% assign prev_enabled = false %}
+  {% elsif site.vp_theme.doc_footer.prev %}
+    {% assign prev_desc = site.vp_theme.doc_footer.prev %}
+  {% endif %}
+
+  {% if site.vp_theme.doc_footer.next == false %}
+    {% assign next_enabled = false %}
+  {% elsif site.vp_theme.doc_footer.next %}
+    {% assign next_desc = site.vp_theme.doc_footer.next %}
+  {% endif %}
+{% endif %}
+
+{% if page.doc_footer and page.doc_footer != false %}
+  {% if page.doc_footer.prev == false %}
+    {% assign prev_enabled = false %}
+  {% elsif page.doc_footer.prev %}
+    {% assign prev_desc = page.doc_footer.prev %}
+  {% endif %}
+
+  {% if page.doc_footer.next == false %}
+    {% assign next_enabled = false %}
+  {% elsif page.doc_footer.next %}
+    {% assign next_desc = page.doc_footer.next %}
+  {% endif %}
+{% endif %}
+
+{% if page.prev == false %}
+  {% assign prev_enabled = false %}
+{% endif %}
+
+{% if page.next == false %}
+  {% assign next_enabled = false %}
+{% endif %}
+
+{% assign prev_url = nil %}
+{% assign prev_title = nil %}
+{% assign next_url = nil %}
+{% assign next_title = nil %}
+
+{% if prev_enabled %}
+  {% if page.prev and page.prev != false and page.prev.link %}
+    {% assign prev_url = page.prev.link %}
+    {% assign prev_title = page.prev.text | default: page.prev.link %}
+  {% elsif prev_doc %}
+    {% assign prev_url = prev_doc.url | relative_url %}
+    {% assign prev_title = prev_doc.title %}
+  {% endif %}
+{% endif %}
+
+{% if next_enabled %}
+  {% if page.next and page.next != false and page.next.link %}
+    {% assign next_url = page.next.link %}
+    {% assign next_title = page.next.text | default: page.next.link %}
+  {% elsif next_doc %}
+    {% assign next_url = next_doc.url | relative_url %}
+    {% assign next_title = next_doc.title %}
+  {% endif %}
+{% endif %}
+
+{% assign show_prev_link = false %}
+{% assign show_next_link = false %}
+{% if prev_url and prev_title %}
+  {% assign show_prev_link = true %}
+{% endif %}
+{% if next_url and next_title %}
+  {% assign show_next_link = true %}
+{% endif %}
+
+{% assign show_footer = false %}
+{% if edit_link or show_last_updated or show_prev_link or show_next_link %}
+  {% assign show_footer = true %}
+{% endif %}
+
+{% if show_footer %}
+  <footer class="VPDocFooter">
+    {% if edit_link or show_last_updated %}
+      <div class="edit-info">
+        {% if edit_link %}
+          <div class="edit-link">
+            <a class="VPLink link vp-external-link-icon no-icon edit-link-button" href="{{ edit_link }}" target="_blank" rel="noreferrer">
+              <span class="vpi-square-pen edit-link-icon"></span>
+              {{ edit_link_text }}
+            </a>
+          </div>
+        {% endif %}
+        {% if show_last_updated %}
+          <div class="last-updated">
+            <p class="VPLastUpdated">{{ last_updated_text }}: <time datetime="{{ last_updated_at | date_to_xmlschema }}" lang="{{ site.lang | default: 'en-US' }}">{{ last_updated_at | date: last_updated_format }}</time></p>
+          </div>
+        {% endif %}
+      </div>
+    {% endif %}
+
+    {% if show_prev_link or show_next_link %}
+      <nav class="prev-next" aria-labelledby="doc-footer-aria-label">
+        <span class="visually-hidden" id="doc-footer-aria-label">Pager</span>
+
+        <div class="pager">
+          {% if show_prev_link %}
+            <a class="VPLink link pager-link prev" href="{{ prev_url }}">
+              <span class="desc">{{ prev_desc }}</span>
+              <span class="title">{{ prev_title }}</span>
+            </a>
+          {% endif %}
+        </div>
+
+        <div class="pager">
+          {% if show_next_link %}
+            <a class="VPLink link pager-link next" href="{{ next_url }}">
+              <span class="desc">{{ next_desc }}</span>
+              <span class="title">{{ next_title }}</span>
+            </a>
+          {% endif %}
+        </div>
+      </nav>
+    {% endif %}
+  </footer>
+{% endif %}

data/_includes/head.html

@@ -0,0 +1,98 @@
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  {% assign page_title = page.title | default: site.title %}
+  <title>{% if page_title and page_title != site.title %}{{ page_title }} | {{ site.title }}{% else %}{{ site.title }}{% endif %}</title>
+  <meta name="description" content="{{ page.description | default: site.description | escape }}">
+  <link rel="icon" href="{{ site.vp_theme.logo | default: site.vp_theme.logo_light | default: '/vitepress-logo-mini.svg' | relative_url }}">
+  {% assign vp_google_fonts_url = site.vp_theme.google_fonts_url | default: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap' %}
+  {% if vp_google_fonts_url %}
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link rel="stylesheet" href="{{ vp_google_fonts_url }}">
+  {% endif %}
+
+  <script>
+    (function() {
+      var storageKey = 'vitepress-theme-appearance';
+      var validModes = ['auto', 'dark', 'light'];
+      function normalizeMode(value) {
+        return validModes.indexOf(value) >= 0 ? value : 'auto';
+      }
+      var mode = 'auto';
+      try {
+        var stored = window.localStorage.getItem(storageKey);
+        if (stored) mode = normalizeMode(stored);
+      } catch (e) {}
+
+      var isDark = mode === 'dark' || (mode === 'auto' && window.matchMedia('(prefers-color-scheme: dark)').matches);
+      document.documentElement.classList.toggle('dark', isDark);
+      document.documentElement.classList.toggle('light', !isDark);
+      document.documentElement.setAttribute('data-appearance-mode', mode);
+
+      if (/Mac|iPhone|iPad|iPod/.test(navigator.platform)) {
+        document.documentElement.classList.add('mac');
+      }
+    })();
+  </script>
+
+  <link rel="stylesheet" href="{{ '/assets/css/vitepress-core.css' | relative_url }}">
+  <link rel="stylesheet" href="{{ '/assets/css/vitepress-components.css' | relative_url }}">
+  <link rel="stylesheet" href="{{ '/assets/css/vp-icons.css' | relative_url }}">
+  <link rel="stylesheet" href="{{ '/assets/css/vitepress-overrides.css' | relative_url }}">
+
+  {% assign vp_font_family_base = site.vp_theme.font_family_base %}
+  {% assign vp_font_family_mono = site.vp_theme.font_family_mono %}
+  {% assign vp_css_vars_light = site.vp_theme.css_vars.light %}
+  {% assign vp_css_vars_dark = site.vp_theme.css_vars.dark %}
+  {% assign has_theme_var_overrides = false %}
+  {% if vp_font_family_base or vp_font_family_mono %}
+    {% assign has_theme_var_overrides = true %}
+  {% endif %}
+  {% if vp_css_vars_light and vp_css_vars_light.size > 0 %}
+    {% assign has_theme_var_overrides = true %}
+  {% endif %}
+  {% if vp_css_vars_dark and vp_css_vars_dark.size > 0 %}
+    {% assign has_theme_var_overrides = true %}
+  {% endif %}
+  {% if has_theme_var_overrides %}
+    <style id="vp-theme-vars">
+      :root {
+        {% if vp_font_family_base %}--vp-font-family-base: {{ vp_font_family_base }};{% endif %}
+        {% if vp_font_family_mono %}--vp-font-family-mono: {{ vp_font_family_mono }};{% endif %}
+        {% if vp_css_vars_light %}
+          {% for pair in vp_css_vars_light %}
+            {% assign css_var_name = pair[0] | strip %}
+            {% if css_var_name contains '--' %}
+              {{ css_var_name }}: {{ pair[1] }};
+            {% else %}
+              --{{ css_var_name }}: {{ pair[1] }};
+            {% endif %}
+          {% endfor %}
+        {% endif %}
+      }
+      {% if vp_css_vars_dark and vp_css_vars_dark.size > 0 %}
+        .dark {
+          {% for pair in vp_css_vars_dark %}
+            {% assign css_var_name = pair[0] | strip %}
+            {% if css_var_name contains '--' %}
+              {{ css_var_name }}: {{ pair[1] }};
+            {% else %}
+              --{{ css_var_name }}: {{ pair[1] }};
+            {% endif %}
+          {% endfor %}
+        }
+      {% endif %}
+    </style>
+  {% endif %}
+
+  {% assign vp_rouge_css = site.vp_theme._generated_rouge_css %}
+  {% if vp_rouge_css and vp_rouge_css != '' %}
+    <style id="vp-rouge-theme">
+{{ vp_rouge_css }}
+    </style>
+  {% endif %}
+
+  {% include vp_slots/head.html %}
+  <script src="{{ '/assets/js/vitepress-theme.js' | relative_url }}" defer></script>
+</head>