# Hux Blog: A Jekyll Theme and Personal Blog Built for GitHub Pages

> Hux Blog is a Jekyll-based personal blog and theme originally designed by Huxpro, offering Progressive Web App support, a LESS-based style system, and a clean typographic layout that can be forked and customized for GitHub Pages hosting.

**Huxpro/huxpro.github.io** — My Blog / Jekyll Themes / PWA

- Repository: https://github.com/Huxpro/huxpro.github.io
- Website: http://huangxuan.me
- Stars: 7,613 · Forks: 6,562
- Language: HTML
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/huxpro-huxpro-github-io

## What Hux Blog Is and Who It Serves

Hux Blog started as the personal blog of Huang Xuan (Huxpro) and evolved into a Jekyll theme that other developers fork for their own GitHub Pages sites. The repository at huxpro.github.io is described as the original theme, preserved at that address, while the author's current website lives at hux.pro.

The target audience is engineers who want a ready-made Jekyll blog with a professional typographic appearance, Progressive Web App features, and enough configurability to swap colors, posts, and about pages without writing a build system from scratch. The repository also serves as a reference implementation for those interested in how PWA techniques (a service worker at sw.js, an offline page, a web app manifest) integrate with a static Jekyll site.

## Repository Layout and Key Directories

The repository is structured as a standard Jekyll project with several additions for the theme's asset pipeline. The critical Jekyll code lives in two directories: _includes/, which holds reusable Liquid template fragments, and _layouts/, which holds the page templates that wrap post content. Understanding those two directories is the minimum needed to customize how posts are rendered.

Styles are written in LESS under the less/ directory and compiled to CSS during the Grunt build. The css/ directory holds the compiled output that Jekyll serves. The fonts/ directory packages the typefaces used by the theme. The pwa/ directory and sw.js at the root implement the Progressive Web App layer, including a service worker and an offline.html fallback page.

Post content lives in _posts/ and follows Jekyll's standard filename convention. The search.json file at the root feeds a client-side search implementation. The package.json names the project hux-blog at version 1.8.2, and the devDependencies list Grunt, grunt-contrib-less, grunt-contrib-uglify, and grunt-contrib-watch as the only build tools required.

## Getting the Site Running Locally

The README requires Ruby and Bundler, and links to the official Jekyll guide for installing those dependencies. With those in place, install the Gem dependencies listed in the Gemfile:

```sh
$ bundle install
```

Serve the site locally on port 4000:

```sh
$ bundle exec jekyll serve
```

The README notes an alternative shorthand: `npm start` runs the same command via the scripts section of package.json. For active theme development, the Grunt watch task monitors LESS files and recompiles CSS on change. Running development mode starts both the Grunt watcher and the Jekyll server:

```sh
$ npm run dev
```

This command is defined in package.json as `grunt watch & npm run start`. Grunt must be installed globally or accessible via the local node_modules path for this to work.

## The Asset Pipeline: Grunt, LESS, and What Is Old-Fashioned About It

Modifying the theme's visual appearance requires working with the Grunt pipeline. The Gruntfile.js defines tasks for compiling LESS to CSS, minifying JavaScript, adding license banners to keep the Apache 2.0 attribution intact, and watching for source changes.

The README is direct about the state of this pipeline: "Yes, they were inherited and are extremely old-fashioned. There is no modularization and transpilation, etc." This means there is no webpack, no ES module bundling, and no TypeScript compilation. JavaScript is concatenated and minified through grunt-contrib-uglify without a module graph. CSS is compiled from LESS files without PostCSS or Autoprefixer.

For teams accustomed to modern JavaScript tooling, this is a meaningful constraint. Adding a new JavaScript dependency means manually copying a file and updating the Grunt config. The upside is that the build has no complex dependency graph to break: the Grunt tasks are small and straightforward to read.

