hexo-theme-warmpaper

"8000 years ago, a Halafian potter painted the same radiating pattern that an AI company would choose as its logo — some visual instincts are older than civilization itself."

A warm Hexo blog theme inspired by Claude's color palette.
Beige background with a subtle orange grid-paper texture for an immersive reading experience.

Live Demo: pidan.dev | 中文

Features

Claude-inspired color scheme (warm beige + orange accent)
Subtle orange grid-paper background texture
Single-column post layout + sticky TOC sidebar with scroll tracking
Card-style post list on homepage
Responsive design (TOC auto-hides on mobile)
LXGW WenKai GB font (CDN with subset loading)
Comment systems: Waline and Giscus (GitHub Discussions), both optional and can coexist
Math (LaTeX) rendering via MathJax v4 (optional)

Installation

Clone the theme into your Hexo blog's themes directory:

cd your-hexo-blog
git clone https://github.com/finch-xu/hexo-theme-warmpaper.git themes/warmpaper

Install the EJS renderer (if not already installed):

npm install hexo-renderer-ejs --save

Enable the theme in your blog's root _config.yml:

theme: warmpaper

Development

Prerequisites

Node.js >= 14
Hexo CLI (npm install -g hexo-cli)

Setting Up

Create a test Hexo blog:

hexo init hexo-test-blog
cd hexo-test-blog
npm install
npm install hexo-renderer-ejs --save

Link the theme to the blog's themes directory:

# Option 1: Symlink (recommended, changes apply instantly)
ln -s /path/to/hexo-theme-warmpaper themes/warmpaper

# Option 2: Clone directly
git clone https://github.com/finch-xu/hexo-theme-warmpaper.git themes/warmpaper

Update the blog's _config.yml:

theme: warmpaper

Create test posts (include multi-level headings to test TOC):

hexo new post "Test Post"

Dev Server

hexo clean && hexo server

Visit http://localhost:4000 to preview. Refresh after modifying theme files.

Common Commands

# Clear cache (recommended after template changes)
hexo clean

# Start local preview server
hexo server

# Start server with drafts visible
hexo server --draft

# Generate static files
hexo generate

# Clean + generate + preview (all-in-one)
hexo clean && hexo generate && hexo server

Static Preview

The project includes preview.html which can be opened directly in a browser to preview the theme's visual style without a Hexo setup.

Build & Deploy

Generate static files:

hexo clean && hexo generate

Generated files are in the public/ directory, deployable to any static hosting service (GitHub Pages, Vercel, Netlify, etc.).

Deploy to GitHub Pages

npm install hexo-deployer-git --save

Configure in your blog's _config.yml:

deploy:
  type: git
  repo: https://github.com/your-username/your-username.github.io.git
  branch: main

Deploy:

hexo clean && hexo deploy

Theme Configuration

Edit _config.yml in the theme directory:

# Navigation menu
menu:
  Home: /
  Archives: /archives

# Profile card (above post list on homepage)
profile:
  avatar: /images/avatar.png     # Avatar image path
  description: "A short bio"     # Bio text
  links:                         # Social links (any number)
    - name: GitHub
      url: https://github.com/yourname
      icon: github               # Supported: github, email, website, twitter, rss, bilibili, zhihu
    - name: Email
      url: mailto:your@email.com
      icon: email
    - name: Website
      url: https://yoursite.com
      icon: website

# Table of Contents (right sidebar)
toc:
  enable: true
  max_depth: 3
  min_depth: 2
  list_number: false

# Math (LaTeX) via MathJax v4 — needs a Markdown renderer that keeps $...$, see "Math" below
math:
  enable: false

# Waline comment system
waline:
  enable: false
  serverURL: 'https://your-server-url'

# Post excerpt link text
excerpt_link: Read More

# Footer copyright (leave empty for default)
copyright: ""

Directory Structure

hexo-theme-warmpaper/
├── _config.yml              # Theme configuration
├── package.json
├── layout/
│   ├── layout.ejs           # Base HTML skeleton
│   ├── index.ejs            # Homepage
│   ├── post.ejs             # Post detail page
│   ├── page.ejs             # Standalone page
│   ├── archive.ejs          # Archive page
│   ├── category.ejs         # Category page
│   ├── tag.ejs              # Tag page
│   └── partial/
│       ├── head.ejs         # HTML head
│       ├── header.ejs       # Navigation bar
│       ├── footer.ejs       # Footer
│       ├── profile.ejs      # Profile card
│       ├── post-card.ejs    # Post card
│       ├── pagination.ejs   # Pagination
│       ├── toc.ejs          # TOC sidebar
│       ├── comment.ejs      # Waline comment template
│       ├── giscus.ejs       # Giscus comment component
│       └── math.ejs         # MathJax formula component
└── source/
    ├── css/
    │   ├── style.css        # Main stylesheet
    │   ├── waline.css       # Waline comment styles
    │   ├── giscus.css       # Giscus comment styles
    │   └── math.css         # Math (formula) styles
    ├── images/
    │   └── logo.svg         # Default theme logo
    └── js/
        └── main.js          # TOC scroll tracking

Math

The theme ships built-in MathJax v4 for rendering LaTeX. It is off by default. Enable it in _config.yml:

math:
  enable: true

Inline math uses $ ... $ or $ ... $; display math uses $$ ... $$ or \[ ... \].
Per-post override: set math: true (force on) or math: false (off for one post) in the post's front-matter.
Loaded only on posts and standalone pages, not on the homepage or listing pages.

Important prerequisite: your Markdown renderer must keep $...$ intact. Hexo's default hexo-renderer-marked turns x_i into italics and eats the backslash in \alpha, breaking formulas. Switch to a math-aware renderer, for example:

npm un hexo-renderer-marked
npm i hexo-renderer-markdown-it

MathJax is loaded on demand from the jsDelivr CDN (pinned to 4.1.2 with Subresource Integrity; bump the version and the integrity hash together when upgrading). If you previously wired up MathJax / KaTeX yourself, remove it to avoid rendering each formula twice.

Fonts

This theme uses the following external font resources:

LXGW WenKai GB

An open-source Kai-style font used for site-wide typography, derived from FONTWORKS Klee One, conforming to mainland China G-source glyph standards.

Font repo: https://github.com/lxgw/LxgwWenkaiGB
Webfont subsets: https://github.com/CMBill/lxgw-wenkai-gb-web
CDN (Regular): https://cdn.jsdelivr.net/npm/lxgw-wenkai-gb-web@latest/lxgwwenkaigb-regular/result.css
CDN (Medium): https://cdn.jsdelivr.net/npm/lxgw-wenkai-gb-web@latest/lxgwwenkaigb-medium/result.css
Font license: SIL Open Font License 1.1

License

Theme code is released under the MIT License.

Referenced font resources are licensed under the SIL Open Font License 1.1.

FilesExpand file tree

README_EN.md

Latest commit

History