pdf-to-dita

Overview

pdf-to-dita orchestrates a five-stage pipeline that transforms any PDF into a well-structured DITA 1.3 guide, validates every generated file, applies best-practices fixes, and produces a consolidated quality report.

PDF  →  [1] Extract  →  [2] Chunk  →  [3] Validate  →  [4] Optimize  →  [5] Review
         extracted.json   topics/*.dita  validation_       optimization_    review_
                          root.ditamap   report.json       report.json      report.json

Pipeline stages

Stage 1 — Extract (extract_pdf.py)

Reads the PDF with pdfplumber and produces a structural JSON document.

• Detects heading levels from font-size ratios (body text = most common size; ratio ≥ 1.15 → heading).
• Preserves paragraphs, ordered/unordered lists, and tables.
• Outputs extracted.json with a nested sections tree.

python pdf-to-dita/scripts/extract_pdf.py input.pdf > extracted.json

Output excerpt:

{
  "source": "/abs/path/input.pdf",
  "title":  "Getting Started Guide",
  "pages":  42,
  "sections": [
    {
      "level": 1,
      "title": "Installation",
      "content": [
        {"type": "paragraph", "text": "This guide covers..."},
        {"type": "list", "ordered": true, "items": ["Download the package", "Run setup.sh"]}
      ],
      "subsections": []
    }
  ]
}

Stage 2 — Chunk (chunk_to_dita.py)

Converts the extracted JSON into DITA 1.3 XML topics and a root ditamap.

Topic-type heuristics:

Output structure:

output_dir/
├── root.ditamap
└── topics/
    ├── installation.dita        (task)
    ├── configuration-options.dita (reference)
    └── overview.dita             (concept)

python pdf-to-dita/scripts/chunk_to_dita.py extracted.json ./output --map-title "My Guide"

Stage 3 — Validate (validate_output.py)

Calls validate_dita_topic.py and validate_ditamap.py on every generated file.

python pdf-to-dita/scripts/validate_output.py ./output

Output excerpt:

{
  "summary": {
    "total_files": 8, "valid": 7, "invalid": 1,
    "total_errors": 2, "total_warnings": 5
  },
  "files": [
    { "file": "topics/installation.dita", "is_valid": true, "errors": [], "warnings": [] }
  ]
}

Stage 4 — Optimize (optimize_dita.py)

Calls best_practices.py on each topic, auto-fixes common violations, then re-validates.

Auto-fixes applied:

Remaining errors and warnings after auto-fix are reported but not auto-corrected (require human review).

python pdf-to-dita/scripts/optimize_dita.py ./output

Stage 5 — Review (review_dita_guide.py)

Runs the full hierarchical guide review via review-dita-guide, traversing the generated map → topics and checking for:

• Missing href targets
• Duplicate topic @id values across the guide
• Cross-file structural issues

python review-dita-guide/scripts/review_dita_guide.py ./output/root.ditamap --best-practices

Running the full pipeline

# Full pipeline (all 5 stages)
python pdf-to-dita/scripts/pipeline.py input.pdf ./output

# With custom map title
python pdf-to-dita/scripts/pipeline.py input.pdf ./output --map-title "My Product Guide"

# Skip Stage 5 for faster iteration
python pdf-to-dita/scripts/pipeline.py input.pdf ./output --skip-review

# Resume from extracted JSON (skip PDF re-extraction)
python pdf-to-dita/scripts/pipeline.py --from-json extracted.json ./output

# Full verbose report
python pdf-to-dita/scripts/pipeline.py input.pdf ./output --format full

Summary report output:

{
  "overall": "ok",
  "output_dir": "./output",
  "stages": [
    { "stage": "extract",  "status": "ok", "elapsed_s": 3.2 },
    { "stage": "chunk",    "status": "ok", "elapsed_s": 0.4 },
    { "stage": "validate", "status": "warnings", "elapsed_s": 1.1 },
    { "stage": "optimize", "status": "ok", "elapsed_s": 1.3 },
    { "stage": "review",   "status": "ok", "elapsed_s": 2.0 }
  ],
  "validation":   { "total_files": 8, "valid": 8, "total_errors": 0, "total_warnings": 3 },
  "optimization": { "total_topics": 7, "fixes_applied": 4, "remaining_errors": 0 },
  "review":       { "maps": 1, "topics": 7, "errors": 0, "warnings": 3 }
}

Exit codes

Integration with other skills

Installation

# Required for Stage 1 (PDF extraction)
pip install pdfplumber

# Or install with the project optional dependency group
pip install "dita-skills[pdf]"

Common issues

See also

• validate-dita-topic — standalone topic validation
• validate-ditamap — standalone map validation
• dita-best-practices — standalone best-practices analysis
• review-dita-guide — full hierarchical guide review
• refactor-dita-content — improve reuse and modularity of generated topics