The syntax highlighter is Rouge, which Jekyll uses by default. The README explains that Rouge is compatible with Pygments themes, so any Pygments CSS file can be placed in highlight.less to change how code blocks look.

## Progressive Web App Features and Offline Support

The repository includes a service worker (sw.js) at the root, an offline.html fallback, and a pwa/ directory. These elements make the blog installable as a Progressive Web App on supporting browsers and give readers a fallback page when they visit while offline.

The service worker approach is built into the Jekyll site as static files rather than generated at build time. This means cache strategies and the list of precached assets are defined manually in sw.js rather than through a toolchain like Workbox. For a personal blog where content changes infrequently, this is a workable trade-off, but it means updating the service worker is a manual step whenever significant content or asset changes are made.

The search.json file at the root serializes post metadata for the client-side search feature, generating a flat JSON index that JavaScript in the browser reads to filter results. No server-side search component is required.

## Ports, Boilerplate, and Known Limitations

The README lists community ports of the theme to other static site generators. A Hexo port is maintained by a third party, and a React-SSR variant exists but is separate from this repository and not under the same author's maintenance.

The official starter/boilerplate repository linked from the README is explicitly noted as out of date, with a call for contributors to update it. Anyone starting a new site from Hux Blog should fork the main repository directly rather than using the boilerplate, since the boilerplate may not reflect the current theme structure.

The Chinese documentation linked in the README is also described as somewhat out of date. The primary English README is the authoritative reference.

The repository has no GitHub releases. The package.json records the version as 1.8.2, but there is no formal changelog. The last push was on 2026-09-13.

## License and Upstream Attribution

The project is licensed under Apache License 2.0, copyright 2015 to present by Huxpro. The README notes that Hux Blog derives from the Clean Blog Jekyll Theme by Blackrock Digital, which is MIT-licensed. The Grunt build tasks include a banner step specifically to keep the Apache 2.0 license header intact in compiled output.

This dual-origin licensing means forks must retain the Apache 2.0 attribution for Hux Blog's own additions and the MIT attribution for the Clean Blog base. Both licenses permit commercial use. The Apache 2.0 license adds an explicit patent grant that the MIT license does not include.

## Conclusion

Hux Blog suits developers who want a Jekyll-based personal blog with a clean typographic design and do not want to maintain a full Node.js build pipeline. The Grunt-based asset compilation pipeline is described in the README as 'extremely old-fashioned' with no modularization or transpilation, so teams expecting a modern front-end toolchain should evaluate more recent Jekyll starters. The boilerplate repository linked in the README is noted as out of date. For anyone starting from this theme, running `bundle exec jekyll serve` confirms the build works before customizing _config.yml and the _posts directory.

## FAQ

### Is it free to host a site using the Hux Blog theme on GitHub Pages?

GitHub Pages hosting for public repositories is free of charge. The Hux Blog theme itself is Apache-licensed and costs nothing. Running the theme locally requires Ruby, Bundler, and optionally Node.js with Grunt for theme development.

### What do I need to install before running Hux Blog locally?

The README requires Ruby and Bundler. Once those are in place, running `bundle install` from the repository root installs the Jekyll Gems and other dependencies listed in the Gemfile. For theme development, Node.js and Grunt are also needed to compile LESS files.

### Can the Hux Blog theme be used with Jekyll plugins or static site generators other than Jekyll?

The repository is a Jekyll project. Community ports for Hexo and a React-SSR variant are listed in the README but are maintained by third parties. The main repository targets Jekyll and GitHub Pages.

## Sources

- [Huxpro/huxpro.github.io on GitHub](https://github.com/Huxpro/huxpro.github.io)
- [Issues](https://github.com/Huxpro/huxpro.github.io/issues)
- [License: Apache-2.0](https://github.com/Huxpro/huxpro.github.io/blob/master/LICENSE)
- [Project website](http://huangxuan.me)
- [README](https://github.com/Huxpro/huxpro.github.io/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/huxpro-huxpro-github-io