npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

hexo-theme-shiro

v1.5.0

Published

A pure and simple theme for Hexo.

Vulnerabilities

Powered byPowered by Snyk
  • 0High
  • 0Medium
  • 0Low

Links

Git

Maintainers

acrisliuacrisliu

Keywords

hexothemeshirotailwindcleansimple

Readme

Shiro (白)

English | 简体中文

A clean, elegant, and robust Hexo theme inspired by whitespace (余白). Built with Nunjucks and Tailwind CSS.

Made by Acris with ❤️

Live Demo

Features

  • Clean Aesthetics: Minimalist design with focus on typography and readability.
  • Responsive: Fully responsive design for mobile and desktop.
  • Tailwind CSS: Modern utility-first CSS framework.
  • Multi-language: Supports English, Simplified Chinese (zh-CN), Traditional Chinese (zh-TW), Japanese (ja-JP), and French (fr).
  • Dark Mode: Elegant dark theme with warm neutral tones, 3-state toggle (system/light/dark).
  • Table of Contents: Build-time generated sidebar TOC for articles with configurable heading depth; client JavaScript only handles folding and active-section highlighting.
  • Reading Progress Bar: Thin vermilion progress bar at the top of the page.
  • Back to Top: Smooth scroll back-to-top button.
  • Code Blocks: Syntax highlighting with copy button and language labels.
  • Images: Content images get build-time loading, decoding, size, and priority attributes; the first article image is kept eager for the initial viewport, and LightGallery assets load on first image click.
  • Comments: Disqus and giscus (GitHub Discussions) comment systems, loaded near the comments area.
  • Google Analytics: GA4 support with non-blocking script loading.
  • RSS: Atom feed support (requires hexo-generator-feed).
  • Seal Stamp: Optional decorative vermilion seal (印章) icon in the header, with customizable character via seal_text.
  • Static Site Search: Built-in static site search powered by Pagefind — index is generated automatically after hexo generate, no external service required.
  • Fast: Optimized for performance with minimal JavaScript, cached build-time page analysis, and content image loading/size hints.

Installation

Install

If you're using Hexo 5.0 or later, the simplest way to install is through npm:

npm i hexo-theme-shiro

Install via git:

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

If you would like to enable RSS, install the feed plugin:

npm i hexo-generator-feed

Enable

Modify theme setting in _config.yml to shiro:

_config.yml
- theme: some-theme
+ theme: shiro

🛠️ Upgrade

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.

Configuration

Config file

Create a dedicated theme config file _config.shiro.yml in your site root (Supported since Hexo 5.0.0). This file will have higher priority than the theme's default config.

Copy the default config that matches your installation into _config.shiro.yml in your site root:

  • npm install: node_modules/hexo-theme-shiro/_config.yml
  • git install: themes/shiro/_config.yml
# Site
site:
  favicon: /favicon.svg
  # Year the site was created; displayed in footer as "since–current" (omit to show current year only)
  # since: 2020
  # Whether to display the seal (stamp) in the header
  seal: true
  # Text displayed inside the seal stamp and favicon (single character recommended)
  seal_text: "白"
  rss:
    enabled: false
    path: /atom.xml

# Navigation menu
# The "name" field accepts any text — use your preferred language.
# Examples: "Home" (English), "首页" (Chinese), "ホーム" (Japanese)
menu:
  - name: Home
    url: /
  - name: Archives
    url: /archives
  - name: Categories
    url: /categories
  - name: Tags
    url: /tags
#  - name: About
#    url: /about
#  - name: GitHub
#    url: https://github.com/Acris/hexo-theme-shiro
#    # Open in new tab
#    target: _blank

# Excerpt settings
# Priority: <!-- more --> tag > auto-truncation (when fallback.enabled: true) > full content.
# For better readability, prefer adding <!-- more --> manually in posts.
excerpt:
  # If post has <!-- more -->, use it.
  # Otherwise fallback to auto-truncated excerpt.
  fallback:
    enabled: true
    # Number of characters to truncate (not words)
    length: 200

# Table of Contents (TOC)
toc:
  enabled: true
  # Max heading depth: 2 = h2, 3 = h2+h3, 4 = h2+h3+h4
  depth: 3
  # Minimum number of headings to show TOC
  min_headings: 3

# Dark mode
# Default theme: system (follow OS), light, or dark
# When default is "system", the toggle cycles through 3 states: system → light → dark.
# When default is "light" or "dark", the toggle switches between light ↔ dark only (no system option).
# When toggle is false, the theme toggle button is hidden and the default theme is always used.
# If toggle is disabled, it is recommended to set default to "light" to match the theme's design.
dark_mode:
  default: light
  toggle: true

# Reading progress bar (thin vermilion bar at top of page)
progress_bar:
  enabled: true

# Back to top button
back_to_top:
  enabled: true

# Comment systems
# Supported providers: disqus, giscus
# Set enabled to true and choose a provider.
#
# Disqus: register at https://disqus.com/admin/create/ and note the
# unique shortname assigned to your site (e.g., "my-blog-name").
#
# 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
  disqus:
    shortname: ""
  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
    # Required when mapping is "specific" or "number"
    term: ""
    # 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/[email protected]/source/css/giscus.min.css
    # true to enable lazy loading (adds data-loading="lazy")
    lazy_loading: false

