🚀 Shiro v1.3.2 Released: Automatic Cache-Busting for Static Assets

A minor release that eliminates the need to manually purge CDN/Cloudflare caches after theme updates. All local CSS and JS assets now include a content-based hash in their URLs, ensuring browsers always load the latest version.

✨ New Features

🔄 Automatic Cache-Busting with versioned_url Helper

Added a new versioned_url Hexo helper that appends a ?v=<hash> query parameter to local asset URLs. The hash is derived from the file's MD5 content digest (first 8 characters), so the URL only changes when the file content actually changes.

• No more manual cache purging — after deploying a new version, browsers and CDNs will automatically fetch updated assets because the URL has changed.
• Zero configuration required — the helper works out of the box with no additional settings.
• Graceful fallback — if a file is not found at the theme level, the helper falls back to the standard url_for output without a version parameter.

Example output:

css/style.min.css?v=69bbab69
js/lightgallery.js?v=a1b2c3d4

🔧 Improvements

Asset Loading

• Replaced all url_for calls for local CSS and JS assets with the new versioned_url helper across layout templates:
  • layout/_partial/common/head.njk — style.min.css
  • layout/_layout.njk — lightgallery.js, clipboard.js, toc.js, progress.js, theme-toggle.js, mobile-menu.js

Documentation

• Updated version references in package.json, _config.yml, README.md, and README_CN.md.

🛠️ Upgrade Notes

To update your theme to the latest version, use the method matching your installation:

npm

npm i hexo-theme-shiro@latest

Git

cd themes/shiro
git pull

Note: After upgrading, review the default _config.yml for any new or changed options, and update your _config.shiro.yml accordingly.

This release is fully backward compatible — no configuration changes are required. Simply update the theme files and rebuild your site.

🤝 Feedback

Thank you for using Shiro! If you encounter any issues with the new features or have suggestions, please feel free to open an issue.

If you enjoy using Shiro, please consider giving it a ⭐️ on GitHub to support my work!

Full Changelog: v1.3.1...v1.3.2

Made by Acris with ❤️

🩹 Shiro v1.3.1 Released: giscus Dark Mode Fix & Style Refinements

A patch release that fixes giscus comment system theme switching between light and dark modes, along with minor style and documentation refinements.

🐛 Bug Fixes

💬 giscus Dark/Light Mode Switching

Fixed an issue where toggling between light mode and dark mode did not update the giscus comment box theme accordingly. The color-scheme property is now correctly applied to .giscus-frame in both light and dark modes, ensuring the comment area reflects the active color scheme when switching modes.

🔧 Improvements

Comment System Styles

• Restored color-scheme: light / color-scheme: dark on .giscus-frame for proper browser-native control rendering inside the iframe.
• Removed redundant .dark style overrides for Disqus, relying on CSS variable auto-switching instead.

Documentation

• Normalized "Giscus" → "giscus" (lowercase) across _config.yml, README.md, and README_CN.md to match the official giscus branding.

🛠️ Upgrade Notes

To update your theme to the latest version, use the method matching your installation:

npm

npm i hexo-theme-shiro@latest

Git

cd themes/shiro
git pull

Note: After upgrading, review the default _config.yml for any new or changed options, and update your _config.shiro.yml accordingly.

This release is fully backward compatible — no configuration changes are required. Simply update the theme files and rebuild your site.

🤝 Feedback

Thank you for using Shiro! If you encounter any issues with the new features or have suggestions, please feel free to open an issue.

If you enjoy using Shiro, please consider giving it a ⭐️ on GitHub to support my work!

Full Changelog: v1.3.0...v1.3.1

Made by Acris with ❤️

🎉 Shiro v1.3.0 Released: giscus Comment System, Custom Theme CSS & More

I'm excited to share Shiro v1.3.0 — a feature update that brings full giscus comment system support with a custom theme perfectly matched to Shiro's aesthetic, along with code quality improvements across the board!

✨ What's New

💬 giscus Comment System

Added full support for giscus — a comment system powered by GitHub Discussions. giscus joins the existing Disqus integration, giving you a lightweight, privacy-friendly alternative with no tracking, no ads, and no database required.

