Onboarding: iissnan/hexo-theme-next

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/iissnan/hexo-theme-next shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across all four use cases

• 15 active contributors
• Distributed ownership (top contributor 43% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 3y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live iissnan/hexo-theme-next repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/iissnan/hexo-theme-next.

What it runs against: a local clone of iissnan/hexo-theme-next — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in iissnan/hexo-theme-next | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 1303 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>iissnan/hexo-theme-next</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of iissnan/hexo-theme-next. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/iissnan/hexo-theme-next.git
#   cd hexo-theme-next
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of iissnan/hexo-theme-next and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "iissnan/hexo-theme-next(\\.git)?\\b" \\
  && ok "origin remote is iissnan/hexo-theme-next" \\
  || miss "origin remote is not iissnan/hexo-theme-next (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "_config.yml" \\
  && ok "_config.yml" \\
  || miss "missing critical file: _config.yml"
test -f "layout/_layout.swig" \\
  && ok "layout/_layout.swig" \\
  || miss "missing critical file: layout/_layout.swig"
test -f "layout/_macro/post.swig" \\
  && ok "layout/_macro/post.swig" \\
  || miss "missing critical file: layout/_macro/post.swig"
test -f "layout/_partials/head.swig" \\
  && ok "layout/_partials/head.swig" \\
  || miss "missing critical file: layout/_partials/head.swig"
test -f "languages/default.yml" \\
  && ok "languages/default.yml" \\
  || miss "missing critical file: languages/default.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 1303 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1273d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/iissnan/hexo-theme-next"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

NexT is an elegant Hexo theme that transforms Markdown content into a beautiful static blog with multiple visual schemes (Muse, Mist, Pisces, Gemini). It solves the problem of creating a professional, feature-rich blog without building a theme from scratch, offering built-in support for comments, search, social widgets, and responsive design through Stylus/CSS preprocessing. Monolithic theme structure: /layout contains Swig templates organized into _partials/ (reusable components like footer, comments), _macro/ (repeating patterns like posts and sidebars), and _custom/ (user overrides). Language files in /languages/*.yml provide i18n. Styling in Stylus (.styl files, not shown in top 60). Configuration via root _config.yml.

Who it's for

Hexo blog authors and maintainers who want a production-ready, highly customizable theme with multiple design schemes. Contributors are theme developers and Hexo ecosystem users seeking to extend or modify the NexT appearance and functionality.

Maturity & risk

This specific repository (iissnan/hexo-theme-next) is no longer actively maintained as of the README warning—the maintainer has passed stewardship to the community fork at theme-next/hexo-theme-next. The v5.1.4 codebase is stable and production-ready but receives no new updates; users should migrate to the maintained fork for active support.

Single-maintainer abandonment is the primary risk—this repo is explicitly unmaintained. Dependencies are dated (Coffee-script 1.10, Gulp 3.9, js-yaml 3.8) with no security audit trail. The codebase has zero test files in the top 60, meaning zero test coverage for layout or styling logic. Migration to theme-next/hexo-theme-next is strongly recommended for new projects.

Active areas of work

Nothing—this repository is archived. Development has moved to theme-next/hexo-theme-next. The README explicitly states 'This repository is no longer maintained' and directs users to the community fork for v6 and v7 releases.

Get running

Clone the specific v5.1.4 release tag (as this master branch is unmaintained):

mkdir themes/next
git clone --branch v5.1.2 https://github.com/iissnan/hexo-theme-next themes/next
cd themes/next
npm install

Then configure your Hexo _config.yml with theme: next. For active development, use the maintained fork instead: git clone https://github.com/theme-next/hexo-theme-next themes/next.

Daily commands: This is a Hexo theme, not a standalone app. Install into a Hexo blog:

cd your-hexo-blog
git clone https://github.com/iissnan/hexo-theme-next themes/next
cd themes/next && npm install

Then run Hexo's dev server from the blog root: hexo server. The theme is not independently runnable—it requires a Hexo instance with content in source/_posts/.

Map of the codebase

• _config.yml — Main theme configuration file where all visual schemes, features, and integrations are enabled/disabled — essential first read for understanding theme capabilities
• layout/_layout.swig — Root template layout that structures the entire page; all other templates inherit from this, making it the core rendering entry point
• layout/_macro/post.swig — Post rendering macro used across multiple pages; handles display of blog articles and is critical to content presentation
• layout/_partials/head.swig — HTML head partial that includes stylesheets, meta tags, and critical rendering path setup; directly impacts performance and SEO
• languages/default.yml — Default i18n language strings used throughout templates; base reference for all 13+ language translations in the theme
• gulpfile.coffee — Build task definitions for linting and asset processing; required to understand theme development workflow and testing

How to make changes

Add a New Language Translation

1. Create a new YAML language file in the languages directory following the structure of languages/default.yml (languages/default.yml)
2. Add all translation key-value pairs matching keys from default.yml for your language code (languages/{language-code}.yml)
3. Users enable your language in their Hexo site _config.yml by setting the language field to your language code (_config.yml)

Enable or Configure a Third-Party Service (Analytics/Comments/Search)

1. Edit the theme's _config.yml and locate the service section (e.g., analytics, comments, algolia_search) (_config.yml)
2. Set the service configuration parameters and enable: true for the desired provider (_config.yml)
3. The relevant index.swig router in layout/_third-party/ will automatically include the enabled service template based on config (layout/_third-party/analytics/index.swig)

Customize or Add a New Sidebar Widget

1. Create a new sidebar widget macro in layout/_macro/ following the pattern of post-copyright.swig or reward.swig (layout/_macro/post-copyright.swig)
2. Add the widget to the sidebar rendering macro in layout/_macro/sidebar.swig with appropriate conditional logic (layout/_macro/sidebar.swig)
3. Add configuration options to _config.yml to control when the widget appears (_config.yml)

Modify or Add a Custom Header/Footer Element

1. Edit layout/_custom/header.swig or layout/_custom/sidebar.swig to inject custom HTML without modifying core theme files (layout/_custom/header.swig)
2. Alternatively, edit the main header/footer partials if making theme-wide changes (layout/_partials/header.swig)
3. Reference custom CSS by including it in layout/_partials/head/custom-head.swig (layout/_partials/head/custom-head.swig)

Why these technologies

• Swig templating engine — Swig is Hexo's default template engine; provides macro support and conditional rendering needed for multi-scheme and feature-flag architecture
• YAML configuration (_config.yml) — Declarative configuration reduces code coupling; users enable/disable features without modifying templates, enabling safe theme updates
• Gulp + CoffeeScript for build — Provides task automation for CSS/JS linting; ensures code quality before deployment without heavy build infrastructure
• Multiple color schemes (Muse, Mist, Pisces, Gemini) — Modular CSS+JS approach allows users to select visual style at runtime; reduces duplication vs. separate theme forks
• Pluggable analytics/comments/search — Router pattern in layout/_third-party/ decouples third-party integrations; enables easy addition of new providers without modifying core layouts

Trade-offs already made

• Static site generation (Hexo) vs. dynamic rendering

  • Why: Hexo generates static HTML at build time, eliminating server costs and improving performance for content-heavy blogs
  • Consequence: No real-time features (live comments, dynamic search) without additional JS client code; all customization happens at build time

• Template-based macros vs. component system

  • Why: Swig macros are lightweight and integrate tightly with Hexo's rendering pipeline without extra dependencies
  • Consequence: Limited code reuse and testability compared to modern component frameworks; macro logic embedded in templates makes debugging harder

• Configuration in _config.yml vs. per-page overrides

  • Why: Centralized YAML config keeps theme setup simple and consistent across all pages
  • Consequence: Users cannot override settings per-post without forking theme; requires template modification for granular control

• Multiple hard-coded third-party integrations

  • Why: Pre-integrates popular services (Google Analytics, Disqus, Valine, Algolia) to reduce setup friction for typical users
  • Consequence: Adds maintenance burden when services change API; theme bloat from unused providers; difficult to swap providers without theme update

Non-goals (don't propose these)

• Does not provide a dynamic comment backend; relies entirely on third-party services (Disqus, Valine, Changyan)
• Does not handle user authentication or content access control
• Does not support real-time updates or server-side rendering; static HTML only
• Not maintained as of the README — project is archived; community fork exists at https://github.com/theme-next/hexo-theme-next
• Does not provide CMS or content management UI; theme only, requires Markdown files and Hexo CLI

Traps & gotchas

No test files: Zero automated test coverage means CSS or template changes have no safety net—manual testing required. Swig version coupling: Hexo pins Swig template version; incompatibilities can break rendering (undocumented). CoffeeScript build artifacts: gulpfile.coffee requires coffee-script binary in PATH; macOS users on ARM64 may hit compilation issues with v1.10.0. Language file extension: All language files are .yml not .yaml—exact naming matters. No compiled assets in repo: CSS is generated from Stylus at build time by Hexo, not included—theme requires Hexo build step. Scheme selection timing: Scheme CSS loads via Hexo config, not at runtime—switching requires rebuild, no live-reload support.

Architecture

Concepts to learn

• Swig Template Engine — NexT uses Swig (Mozilla's template language) exclusively for layout files; understanding Swig tags like {% if %}, {% macro %}, and {{ variable }} is mandatory to modify any template
• Hexo Plugin Lifecycle — This theme integrates deeply with Hexo's rendering pipeline via helper functions, filters, and config hooks; understanding when Hexo calls theme functions is critical for extending it
• Stylus CSS Preprocessor — All theme styling is written in Stylus (not shown in file list but foundational); Stylus variables, mixins, and nesting are used throughout for scheme support and responsive breakpoints
• Multi-Scheme Architecture (CSS Fallback Pattern) — NexT implements four selectable schemes (Muse/Mist/Pisces/Gemini) by conditionally loading different CSS files at build time—not runtime switching; understanding this constraint is key to adding new schemes
• i18n via YAML Language Files — UI strings are centralized in /languages/*.yml files rather than hardcoded; contributing translations or new UI strings requires understanding Hexo's language helper (__()) and YAML structure
• JAMstack Static Blog Pattern — NexT is part of the Hexo JAMstack ecosystem—content is Markdown converted to static HTML at build time, not rendered on request; this shapes design decisions around dynamic features (comments via 3rd-party APIs, search via pre-generated JSON)
• CSS Preprocessor Build Pipeline — Gulp tasks in gulpfile.coffee orchestrate linting and asset processing; understanding this build step is essential for testing theme changes locally before publishing

Related repos

• theme-next/hexo-theme-next — The actively maintained community fork of this project—users should migrate here for v6/v7 updates, bug fixes, and ongoing support
• hexojs/hexo — The parent Hexo static site generator that this theme depends on; theme is rendered by Hexo's Swig engine and uses Hexo plugin APIs
• iissnan/hexo-generator-json-content — Companion plugin by the same author that generates JSON search index—commonly paired with NexT's search widget feature
• probberechts/hexo-theme-cactus — Alternative Hexo theme in the same ecosystem; useful reference for competing multi-scheme architecture patterns
• ppoffice/hexo-theme-icarus — Another popular Hexo theme with plugin system and multiple layouts—demonstrates different approaches to scheme/customization architecture

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test suite for Swig template partials

The repo has 20+ Swig template files in layout/_partials and layout/_macro but no test directory structure. With a test npm script already defined, adding unit tests for critical template rendering (comments, pagination, search, share buttons) would prevent regressions and improve maintainability for new contributors working on template logic.

• [ ] Create test/ directory structure mirroring layout/_partials and layout/_macro
• [ ] Add Mocha/Jest configuration to gulpfile.coffee and package.json devDependencies
• [ ] Write tests for layout/_partials/pagination.swig and layout/_partials/comments.swig (most commonly customized)
• [ ] Add test execution to .travis.yml CI pipeline
• [ ] Document test patterns in .github/CONTRIBUTING.md

Add GitHub Actions workflow for linting language files

The repo has 13 language YAML files (languages/*.yml) but no automated validation. These are frequently contributed to by the community, and syntax errors in these files break builds silently. Adding a GitHub Action would catch malformed YAML and missing translation keys before merge.

• [ ] Create .github/workflows/lint-languages.yml workflow file
• [ ] Add yaml linter step to validate all languages/*.yml files
• [ ] Add step to validate that all language files contain the same root keys as languages/default.yml
• [ ] Add step to check for trailing whitespace (enforced by .editorconfig)
• [ ] Reference the new workflow in .github/CONTRIBUTING.md

Refactor gulpfile.coffee into modular task files for scheme-specific builds

The repo supports 4 visual schemes (muse, mist, pisces, gemini) with scheme-specific scripts in layout/_scripts/schemes/, but gulpfile.coffee likely treats all schemes identically. Creating scheme-specific Gulp tasks would allow contributors to build and test individual schemes without processing all of them, improving development experience.

• [ ] Analyze current gulpfile.coffee structure and identify scheme-agnostic vs scheme-specific tasks
• [ ] Create gulpfile-tasks/ directory with separate files: tasks/lint-scripts.coffee, tasks/build-schemes.coffee, tasks/validate-config.coffee
• [ ] Refactor main gulpfile.coffee to load and orchestrate tasks from gulpfile-tasks/
• [ ] Add npm scripts for individual schemes: npm run build:muse, npm run build:pisces, etc.
• [ ] Update .travis.yml to test individual schemes

Good first issues

• Add test suite for Swig template syntax: Zero test files exist despite 398KB of JavaScript logic; adding jest/mocha tests for /layout/_macro/post.swig and /layout/_partials/comments.swig would prevent rendering regressions and help future maintainers
• Document config schema with JSDoc in _config.yml: Config file has no inline documentation of valid keys, types, or defaults; adding structured comments (e.g., # @type {boolean} for each option) would improve DX for theme users extending it
• Add Lighthouse CI checks to .travis.yml: CI pipeline (.travis.yml) runs only linting; adding Lighthouse performance/accessibility audits for a built demo site would catch CSS/template bloat and a11y regressions early

Top contributors

• @ivan-nginx — 43 commits
• @shenzekun — 26 commits
• @geekrainy — 9 commits
• @maple3142 — 4 commits
• @xCss — 4 commits

Recent commits

• 9c8cea6 — Remove useless comments (kamuiiiii)
• 620b1e8 — Update README, add no longer maintained warning (#2200) (stevenjoezhang)
• 395bcfc — Update ISSUE_TEMPLATE.md (ivan-nginx)
• 1c01ec1 — Update ISSUE_TEMPLATE.md (ivan-nginx)
• 9f7f5ae — Update links in readme's. (ivan-nginx)
• ef1f33b — Update readme (ivan-nginx)
• 413b9a1 — «Promotion». (ivan-nginx)
• bfb7a3b — FIX: In mobile, menu content will cover side bar. (ivan-nginx)
• 049ec23 — Add 6.0.0 link to the bottom-right. (ivan-nginx)
• 5b2268b — Update README.cn.md (ivan-nginx)

Security observations

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.