whiteblog-theme 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45a0326c5e5c35bd0a3bfbc4177297bd6fa1d084e47b282a3181a681a95c2d07
-  data.tar.gz: 4cc7275d2324d4d843e64fb3ebce99fb5d5291317c602a60b6c9494aadb4b621
+  metadata.gz: c5e08ffe1dcb3bcc2fdeebfeb6c74b7140b20d58f284bc361c4fe081f35b6875
+  data.tar.gz: '0202736924aad8cc484232337cc96841e4a1bc40dd352eadf7f328ed2b45eff6'
 SHA512:
-  metadata.gz: 6d0adb86492d3fa856593e21b9a7f96d8ba00d9482b02761da74df31943bfc13f75886f574893717201a5eafdc34177dc2f15eeb81ac1fe1dcb99d211e737a52
-  data.tar.gz: 47b049292fb97a82f7aa7529b4b43be25f55be47eb196096910437ca7a28b7cf8b1a654a094d983b6c3c1dfed5054ff161c8fe0f1899cf41f193bb50e6fb5a0c
+  metadata.gz: 9b91bccd52c09bc85accee9dd569fcd92d8f3b06dad265989ffb4546bdb9097a1db5ea491c6677965442495691edc1ba8495de7edad3350816be1fb9a4a72994
+  data.tar.gz: 2ce8686257fc699d8cd0606c2ee0aed53d473a4caa28a7c044749da44fd867dbacbdd5e66f9d87e39201253da3e2091dbc00bb3e84a8bbe74d744685abbc91be

data/README.md

