# CaDaR Documentation

This directory contains the modern, interactive documentation for CaDaR built with Docusaurus.

## 🚀 Features

- **Modern UI**: Clean, responsive design with dark/light mode
- **Interactive Playground**: Try CaDaR in your browser
- **Visual Pipeline Explorer**: Understand the 6-stage transliteration process
- **Code Examples**: Live code snippets with syntax highlighting
- **Mobile Friendly**: Works perfectly on all devices
- **Fast Search**: Find what you need instantly

## 📖 Documentation Structure

```
docs/
├── intro.md                    # Introduction and overview
├── getting-started/            # Installation and quick start
│   ├── installation.md
│   └── quickstart.md
├── user-guide/                # User documentation
│   ├── overview.md
│   ├── python-api.md
│   ├── examples.md
│   └── character-mappings.md
├── architecture/              # Technical architecture
│   ├── pipeline.md
│   ├── icr.md
│   └── linguistic-modules.md
├── development/               # Developer docs
│   ├── contributing.md
│   ├── building.md
│   └── testing.md
├── api/                      # API reference
│   └── python.md
└── changelog.md             # Version history
```

## 🛠️ Local Development

### Prerequisites

- Node.js 18+ 
- npm or yarn

### Setup

```bash
# Navigate to docs directory
cd cadar-docs

# Install dependencies
npm install

# Start development server
npm start
```

### Building

```bash
# Build for production
npm run build

# Serve built files locally
npm run serve
```

### Deployment

The documentation is configured to deploy to GitHub Pages automatically. To deploy manually:

```bash
# Deploy to GitHub Pages
npm run deploy
```

Or use the convenience script from the project root:

```bash
# Build only
./build-docs.sh

# Build and serve locally
./build-docs.sh --serve

# Build and deploy
./build-docs.sh --deploy
```

## 🎨 Customization

### Theme Customization

- Edit `src/css/custom.css` for custom styles
- Modify `docusaurus.config.ts` for theme configuration
- Add custom components in `src/components/`

### Adding New Pages

1. Create markdown file in appropriate `docs/` subdirectory
2. Add to `sidebars.ts` navigation
3. Rebuild to see changes

### Components

Key custom components:

- **Playground** (`src/pages/playground.tsx`): Interactive transliteration demo
- **PipelineVisualization** (`src/components/PipelineVisualization.tsx`): Visual pipeline explorer

## 📝 Writing Documentation

### Front Matter

All markdown files should have front matter:

```yaml
---
sidebar_position: 1
title: Your Page Title
---

# Your content here
```

### Code Examples

Use syntax highlighting for code:

```python
import cadar

result = cadar.ara2bizi("سلام", darija="Ma")
print(result)
```

### React Components

Import and use React components in MDX:

```jsx
import PipelineVisualization from '@site/src/components/PipelineVisualization';

<PipelineVisualization />
```

## 🌐 Deployment

The documentation is configured to deploy to:
- GitHub Pages: `https://oit-technologies.github.io/CaDaR/`

### GitHub Actions

Automated deployment is set up via GitHub Actions in `.github/workflows/docs.yml`:

- Triggered on push to main branch
- Builds and deploys to GitHub Pages
- Uses Node.js cache for faster builds

## 📊 Analytics

To add analytics:

1. Update `docusaurus.config.ts` with your analytics provider
2. Rebuild documentation

## 🔧 Troubleshooting

### Common Issues

1. **Build fails with TypeScript errors**
   - Run `npm run typecheck` to see detailed errors
   - Fix type errors in `.tsx` files

2. **Styles not loading**
   - Check `src/css/custom.css` imports
   - Restart development server

3. **Components not rendering**
   - Verify imports in MDX files
   - Check browser console for errors

### Getting Help

- Check [Docusaurus documentation](https://docusaurus.io/docs)
- Open an issue on [CaDaR repository](https://github.com/Oit-Technologies/CaDaR/issues)

## 🤝 Contributing

To contribute to the documentation:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test locally
5. Submit a pull request

### Documentation Standards

- Use clear, concise language
- Include code examples
- Test all examples
- Follow style guidelines
- Add to changelog for significant changes

## 📋 TODO

- [ ] Add version switcher for multiple CaDaR versions
- [ ] Implement live Python REPL in playground
- [ ] Add more interactive examples
- [ ] Include performance benchmarks
- [ ] Add video tutorials
- [ ] Implement search analytics