LoveIt: A Hugo Theme for Posts That Need Math, Diagrams and Music

What LoveIt adds that a plain Hugo theme does not

Hugo ships with shortcodes for the basics, but a post that mixes a KaTeX formula, a mermaid flowchart, an ECharts chart and a Bilibili video normally means pasting vendor script tags into the Markdown by hand. LoveIt packages those as shortcodes and extended Markdown syntax, so the author writes a tag and the theme handles the library. The README lists KaTeX for mathematical formulas, mermaid for diagrams, ECharts for interactive data visualization, Mapbox GL JS for maps, APlayer with MetingJS for a music player, and a Bilibili player. It also extends Markdown for Font Awesome icons, ruby annotation and fractions.

The target reader is a Hugo user who publishes technical or media-heavy posts and wants the visual layer decided in advance: light and dark mode, a self-expanding table of contents, pagination, responsive layout, and i18n. The README also lists up to 84 social links, up to 27 share sites, and comment backends including Disqus, Gitalk, Valine, Facebook, Telegram, Commento, utterances and giscus. That breadth is the point. It is also the reason the theme carries more moving parts than a minimal Hugo theme does.

How the theme is assembled: Hugo templates, a Babel step and vendored libraries

The repository layout separates what Hugo reads from what the browser runs. Hugo reads layouts/, assets/, i18n/, archetypes/ and hugo.toml. The browser-side code lives in src/js and is compiled by Babel into assets/js/theme.js. The package.json script that does this is "compile": "npx babel src/js --out-file assets/js/theme.js". A second script, compile-lunr-segmentit, runs browserify over src/lib/lunr/lunr.segmentit.js with babelify and the @babel/preset-env preset, producing assets/lib/lunr/lunr.segmentit.js.

That second script matters for anyone writing in Chinese or Japanese. Lunr.js does not segment unspaced text on its own, so the theme bundles segmentit, a segmentation library, and wires it into a Lunr build. Search in the README is described as supported by Lunr.js or algolia; the Lunr path is the one that depends on this compiled artifact, while algolia moves the index to a hosted service.

The module declaration in go.mod is github.com/dillonzq/LoveIt with go 1.18, which is what makes the theme installable as a Hugo module rather than only as a git submodule. The theme.toml file at the repository root is the metadata Hugo expects for a theme directory, and netlify.toml plus .github/ hold the deploy and CI configuration used for the project's own demo site.

Installing LoveIt and rendering the exampleSite

The README documents building the documentation locally with a single command, run from the theme repository root:

hugo server --source=exampleSite

The --source flag points Hugo at exampleSite/, which is the demo content directory in the repository. Hugo serves the site on its default local address and the reader should see the LoveIt demo, including the home page and its documentation section. The exampleSite directory is also where the theme's own hugo.toml lives, so it doubles as a working configuration reference.

For theme development, package.json exposes a longer set of scripts. The development server with drafts enabled and fast render disabled is:

npm run hugo-server

A production build of the example site, with garbage collection and minification, is:

npm run hugo-production

If you edit anything under src/js, the compiled bundle in assets/js/theme.js goes stale until you run npm run compile. The Lunr segmentation build is separate and only needs rerunning when src/lib/lunr/lunr.segmentit.js changes. Note that the preinstall script runs npx npm-force-resolutions, so an npm install in this repository is not a plain install.

To use the theme in your own site, add it as a Hugo module or a git submodule and enable it in your site configuration. The README does not spell out the module import line, so take the module path from go.mod, github.com/dillonzq/LoveIt, and confirm the exact configuration syntax against the documentation site rather than guessing.

The dependency surface is the real cost

Every one of those shortcodes is a third-party library that has to be fetched and executed. The README states that a CDN for third-party libraries is supported, which is convenient and also means a page can pull scripts from hosts outside your control unless you self-host the assets. A post with a mermaid diagram, a KaTeX formula and an ECharts chart loads three separate libraries. On a page that uses none of them, the honest question is whether the theme's asset pipeline avoids shipping them anyway; the README describes the features but does not document per-page asset gating.

