CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Purpose

This repository contains the documentation site for doc.davidhsaiou.com, built with docfx. Markdown articles live under docs/, navigation is driven by toc.yml files, and the custom template lives under templates/custom/.

Operational notes — Cloudflare zstd workaround

The docfx site at doc.davidhsaiou.com once silently lost its left-sidebar TOC tree because Cloudflare auto-applied Content-Encoding: zstd to JS responses, and Chromium's native import() module loader returned an empty namespace for zstd-encoded module scripts (while fetch() decoded the same body fine — verified via Blob-URL re-import).

Workaround applied (2026-04-22): A Cloudflare Cache/Transform Rule sets Cache-Control: no-transform on /public/*.js responses for the doc.davidhsaiou.com zone. This prevents Cloudflare from re-encoding JS modules with zstd. TOC tree returned immediately after the rule was applied.

Configuration: Cloudflare zone for doc.davidhsaiou.com → Rules → Transform/Cache Rule on *.js paths → set Cache-Control: no-transform.

If TOC disappears again, check first:

  1. curl -sI https://doc.davidhsaiou.com/public/main.js — if Content-Encoding: zstd is back, the no-transform rule was removed or scoped wrong.
  2. Browser console: (await import('/public/main.js')).default should return { start: Function }. If it returns undefined, the zstd issue is back.

Anti-pattern: Do NOT look for repo-level fixes (template, CSS, JS) — the file in the repo is correct (export default { start() {} }). The bug is purely in the network/encoding path between Cloudflare and the browser.

Original investigation: COR-1226 fixed the IIFE → ES module export issue; the zstd interaction was discovered after that fix shipped in v0.1.1.