# Analytics
# Currently supports Google Analytics 4 (GA4).
# To get a GA4 Measurement ID, go to https://analytics.google.com/,
# create a property, then find the ID (format: G-XXXXXXXXXX) under
# Admin > Data Streams > Web > Measurement ID.
analytics:
  google:
    enabled: false
    # e.g., "G-XXXXXXXXXX"
    id: ""

# Site search powered by Pagefind (https://pagefind.app/)
# Index is built automatically after `hexo generate` and written to `public/pagefind/`.
# Strongly recommended: install Pagefind as a site-level devDependency:
# `npm install pagefind --save-dev`
# Without it the hook falls back to `npx --yes pagefind`, which may download during
# `hexo generate` and noticeably slow builds or fail in offline CI.
search:
  enabled: false
  # Pagefind document root selector. Defaults to body to tolerate generated pages
  # without an outer <html> element; set to html to keep Pagefind's default.
  root_selector: body
  # Force language for tokenization (auto-detected from <html lang> by default).
  # Override only if Pagefind fails to detect your site language correctly.
  # force_language: zh

Creating Pages (Tags & Categories)

Since Hexo does not generate 'all tags' or 'all categories' pages by default, you need to create them manually if you wish to use them in the menu.

  1. Create the pages:

    hexo new page tags
hexo new page categories

  2. Modify source/tags/index.md:

    ---
title: Tags
layout: tag
---

  3. Modify source/categories/index.md:

    ---
title: Categories
layout: category
---

Search

Shiro ships with a built-in static site search powered by Pagefind. The index is generated automatically after hexo generate, so you do not need to run a separate search command before publishing generated output.

npm install (strongly recommended)

For the fastest and most reproducible builds, install Pagefind as a devDependency in your site root (not the theme directory):

npm install pagefind --save-dev

This is recommended for both npm i hexo-theme-shiro installs and git clone installs under themes/shiro/. After that, hexo g resolves Pagefind from your site's node_modules automatically. If Pagefind is not installed, the build hook falls back to npx --yes pagefind, which can download during hexo generate, noticeably slow the build, and fail in offline CI. When search.enabled: true, indexing failures fail Hexo generation so broken search is caught before publishing. Treat the npx fallback as an emergency convenience path, not a setup for regular publishing.

Configuration (_config.yml / _config.shiro.yml)

search:
  enabled: true
  # Pagefind document root selector. Defaults to body to tolerate generated pages
  # without an outer <html> element; set to html to keep Pagefind's default.
  root_selector: body
  # Force language for tokenization (auto-detected from <html lang> by default).
  # Override only if Pagefind fails to detect your site language correctly.
  # force_language: zh

Set search.enabled: false to disable the feature: the build hook is skipped and the search button is not rendered.

Local preview

The hook runs on Hexo's before_exit event for the generate (g) and deploy (d) commands. For publishing, run hexo generate before deployment so public/pagefind/ is written before upload. hexo server renders pages from memory and does not trigger this hook, so the search index is not rebuilt during local preview. To preview search locally, run a real build and serve the output:

hexo clean && hexo g
npx serve public

Development

If you want to modify the theme source code or contribute:

Project Structure

hexo-theme-shiro/
├── layout/                 # Nunjucks templates
│   ├── _layout.njk         # Base layout
│   ├── _macro/             # Reusable macros (ui, archive)
│   ├── _partial/           # Partials (head, header, footer, components, comments/index, analytics)
│   ├── index.njk           # Home page
│   ├── post.njk            # Article page
│   ├── page.njk            # Standalone page
│   ├── archive.njk         # Archive page
│   ├── tag.njk             # Tag page
│   └── category.njk        # Category page
├── scripts/
│   ├── helpers.js          # Custom Hexo helpers and generators (build_toc, clean_description, og_image, favicon_svg, etc.)
│   ├── images.js           # after_post_render image loading/decoding/sizing optimizer
│   └── pagefind.js         # Pagefind indexing hook
├── source/
│   ├── css/_tailwind.css   # Core Tailwind CSS source (compiled to style.min.css)
│   ├── css/_src/*.css      # Optional feature CSS sources ignored by Hexo
│   ├── css/*.min.css       # Generated CSS assets loaded on demand
│   ├── js/_src/*.js        # Client-side script sources ignored by Hexo
│   └── js/*.min.js         # Generated client-side scripts and feature bootstraps
├── tools/
│   ├── build-assets.js     # Release asset build script
│   └── snippets/           # Build-time JS snippets injected before minification
├── languages/              # i18n YAML files (en, zh-CN, zh-TW, ja, fr, etc.)
├── _config.yml             # Theme default config
└── package.json

Getting Started

  1. Install dependencies in the theme directory:

    cd themes/shiro
npm install

  2. Watch for CSS changes during development:

    npm run dev

  3. Build CSS and JavaScript for production:

    npm run build

Note: After modifying _tailwind.css, optional feature CSS under source/css/_src/, files under source/js/_src/, or build-time snippets under tools/snippets/, run npm run build to regenerate style.min.css, feature *.min.css, and *.min.js assets.

Adding a New Language

  1. Create a new YAML file in languages/ (e.g., ko.yml).
  2. Copy the structure from languages/en.yml and translate all values.
  3. Keep keys sorted alphabetically at each level and ensure all top-level namespaces (clipboard, common, gallery, index, nav, page, search, theme, toc) are present.

Thanks

Thanks to JetBrains for providing open source licenses.

License

MIT License