The README claims 99/100 on mobile and 100/100 on desktop in Google PageSpeed Insights. Treat that as a claim about the demo site's home page, not a property of your site. A documentation home page with no embedded players is a different measurement target from a post carrying a music player and a map.

The JavaScript build step is the other constraint. If you install LoveIt as a module and never touch src/, you do not need Node at all, because assets/js/theme.js is committed. The moment you want to change theme JavaScript, you inherit Babel, browserify, core-js and segmentit as build dependencies, plus the npm-force-resolutions preinstall hook. For a theme whose selling point is convenience, that is a heavier contributor setup than a CSS-only alternative.

LoveIt against the themes it forked from

LoveIt is derived from LeaveIt and KeepIt, and the README says so directly, noting that the three look similar and pointing readers to a section explaining the differences. That section is the honest comparison to make, because the alternatives are the ancestors rather than an unrelated project.

The listed differences are a custom header, custom CSS, a new home page compatible with the latest Hugo version, style detail adjustments covering color, font size, margins and code preview, a more readable dark mode, CSS animations, a self-expanding table of contents, and a wider set of social links, share sites and comment systems. Search via Lunr.js or algolia, one-click code copy, the extended Markdown syntax, KaTeX, mermaid, ECharts, Mapbox, the music player and the Bilibili player are all listed as LoveIt features.

So the practical difference is breadth and maintenance rather than a different rendering model. All three are Hugo themes with the same visual lineage. If you only need a clean blog with a dark mode, the upstream themes are smaller surfaces. If you want the shortcode set and the extended Markdown syntax, LoveIt is the one that carries them, and the README's own advice is to pick based on which design language you prefer.

Version compatibility and what upgrading costs

The README opens with a Hugo badge reading ^0.128.0, and the compatibility section is a table mapping LoveIt branches or versions to supported Hugo versions. The table's body is truncated in the README as given here, so the exact rows are not verifiable from this text. Check that table before pinning a Hugo version, because a theme that relies on recent Hugo template functions will fail to build on an older binary, and the failure appears at build time rather than at runtime.

Release cadence is uneven. v0.2.11 is dated 2022-05-12, v0.3.0 is dated 2025-02-12, and v0.3.1 is dated 2026-02-25. That is a long gap followed by two releases about a year apart, so a site pinned to v0.2.11 has skipped a major-version jump to reach the current line. The repository itself is not archived and the last push was on 2026-09-01, which is recent, but the tagged releases are the stable surface and they move slowly.

Upgrade cost depends on how much you changed. If you edited layouts/ or assets/ directly, a theme update conflicts. Installing via Hugo modules or a submodule keeps your overrides in your own site directory and makes the update a version bump. The README does not document a rollback procedure, so keep the previous module or submodule revision recorded before you move.

The licence is MIT, stated in the README badge and in the LICENSE file at the repository root, and package.json repeats "license": "MIT". MIT permits reuse and modification with the copyright notice retained. That covers the theme's own code. The bundled third-party libraries carry their own licences, and the README does not enumerate them here; if you redistribute a built site or fork the theme, check the licence of each library you actually ship. This is a description of what the repository states, not legal advice.

Editorial conclusion

LoveIt fits a Hugo site where posts carry formulas, diagrams or embedded media and the author is comfortable editing hugo.toml. It is the wrong pick if you want a theme with no JavaScript build step, or if you only need plain prose and resent carrying Lunr, KaTeX, mermaid, ECharts and Mapbox assets. Before adopting it, verify the Hugo version you run against the compatibility table in the README, and decide whether search will use Lunr.js or algolia, because that choice changes which assets get loaded.

Frequently asked questions

Official sources

1. dillonzq/LoveIt on GitHub
2. License: MIT
3. Project website
4. README
5. Releases