Skip to main content

Project Structure

docusaurus-template/
├── 📁 .github/              # GitHub Actions workflows and templates
├── 📁 .husky/               # Git hooks for code quality
├── 📁 .vscode/              # VS Code settings and extensions
├── 📁 config/               # YAML configuration files
├── 📁 data/                 # Auto-generated JSON data (from config/)
├── 📁 docs/                 # Documentation content
├── 📁 scripts/              # Build and automation scripts
├── 📁 src/                  # React/TypeScript source code
├── 📁 static/               # Static assets (images, themes)
├── 📄 docusaurus.config.ts  # Main Docusaurus configuration
└── 📄 package.json          # Project dependencies and scripts

Key Directories​

Configuration (config/)​

  • Purpose: YAML configuration files for all components
  • Files: globalConfig.yml, navBarLinks.yml, projects.yml, portfolioData.yml, cvData.yml, badges.yml, giscus.yml, etc.
  • Auto-converted to JSON in data/ directory during build

Data (data/)​

  • Purpose: Auto-generated JSON files from YAML configs
  • Generated by: Pre-build scripts
  • Used by: React components for dynamic content

Scripts (scripts/)​

  • Purpose: Build automation and utilities
  • Key files: pre-build.ts, validate-github-config.ts
  • TypeScript: Uses separate tsconfig.json

Source (src/)​

  • Purpose: React components and TypeScript code
  • Structure: Components, hooks, pages, themes, types
  • Framework: React with TypeScript

Build Process​

  1. Pre-build (scripts/pre-build.ts)
    • Converts YAML configs to JSON
    • Generates theme configurations
    • Creates navigation structures
  2. Docusaurus Build
    • Processes React components
    • Builds static site
    • Outputs to artifacts/

Development Scripts​

Quick Start​

# Standard development server
pnpm start

# Development with config watching
pnpm run dev

# Using PowerShell helper
.\dev.ps1 -Mode watch

Available Scripts​

  • pnpm start - Standard development server (with prebuild)
  • pnpm run dev - Development with config file watching
  • pnpm run build:prod - Production build to ./artifacts
  • pnpm run quality - Run all quality checks (format, lint, typecheck, validate)
  • pnpm run prebuild - Manual pre-build process
  • pnpm run test - Run Vitest tests
  • pnpm run validate:github - Validate GitHub configuration

File Organization Principles​

  1. Configuration is YAML-first - All configs in config/ directory
  2. Auto-generation - JSON files are generated, not manually edited
  3. TypeScript everywhere - Strict typing for all code
  4. Modular components - Reusable React components
  5. Quality gates - Linting, formatting, and type checking

Maintenance​

Adding New Components​

  1. Create YAML config in config/
  2. Add TypeScript types in src/types/
  3. Create React component in src/components/
  4. Update schema validation if needed

Configuration Changes​

  1. Edit YAML files in config/
  2. Run pnpm run prebuild to regenerate JSON
  3. Test changes with pnpm run dev

Quality Assurance​

  • Run pnpm run quality before commits (includes format:check, lint, typecheck, prebuild:check, validate:github)
  • Use pnpm run quality:fix to auto-fix formatting and linting issues
  • Husky hooks enforce quality on commit

Cleanup Guidelines​

This project follows these organization principles:

  • ✅ No duplicate configuration systems
  • ✅ Clear separation of concerns
  • ✅ Automated code generation
  • ✅ Comprehensive ignore files
  • ✅ Organized package.json scripts