name	docusaurus-scaffold
description	Scaffold and initialize a Docusaurus project with the specific structure for the Physical AI textbook. Agent: BookArchitect
version	1.2.0
inputs	[object Object]

Docusaurus Scaffold

Agent: BookArchitect

Scaffold and initialize a Docusaurus project with the specific structure for the Physical AI textbook. Creates a complete documentation site with chapters, i18n support, and GitHub Pages deployment configuration.

Quick Setup

# Full setup with defaults
.claude/skills/docusaurus-scaffold/scripts/setup.sh

# Custom configuration
.claude/skills/docusaurus-scaffold/scripts/setup.sh \
  --title "Physical AI Book" \
  --github-org faiqahm \
  --repo hackathon_I_book \
  --locales "en,ur" \
  --chapters 5

# Initialize and install dependencies
.claude/skills/docusaurus-scaffold/scripts/setup.sh --install

# Initialize, install, and start dev server
.claude/skills/docusaurus-scaffold/scripts/setup.sh --install --start

Command Options

Option	Description	Default
`--title TITLE`	Site title	`Physical AI Book`
`--github-org ORG`	GitHub org/username	`faiqahm`
`--repo NAME`	Repository name	`hackathon_I_book`
`--locales LOCALES`	Comma-separated locales	`en,ur`
`--chapters N`	Number of chapters	`3`
`--install`	Run npm install after setup	off
`--start`	Start dev server (requires --install)	off
`-h, --help`	Show help message	-

What It Creates

1. Project Structure

project/
├── docs/
│   ├── intro.md                 # Introduction/Welcome page
│   ├── chapter-1/
│   │   ├── _category_.json      # Chapter metadata
│   │   ├── index.md             # Chapter overview
│   │   ├── lesson-1.md          # Lesson content
│   │   └── lesson-2.md
│   ├── chapter-2/
│   │   └── ...
│   └── chapter-3/
│       └── ...
├── i18n/
│   └── ur/
│       ├── docusaurus-theme-classic/
│       │   ├── navbar.json
│       │   └── footer.json
│       └── docusaurus-plugin-content-docs/
│           └── current/
│               ├── intro.md
│               └── chapter-1/
│                   └── ...
├── src/
│   ├── css/
│   │   └── custom.css           # RTL support for Urdu
│   └── pages/
│       └── index.js             # Homepage redirect
├── static/
│   └── img/
│       └── favicon.svg
├── docusaurus.config.js         # Main configuration
├── sidebars.js                  # Sidebar configuration
└── package.json

2. Configuration Files

docusaurus.config.js

GitHub Pages deployment settings
i18n with RTL support for Urdu
Navbar with locale dropdown
Dark/light theme support

sidebars.js

Auto-generated sidebar from docs folder
Chapter organization with collapsible sections

3. Textbook Structure

Each chapter follows this structure:

# Chapter N: Title

## Learning Objectives
- Objective 1
- Objective 2

## Prerequisites
- Prerequisite 1

## Content
(Main lesson content)

## Exercises
1. Exercise 1
2. Exercise 2

## Summary
Key takeaways from this chapter.

## Next Steps
Link to next chapter or related content.

4. i18n Support

English (en): Default locale, LTR
Urdu (ur): RTL support with custom CSS
Translation files for navbar/footer
Translated chapter content structure

Bundled Resources

1. Docusaurus Configuration

File: docusaurus.config.js

const config = {
  title: 'Physical AI Book',
  tagline: 'Learn Physical AI, ROS 2, and Robotics',
  favicon: 'img/favicon.svg',

  // GitHub Pages deployment
  url: 'https://faiqahm.github.io',
  baseUrl: '/hackathon_I_book/',
  organizationName: 'faiqahm',
  projectName: 'hackathon_I_book',

  // Enable Mermaid for Diagrams
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],

  // i18n configuration
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'ur'],
    localeConfigs: {
      en: { label: 'English', direction: 'ltr' },
      ur: { label: 'اردو', direction: 'rtl', htmlLang: 'ur-PK' },
    },
  },
  // ... rest of config
};

2. RTL Styles for Urdu

File: src/css/custom.css

/* RTL Support for Urdu */
html[dir='rtl'] {
  direction: rtl;
}

html[dir='rtl'] .navbar__items {
  flex-direction: row-reverse;
}

html[dir='rtl'] .markdown {
  text-align: right;
}

/* Urdu font family */
html[lang='ur'] {
  font-family: 'Noto Nastaliq Urdu', 'Jameel Noori Nastaleeq', serif;
}

3. Chapter Template

File: docs/chapter-N/index.md

---
sidebar_position: N
---

# Chapter N: [Title]

## Learning Objectives

