CSS Dojo Development Guide
You are working with CSS Dojo, an interactive CSS learning platform built with Docusaurus 3.8.1, React 19, and TypeScript. This platform provides educational content with hands-on CSS experimentation through interactive playgrounds.
Project Overview
CSS Dojo is a Japanese-language documentation site focused on teaching CSS concepts through interactive demos and playgrounds. The site uses Docusaurus v4 future flag for improved compatibility and is deployed to GitHub Pages at `ashphy.com/css-dojo/`.
Development Commands
When working on this project, use these commands:
**Install dependencies**: `npm install`**Start development server**: `npm start` (includes hot reload)**Build for production**: `npm run build`**Serve production build**: `npm run serve`**Type checking**: `npm run typecheck`**Clear Docusaurus cache**: `npm run clear` (use when encountering cache-related issues)Architecture and File Structure
Configuration Files
`docusaurus.config.ts` - Main site configuration (metadata, navbar, footer, theme settings, Japanese locale)`sidebars.ts` - Sidebar navigation (auto-generated from docs folder structure)Content Locations
`docs/` - Main learning content in MDX format (auto-generates sidebar navigation)`blog/` - Blog posts with RSS/Atom feeds`src/pages/` - Custom React pages and static markdown`static/img/` - Static image assetsStyling
`src/css/custom.css` - Global CSS overrides using Infima CSS framework variablesCSS custom properties for light/dark theme supportCSS modules for component-specific stylingCustom Components
`src/components/` - Reusable React components (e.g., HomepageFeatures)`docs/[Topic]/components/` - Topic-specific interactive components (co-located with documentation)Interactive Learning Components
The platform features several types of interactive components:
Playground Component
Location: `docs/Flexbox/components/playground.tsx`Interactive HTML/CSS editor using Monaco EditorLive preview system using iframe-based safe code executionAllows students to experiment with CSS in real-timeDemo Components
Various interactive demos for specific CSS concepts (alignment, wrapping, sizing, etc.)Located alongside related documentation for easy maintenanceFollow Docusaurus patterns with `@theme/` importsKey Technologies
**Docusaurus 3.8.1** - Static site generator with React-based architecture**React 19** - Latest React version for UI components**TypeScript 5.6** - Strong typing throughout codebase**MDX** - Markdown with embedded React components for interactive content**Infima** - CSS framework optimized for content-centric websites**@monaco-editor/react** - Code editor for interactive playground**@uiw/react-codemirror** - Alternative code editor with CSS/HTML language supportContent Development Guidelines
Writing Documentation
1. Create MDX files in the `docs/` folder following the existing structure
2. Use frontmatter for metadata (title, description, sidebar position)
3. Write content in Japanese (site locale is `ja`)
4. Embed interactive components where they enhance learning
Creating Interactive Components
1. Place components in `docs/[Topic]/components/` for topic-specific demos
2. Use TypeScript for type safety
3. Follow iframe-based preview pattern for safe code execution
4. Import using relative paths from MDX files
Adding New Topics
1. Create a new folder under `docs/` for the topic
2. Add `_category_.json` for folder metadata
3. Create MDX files for lessons
4. Build interactive components in a `components/` subfolder
5. Sidebar navigation will auto-generate from folder structure
Development Best Practices
**Hot Reload**: Development server includes hot reload for rapid iteration**No Testing Framework**: This is a documentation-focused project without automated tests**Component Co-location**: Keep interactive components near related documentation**Type Safety**: Leverage TypeScript throughout the codebase**Cache Issues**: Run `npm run clear` if you encounter build or navigation issues**GitHub Pages Deployment**: Site configured for deployment to `ashphy.com/css-dojo/`Common Tasks
Adding a New Lesson
1. Create a new MDX file in the appropriate `docs/` subfolder
2. Add frontmatter with title and sidebar position
3. Write content in Japanese with clear explanations
4. Create interactive demos if beneficial for understanding
5. Test in development server before committing
Modifying Site Configuration
1. Edit `docusaurus.config.ts` for site-wide changes (navbar, footer, theme)
2. Edit `sidebars.ts` if you need custom sidebar behavior
3. Edit `src/css/custom.css` for global styling changes
4. Run `npm run typecheck` to verify configuration changes
Creating Interactive Playground
1. Reference existing playground in `docs/Flexbox/components/playground.tsx`
2. Use Monaco Editor for code editing experience
3. Implement iframe-based preview for security
4. Support HTML and CSS editing with live updates
5. Follow React 19 patterns and TypeScript best practices
Notes
Site is Japanese-language focused (`ja` locale configured)Auto-generated sidebars from `docs/` folder structureComponent architecture follows Docusaurus conventionsInteractive learning approach with hands-on experimentationNo testing framework configured (documentation-focused project)