d9161f64f5
- 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>
95 lines
3.4 KiB
Markdown
95 lines
3.4 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## Project Overview
|
|
|
|
This is a tool for exporting Outline wiki data via API. The script runs inside a Docker container on the `domnet` network to bypass Authentik SSO authentication and access the internal Outline API directly (`http://outline:3000`).
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
# Run the export with tree visualization
|
|
./export_with_trees.sh
|
|
|
|
# Preview without exporting (dry run)
|
|
./export_with_trees.sh --dry-run
|
|
|
|
# Run with verbose output
|
|
./export_with_trees.sh -v
|
|
```
|
|
|
|
### CLI Options
|
|
```
|
|
--dry-run, -n Preview what would be exported without writing files
|
|
--output, -o DIR Output directory (overrides settings.json)
|
|
--verbose, -v Increase verbosity (-vv for debug)
|
|
--skip-verify Skip post-export verification
|
|
--skip-health-check Skip pre-export health check
|
|
--settings FILE Path to settings file (default: settings.json)
|
|
```
|
|
|
|
### Running the Python Export Directly
|
|
```bash
|
|
docker run --rm --network domnet \
|
|
-v "$(pwd):/work" \
|
|
-w /work \
|
|
python:3.11-slim \
|
|
bash -c "pip install -q requests tqdm && python3 outline_export_fixed.py"
|
|
|
|
# With options
|
|
docker run --rm --network domnet \
|
|
-v "$(pwd):/work" \
|
|
-w /work \
|
|
python:3.11-slim \
|
|
bash -c "pip install -q requests tqdm && python3 outline_export_fixed.py --dry-run"
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Docker Network Integration
|
|
- Script runs in Docker container attached to `domnet` bridge network
|
|
- Direct API access to `http://outline:3000` (internal) bypasses SSO
|
|
- Uses `python:3.11-slim` image with `requests` and `tqdm` dependencies
|
|
|
|
### Export Flow
|
|
1. Fetch collections via `/api/collections.list`
|
|
2. Get navigation tree via `/api/collections.documents` (source of truth for hierarchy)
|
|
3. Fetch full document content via `/api/documents.info` (with caching)
|
|
4. Export recursively maintaining parent-child structure
|
|
5. Save metadata (`_collection_metadata.json`) per collection
|
|
6. Generate manifest with checksums for verification
|
|
|
|
### Key Files
|
|
- `export_with_trees.sh` - Main export script with tree visualization
|
|
- `outline_export_fixed.py` - Core export logic with `OutlineExporter` class
|
|
- `settings.json` - API URL and token configuration (contains secrets)
|
|
- `outline_export/` - Output directory with markdown files and metadata
|
|
- `outline_backup_*.tar.gz` - Timestamped compressed backups
|
|
|
|
### Configuration
|
|
Settings are in `settings.json`:
|
|
- `source.url` - Internal Docker URL (`http://outline:3000`)
|
|
- `source.token` - Outline API token
|
|
- `export.output_directory` - Output path (default: `outline_export`)
|
|
- `advanced.max_hierarchy_depth` - Prevent infinite recursion (default: 100)
|
|
|
|
## Important Notes
|
|
|
|
### Security
|
|
- `settings.json` contains API token - never commit to git
|
|
- Backup files may contain sensitive wiki content
|
|
|
|
### Backup System
|
|
- Each export automatically backs up previous exports to `outline_backup_YYYYMMDD_HHMMSS.tar.gz`
|
|
- Old uncompressed export directory is deleted after backup
|
|
- Backups achieve 90%+ compression on markdown content
|
|
|
|
### Reliability Features
|
|
- **Health check**: Verifies API connectivity before export
|
|
- **Retry logic**: Failed API requests retry up to 3 times with exponential backoff
|
|
- **Logging**: Structured logging with configurable verbosity levels
|
|
|
|
### Document Counting
|
|
The navigation tree (`/api/collections.documents`) is the source of truth for document hierarchy. Document counting is recursive to include all nested children.
|