outline-sync/README.md

# Outline Export Tool

Export Outline wiki data with full hierarchy and tree visualization.

## Quick Start

### 1. Configure Settings

Ensure `settings.json` contains your Outline API token:
```bash
cat settings.json
```

### 2. Run Export

```bash
./export_with_trees.sh
```

## Command Line Options

```bash
# Standard export with tree visualization
./export_with_trees.sh

# Preview without exporting (dry run)
./export_with_trees.sh --dry-run

# Verbose output
./export_with_trees.sh -v

# Debug output
./export_with_trees.sh -vv

# Skip verification step
./export_with_trees.sh --skip-verify

# Custom output directory
./export_with_trees.sh -o /path/to/output
```

### All CLI Options

| Option | Short | Description |
|--------|-------|-------------|
| `--dry-run` | `-n` | Preview without writing files |
| `--output` | `-o` | Output directory (overrides settings) |
| `--verbose` | `-v` | Increase verbosity (-vv for debug) |
| `--skip-verify` | | Skip post-export verification |
| `--skip-health-check` | | Skip pre-export health check |
| `--settings` | | Path to settings file |

## What It Does

1. **Health check** - Verifies API connectivity and authentication
2. **Shows current structure** - Tree view from Outline API
3. **Backs up previous exports** - Timestamped `.tar.gz` archives
4. **Exports all documents** - With full hierarchy preserved
5. **Shows exported structure** - Tree view of files
6. **Verifies counts** - Compares API vs exported documents

## Features

- **Retry logic**: Failed API requests retry up to 3 times with exponential backoff
- **Health check**: Verifies API before starting export
- **Dry-run mode**: Preview what would be exported
- **Structured logging**: Configurable verbosity levels
- **Document caching**: Prevents duplicate API fetches
- **Checksum verification**: Ensures export integrity

## File Structure

```
outline-tools/
├── export_with_trees.sh        # Main export script
├── outline_export_fixed.py     # Python export logic
├── settings.json               # API configuration
├── CLAUDE.md                   # AI assistant docs
├── README.md                   # This file
│
└── Output (created after export):
    ├── exports/                # Exported documents
    └── exports_backup_*.tar.gz # Previous backups
```

## Configuration

### settings.json

```json
{
  "source": {
    "url": "http://outline:3000",
    "token": "ol_api_..."
  },
  "export": {
    "output_directory": "exports",
    "verify_after_export": true
  },
  "advanced": {
    "max_hierarchy_depth": 100,
    "api_timeout_seconds": 30,
    "progress_bar": true,
    "max_retries": 3,
    "retry_backoff": 1.0
  }
}
```

### Configuration Options

| Section | Key | Default | Description |
|---------|-----|---------|-------------|
| source | url | - | Outline API URL |
| source | token | - | API authentication token |
| export | output_directory | exports | Where to save files |
| export | verify_after_export | true | Run verification after export |
| advanced | max_hierarchy_depth | 100 | Prevent infinite recursion |
| advanced | progress_bar | true | Show progress bars |
| advanced | max_retries | 3 | API retry attempts |
| advanced | retry_backoff | 1.0 | Retry backoff multiplier |

## How It Works

### Docker Network Access

The script runs in a Docker container on `domnet` to access Outline internally:

```
export_with_trees.sh → Docker Container (domnet) → outline:3000
```

This bypasses Authentik SSO that would block external HTTPS requests.

### Export Process

1. **Health check** - Verify API connectivity
2. **Fetch collections** from Outline API
3. **Build hierarchy** from navigation tree (source of truth)
4. **Export recursively** maintaining parent-child structure
5. **Save metadata** per collection
6. **Verify** document counts and checksums

## Output Format

### Collection Structure
```
exports/
├── Collection_Name/
│   ├── _collection_metadata.json
│   ├── Document.md
│   └── Child_Document.md
├── export_metadata.json
└── manifest.json
```

### Document Format
```markdown
# Document Title

<!-- Document ID: abc123 -->
<!-- Created: 2025-01-13T10:00:00Z -->
<!-- Updated: 2025-01-13T14:30:00Z -->
<!-- URL: https://outline.domverse.de/doc/... -->

---

Document content here...
```

## Troubleshooting

### Health Check Fails
```bash
# Check if Outline is accessible
docker exec -it outline curl -s http://localhost:3000/api/auth.info

# Verify API token
docker run --rm --network domnet python:3.11-slim \
  python3 -c "import requests; r=requests.post('http://outline:3000/api/auth.info', headers={'Authorization': 'Bearer YOUR_TOKEN'}); print(r.status_code)"
```

### Docker Permission Denied
```bash
sudo usermod -aG docker $USER
newgrp docker
```

### Container Not Found
```bash
# Verify Outline is running
docker ps | grep outline
```

### Verification Fails
```bash
# Clean start
rm -rf exports/
./export_with_trees.sh
```

### API Errors
Check `exports/export_errors.json` for details on failed documents.

## Security

- `settings.json` contains API token - never commit to git
- Backup files may contain sensitive wiki content
- Consider restricting file permissions:
  ```bash
  chmod 600 settings.json
  chmod 700 exports/
  ```

---

**Last Updated:** 2026-01-14