Skip to content

AGENTS.md

Latest commit

 

History

History
199 lines (156 loc) · 6.67 KB

AGENTS.md

File metadata and controls

199 lines (156 loc) · 6.67 KB

AGENTS Guide

Project Snapshot

  • Docusaurus 3 docs site for https://karing.app
  • Runtime: Node.js >=18.0
  • Package manager: npm with package-lock.json
  • Languages: JavaScript, Markdown, MDX-compatible docs, CSS
  • Locales: zh-Hans default, en secondary
  • Main config: package.json, docusaurus.config.js, sidebars.js

Directory Map

  • docs/: primary Chinese docs
  • i18n/en/docusaurus-plugin-content-docs/current/: English localized docs
  • src/pages/: route-backed Docusaurus pages
  • src/components/: reusable React components
  • src/css/: global theme overrides
  • static/: static assets

Agent Priorities

  • Preserve current Docusaurus structure and routing.
  • Prefer minimal, targeted edits over broad rewrites.
  • Keep Chinese and English docs structurally aligned when needed.
  • Do not introduce new tooling unless explicitly requested.
  • Verify behavior using committed scripts only.

Core Commands

Install

npm install

Dev server

npm run start
  • Use for live preview while editing docs, pages, or CSS.

Local verification

npx docusaurus start
  • Preferred verification command for this repo; start local environment and check for obvious errors.

Serve built site

npm run serve
  • Use after npm run build to inspect production output locally.

Clear cache

npm run clear
  • Use if dev server or build behaves inconsistently.

Translation scaffold

npm run write-translations
  • Generates locale scaffolding; run only when intentionally updating translations.

Heading IDs

npm run write-heading-ids

Docusaurus CLI passthrough

npm run docusaurus -- <command>

Deploy

npm run deploy
  • Present in scripts, but do not run unless explicitly requested.

Lint and Test Status

  • No dedicated lint script in package.json.
  • No dedicated test script in package.json.
  • No Jest or Vitest config is checked into the repo root.
  • Practical validation is starting the local Docusaurus environment.

Single Test Guidance

  • No single-test command exists because there is no automated test runner.
  • For page- or component-level work:
    1. Run npx docusaurus start.
    2. Open the affected route and verify it manually.
  • For docs-only changes, verify links, images, and sidebar placement.
  • For React or CSS changes, verify desktop and mobile widths.

Code Style: General

  • Follow the existing file style before generic rules.
  • Prefer ESM syntax: import / export default.
  • Use semicolons in JavaScript.
  • Prefer single quotes unless interpolation or surrounding code suggests otherwise.
  • Keep formatting simple and readable.
  • Match surrounding indentation.
  • src/pages/*.js and src/components/*.js commonly use 2 spaces.
  • docusaurus.config.js uses 4 spaces in many blocks.
  • Preserve existing line wrapping unless local cleanup clearly helps.

Imports

  • Keep imports at the top of the file.
  • Preferred grouping order:
    1. React and third-party packages
    2. Docusaurus/theme imports
    3. Local components and assets
    4. Local CSS modules
  • Avoid unused imports.
  • Reuse existing alias patterns such as @site/... when already present.

React and JavaScript Conventions

  • Use function components, matching the repo.
  • Export a single default component from page files unless there is a strong reason not to.
  • Keep components small and page-focused.
  • Prefer straightforward hooks usage over abstraction.
  • Do not introduce TypeScript unless explicitly requested.
  • Use descriptive names such as HomepageHeader or CountdownRedirect.
  • Use PascalCase for components.
  • Use camelCase for variables, functions, props, and handlers.
  • Use UPPER_SNAKE_CASE only for real constants.

Error Handling and Browser Safety

  • Most custom code runs in the browser.
  • Guard browser-only APIs if code may run during build or SSR.
  • Access window inside useEffect or behind runtime guards when needed.
  • Fail simply and visibly rather than adding heavy error infrastructure.
  • Do not swallow errors silently if a fallback or message would help.

Docusaurus-Specific Guidance

  • Keep docs.routeBasePath behavior intact; docs are served from /, not /docs.
  • Respect sidebars.js, which uses autogenerated structure.
  • New docs should be placed intentionally so ordering follows directory structure and frontmatter.
  • Use frontmatter only when needed; existing docs often use sidebar_position.
  • Preserve configured locales in docusaurus.config.js.
  • Do not change analytics, scripts, URL, or deployment metadata unless asked.

Markdown and Docs Authoring

  • Match the tone of nearby docs.
  • Keep user-facing docs concise, practical, and task-oriented.
  • Use relative links that fit current routing conventions.
  • Verify image paths carefully; many docs use sibling img/ folders.
  • Preserve frontmatter blocks.
  • Prefer short sections and bullet lists over dense prose.
  • Keep headings stable because anchors may be shared externally.
  • When a change affects structure or critical meaning, update the matching English doc too.

CSS Guidance

  • Prefer CSS modules for page- or component-specific styling.
  • Use src/css/custom.css for global theme overrides or shared classes.
  • Reuse Docusaurus or Infima utility classes where practical.
  • Avoid large visual redesigns unless requested.
  • Keep responsive behavior intact.

Content and Localization

  • docs/ is the primary source of truth.
  • English translations live under i18n/en/docusaurus-plugin-content-docs/current/.
  • If a doc is added, moved, or renamed in docs/, consider the English mirror too.
  • If you cannot fully translate content, preserve structure and minimize partial edits.

What Not to Do

  • Do not add a lint or test framework unless explicitly requested.
  • Do not reorganize the docs tree without considering autogenerated sidebar impact.
  • Do not mass-reformat unrelated files.
  • Do not edit generated output unless specifically asked.
  • Do not run deployment commands without explicit instruction.

Repository Rule Files

  • No .cursorrules file was found.
  • No .cursor/rules/ directory was found.
  • No .github/copilot-instructions.md file was found.
  • There are no additional Cursor or Copilot instructions to merge.

Recommended Workflow

  1. Read package.json, docusaurus.config.js, and the nearest related file before editing.
  2. Make the smallest change that satisfies the request.
  3. For docs changes, inspect sibling docs for tone and structure.
  4. Run npx docusaurus start after meaningful changes and check for obvious errors.
  5. If the change is page-specific, verify the affected route manually.
  6. Report clearly if validation is partial because the repo has no dedicated tests.