outline-sync/CLAUDE.md

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

# 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

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.