insights4you-jekyll-theme 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7e7de0952caad7e7ba6bdb9650aaa40e8a343c177967a0cdbf42801a46f1d738
-  data.tar.gz: 727f114144cd5246336b73239b9cc285d8240cd7bbf68b6ec42479185040096f
+  metadata.gz: 4409020af0e3cbe25b0aa6f1563daa55e07a1d96150e85518897ddff5c621d05
+  data.tar.gz: 99f9c2b937854c1d8425a671f373f1c683dfca6461a771a7393d4bac9c2a93a1
 SHA512:
-  metadata.gz: 804f08bc79666cc67596b3bf0ab5cafcf61a6279f18e10c4852c1fadd4f57ef6e6b501f0cea1154c421e9251bc2a9c856699f1992f5493ee2bf6269e16e09478
-  data.tar.gz: c00d4da9f2ac0caf0fa15acc27426a0d8e5f9065d35223a62238eae69c614afb35db0bc6f507817ed559e7566513f12bbb9eb052344f59b245f64d270fa1a242
+  metadata.gz: e0041ca8bcace71229e8db0e7dd8d4a9ec9df4c30298597e9baf29d77dbaeb4daa6b473c77ed51a13af62294c1c7d808e2e228865d349a21d91c1d060b54cadd
+  data.tar.gz: a84cca38a95e45848a6acee9c48c4ac129280f7275d1df3c99a6954f78e620d79d8d386901de67ba13cbca2fddeda570d1579e9822fa4c67b4a2fe181ee616e8

