Chaos

Chaos is a minimalist Hugo theme built for clarity, performance and Chinese typography support, requiring Hugo 0.158.0 or later (standard, not extended). Sites install it as a Hugo Module, a Git submodule or by extracting a release tarball, then configure it through hugo.toml plus Markdown front matter.

What is Chaos?

Chaos is a Hugo theme that turns Markdown content into a static blog with article pages, taxonomy listings, archives, paginated home pages, ATOM/RSS feeds and an XML sitemap. It runs on Hugo as the generator and ships no JavaScript framework; all assets are self-hosted. The README names the repository as github.com/delphij/chaos-theme and provides an exampleSite/ demo blog for local preview.

What makes Chaos stand out?

• Chinese and CJK typography — modern CSS (text-autospace, hanging-punctuation, auto-phrase) plus a warning that sites must set hasCJKLanguage = true themselves, because Hugo does not inherit it from a theme and would otherwise undercount words and never truncate summaries.
• Japanese Wairo palette — accents and inks use traditional colours at values published in 和色大辞典, from 生成り色 #FBFAF5 and 蘇芳 #9E3D3F by day to 退紅 #D69090 and 浅縹 #84B9CB by night, with WCAG AA contrast targets.
• Three-state colour mode — Auto/Light/Dark toggle that follows live OS preference changes.
• Offline client-side search — a two-tier index written by build_search_index.py: a small core index for titles and tags, then a body index streamed via requestIdleCallback; ranking combines BM25-IDF with field boosts (+120 exact title, +45 tag phrase) and demotes posts marked deprecated to 0.25x.
• KaTeX math — enabled through Goldmark passthrough with $$ block and \( inline delimiters.
• Print-ready articles — footnotes and external links merge into one numbered notes list, code blocks shorter than 14 lines stay unbroken.
• Instant navigation — W3C Speculation Rules API with an instant.page 5.2.0 fallback, plus CSS view transitions.
• Responsive images — page-bundle images render as <picture> with WebP, 360/640/960/1232px widths and explicit dimensions to avoid layout shift.

Who is it for?

• Chinese-language bloggers: publish Simplified or Traditional content with correct word counts, ruby annotations via [汉字]^(hàn zì) and balanced CJK line breaking.
• Technical writers: document kernel debugging or shell scripts with KaTeX, syntax highlighting and searchable code blocks.
• Multilingual publishers: run content in English, zh-CN, zh-TW, Japanese and Korean with automatic hreflang and x-default links.

What can you do with Chaos?

• Write interactive tutorials: declare code_vars in front matter and readers edit parameters in a panel, updating every code block occurrence and persisting values in the URL query string.
• Embed X posts privately: run fetch_x_embed.py to cache tweets into data/x_embeds/, stripping scripts, event handlers and iframes.
• Add comments: configure the optional Remark42 server via remarkURL, remarkSiteId and remarkLocale.

Pros and cons

• Build steps are required for some features: search needs build_search_index.py, and readable feeds/sitemap need post_build.sh with xsltproc.
• Known limitation: Chrome and Edge do not apply CJK line-breaking to inline KaTeX formulas, so Chinese punctuation may start a line; Safari and Firefox work correctly.

FAQ

Is Chaos free?

The README does not state a license or price; it is distributed through GitHub releases and the Hugo Module path github.com/delphij/chaos-theme, so treat it as an open-source repository whose terms are set in that repo.

Does Chaos support dark mode?

Yes. A three-state toggle switches between Auto, Light and Dark, and Auto syncs with OS preference changes in real time. Dark mode keeps the colour roles rather than inverting values, pairing 蘇芳 with 退紅 and 藍 with 浅縹.

What Hugo version does Chaos need?

Hugo 0.158.0 or later, in the standard edition; the extended build is not required. The theme also needs no npm packages, and all dependencies such as KaTeX 0.19.0 and Mermaid 11.17.2 are vendored in static/_3p/.