Hexo Theme Cosy is a document-oriented Hexo theme built with Web Components and litElement that prioritizes loading speed, shipping only 52.2 KB of JavaScript after gzip compression. It is developed for Hexo 7.0 and uses a pnpm workspace monorepo structure with a webpack dev server for hot updates during development.
What is Hexo Theme Cosy?
Cosy is a theme for Hexo, the static site generator, designed for documentation-style blogs and fast-loading content sites. It takes Hexo markdown posts and pages as input and renders them into a static site through the Hexo build process, with the theme output generated into the theme-cosy/build directory. The project is maintained as an open-source repository and includes both Chinese and English README files. Its UI components are implemented as Web Components inheriting from a CosyElement base class built on LitElement, and the visual style follows a "Linear Design" aesthetic.
Key Features
- Ultra-light JavaScript — The theme's total JavaScript bundles to 52.2 KB when gzip-compressed, minimizing render-blocking resources.
- Theme switching — Built-in dark and light modes, as shown in the project preview screenshots.
- Prism syntax highlighting — Code blocks are highlighted using Prism, with no disable option listed in the features table.
- Algolia search — Integrated Algolia search is included as a feature; it can be enabled for site search.
- Global theme color configuration — The accent color for the entire theme is controlled by a
colorattribute in the Hexo theme configuration file. - KaTeX formulae — Mathematical formulas can be rendered with KaTeX, and the feature can be disabled.
- Mermaid flowcharts — Mermaid diagrams are supported for flowcharts and graphs, with a disable option.
- Comment system options — Both Valine and Twikoo comment systems are supported, each independently disableable.
- HeFeng weather widget — A weather widget powered by HeFeng is available and can be disabled.
- Custom pages and shortcuts — Preferences and Tags custom pages are included, and a keyboard shortcut system is built in.
Who is it for?
Cosy is for bloggers and technical writers who publish documentation or long-form content and want a clean, linear layout with fast load times. Developers who use Hexo and want to customize their theme with reusable Web Components will find the monorepo structure and dev server workflow useful. Site owners looking for a theme with integrated Algolia search, KaTeX math, and Mermaid diagrams can configure these features directly in the theme config.
What can you do with Hexo Theme Cosy?
- Technical bloggers: publish markdown posts with syntax-highlighted code blocks, KaTeX formulas, and Mermaid diagrams without adding heavy client-side libraries.
- Documentation sites: organize content into a document-oriented layout with Preferences and Tags pages, plus Algolia search for discoverability.
- Theme developers: create new modules under
apps/theme/src/moduleswithindex.ejs,index.ts, andindex.lessfiles, then include them with EJS partials. - Customizers: disable optional widgets like the HeFeng weather widget or switch between Valine and Twikoo comments through the feature flags.
How does Cosy work?
To develop or customize the theme, clone the repository and run pnpm install to install dependencies. Then build the utility package with pnpm build:util, start the webpack dev server with pnpm dev, and run pnpm dev:hexo to enable hot updates on the Hexo test site; the browser preview opens at localhost:12004. For production, pnpm build outputs the complete theme to the theme-cosy/build directory.
Pros and cons
- Pros: Very small JS footprint, modern Web Component architecture, hot-reload development workflow, and a large set of optional integrations.
- Cons: The theme requires Hexo 7.0, whose configuration file format differs from earlier 6.3 versions, and the pnpm workspace monorepo setup adds complexity for casual users.
FAQ
Is Hexo Theme Cosy free?
The repository does not mention pricing, and it is published as an open-source Hexo theme, so it is available for free use under the project's license terms.
What Hexo version does Cosy require?
The v2.0 update notes state the theme is developed based on Hexo 7.0, and that its configuration file differs from the one used by Hexo 6.3. You should use Hexo 7.0 or newer.
How large is the theme's JavaScript?
The total JavaScript size is 52.2 KB when compressed with gzip, which is the key selling point for pages that prioritize loading speed.
How do I add a new module to Cosy?
Create a folder under apps/theme/src/modules containing an index.ejs, index.ts, and index.less. The EJS file should include the <!-- inject:css --> and <!-- inject:js --> comment markers that webpack replaces, then run pnpm dev again.
Can I disable the optional features?
Yes. The feature table lists disable options for the HeFeng weather widget, KaTeX formulae, Mermaid flowcharts, Valine comments, and Twikoo comments. Theme switching, Prism highlighting, Algolia search, and global color configuration do not have listed disable options.
