blogs/FixIt
1
0
Fork 0
mirror of https://github.com/hugo-fixit/FixIt.git synced 2026-08-24 15:28:57 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
0fe8e100df8382f8cbe34239eea30f2c1e4089c4
FixIt/CLAUDE.md
T
Cell 14a965f9c1 refactor(assets): migrate JavaScript to TypeScript service architecture (#766) 
* refactor: add TypeScript support and refactor utility functions

* docs: add CLAUDE.md for Claude Code guidance

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(assets): replace factory-function pattern with service classes and DI container

Introduce typed service container, event bus, and service interfaces to replace
the shared FixItContext factory-function pattern. Each module is now a standalone
class implementing a typed interface, with explicit constructor-injected
dependencies. The window.fixit backward-compatibility facade is built via a
publicAPI() helper that extracts class methods.

Also removes unnecessary setTimeout/afterPaint deferred execution wrappers
from init sequences, and improves module header comments.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor: replace private properties with class fields in modules

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* refactor(assets): rewrite link page script in TypeScript

Rename pages/link.js to link.ts with proper type annotations and update
the Hugo template reference accordingly.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs: rewrite CLAUDE.md and copilot-instructions.md in English

Update both files to reflect the new service-class architecture with
DI container, typed event bus, and ES6 # private fields.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix: update event handling to use CustomEvent for better type safety

* refactor: enhance theme switching by adding isChanged flag to event details

* refactor(assets): refactor Mermaid module structure and event wiring

* refactor(assets): align lib integrations with TypedEventBus and add module overviews

* chore(assets): remove vite-specific import ignore comments

* refactor(assets): remove deprecated forEach utility and use native forEach

Replace custom forEach wrapper with native .forEach() on NodeList, HTMLCollection (via querySelectorAll), and arrays. The utility was already marked @deprecated and all 30+ call sites use synchronous handlers, making the wrapper unnecessary. Also replace getElementsByClassName/getElementsByTagName with querySelectorAll for consistency.

- Delete utils/array.ts (no longer needed)
- Remove forEach export from utils/index.ts
- Refactor 11 module files to use native .forEach()
- Switch getElementsByClassName to querySelectorAll in theme.ts and charts.ts

* refactor(assets): split ChartsModule into independent lib files

Move ECharts, Mapbox GL, and TypeIt integrations from the ServiceContainer-managed ChartsModule into three standalone lib files (echarts.ts, mapbox.ts, typeit.ts). Each lib:
- Instantiates its own TypedEventBus
- Reads config from window.config.*
- Self-initializes on DOMContentLoaded
- Handles decrypt/re-init events independently
- Uses implicit idempotency via DOM element queries

Key improvements:
- Reduces ServiceContainer complexity
- Makes chart libs independently loadable
- Fixes partial decryption handling in echarts (only re-inits decrypted portion)
- Maintains consistency with aplayer/file-tree lib pattern

* refactor(assets): extract third-party libraries to standalone lib files

Extract twemoji, pangu, cookieconsent, watermark, lightgallery, and json-viewer
from modules into separate lib files for better separation of concerns. Each lib
is loaded conditionally via assets.html and handles its own initialization and
event lifecycle independently.

Additionally, unify fixit event handling by replacing document.addEventListener
calls with TypedEventBus.on() in EncryptionModule and MiscModule for consistent
event architecture.

Remove unused MiscService dependency from ContentModule.

* refactor(assets): unify js.Build pipeline and defaults

- extract shared helper partial function/js-build.html for js.Build + minify

- make plugin script renderer and Mermaid use the same js.Build logic

- default Build.minify to hugo.IsProduction when unset

- default Build.sourceMap to cond hugo.IsDevelopment "linked" "none"

- remove duplicated sourceMap branching in layout templates

- update js targetPath naming to .js (no explicit .min.js suffix)

* refactor(assets): extract comment systems to independent lib files

Extract comment system initialization logic from CommentModule into 7 independent
lib files (artalk, gitalk, valine, waline, utterances, twikoo, giscus). Each lib:
- Conditionally loads based on window.config.comment configuration
- Handles backend-specific initialization via DOMContentLoaded
- Manages its own theme synchronization and event listeners
- Is loaded conditionally in assets.html only when enabled

Simplify CommentModule to handle only:
- Comment section UI display and visibility toggle
- Shared lightGallery initialization utility (used by Artalk and Twikoo)
- Comment expiration handling

This reduces module complexity and enables per-backend lazy loading.

* refactor(assets): unify js.Build pipeline and consolidate PWA config

Enhance js-build.html to accept Build as bool/dict, auto-derive
targetPath from resource name (.ts → .js), and skip js.Build when
Build is false/omit. Simplify assets.html by removing explicit
targetPath dicts for all .ts lib builds. Consolidate enablePWA and
serviceWorkerURL into a PWA config object.

* refactor(assets): decouple toc from content module and add JSDoc headers

- Remove TocService dependency from ContentModule, toc now self-manages
- Rename initContent() → setup(), init() → setup() for toc
- Make initFootnotes private (#initFootnotes)
- Add multi-line JSDoc headers with Responsibilities to all modules,
  main.ts, pages/link.ts, and head/color-scheme.ts

* refactor(assets): split types.ts into types/ directory module

* refactor(assets): simplify JS module architecture and expose typed window.fixit API

- Remove DI container (core/container.ts), use direct constructor calls
- Export shared eventBus singleton from core/event-bus.ts, remove 16 redundant instances
- Merge thin modules: SvgModule/CommentModule/LinkGuardModule into ContentModule/MiscModule
- Trim service interfaces to externally-used methods only
- Replace publicAPI() reflection with minimal typed window.fixit facade
- Expose public APIs: setThemeMode, eventBus, initContent, mask overlay, scroll state
- Extract setThemeMode from initSwitchTheme closure as public method
- Rename fixit:reset to fixit:re-encrypt, remove dead events
- Replace custom.js.example with custom.ts.example
- Update CLAUDE.md and copilot-instructions.md

* style(i18n): use semantic names for comment dividers instead of file paths

Replace file-path-based comment dividers (e.g. partials/base/header.html)
with semantic names (e.g. Header) across all 16 i18n files for consistency.

* chore(workflow): update cron schedule for library updates

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-28 12:43:42 +08:00

142 lines
6.6 KiB
Markdown
Raw Blame History

# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
FixIt is a modern, responsive theme for the Hugo static site generator. Built with Hugo templates, SCSS, and TypeScript.
## Development Commands
### Prerequisites
- Node.js >= 20
- Hugo Extended >= 0.158.0 (Dart Sass required)
- pnpm
### Development
```bash
pnpm install # Install dependencies
pnpm dev:demo # Start demo site dev server
pnpm dev:test # Start test site dev server
pnpm dev:docs # Start docs dev server (requires fixit-docs as sibling directory)
```
### Build
```bash
pnpm build:demo # Build demo site
pnpm build:test # Build test site
pnpm build # Build all sites (demo + test, merged into public/)
pnpm preview # Preview built site (requires build first)
```
### Code Quality
```bash
pnpm lint # Run ESLint
pnpm typecheck # Run TypeScript type checking
```
There are no unit tests. Verify changes by building `pnpm build:demo` or `pnpm build:test` and inspecting the output.
## Architecture
### Monorepo Structure
Root `package.json` is `@hugo-fixit/core`. pnpm workspaces include `apps/*` and `packages/*`:
- `apps/demo/` — Demo site (deployed to `demo.fixit.lruihao.cn`)
- `apps/test/` — Test site for exercising theme features
- `packages/shared` — Shared utilities (exports `workspaceRoot`)
- `packages/versioning` — Version management (auto-updates version in `layouts/_partials/init/index.html` during pre-commit)
- `packages/integration` — Post-build: merges demo/test output into `public/`
### JavaScript Module System (`assets/js/`)
Service-class architecture with direct constructor calls:
- **`main.ts`** — Entry point. Instantiates all modules with direct constructor calls, builds the typed `window.fixit` public API facade, and runs the init sequence on `DOMContentLoaded`.
- **`types/`** — TypeScript type definitions:
- `config.ts` — `FixItConfig` and all config sub-types.
- `ui.ts` — `FixItPublicAPI`, global `window` augmentation for third-party libs.
- `third-party.ts` — Types for vendored libraries.
- **`core/`** — Infrastructure layer:
- `event-bus.ts` — Typed event bus singleton wrapping DOM `CustomEvents`. Exports `eventBus` (module-level singleton) and `FixItEventMap` type.
- `tokens.ts` — Service interfaces (`CoreService`, `ThemeService`, `CodeService`, etc.) used for module constructor typing.
- **`modules/`** — Feature modules. Each is a class implementing its service interface. Dependencies are constructor-injected. Private state uses ES6 `#` fields. Modules: charts, code, content, core, encryption, events, menu, misc, search, theme, toc. `pagefind.ts` is a standalone factory consumed by `SearchModule`.
- **`utils/`** — Pure utility functions (no side effects, no DOM state). Re-exported from `utils/index.ts`.
- **`lib/`** — Third-party library wrappers (aplayer, echarts, file-tree, fixit-decryptor, lightgallery, mapbox, mathjax, mermaid, etc.). All import the shared `eventBus` singleton.
- **`head/`** — `color-scheme.ts` runs synchronously in `<head>` before body render to prevent flash of wrong theme.
- **`pages/`** — Page-specific scripts (e.g. `link.ts` for the link guard redirection page).
Cross-module communication uses the shared `eventBus` singleton, not direct module imports. The `window.fixit` facade exposes a typed public API for user custom scripts (`custom.ts`): theme control, scroll state, mask overlay management, content re-initialization, and the event bus.
### Hugo Templates (`layouts/`)
- **`_partials/`** — Reusable template components (organized into `init/`, `base/`, `function/`, `plugin/`, `single/`, `store/`)
- **`_shortcodes/`** — 31 custom shortcodes (admonition, aplayer, echarts, file-tree, mermaid, tabs, timeline, etc.)
- **`_markup/`** — 15 render hooks (code blocks, headings, images, links, tables, blockquote alerts, passthrough for math)
### Asset Pipeline
Hugo Pipes processes all assets. The key orchestration is in `_partials/base/assets.html`:
- **CSS**: `scss/config.template.scss` generates runtime CSS custom properties from Hugo config. `scss/main.scss` is the entry point importing `core/`, `pages/`, `widgets/`, `custom`.
- **JS**: `_partials/function/js-build.html` wraps `js.Build` with minify-in-production defaults. Hugo's `@params` injection passes config values into TypeScript at build time.
- **Third-party libraries**: Stored in `assets/lib/` (vendored, not npm-managed). Tracked by `librarybot.yml` and updated weekly by the `hugo-fixit/librarybot` GitHub Action. Can be overridden via CDN config in `assets/data/cdn/jsdelivr.yml` or `unpkg.yml`.
### Theme Configuration
- **`hugo.toml`** — Default theme configuration (1700+ lines). Uses `_merge = "shallow"` to let user configs override without deep merging.
- **`theme.toml`** — Theme metadata
## Coding Standards
### SCSS (`assets/scss/`)
- CSS classes: BEM or semantic naming (`header-desktop`, `menu-item`)
- SCSS variables: hyphen-separated, semantic (`$global-font-family`)
- CSS custom properties: prefixed with `fi-` / `--fi-`
- Use CSS variables for theme switching; SCSS variables for colors (no hardcoded values)
- Prefer relative units (rem, em, %) over absolute units
- Keep selector nesting shallow
### TypeScript
- Use ES6 `#` private fields — not TypeScript `private` with `_` prefix
- One module per file, one service interface per module
- Constructor injection for dependencies — no global state access
- Import the shared `eventBus` singleton from `core/event-bus` — do not create new instances
- Pure functions only in `utils/` — no side effects, no DOM state
### Hugo Templates
- Variable naming: camelCase (`$footerConfig`, `$fingerprint`)
- Translation: use `T` function (`{{ T "header.switchTheme" }}`)
- Whitespace: use `{{- -}}` trim markers
- Use `partialCached` for expensive partials that don't change per page
- Use `.Site.Store` for shared computed values (e.g. fingerprint)
- Check `hugo.IsProduction` before adding analytics or minification
## Commit Convention
Follows [Conventional Commits](https://www.conventionalcommits.org/):
```
<type>(<scope>): <subject>
```
Types: `feat`, `fix`, `refactor`, `chore`, `docs`, `perf`, `style`, `test`, `ci`, `build`
Scopes: `workflow`, `archetypes`, `assets`, `i18n`, `layouts`, `config`, or specific directories.
## Pre-commit Hooks
Pre-commit runs: versioning (dev mode), typecheck, lint-staged (eslint --fix on staged files).
## ESLint
Uses `@antfu/eslint-config` with TypeScript support. Config at `eslint.config.js`.
Reference in New Issue View Git Blame Copy Permalink