hexo-theme-redefine

# AGENTS This file is for automated coding agents working in this repo. ## Project Snapshot - Hexo theme implementation with browser JS in `source/js/**`, Hexo Node scripts in `scripts/**`, and Stylus/Tailwind CSS in `source/css/**`. - Build outputs are committed to `source/js/build/**` and `source/css/build/tailwind.css`. - The theme config lives in `_config.yml` and is exported at build/runtime by `scripts/config-export.js`. ## Environment & Tooling - Package manager: npm (CI uses `npm install`). - Node versions seen in CI: 20.x for build, 18 for release workflows. - No TypeScript, no test runner configured. ## Commands (Build / Lint / Test) - Install deps: `npm install`. - Build all assets: `npm run build` (runs CSS + JS builds). - Build CSS only: `npm run build:css` (Tailwind CLI). - Build JS only: `npm run build:js` (minifies into `source/js/build`). - Watch CSS: `npm run watch:css`. - Pre-commit hook blocks committing build outputs on non-`main`/`dev` branches (see `.husky/pre-commit`). - Lint: no npm script or config present; add one if needed. - Tests: no test runner configured. - Single test: N/A (no unit/integration test tooling configured). - Manual verification (if you have a Hexo site): `hexo clean && hexo g` in the site repo. ## Generated Assets (Do Not Edit Directly) - `source/css/build/tailwind.css` is generated from `source/css/tailwind.source.css`. - `source/js/build/**` is generated by `source/js/build.js` (Terser minification + lib copy). - If you touch `source/js/**` or `source/css/**`, rerun `npm run build` for verification. Build outputs are committed by CI on `dev`/`main` after merge. ## JavaScript Style (Browser: `source/js/**`) - Module system: ES modules with `import`/`export`; keep imports at top. - Formatting: 2-space indentation, semicolons, double quotes. - Prefer `const`; use `let` only when reassigning. - Use trailing commas in multi-line objects/arrays/params (matches existing files). - Naming: `camelCase` for variables/functions, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants. - Init patterns: exported functions commonly named `initX`, `onX`, `handleX`. - Guards: early returns for invalid inputs or missing DOM nodes. - Optional chaining and nullish coalescing are used; keep null-safe checks. - Event listeners: prefer `{ signal }` and pass an `AbortSignal` when available. - Side effects: keep in `onReady`/`onPageView` hooks or explicit init functions. ## JavaScript Style (Hexo/Node: `scripts/**`) - Module system: CommonJS with `require(...)` and `"use strict";` at top. - Use `hexo.extend.*` APIs (helpers, filters, events) as seen in existing scripts. - Keep functions small and mostly pure; use `try/catch` around external data parsing. - Avoid direct DOM usage here; this layer runs in Node during Hexo build. ## Error Handling & Logging - Use `try/catch` for unsafe operations (JSON/YAML parsing, URL parsing, fetch). - Log with `console.warn`/`console.error` for non-fatal failures. - Prefer to return early after logging; avoid throwing unless it should break the build. ## Styling (Stylus + Tailwind) - Stylus files use `//` comments and section separators; mirror existing structure. - Variables use `$` prefix and hyphenated names (see `source/css/common/variables.styl`). - Reuse mixins like `redefine-tablet()` and `redefine-mobile()` for breakpoints. - Read config in Stylus via `hexo-config('path.to.setting')`. - Class naming: favor existing kebab-case classes and theme-specific names. - Tailwind source lives in `source/css/tailwind.source.css`; never edit the generated file. ## Configuration/Data Flow - `_config.yml` is the theme config; new options should be exported in `scripts/config-export.js`. - `scripts/config-export.js` writes `window.config`, `window.theme`, and language data into the page. - Keep JS code resilient to missing config by using optional chaining and defaults. ## Imports & Dependencies - Prefer local relative imports within `source/js/**`. - Keep import lists grouped by path depth; avoid reordering unless needed. - Avoid adding new dependencies unless required; check impact on Hexo users. ## Files & Naming Conventions - Browser JS filenames are mostly `camelCase.js` (e.g., `homeBanner.js`). - Hexo script filenames often use `kebab-case.js` (e.g., `config-export.js`). - Keep new files in the same naming style as their folder. ## Content & i18n - Language files live in `languages/**` and are loaded by `scripts/config-export.js`. - If you add new UI strings, update the language YAMLs accordingly. ## CI/Automation Notes - GitHub Actions build workflow runs `npm run build` on `main`/`dev` changes to JS/CSS. - CI commits updated build assets back to the branch when they change. ## Contribution Notes (from CONTRIBUTING.md) - PRs should target the `dev` branch. - Commit message format: `[section]: [brief info]` (example: `footer: optimize style`). - Test changes locally before opening a PR. ## Cursor/Copilot Rules - No `.cursor/rules/`, `.cursorrules`, or `.github/copilot-instructions.md` found in this repo. ## Suggested Agent Workflow - Locate relevant source in `source/js/**`, `source/css/**`, or `scripts/**`. - Make changes in source files, not generated build outputs. - Run `npm run build` to refresh compiled assets. - If you cannot run builds, state the missing verification in your report. ## Quick Pointers - Main client entry: `source/js/main.js`. - JS build script: `source/js/build.js`. - Tailwind entry: `source/css/tailwind.source.css`. - Core Stylus vars: `source/css/common/variables.styl`. - Hexo helper for config export: `scripts/config-export.js`. ## Notes for Single-Test Requests - There is no test framework configured, so single-test execution is not applicable. - If a test runner is added later, document the exact single-test command here. ## Guardrails for Agents - Keep changes minimal and consistent with existing style. - Do not edit auto-generated build files by hand. - Preserve license headers or top-of-file banners when present. - Avoid adding non-ASCII characters unless the file already uses them. ## When Updating CSS/JS - Update `source/js/**` or `source/css/**` first. - Rebuild with `npm run build` for verification. - Build outputs are committed by CI on `dev`/`main` after merge. ## When Adding New Config Options - Add defaults in `_config.yml`. - Export them in `scripts/config-export.js`. - Consume with optional chaining and defaults in JS. - Consider adding Stylus variables via `hexo-config()` if needed. ## When Modifying Hexo Filters/Helpers - Keep functions pure and avoid heavy computation in filters. - Use defensive checks for config and data fields. ## When Modifying UI Behavior - Keep init logic in `init*` functions and register via lifecycle hooks. - Use `AbortSignal` or cleanup patterns to avoid duplicate listeners. ## Security/Privacy - Do not log or expose user secrets from `_config.yml`. - Treat external URLs as untrusted; validate before use where possible. ## Docs - Developer docs: https://redefine-docs.ohevan.com/developer - User docs: https://redefine-docs.ohevan.com/ ## End - Keep this file updated when tooling or conventions change.