Skip to content

AGENTS.md

Latest commit

 

History

History
164 lines (121 loc) · 5.81 KB

AGENTS.md

File metadata and controls

164 lines (121 loc) · 5.81 KB
Raw

AGENTS.md - Agent Coding Guidelines

This file contains guidelines for agentic coding assistants working in this Docusaurus documentation repository.

Build and Development Commands

# Start development server (default: http://localhost:3000)
npm start

# Build for production
npm build

# Serve built site locally
npm serve

# Clear build cache
npm clear

# Write translations
npm write-translations

# Write heading IDs
npm write-heading-ids

# Swizzle default Docusaurus components for customization
npm run swizzle

Note: This project has no configured linting, testing, or type checking scripts. Code quality is maintained through manual review.

Project Structure

  • docs/ - Documentation content (MDX files organized by category)
  • src/ - Custom React components and pages
  • src/components/ - Reusable UI components (Button, Card, Icons)
  • src/css/custom.css - Global styles and TailwindCSS import
  • src/pages/ - Custom pages (homepage, markdown pages)
  • static/ - Static assets (images, PDFs, JS files)
  • docusaurus.config.js - Site configuration
  • sidebars.js - Navigation sidebar configuration

Code Style Guidelines

Imports

  • Use ES6 import syntax
  • Import React in all component files: import React from 'react';
  • Import Docusaurus components from @docusaurus/* (e.g., @docusaurus/Link, @docusaurus/useDocusaurusContext)
  • Import custom components from @site/src/components/* pattern in MDX
  • Import static assets using require('@site/static/img/...').default pattern
  • Group imports in order: React → Docusaurus → Third-party → Local

Components

  • Use functional components with React Hooks
  • Export named components: export { Button, CardContent };
  • Export default for main components: export default function HomepageFeatures()
  • Use clsx for conditional className composition
  • Use TailwindCSS for styling (imported via @import "tailwindcss" in custom.css)

Type Safety

  • Use // @ts-check comment at file top for TypeScript checking in JS files
  • Use JSDoc type annotations for better IDE support
  • Example: /** @type {import('@docusaurus/types').Config} */

MDX Frontmatter

Every MDX file must have frontmatter:

---
sidebar_position: 1.0
sidebar_label: "Display Name"
---

CSS Modules

  • Use .module.css suffix for component-scoped styles
  • Import and apply via: import styles from './styles.module.css';
  • Use camelCase class names in JS files matching kebab-case in CSS

Naming Conventions

  • Files: PascalCase for components (e.g., Button.js, HomepageFeatures/)
  • Components: PascalCase (e.g., const Button, function Feature)
  • Variables/Functions: camelCase (e.g., const featureList, export default function Home())
  • CSS Classes: kebab-case in CSS, camelCase in JS (CSS Modules)
  • Constants: PascalCase or UPPER_CASE (e.g., const FeatureList)

Formatting

  • Use 2-space indentation
  • No trailing whitespace
  • Use single quotes for strings (except in JSX attributes)
  • Use trailing commas in multi-line arrays/objects
  • Max line length: ~100 characters (soft limit)

Error Handling

  • Docusaurus handles most routing errors via onBrokenLinks: 'throw' and onBrokenMarkdownLinks: 'warn'
  • For image imports, use .default when required: require('./img.png').default
  • Validate frontmatter structure matches sidebar expectations

Content Guidelines

  • Write documentation in Simplified Chinese (zh-Hans)
  • Use numbered steps with emoji: #### 1️⃣ Step title
  • Use Docusaurus admonitions: :::tip, :::warning, :::info, :::note, :::danger
  • Use inline links with emojis: **Link text🔗** or **Link text** in Markdown
  • Image format: 
    <div style={{ display: "flex", justifyContent: "left", alignItems: "center", marginBottom: "40px"}}>
<img src={require('./img/filename.png').default} alt="description" width="700px" style={{boxShadow: "0px 0px 5PX 2PX rgba(0, 0, 0, 0.1), inset 0 0 50px rgba(0, 0, 0, 0.3)"}}/>
</div>
  • Use descriptive alt text for accessibility
  • Shadow style: boxShadow: "0px 0px 5PX 2PX rgba(0, 0, 0, 0.1), inset 0 0 50px rgba(0, 0, 0, 0.3)"

File Paths

  • Project paths: No Chinese characters allowed in file/project paths (build errors)
  • Image paths: Relative to MDX file using require('./img/...').default
  • Documentation links: Use /docs/stm32/... pattern for internal links
  • External links: Include target="_blank" for external URLs

Configuration

  • docusaurus.config.js: Main site config with theme, navbar, plugins
  • sidebars.js: Navigation structure - uses autogenerated type from stm32 directory
  • postcss.config.mjs: TailwindCSS PostCSS plugin configuration
  • babel.config.js: Uses Docusaurus default preset

Development Notes

  • Node.js version: >=18.0 (see package.json engines field)
  • Package manager: pnpm (lockfile: pnpm-lock.yaml, package-lock.json present)
  • i18n: Default locale is zh-Hans (Simplified Chinese only)
  • Custom PostCSS plugin for TailwindCSS integration
  • Static files in static/ served at root URL

Component Patterns

Button component: Takes { icon, href, children } props, uses Tailwind classes Card components: Card and CardContent for content grouping Icons: Emojis or image imports, exported as named functions

When Adding Features

  1. Add new components to src/components/
  2. Import and use in MDX via @site/src/components/ComponentName
  3. Update sidebars.js if adding new docs (uses auto-generation by default)
  4. Test locally with npm start before committing
  5. Verify Chinese text displays correctly
  6. Check internal and external links work

Testing

  • No automated test suite configured
  • Manual testing required: run npm start and verify in browser
  • Check responsiveness on different screen sizes
  • Verify all images load correctly
  • Test all navigation links