data/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0]
+
+### Added
+- **Blog**: `_layouts/post.html` and a card-based blog listing pattern (see the example site's `pages/blog.html`) - the theme previously had no working blog at all.
+- **Local Projects**: the "Local Projects" section of `utils/projects.html` was a static empty placeholder; it now renders real cards from a site's `projects` collection (`name`, `tools`, `image`, `description`, `external_url`), alongside the existing auto-generated GitHub-starred-repos grid.
+- **Comments**: optional Giscus (GitHub Discussions) comments on posts, via `_includes/utils/comments.html` and a `giscus:` block in `_config.yml`.
+- **i18n**: `_data/i4y-strings.yml` makes every hardcoded UI string (project page headings, empty/error states, search placeholder) overridable by a consuming site.
+- **Instant search**: `_includes/utils/search.html`, a dependency-free client-side filter over any card grid - closes the gap with the long-standing "Search Functionality" feature claim in the README, which was never actually implemented.
+- Simple tags page pattern (groups posts by `site.tags`).
+
+### Fixed
+- `_layouts/error.html` never actually read `_data/i4y-errors.json`: it referenced an undefined `errors` variable, and separately indexed it with an unconverted integer front-matter value against string JSON keys. Error pages always fell back to generic text/icon instead of the configured copy and illustration.
+- `_includes/ui/button.html` built internal links with `site.base`, a variable that doesn't exist anywhere in the theme, producing `href="//path"` (a protocol-relative URL pointing at a fake host) for every internal button. Switched to the `relative_url` filter.
+- `_sass/bootstrap/scss/vendor/_rfs.scss` was missing from the vendored Bootstrap 5.3.3 copy, so `bundle exec jekyll build` failed on **every** site using this theme with a real Sass compiler. Root cause: `.gitignore` had a bare `vendor/` entry, which ignores a folder named `vendor` at *any* depth, not just the repo root - it was silently dropping this file from every commit. Fixed to `/vendor/`.
+- README badge pointed at a non-existent `.github/workflows/gem-build.yml` (the real file is `gem.yml`).
+- `spec.description` in the gemspec was `File.read('README.md')`, so the RubyGems.org listing showed raw Markdown/HTML instead of a normal description.
+- `example-site/about.markdown` and `pages/blog.html` used `layout: home` / `layout: post`, neither of which existed in the theme - both silently rendered without any layout at all.
+- `example-site/pages/404.html` rendered its error illustration twice (once via the layout, once via an extra include in the page body).
+- `example-site/_config.yml` set `theme:` and `remote_theme:` at the same time, and used a `github: user:` key that `jekyll-github-metadata` doesn't recognize (the real key is `repository:`).
+
+### Changed
+- `spec.files` in the gemspec no longer packages the vendored Bootstrap's JS source or `package.json` - only the `.scss` partials Jekyll actually needs, and the Bootstrap `LICENSE` for compliance. Shrinks the published gem.
+- README rewritten to document what the theme actually does today (including the GitHub Pages native-build incompatibility and the GitHub Actions deploy workaround), replacing several `[WIP]` sections and one feature claim ("Search Functionality") that had never been implemented.
+- Removed `docs/` - it described a considerably more elaborate, never-implemented version of the projects feature (a separate fetch script, on-disk cache, dedicated local-projects collection). Superseded by the simpler real implementation, now documented in the README.
+
 ## [0.4.0]
 
 ### Added
@@ -104,6 +129,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **N/A**: No files or features were removed in this release.
 
 
+[0.5.0]: https://github.com/marciopaiva/insights4you-jekyll-theme/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/marciopaiva/insights4you-jekyll-theme/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/marciopaiva/insights4you-jekyll-theme/compare/v0.2.3...v0.3.0
 [0.2.3]: https://github.com/marciopaiva/insights4you-jekyll-theme/compare/v0.2.2...v0.2.3

data/README.md

@@ -2,12 +2,12 @@
 
 # Insights4YOU Jekyll Theme
 
-A sleek and modern Jekyll theme inspired by the [Tabler Admin Dashboard](https://github.com/tabler/tabler). This theme offers a clean, professional, and responsive interface, making it ideal for developers, content creators, and businesses. Whether you're building documentation sites, admin panels, or project showcases, this theme provides a minimal-effort solution with customizable layouts and modern design elements.
+A sleek and modern Jekyll theme inspired by the [Tabler Admin Dashboard](https://github.com/tabler/tabler). This theme offers a clean, professional, and responsive interface, making it ideal for developers, content creators, and businesses. Whether you're building a personal site, a blog, or a project showcase, this theme provides a minimal-effort solution with customizable layouts and modern design elements.
 
 ![Theme Preview](assets/images/preview-dark.png)
 
 [![last commit](https://img.shields.io/github/last-commit/marciopaiva/insights4you-jekyll-theme?logo=github)][repo]
-[![gem build](https://github.com/marciopaiva/insights4you-jekyll-theme/actions/workflows/gem-build.yml/badge.svg)][build]
+[![gem build](https://github.com/marciopaiva/insights4you-jekyll-theme/actions/workflows/gem.yml/badge.svg)][build]
 [![codacy badge](https://img.shields.io/codacy/grade/4e556876a3c54d5e8f2d2857c4f43894?logo=codacy)][codacy]
 [![gem version](https://img.shields.io/gem/v/insights4you-jekyll-theme?&logo=rubygems&logoColor=ghostwhite&label=gem&color=orange)][gem]
 [![downloads](https://img.shields.io/gem/dt/insights4you-jekyll-theme?logo=rubygems&color=blue)][gem]
@@ -17,69 +17,134 @@ A sleek and modern Jekyll theme inspired by the [Tabler Admin Dashboard](https:/
 
 ## 🌟 Features
 
-- 🌙 **Dark and Light Themes**: Switch between dark and light modes for a personalized experience
-- 📱 **Responsive Design**: Fully optimized for mobile, tablet, and desktop devices
-- 🔧 **Customizable Layouts**: Easily modify layouts to suit your needs
-- 🚀 **SEO Optimized**: Built-in support for Jekyll SEO tags to improve search engine visibility
-- 📦 **Gem-Based Installation**: Simple installation via RubyGems
-- 📝 **Markdown Support**: Write content using Markdown for simplicity and flexibility
-- 🎨 **Modern Design**: Inspired by the Tabler Admin Dashboard for a sleek and professional look
-- 📊 **Analytics Ready**: Add analytics scripts easily for tracking user interactions
-- 🔍 **Search Functionality**: Built-in search capabilities for content discovery
-- 🎯 **Clean Code**: Well-documented and maintainable codebase
-- 🛠️ **Developer Friendly**: Easy to extend and customize
-- 📱 **Mobile First**: Designed with mobile devices in mind
+- 🌙 **Dark and Light Themes**: A "Theme Builder" panel lets visitors switch color mode, accent color, font family, gray base and corner radius on the fly (saved in `localStorage`)
+- 📱 **Responsive Design**: Built on Bootstrap 5 / Tabler, fully usable on mobile, tablet and desktop
+- ✍️ **Blog**: `_posts` support with a ready-to-use post layout and a card-based listing page
+- 🔍 **Instant Search**: Client-side filtering over any card grid (e.g. the blog listing) as you type - no build step or external service
+- 📦 **Projects, two ways**: a `projects` collection for hand-curated local project cards, plus an auto-generated grid of your GitHub repositories that have at least one star (via `jekyll-github-metadata`)
+- 💬 **Comments via Giscus**: optional, GitHub Discussions-based comments on posts - no third-party ads or tracking
+- 🌐 **Translatable UI strings**: every built-in label (project page headings, error pages, empty states, search placeholder) can be overridden by your own `_data/i4y-strings.yml` and `_data/i4y-errors.json`
+- 🚀 **SEO Ready**: ships with `jekyll-seo-tag`, `jekyll-sitemap` and `jekyll-feed` support
+- 📦 **Gem-Based Installation**: install via RubyGems, or track the repo directly with Bundler's `github:` source
+- 🎨 **200+ bundled icons**: Tabler's icon set, inlined as SVG by default (or as an icon font, if you prefer)
 
 ## 📋 Requirements
 
-- Ruby >= 2.7.0
-- Jekyll ~> 4.2
-- Bundler ~> 2.3
+- Ruby >= 3.2.2
+- Jekyll >= 4.4, < 5.0
+- Bundler ~> 2.4
 
-## 🚀 Quick Start
+⚠️ **This theme will not build on GitHub Pages' native "Deploy from a branch" option.** GitHub Pages' native build pins Jekyll to 3.10 and its Sass converter to the legacy Ruby Sass line, which cannot compile the Dart-Sass module syntax (`@use`, `color.adjust(...)`) that Bootstrap 5.3+ uses. Deploy via **GitHub Actions** instead - see [Deploying to GitHub Pages](#-deploying-to-github-pages) below.
 
-1. **Install the theme:**
-```ruby
-gem install insights4you-jekyll-theme
-```
+## 🚀 Quick Start
 
-2. **Create a new Jekyll site:**
-```ruby
-jekyll new my-website
+1. **Create a new Jekyll site** (or use an existing one):
+```bash
+jekyll new my-website && cd my-website
 ```
 
-3. **Add the theme to your Jekyll site's `Gemfile`:**
+2. **Add the theme to your `Gemfile`:**
 ```ruby
 gem "insights4you-jekyll-theme"
+
+group :jekyll_plugins do
+  gem "jekyll-feed"
+  gem "jekyll-seo-tag"
+  gem "jekyll-sitemap"
+  gem "jekyll-github-metadata"
+  gem "jekyll-paginate"   # required by the theme's own dependencies, even if unused
+  gem "jemoji"
+end
 ```
 
-4. **Update your `_config.yml`:**
+3. **Update your `_config.yml`:**
 ```yaml
 theme: insights4you-jekyll-theme
+repository: your-username/your-repo   # NWO used by jekyll-github-metadata
+
+plugins:
+  - jemoji
+  - jekyll-seo-tag
+  - jekyll-sitemap
+  - jekyll-feed
+  - jekyll-github-metadata
+
+author:
+  name: Your Name
+  bio: Your one-line bio
+  image: https://example.com/your-avatar.jpg
+  email: you@example.com
+  github: your-username        # matched against _data/i4y-social-media.yml
+  linkedin: your-linkedin-slug
 ```
 
-5. **Install dependencies:**
+4. **Install dependencies and start your site:**
 ```bash
 bundle install
+bundle exec jekyll serve
 ```
 
-6. **Start your site:**
-```bash
-bundle exec jekyll serve
+## 🚢 Deploying to GitHub Pages
+
+Because of the Sass constraint above, set your repository's **Settings → Pages → Source** to **"GitHub Actions"**, and add a workflow like this (adjust the ruby version/paths as needed):
+
+```yaml
+name: Deploy Jekyll site to Pages
+
+on:
+  push:
+    branches: ["main"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.2"
+          bundler-cache: true
+      - id: pages
+        uses: actions/configure-pages@v5
+      - env:
+          JEKYLL_ENV: production
+          PAGES_REPO_NWO: ${{ github.repository }}
+          JEKYLL_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: _site
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
 ```
 
+`JEKYLL_GITHUB_TOKEN` gives `jekyll-github-metadata` a 5,000 requests/hour budget instead of the unauthenticated 60/hour limit - without it, the GitHub-repositories grid may silently come up empty on repeated builds.
+
 ## 🎯 Demo Site
 
 To see the theme in action, check out the included example site:
 
 ```bash
-# Clone the repository
 git clone https://github.com/marciopaiva/insights4you-jekyll-theme.git
-
-# Navigate to theme directory
 cd insights4you-jekyll-theme
-
-# build and test
 make dev
 ```
 
@@ -87,27 +152,50 @@ Visit `http://localhost:4000` to see the demo site in action.
 
 ## 🎨 Customization
 
-### Theme Configuration
-[WIP]
-
-### Available Layouts
-- `default`: Standard page layout
+### Layouts
+| Layout | Use it for |
+|---|---|
+| `base` | Root HTML document. You won't use this directly. |
+| `default` | Standard pages (home, about, projects...). Set `layout-wrapper-full: true` in front matter for a centered "card" wrapper instead of the full-width container - handy for long-form content. |
+| `post` | Blog posts. Renders title, date, tags, content, and Giscus comments (if enabled and `page.comments: true`). |
+| `error` | Error pages (404, etc). Set `page-error: "404"` in front matter to pull text/illustration from `_data/i4y-errors.json`. |
+
+### Front matter reference
+| Key | Where | Effect |
+|---|---|---|
+| `weight` | any page | Order in the navbar (lower first) |
+| `icon` | any page | Tabler icon name shown next to its navbar entry |
+| `external_url` | any page | Makes its navbar entry link elsewhere instead of `page.url` |
+| `no-container` | page/layout | Removes the `.container-xl` around the page body |
+| `layout-wrapper-full` | page/layout | Centered card wrapper (see `default` layout above) |
+| `custom_css` / `custom_js` | any page | Arrays of extra `/assets/{css,js}/<name>.{css,js}` files to load |
+| `comments` | posts | Show the Giscus widget on this post (also needs `site.giscus.enabled: true`) |
+
+### Translating the UI
+Every hardcoded label lives in `_data/i4y-strings.yml`. Copy the theme's version into your own site's `_data/i4y-strings.yml` and translate it - your site's file takes precedence over the theme's. Error-page copy (`_data/i4y-errors.json`) works the same way.
+
+### Adding local projects
+Declare a `projects` collection in `_config.yml`:
+```yaml
+collections:
+  projects:
+    output: true
+    permalink: /projects/:name
+```
+Then add files under `_projects/`:
+```yaml
+---
+name: My Project
+tools: [Rust, Tauri]
+image: /assets/images/my-project.png   # optional
+description: One or two sentences about it.
+external_url: https://github.com/you/my-project   # omit to link to this file's own body instead
+---
+Optional markdown body, rendered as the project's own detail page when there's no `external_url`.
+```
 
 ### Custom Styling
-Create a new file `assets/css/custom.scss` to add your own styles:
-
-[WIP]
-
-## 📝 Documentation
-
-### Directory Structure
-[WIP]
-
-### Creating Posts
-[WIP]
-
-### Creating Pages
-[WIP]
+Add your own `_sass` partials and `@import` them from a site-level `assets/css/custom.scss`, then reference it from a page's `custom_css` front matter key.
 
 ## 🤝 Contributing
 
@@ -130,7 +218,7 @@ This project is licensed under the MIT License - see the LICENSE file for detail
 - All contributors who help improve this theme
 
 [repo]: https://github.com/marciopaiva/insights4you-jekyll-theme
-[build]: https://github.com/marciopaiva/insights4you-jekyll-theme/actions/workflows/gem-build.yml
+[build]: https://github.com/marciopaiva/insights4you-jekyll-theme/actions/workflows/gem.yml
 [codacy]: https://app.codacy.com/gh/marciopaiva/insights4you-jekyll-theme/dashboard
 [gem]: https://rubygems.org/gems/insights4you-jekyll-theme
 [license]: https://github.com/marciopaiva/insights4you-jekyll-theme/blob/master/LICENSE

data/_data/i4y-strings.yml

@@ -0,0 +1,32 @@
+# UI strings used by theme includes/layouts. Override this whole file in
+# your own site's _data/i4y-strings.yml to translate the theme (Jekyll site
+# data takes precedence over the theme's bundled data file of the same name).
+
+projects:
+  title: "Projects"
+  description: "Here you'll find a collection of my projects, experiments, and learning."
+  unable_to_load_title: "Unable to load repositories"
+  unable_to_load_description: "There was a problem fetching the repository data. Please try again later."
+  no_starred_title: "No starred repositories found"
+  no_starred_description: "Repositories with at least one star will appear here."
+  uncategorized: "Uncategorized"
+  stars: "Stars"
+  watchers: "Watchers"
+  forks: "Forks"
+  issues: "Issues"
+  no_description: "No description available"
+  view_repository: "View Repository"
+  local_projects: "Local Projects"
+  view_project: "View Project"
+
+empty:
+  title: "No results found"
+  subtitle: "Try adjusting your search or filter to find what you're looking for."
+  button_text: "Search again"
+
+error:
+  default_header: "Oops… You just found an error page"
+  home_button: "Take me home"
+
+search:
+  placeholder: "Search..."

data/_includes/ui/button.html

@@ -13,7 +13,7 @@
 	{% if include.external %}
 		{% assign href = include.href %}
 	{% else %}
-		{% assign href = site.base | append: '/' | append: include.href %}
+		{% assign href = include.href | relative_url %}
 	{% endif %}
 {% endif %}
 

data/_includes/ui/empty.html

@@ -11,12 +11,12 @@
 	{% endif %}
 
 
-	<p class="empty-title">{{ include.title | default: "No results found" }}</p>
+	<p class="empty-title">{{ include.title | default: site.data.i4y-strings.empty.title | default: "No results found" }}</p>
 	<p class="empty-subtitle text-secondary">
-		{{ include.subtitle | default: "Try adjusting your search or filter to find what you're looking for." }}
+		{{ include.subtitle | default: site.data.i4y-strings.empty.subtitle | default: "Try adjusting your search or filter to find what you're looking for." }}
 	</p>
 	<div class="empty-action">
-		{% assign button-text = include.button-text | default: "Search again" %}
+		{% assign button-text = include.button-text | default: site.data.i4y-strings.empty.button_text | default: "Search again" %}
 		{% assign button-icon = include.button-icon | default: "search" %}
 		{% include ui/button.html text=button-text color="primary" icon=button-icon href="." %}
 	</div>

data/_includes/utils/comments.html

@@ -0,0 +1,34 @@
+{% if site.giscus.enabled and site.giscus.repo and site.giscus.repo_id and site.giscus.category_id %}
+<div class="mt-5" id="giscus-comments">
+  <script src="https://giscus.app/client.js"
+    data-repo="{{ site.giscus.repo }}"
+    data-repo-id="{{ site.giscus.repo_id }}"
+    data-category="{{ site.giscus.category | default: 'Comments' }}"
+    data-category-id="{{ site.giscus.category_id }}"
+    data-mapping="{{ site.giscus.mapping | default: 'pathname' }}"
+    data-strict="0"
+    data-reactions-enabled="1"
+    data-emit-metadata="0"
+    data-input-position="bottom"
+    data-theme="{% if page.layout-dark or site.layout-dark %}dark{% else %}light{% endif %}"
+    data-lang="{{ page.lang | default: site.lang | default: 'en' }}"
+    crossorigin="anonymous"
+    async>
+  </script>
+</div>
+<script>
+  document.addEventListener('DOMContentLoaded', function () {
+    function giscusTheme() {
+      return (document.documentElement.classList.contains('dark') || document.body.classList.contains('theme-dark')) ? 'dark' : 'light';
+    }
+    function sendGiscusTheme() {
+      var iframe = document.querySelector('iframe.giscus-frame');
+      if (!iframe) return;
+      iframe.contentWindow.postMessage({ giscus: { setConfig: { theme: giscusTheme() } } }, 'https://giscus.app');
+    }
+    var observer = new MutationObserver(sendGiscusTheme);
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
+    observer.observe(document.body, { attributes: true, attributeFilter: ['class'] });
+  });
+</script>
+{% endif %}