# STA Connector Documentation

This directory contains the VitePress documentation for STA Connector.

## Development

```bash
# Install dependencies
npm install

# Start development server
npm run dev
```

The documentation will be available at `http://localhost:5173`.

## Building for Production

```bash
# Build static site
npm run build

# Preview the build
npm run preview
```

The output will be in `.vitepress/dist/`.

## Deployment

### GitHub Pages (Recommended)

The documentation is automatically deployed to GitHub Pages when pushing to the `main` branch. See `.github/workflows/deploy-docs.yml` for the workflow configuration.

Manual deployment:
```bash
npm run deploy:gh-pages
```

### Netlify

1. Connect your GitHub repository to Netlify
2. Set build command: `npm run build`
3. Set publish directory: `docs/.vitepress/dist`
4. Set base URL environment variable: `DOCS_BASE_URL=/`

Or deploy manually:
```bash
export NETLIFY_AUTH_TOKEN=your_token
export NETLIFY_SITE_ID=your_site_id
npm run deploy
```

### Vercel

1. Import your GitHub repository to Vercel
2. Set framework preset: Other
3. Set build command: `cd docs && npm run build`
4. Set output directory: `docs/.vitepress/dist`
5. Set base URL environment variable: `DOCS_BASE_URL=/`

### Self-Hosted (Nginx)

Build the docs and serve with Nginx:

```bash
# Build
npm run build

# Copy to server
scp -r .vitepress/dist/* user@server:/var/www/sta-connector-docs/

# Nginx configuration
server {
    listen 80;
    server_name docs.example.com;
    root /var/www/sta-connector-docs;

    location / {
        try_files $uri $uri/ /index.html;
    }
}
```

## Structure

```
docs/
├── .vitepress/
│   ├── config.ts          # VitePress configuration
│   └── dist/              # Build output (generated)
├── en/                    # English documentation
│   ├── guide/             # User guides
│   ├── api/               # API reference
│   ├── architecture/      # Architecture docs
│   └── deployment/        # Deployment guides
├── pt/                    # Portuguese documentation
│   └── ...                # Same structure as en/
├── public/                # Static assets
│   └── logo.svg           # Logo
├── scripts/               # Deploy helper scripts
├── index.md               # Homepage (language selection)
├── package.json           # Dependencies and scripts
└── README.md              # This file
```

## Adding Content

### New Page

1. Create a markdown file in the appropriate directory:
   ```bash
   touch docs/en/guide/new-page.md
   ```

2. Add frontmatter:
   ```yaml
   ---
   title: New Page Title
   description: Page description
   ---
   ```

3. Add to sidebar in `.vitepress/config.ts`:
   ```typescript
   sidebar: {
     '/en/guide/': [
       {
         text: 'Introduction',
         items: [
           { text: 'New Page', link: '/en/guide/new-page' }
         ]
       }
     ]
   }
   ```

### Adding Translations

For Portuguese translations:

1. Copy the English file:
   ```bash
   cp docs/en/guide/installation.md docs/pt/guide/installation.md
   ```

2. Translate the content

3. Update links to use `/pt/` prefix

## Configuration

### Base URL

Set the `DOCS_BASE_URL` environment variable for deployment:

- GitHub Pages: `/sta-connector/`
- Custom domain: `/`

### Sitemap

The sitemap is automatically generated during build. Update the hostname in `.vitepress/config.ts`:

```typescript
sitemap: {
  hostname: 'https://your-docs-domain.com'
}
```

### Search

Local search is enabled by default. For Algolia DocSearch:

1. Apply at https://docsearch.algolia.com/
2. Update config:
   ```typescript
   search: {
     provider: 'algolia',
     options: {
       appId: 'YOUR_APP_ID',
       apiKey: 'YOUR_API_KEY',
       indexName: 'sta-connector'
     }
   }
   ```

## Scripts

| Script | Description |
|--------|-------------|
| `npm run dev` | Start development server |
| `npm run build` | Build for production |
| `npm run preview` | Preview production build |
| `npm run deploy` | Deploy using deploy script |
| `npm run deploy:gh-pages` | Deploy to GitHub Pages |

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `DOCS_BASE_URL` | Base URL for deployment | `/sta-connector/` |
| `NETLIFY_AUTH_TOKEN` | Netlify deploy token | - |
| `NETLIFY_SITE_ID` | Netlify site ID | - |
| `VERCEL_TOKEN` | Vercel deploy token | - |

## License

MIT License - See LICENSE file in the project root.