By the end of this chapter, you will be able to:
- [ ] Objective 1
- [ ] Objective 2
- [ ] Objective 3

## Prerequisites

Before starting this chapter, ensure you understand:
- Prerequisite 1
- Prerequisite 2

## Introduction

[Chapter introduction content]

## Key Concepts

### Concept 1
[Explanation]

### Concept 2
[Explanation]

## Hands-On Exercise

```python
# Example code
print("Hello, Physical AI!")

Summary

In this chapter, we covered:

Point 1
Point 2
Point 3

Verification Checklist

docusaurus.config.js exists with correct settings
docs/ folder has intro and chapters
i18n/ur/ folder has translation structure
src/css/custom.css has RTL styles
npm start works without errors
npm run build completes successfully
Locale switcher appears in navbar

Automated Testing

Run the test suite to validate skill functionality:

# Run all tests
.claude/skills/docusaurus-scaffold/scripts/test.sh

Test Suite (18 assertions)

Test	Description	Validates
1	--help flag works	CLI help output
2	package.json created	Basic scaffold
3	docusaurus.config.js created	Configuration
4	sidebars.js created	Sidebar config
5	docs/intro.md created	Introduction page
6	Chapter 1 with index.md	Chapter structure
7	Chapter 2 with index.md	Chapter structure
8	Chapter 3 with index.md	Chapter structure
9	Urdu navbar.json created	i18n translations
10	Urdu intro.md created	i18n content
11	RTL styles in custom.css	RTL support
12	Homepage redirect configured	Redirect component
13	Favicon created	Static assets
14	--chapters 5 creates 5 chapters	Custom chapter count
15	GitHub Actions workflow created	CI/CD pipeline
16	Mermaid in config and package.json	Diagram support
17	Chapter template has Mermaid	Diagram examples
18	--no-workflow skips workflow	Flag functionality

Test Script Features

Isolated execution: Tests run in /tmp/docusaurus-scaffold-test-$$
Automatic cleanup: Directory removed on exit via trap
Color-coded output: PASS (green), FAIL (red), TEST (blue)
Summary report: Pass/fail counts with exit code

Example Output

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🧪 Docusaurus Scaffold Test Suite
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[TEST] Test 1: --help flag works
[PASS] --help displays usage information
...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Test Results
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Passed: 18
  Failed: 0

✓ All tests passed!

Troubleshooting

Issue	Solution
Build fails with broken links	Check internal links use relative paths
Urdu text not RTL	Verify `direction: 'rtl'` in config
Sidebar not showing	Check `_category_.json` in each chapter folder
npm start fails	Delete `node_modules`, run `npm install`
Locale not switching	Clear browser cache, check i18n config

Requirements

Node.js 18+
npm 8+
Git (for deployment)

Physical AI Textbook Chapters

The default scaffold creates these chapters:

Chapter	Title	Topics
Intro	Welcome to Physical AI	Overview, prerequisites, how to use
1	Introduction to Physical AI & ROS 2	What is Physical AI, ROS 2 basics
2	Simulation with Gazebo	Virtual environments, robot simulation
3	Vision-Language-Action Models	VLA concepts, integration

Docusaurus Documentation
GitHub Pages Deployment
Skill: github-pages-deploy - Deploy the site
Skill: urdu-rtl-styler - Enhanced RTL styling
Skill: vercel-fastapi-link - Backend API

Changelog

v1.2.0 (2026-01-02)

Test Suite & Bug Fixes

Add comprehensive test suite (scripts/test.sh) with 18 assertions
Tests run in isolated /tmp directory with automatic cleanup
Color-coded test output with pass/fail summary
Bug fixes discovered during testing:
- Fix bash counter increment syntax for set -e compatibility
  - Changed ((PASSED++)) to PASSED=$((PASSED + 1))
  - Prevents script exit when incrementing from 0
- Fix test cleanup to properly remove .github directory
  - Glob pattern * doesn't match dot-prefix directories
  - Use rm -rf "$DIR" instead of rm -rf "$DIR"/*

v1.1.0 (2026-01-01)

Enhanced Deployment & Diagrams

Add --deploy flag for automated GitHub Pages deployment
Add --build flag to run build after install
Bundle GitHub Actions workflow (.github/workflows/deploy.yml)
Add Mermaid diagram support (@docusaurus/theme-mermaid)
Add example Mermaid diagrams in chapter templates
Add --no-workflow and --no-mermaid flags to skip features

v1.0.0 (2026-01-01)

Initial Release

Docusaurus project scaffolding
Physical AI textbook chapter structure
i18n support (English + Urdu RTL)
GitHub Pages deployment configuration
Custom CSS for RTL languages
Chapter templates with learning objectives

docusaurus-scaffold

Install Skill

SKILL.md