• Fully configurable via _config.yml: repo, repo_id, category, category_id, mapping, reactions, theme, lang, lazy_loading, and src
• Set provider: giscus under comments to enable

🎨 Custom giscus Theme

A custom giscus CSS theme (source/css/giscus.css) designed to blend seamlessly with Shiro's gray-white + vermilion aesthetic:

• Light mode: warm paper tones (#f5f4f2 canvas, #2b3036 text) with vermilion (#b0171a) accent replacing the default blue
• Dark mode: warm dark neutrals (#1f1e1d canvas, #e8e5e1 text) matching Shiro's dark palette, with vermilion (#d4453a) accent
• Automatic light/dark switching via @media (prefers-color-scheme: dark)
• Served via jsDelivr CDN for fast, cached delivery with zero CORS issues
• Theme URL is fully configurable — use the built-in custom theme, any giscus official theme, or your own CSS

🩹 Sub-Pixel Border Fix

Fixed a subtle rendering issue where the giscus comment box's right border could be clipped due to sub-pixel rounding when the container width resolves to a fractional pixel value. Applied width: round(down, 100%, 2px) to ensure the iframe width always snaps to an even pixel boundary.

🔧 Improvements

Code Quality

• Replaced all var declarations with const/let across JS files and inline scripts (only exception: var disqus_config required by Disqus API)
• Refactored giscus.njk to use object iteration for data-* attributes and DOM property assignment for src, async, crossOrigin
• Used unique id="giscus-container" for safe element targeting instead of document.querySelector('.giscus')

CSS Architecture

• Moved giscus and Disqus comment styles out of @layer components to ensure correct specificity against dynamically injected stylesheets
• Removed redundant .dark overrides for Disqus (CSS custom properties auto-switch in dark mode)
• Removed ineffective color-scheme declarations on .giscus-frame iframe

Documentation

• Updated both README.md and README_CN.md with full giscus configuration instructions and examples
• Added inline comments explaining the round() width fix and repurposed color variable names in giscus.css

🛠️ Upgrade Notes

To update your theme to the latest version, use the method matching your installation:

npm

npm i hexo-theme-shiro@latest

Git

cd themes/shiro
git pull

Note: After upgrading, review the default _config.yml for any new or changed options, and update your _config.shiro.yml accordingly.

To enable giscus, add the following to your _config.shiro.yml:

# Comment systems
# Supported providers: disqus, giscus
# Set enabled to true and choose a provider.
#
# giscus: a comment system powered by GitHub Discussions.
# Go to https://giscus.app/ to generate your configuration values.
# Make sure your repository is public and has Discussions enabled.
comments:
  enabled: false
  # disqus or giscus
  provider: giscus
  giscus:
    # giscus script URL (self-hosted or default)
    src: https://giscus.app/client.js
    # GitHub repo (e.g., "owner/repo")
    repo: ""
    # Repository ID from https://giscus.app
    repo_id: ""
    # Discussion category name (e.g., "Announcements")
    category: ""
    # Category ID from https://giscus.app
    category_id: ""
    # pathname, url, title, og:title, specific, number
    mapping: pathname
    # 1 to enable strict title matching
    strict: 0
    # 1 to enable reactions
    reactions_enabled: 1
    # 1 to emit discussion metadata
    emit_metadata: 0
    # bottom or top
    input_position: bottom
    # Language code (e.g., en, zh-CN, ja)
    lang: en
    # giscus theme CSS URL or built-in theme name (e.g., light, dark, preferred_color_scheme)
    # Default uses the bundled Shiro custom theme via jsDelivr CDN.
    theme: https://cdn.jsdelivr.net/npm/hexo-theme-shiro@1.3.0/source/css/giscus.css
    # true to enable lazy loading (adds data-loading="lazy")
    lazy_loading: false

Visit giscus.app to generate your repo_id and category_id.

This release is fully backward compatible — existing Disqus configurations continue to work without any changes.

🤝 Feedback

Thank you for using Shiro! If you encounter any issues with the new features or have suggestions, please feel free to open an issue.

If you enjoy using Shiro, please consider giving it a ⭐️ on GitHub to support my work!

Full Changelog: v1.2.1...v1.3.0

Made by Acris with ❤️

🎉 Shiro v1.2.1 Released: Smooth Theme Transitions, Enhanced TOC, Code Quality Overhaul & More

I'm excited to share Shiro v1.2.1 — a refinement-focused update that brings smooth theme switching animations, improved table of contents, better SEO metadata, and a comprehensive code quality overhaul across the entire theme!

---

✨ What's New

🎨 Smart Theme Toggle with View Transitions

• Theme cycling now supports three states: Light → Dark → System, with smart 2-state fallback when dark_mode.default is not system
• Leverages the View Transitions API for a smooth cross-fade animation when switching themes, with automatic fallback for unsupported browsers
• Fully respects prefers-reduced-motion — transitions are disabled for users who prefer reduced motion

🌐 i18n for Gallery Source Links

• Added multilingual support for LightGallery source link text (gallery_visit_source) and image aria-labels (gallery_view_image)
• Updated all 9 language files (English, French, Japanese, Simplified Chinese, Traditional Chinese) with localized strings
• LightGallery captions now use combined aria-label format (e.g., "View image: caption") for better screen reader experience

---

🔧 Improvements

Table of Contents

• Refined TOC rendering logic with improved small-screen layout behavior
• Updated dark mode .toc-link text color from subtle to muted for better contrast
• Adjusted TOC background for improved readability in both light and dark modes

SEO & Metadata

• Improved footer display with better copyright year handling
• Enhanced SEO metadata generation in build_page_title for tag, archive, and category pages (e.g., "Tags: JavaScript | Site Name")
• Refined og:type to correctly distinguish between article (posts) and website (other pages)

Code Blocks

• Fixed line break preservation when copying code from Hexo highlight blocks — clipboard now correctly joins <span class="line"> elements with newline characters
• Improved code block word wrapping for better readability on narrow screens

Visual Refinements

• Updated .paper border radius from 2xl to xl for more consistent styling
• Optimized .fog-bg with GPU-friendly layers and pseudo-elements for smoother rendering
• Restricted progress bar to posts and pages only, preventing unnecessary script loading on other page types

Architecture & Code Quality

• Comprehensive Tailwind CSS v4 best practices overhaul: unified size-* shorthand, replaced text-[var(--color-seal)] with generated text-seal utilities, consolidated @apply font-* usage
• Merged responsive font media queries into component definitions using Tailwind breakpoint prefixes
• Removed redundant dark mode overrides by leveraging CSS custom property inheritance
• Replaced hand-written pagination with Hexo's built-in paginator() helper for full page number navigation
• Extracted shared article.njk partial to eliminate template duplication between post.njk and page.njk
• Unified icon macro signatures with consistent (class, id) parameters and aria-hidden="true" attributes
• Added CDN Subresource Integrity (SRI) hashes for LightGallery resources
• Added data-csp-fallback marker to Google Fonts preload for targeted CSP fallback
• Added <meta name="generator"> tag per Hexo best practices
• Conditional loading for mobile-menu.js based on menu configuration
• Categories page now sorted alphabetically

Documentation

• Added Chinese documentation
• Updated README live demo link
• Simplified RSS feed plugin installation instructions
• Added seal_text configuration documentation and excerpt priority explanation
• Synced all configuration examples between _config.yml and README

---

🛠️ Upgrade Notes

To update your theme to the latest version, use the method matching your installation:

npm

npm i hexo-theme-shiro@latest

Git

cd themes/shiro
git pull

Note: After upgrading, review the default _config.yml for any new or changed options, and update your _config.shiro.yml accordingly.

This release is fully backward compatible — no configuration changes are required. All existing _config.shiro.yml settings continue to work as before.

If you've customized templates, note that post.njk and page.njk now use a shared article.njk partial, and pagination.njk has been rewritten to use Hexo's paginator() helper.

---

🤝 Feedback

Thank you for using Shiro! If you encounter any issues with the new features or have suggestions, please feel free to open an issue.

If you enjoy using Shiro, please consider giving it a ⭐️ on GitHub to support my work!

Full Changelog: v1.2.0...v1.2.1

Made by Acris with ❤️

🎉 Shiro v1.2.0 Released: Dark Mode, TOC Sidebar, Reading Progress & Major Refinements

I'm excited to share Shiro v1.2.0 — a major update that brings dark mode, table of contents sidebar, reading enhancements, and extensive code quality improvements to the theme!

---

✨ What's New

🌙 Dark Mode

• Three-state toggle: System → Light → Dark, with localStorage persistence
• "夜の白" design: Warm neutral gray tones that complement the light mode's washi paper aesthetic — not a cold inversion, but a moonlit version of the same design language
• Vermilion accent preserved: The signature seal red remains the visual anchor in both modes
• FOUC prevention: Inline script in <head> applies the correct theme before first paint — no flash of wrong colors
• Configurable: dark_mode.default (system/light/dark) and dark_mode.toggle (show/hide the toggle button) in _config.yml

📑 Table of Contents Sidebar

• Auto-generated TOC sidebar for articles with configurable heading depth (toc.depth)
• Only appears when the article has enough headings (toc.min_headings)
• Active heading highlighted with a vermilion dot indicator that follows your reading position
• Sticky "目录" title that stays visible while scrolling through long TOC lists
• Smooth auto-scroll to keep the active item visible in the TOC panel
• Heading positions cached for performance; automatically recalculated on resize and image load
• Configurable via toc.enabled, toc.depth, and toc.min_headings in _config.yml

📊 Reading Progress Bar

• Thin vermilion progress bar fixed at the top of the page, updating in real-time as you scroll
• Automatically hidden on short pages (content less than one viewport height)
• Respects prefers-reduced-motion
• Configurable via progress_bar.enabled in _config.yml

⬆️ Back to Top Button

• Elegant circular button that fades in after scrolling past one viewport height
• Smooth scroll back to top, respects prefers-reduced-motion
• Configurable via back_to_top.enabled in _config.yml

🖥️ Code Block Enhancements

• Language labels: Automatically extracted from Hexo's highlight classes and displayed above code blocks
• Copy button: One-click copy with visual feedback, error handling for non-HTTPS environments
• Fixed width: Code blocks maintain consistent width regardless of content length
• Long inline code wrapping: Inline <code> elements wrap gracefully on mobile without breaking layout

🔧 Improvements

Performance

• Archive page rendering optimized from O(n²) to O(n) single-pass year grouping
• LightGallery CSS/JS conditionally loaded only on post and page layouts
• Google Fonts moved from CSS @import (render-blocking) to async <link rel="preload"> with onload fallback
• All scripts use defer attribute for parallel downloading
• TOC heading positions cached to avoid scroll-time reflow; resize events debounced
• theme-transition narrowed from * selector to key elements only
• Google Analytics moved from <head> to before </body> to avoid render blocking
• Progress bar hidden on short pages to avoid unnecessary 100% display

Accessibility

• Theme toggle button updates aria-label dynamically to reflect current state
• Mobile menu implements focus trap with Tab key cycling
• Navigation separator / has aria-hidden="true"
• Decorative elements properly marked with aria-hidden

Security

• Disqus shortname XSS protection via dump | safe filter
• Clipboard API error handling with .catch() for non-HTTPS environments
• IntersectionObserver fallback for unsupported browsers in Disqus lazy loading

Code Quality

• Dark mode uses 12 semantic CSS variables (--color-text-heading, --color-bg-panel, etc.) — changing the dark palette only requires editing variable definitions
• Simple utilities (text-footnote, tracking-note, max-h-menu, max-w-divider) migrated to Tailwind v4 @utility syntax
• Extracted .header-pill-btn component class to eliminate duplicate inline styles
• Replaced bg-white hack with bg-paper for proper dark mode support
• All JS files wrapped in IIFE with defer, removed redundant DOMContentLoaded listeners
• Unified import ... as ui with context across all templates
• DRY improvements: extracted clean_description variable in head.njk, has_excerpt in post-card.njk
• Replaced inline SVG in post.njk with icon_chevron_down macro call
• preconnect hints moved before CSS links for earlier connection
• Washi paper texture optimized: removed invisible fog layers, fiber angles randomized with coprime background-size to reduce repetition

i18n

• All 9 language files (default, en, en-US, zh-CN, zh-TW, ja, ja-JP, fr, fr-FR) updated with new feature strings
• Theme toggle labels: light / dark / system

Documentation

• README.md rewritten with complete feature list, project structure, development guide, and configuration reference
• Live demo link added

---

🛠️ Upgrade Notes

To update your theme, pull the latest changes:

# npm
npm install hexo-theme-shiro@latest

# git
cd themes/shiro
git pull

New configuration options — add the following to your _config.shiro.yml:

# Table of Contents (TOC)
toc:
  enabled: true
  depth: 3
  min_headings: 3

# Dark Mode
dark_mode:
  default: system    # system | light | dark
  toggle: true       # Show toggle button (set to false to disable switching)

# Reading Progress Bar
progress_bar:
  enabled: true

# Back to Top Button
back_to_top:
  enabled: true

If you've customized templates or styles, you may want to review the changes before merging — this release includes significant CSS restructuring for dark mode support.

---

🤝 Feedback

Thank you for using Shiro! If you encounter any issues with the new features or have suggestions, please feel free to open an issue.

If you enjoy using Shiro, please consider giving it a ⭐️ on GitHub to support my work!

Full Changelog: v1.1.0...v1.2.0

---

Made by Acris with ❤️

🎉 Shiro v1.1.0 Released: Lightbox Gallery for Post Images

I’m excited to share Shiro v1.1.0, bringing a small but delightful enhancement to your reading experience!

This update introduces lightGallery integration, enabling a beautiful lightbox effect for images in blog posts — making image viewing smoother, cleaner, and more immersive.

---

✨ What’s New

🖼️ Lightbox Gallery Support

• Added lightGallery to enable lightbox-style image previews in blog posts
• Click any image inside an article to open it in an elegant overlay
• Improves the overall reading and media viewing experience without disrupting Shiro’s minimal design

---

🛠️ Upgrade Notes

To update your theme, pull the latest changes:

cd themes/shiro
git pull

If you’ve customized templates or styles, you may want to review the changes before merging.

---

🤝 Feedback

Thank you for using Shiro! If you encounter any issues with the new image viewer or have other suggestions, please feel free to open an issue.

If you enjoy using Shiro, please consider giving it a ⭐️ on GitHub to support my work!

Full Changelog: v1.0.0...v1.1.0

---

Made by Acris with ❤️

🎉 Shiro v1.0.0 Released: A Simple and Pure Hexo Theme

I am thrilled to announce the release of Shiro v1.0.0! 🚀

As a personal project, Shiro reflects my vision of what a blog theme should be: minimal, fast, and elegant. This first major release focuses on providing a distraction-free reading experience while offering robust customization options for modern bloggers.

Shiro (白) represents the design philosophy behind this theme: Simple, Pure, and limitless possibilities.

✨ Highlights

🎨 Design & Experience

• Simple and Pure: A clean aesthetic that puts your content first. No clutter, just you and your readers.
• Responsive Design: Carefully crafted to look great on any device, from large desktop monitors to mobile phones.
• Tailwind CSS: Built with modern utility-first CSS for a lightweight footprint and easy styling.

📚 Content Management

• Auto Excerpt: Automatically generates post summaries on the index page for a cleaner layout.
• Archives: A timeline view of all your posts to track the writing journey.
• Categories & Tags: Full support for organizing content, making it easy to navigate specific topics.

⚙️ Functionality & Analytics

• Custom Configuration: Easily configure your Menu, Favicon, and RSS Link directly from the config file.
• Google Analytics 4: Built-in support for GA4 to help you understand your audience.
• Disqus Comment: Integrated Disqus support to engage with readers.
• i18n Support: Ready for the world with built-in multi-language support.
• Nunjucks: Powered by the Nunjucks templating engine for powerful and flexible rendering.

---

🚀 Getting Started

To install Shiro v1.0.0, run the following in your Hexo root directory:

git clone --depth=1 https://github.com/Acris/hexo-theme-shiro.git themes/shiro

Then update your _config.yml to set the theme:

theme: shiro

🤝 Feedback

This project is a labor of love. If you encounter any bugs or have feature requests, please feel free to open an issue.

If you enjoy using Shiro, please consider giving it a ⭐️ on GitHub to support my work!

Full Changelog: https://github.com/Acris/hexo-theme-shiro/commits/v1.0.0

---

Made by Acris with ❤️