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

Further Reading

• Link 1
• Link 2

### 4. Input Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `site_title` | No | `Physical AI Book` | Site title in navbar |
| `github_org` | No | `faiqahm` | GitHub organization |
| `repo_name` | No | `hackathon_I_book` | Repository name |
| `locales` | No | `en,ur` | Supported locales |
| `num_chapters` | No | `3` | Chapters to scaffold |

## Usage Instructions

### Step 1: Run Setup

```bash
.claude/skills/docusaurus-scaffold/scripts/setup.sh --install

Step 2: Add Content

Edit the generated chapter files in docs/:

• docs/intro.md - Welcome page
• docs/chapter-1/index.md - Chapter 1
• docs/chapter-2/index.md - Chapter 2
• etc.

Step 3: Add Translations

For Urdu translations, edit files in i18n/ur/docusaurus-plugin-content-docs/current/:

• Copy English content
• Translate to Urdu
• RTL styling is automatic

Step 4: Test Locally

# English
npm start

# Urdu
npm start -- --locale ur

Step 5: Build & Deploy

# Build all locales
npm run build

# Deploy to GitHub Pages
npm run deploy

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

Related

• 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