@@ -3,10 +3,10 @@
 [![License](http://img.shields.io/:license-mit-blue.svg)](http://doge.mit-license.org)
 ![Gem downloads](https://img.shields.io/gem/dt/whiteblog-theme.svg?colorB=brightgreen&style=flat)
 
-Welcome to your new Jekyll theme! In this directory, you'll find the files you need to be able to package up your theme into a gem. Put your layouts in `_layouts`, your includes in `_includes`, your sass files in `_sass` and any other assets in `assets`.
-
-To experiment with this code, add some sample content and run `bundle exec jekyll serve` – this directory is setup just like a Jekyll site!
-
+A minimal, wide and white Jekyll theme for technical blogs. Ships with a
+dark/light toggle, category pages, client-side search, automatic PNG preview
+generation for posts, an RSS feed, an automatic sitemap, reading-time
+estimates, and pluggable comment providers.
 
 ## Live preview
 
@@ -14,7 +14,23 @@ To experiment with this code, add some sample content and run `bundle exec jekyl
 
 ## Screenshot
 
-![Screenshot of whiteblog-theme](https://raw.githubusercontent.com/vmsilvamolina/whiteblog-theme/master/screenshot.png)
+![Screenshot of whiteblog-theme](https://raw.githubusercontent.com/vmsilvamolina/whiteblog-theme/main/screenshot.png)
+
+## Features
+
+- **Dark mode** — `[data-theme="dark"]` toggle with `prefers-color-scheme`
+  detection and `localStorage` persistence. Colours are CSS variables.
+- **Search** — client-side search over a generated `search.json`
+  (SimpleJekyllSearch, no external service).
+- **Categories** — category index and per-category listing.
+- **Post previews** — `_plugins/previews.rb` renders a social PNG per post
+  (see [Post preview plugin](#post-preview-plugin) for system requirements).
+- **SEO** — meta description, Open Graph and Twitter tags, and JSON-LD
+  `BlogPosting`, all derived from the post excerpt.
+- **Accessibility** — skip link, ARIA labels, accessible pagination,
+  keyboard-dismissable mobile nav, WCAG AA contrast.
+- **Comments** — Disqus, Cusdis or Giscus, selected in `_config.yml`.
+- **Analytics** — optional Google Analytics 4.
 
 ## Installation
 
@@ -38,20 +54,155 @@ Or install it yourself as:
 
     $ gem install whiteblog-theme
 
+## Configuration
 
-## Contributing
+All configuration lives in `_config.yml`.
+
+### Layouts
+
+| Layout      | Use                                    |
+|-------------|----------------------------------------|
+| `default`   | Base for every other layout            |
+| `home`      | Paginated index                        |
+| `post`      | Blog entry                             |
+| `page`      | Static page with sidebar               |
+| `page-wide` | Static page without sidebar            |
+| `allposts`  | Full post listing                      |
+| `categories`| Category view                          |
+
+### Addons
+
+```yaml
+addons:
+  back_to_top      : true    # back-to-top button
+  share_post       : true    # share buttons on posts
+  old_post_warning : false   # banner on old posts
+  buymeacoffee:
+    id             : ""      # buymeacoffee username; empty disables the widget
+    description    : "Support me on Buy me a coffee!"
+    message        : ""
+    color          : ""      # empty uses the theme's --color-accent, or a hex
+    position       : "left"  # left, right
+    x_margin       : "18"    # mobile horizontal margin
+    x_margin_desktop : "72"  # margin at >= 950px, aligned to the sidebar edge
+    y_margin       : "18"
+```
+
+### Comments
+
+Set `comments.provider` and fill in the matching block. Any other blocks are
+ignored.
+
+```yaml
+comments:
+  provider : false           # false, "disqus", "cusdis", "giscus"
+```
+
+**Disqus** — create a site at [disqus.com](https://disqus.com/), then:
+
+```yaml
+comments:
+  provider : "disqus"
+  disqus:
+    shortname : "your-disqus-shortname"
+```
+
+**Cusdis** — self-hosted or [cusdis.com](https://cusdis.com/); copy the App ID
+from your dashboard:
+
+```yaml
+comments:
+  provider : "cusdis"
+  cusdis:
+    appId : "your-cusdis-app-id"
+```
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/vmsilvamolina/whiteblog-theme. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+**Giscus** — enable GitHub Discussions on a public repo, install the
+[giscus app](https://github.com/apps/giscus), then run the configurator at
+[giscus.app](https://giscus.app/) to get the IDs:
+
+```yaml
+comments:
+  provider : "giscus"
+  giscus:
+    repo              : "username/repo-name"
+    repo_id           : "..."     # from giscus.app
+    category          : "General"
+    category_id       : "..."     # from giscus.app
+    mapping           : "pathname"
+    reactions_enabled : "1"
+    input_position    : "top"
+    theme             : "preferred_color_scheme"
+    lang              : "en"
+```
+
+Giscus and Cusdis follow the site's dark/light toggle without a page reload.
+
+### Analytics
+
+```yaml
+analytics:
+  google:
+    tracking_id : "G-XXXXXXXXXX"   # empty / false disables GA4
+```
+
+### Per-page frontmatter
+
+- `head_inline` — raw HTML injected into `<head>` for a single page (extra
+  meta tags, a page-specific stylesheet, etc.).
+- `slug` — overrides the slug used for the preview PNG path,
+  `assets/images/previews/<slug>.png`.
+
+## Post preview plugin
+
+`_plugins/previews.rb` generates one PNG per post via the `imgkit` gem, which
+shells out to **wkhtmltoimage**. If `pngquant` is on `PATH` the PNG is
+compressed in place. Both are external system binaries — install them before
+building:
+
+```bash
+# macOS
+brew install --cask wkhtmltopdf   # provides wkhtmltoimage
+brew install pngquant             # optional, for compression
+
+# Debian / Ubuntu
+apt-get install wkhtmltopdf pngquant
+```
+
+Add the gem to your site's `Gemfile`:
+
+```ruby
+group :jekyll_plugins do
+  gem "imgkit"
+end
+```
+
+GitHub Pages runs in `--safe` mode and will not execute this plugin; build and
+deploy the `_site` output yourself if you need previews.
 
 ## Development
 
 To set up your environment to develop this theme, run `bundle install`.
 
-Your theme is setup just like a normal Jekyll site! To test your theme, run `bundle exec jekyll serve` and open your browser at `http://localhost:4000`. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.
+```bash
+bundle exec jekyll serve            # local server at http://localhost:4000
+bundle exec jekyll serve --drafts   # include drafts
+bundle exec jekyll build            # production build
+```
+
+When the theme is released, only the files in `_layouts`, `_includes`,
+`_sass`, `_pages` and `assets` tracked with Git are bundled. To add a custom
+directory, edit the regexp in `whiteblog-theme.gemspec`.
+
+## Contributing
 
-When your theme is released, only the files in `_layouts`, `_includes`, `_sass` and `assets` tracked with Git will be bundled.
-To add a custom directory to your theme-gem, please edit the regexp in `whiteblog-theme.gemspec` accordingly.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/vmsilvamolina/whiteblog-theme. This project is intended to
+be a safe, welcoming space for collaboration, and contributors are expected to
+adhere to the [Contributor Covenant](http://contributor-covenant.org) code of
+conduct.
 
 ## License
 
-The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The theme is available as open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/_includes/buymeacoffee.html

@@ -0,0 +1,51 @@
+<script data-name="BMC-Widget" data-cfasync="false" src="https://cdnjs.buymeacoffee.com/1.0.0/widget.prod.min.js"
+  data-id="{{ site.addons.buymeacoffee.id }}"
+  data-description="{{ site.addons.buymeacoffee.description }}"
+  data-message="{{ site.addons.buymeacoffee.message }}"
+  data-color="{{ site.addons.buymeacoffee.color }}"
+  data-position="{{ site.addons.buymeacoffee.position }}"
+  data-x_margin="{{ site.addons.buymeacoffee.x_margin }}"
+  data-y_margin="{{ site.addons.buymeacoffee.y_margin }}"></script>
+{% if site.addons.buymeacoffee.color == "" or site.addons.buymeacoffee.color == nil %}
+<script>
+(function() {
+  var s = document.querySelector('script[data-name="BMC-Widget"]');
+  function accent() {
+    return getComputedStyle(document.documentElement).getPropertyValue('--color-accent').trim();
+  }
+  s.dataset.color = accent();
+
+  // the widget only paints the button's background once at render time, so follow
+  // theme toggles (data-theme attribute) manually to keep it in sync
+  new MutationObserver(function() {
+    var color = accent();
+    s.dataset.color = color;
+    var btn = document.getElementById('bmc-wbtn');
+    if (btn) btn.style.background = color;
+  }).observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] });
+})();
+</script>
+{% endif %}
+{% if site.addons.buymeacoffee.x_margin_desktop and site.addons.buymeacoffee.x_margin_desktop != "" %}
+<script>
+(function() {
+  var side = '{{ site.addons.buymeacoffee.position }}'.toLowerCase() === 'left' ? 'left' : 'right';
+  var mq = window.matchMedia('(min-width: 950px)');
+  function position() {
+    var btn = document.getElementById('bmc-wbtn');
+    if (!btn) return;
+    // the widget only sets style.left/right once at render time, so this override sticks
+    // through its hover/click animations (which only touch style.transform)
+    btn.style[side] = (mq.matches ? '{{ site.addons.buymeacoffee.x_margin_desktop }}' : '{{ site.addons.buymeacoffee.x_margin }}') + 'px';
+  }
+  var observer = new MutationObserver(function() {
+    if (document.getElementById('bmc-wbtn')) {
+      position();
+      observer.disconnect();
+    }
+  });
+  observer.observe(document.body, { childList: true });
+  mq.addEventListener('change', position);
+})();
+</script>
+{% endif %}

data/_includes/scripts.html

@@ -12,3 +12,7 @@
 {% if site.analytics.google.tracking_id and site.analytics.google.tracking_id != "" %}
   {% include /analytics/googleAnalytics.html %}
 {% endif %}
+
+{% if site.addons.buymeacoffee.id and site.addons.buymeacoffee.id != "" %}
+  {% include buymeacoffee.html %}
+{% endif %}

data/_sass/whiteblog-theme/_layout.scss

@@ -21,13 +21,13 @@
 }
 
 [data-theme="dark"] {
-  --color-bg: rgb(37,36,47);
+  --color-bg: #1a1a2e;
   --color-accent: #44318D;
   --color-primary: #CE80EF;
   --color-text: #E8E8E8;
   --color-dark: #CCCCCC;
   --color-highlight: #D83F87;
-  --color-code: #FF6B9D;
+  --color-code: #e0aaff;
   --color-code-bg: #282a36;
   --color-notice: #4A3B5C;
   --color-blockquote: #F39237;
@@ -641,6 +641,26 @@ svg {
   vertical-align: unset;
 }
 
+.error-404 {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+  gap: 1.5rem;
+  margin: 2rem 0;
+}
+
+.ascii-404 {
+  display: inline-block;
+  font-family: 'Fira Code', monospace;
+  color: var(--color-code);
+  white-space: pre;
+  text-align: left;
+  overflow-x: auto;
+  max-width: 100%;
+  line-height: 1.15;
+}
+
 .float-abajo {
   display: flex;
   justify-content: flex-end;

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: whiteblog-theme
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Victor Silva
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-10 00:00:00.000000000 Z
+date: 2026-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -83,6 +83,7 @@ files:
 - README.md
 - _includes/analytics/googleAnalytics.html
 - _includes/backtotop.html
+- _includes/buymeacoffee.html
 - _includes/comments-providers/cusdis.html
 - _includes/comments-providers/disqus.html
 - _includes/comments-providers/giscus.html