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

--title TITLE

Physical AI Book

--github-org ORG

faiqahm

--repo NAME

hackathon_I_book

--locales LOCALES

en,ur

--chapters N

3

--install

--start

-h, --help

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 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

direction: 'rtl'

_category_.json

node_modules

npm install

Requirements

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

Physical AI Textbook Chapters

The default scaffold creates these chapters:

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