Initial commit: Export tools and import script requirements
- export_with_trees.sh: Bash wrapper for Outline export - outline_export_fixed.py: Python export implementation - IMPORT_SCRIPT.MD: PRD for import script (to be built) - RALPH_PROMPT.md: Ralph Loop prompt for building import script - CLAUDE.md: Project documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Claude
217
README.md
Normal file
217
README.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user