Issue

#782
#611

Description of the Change

This PR adds comprehensive footnote support to Ghostwriter's rich text editor and report generation system. The implementation spans three main areas:

1. TipTap Editor Extension (JavaScript/TypeScript)

• Created new Footnote extension (javascript/src/tiptap_gw/footnote.tsx) as an inline atom node
• Footnotes display as superscript numbers in the editor with dynamic auto-numbering
• Serializes to HTML as <footnote>content here</footnote> tags for clean semantic markup
• Added FootnoteButton component (javascript/src/frontend/collab_forms/rich_text_editor/footnote.tsx) with modal dialog for entering footnote text
• Integrated into the rich text editor's "Misc" menu toolbar

2. Report Generation (Python)

• Updated HtmlToDocx class in ghostwriter/modules/reportwriter/richtext/docx.py to handle <footnote> HTML tags and convert them to proper Word footnotes using the forked python-docx library
• Implemented sequential footnote ID tracking for reliable numbering across paragraphs and table cells
• Added <w:footnoteRef/> element to display footnote numbers within footnote content at bottom of page
• Implemented post-processing cleanup in DocxReportBuilder to remove extra empty paragraphs from separator footnotes that cause unwanted spacing
• Updated HtmlToPptx to silently ignore footnotes since PowerPoint doesn't support them natively

3. Python-docx Fork Integration

• Integrated GhostManager/python-docx fork (branch: feat/footnote2) which adds native footnote API support to python-docx
• Modified fork to use direct superscript formatting (<w:vertAlign w:val="superscript"/>) instead of referencing non-existent FootnoteReference character style for broader template compatibility
• Updated both local and production Dockerfiles to install git package for GitHub dependency resolution
• Updated requirements/base.txt to install from GitHub repository instead of PyPI

4. Testing

• Added comprehensive test suite (ghostwriter/reporting/tests/test_footnotes.py) with 8 tests covering:
  • Basic footnote creation and verification
  • Multiple footnotes with sequential IDs
  • Multi-paragraph footnotes
  • Footnote access from paragraphs and document
  • HTML-to-DOCX conversion with footnotes in various contexts
  • Footnotes within table cells
• Extended existing rich text test suites for both DOCX and PPTX converters
• All tests use temporary directories with automatic cleanup

Alternate Designs

Footnote Numbering Algorithm: Initially considered using python-docx's built-in _calculate_next_footnote_reference_id() algorithm, but it relies on paragraph ordering in document.paragraphs which doesn't work reliably for dynamically-built documents or table cell paragraphs. The selected approach uses simple sequential ID tracking based on the maximum existing footnote ID, which is more predictable and reliable for HTML-to-DOCX conversion workflows.

Separator Footnote Cleanup Timing: Initially attempted to clean up separator footnotes during document building by modifying the document object directly, but this interfered with docxtpl's internal template rendering state and caused the template variables to not be replaced. The selected approach uses post-processing that reopens the saved BytesIO document, cleans the separators, and re-saves it - avoiding interference with template rendering.

PowerPoint Support: PowerPoint doesn't natively support footnotes. Considered three options:

1. Silently ignore/strip footnotes (selected)
2. Convert to inline parenthetical text like "(Note: ...)"
3. Collect footnotes and add as text at end of slide

Selected option 1 (silent ignore) to keep presentations clean and avoid cluttering slides with footnote text that doesn't fit the presentation medium.

Python-docx Style Reference: The fork initially used <w:rStyle w:val="FootnoteReference"/> which references a character style that may not exist in all Word templates, causing "unreadable content" errors. Modified to use direct formatting via <w:vertAlign w:val="superscript"/> XML element for universal compatibility.

Possible Drawbacks

• External GitHub Dependency: Now depends on a GitHub-hosted fork of python-docx instead of the stable PyPI package. Requires git installation in Docker images and active maintenance of the fork to stay current with upstream changes.

• Docker Image Size: Adding git to Alpine-based Docker images slightly increases build time (~10-20 seconds) and image size (~5-10 MB for git and dependencies).

• Template Post-Processing: The separator cleanup step reopens and re-saves the generated document, which adds minimal overhead but could theoretically cause issues with heavily customized templates containing complex custom XML parts (though this is unlikely in practice).

• PowerPoint Limitation: Footnotes are silently dropped in PPTX exports without user notification, which could confuse users expecting footnotes to appear. This should be documented in user-facing documentation.

• Fork Maintenance: The python-docx fork needs to be kept in sync with upstream releases to receive bug fixes and new features, requiring ongoing maintenance effort.

Verification Process

Unit and Integration Testing:

# Ran full Django test suite with coverage
docker compose -f local.yml run django coverage run manage.py test

# Ran footnote-specific tests
docker compose -f local.yml run django python manage.py test ghostwriter.reporting.tests.test_footnotes

# Verified all 8 new footnote tests pass
# Verified all 31 existing rich text tests still pass (no regressions)

Code Quality Checks:

# Ran pylint on modified Python files
docker compose -f local.yml run django pylint ghostwriter/modules/reportwriter/richtext/docx.py
docker compose -f local.yml run django pylint ghostwriter/modules/reportwriter/base/docx.py
docker compose -f local.yml run django pylint ghostwriter/reporting/tests/test_footnotes.py

# Ran TypeScript type checking
cd javascript && npm run check

# Verified no TypeScript errors in footnote extension or UI components

Manual UI Testing:

1. Started development environment: ./ghostwriter-cli-linux up --dev
2. Created new client "SpecterOps" via web interface
3. Created new project "SpecterOps Pentest" under client
4. Created finding with rich text description containing 3 footnotes:
   • Clicked "Misc" menu (☰ icon) in rich text toolbar
   • Selected "Insert Footnote"
   • Entered footnote text in modal dialog
   • Clicked "Insert" button
   • Verified superscript number appeared inline (¹, ², ³)
   • Repeated for second and third footnotes
5. Generated DOCX report via "Generate Report" button
6. Downloaded and opened report in Microsoft Word 2021
7. Verified results:
   • No "unreadable content" errors when opening file
   • Footnote references appear as superscript numbers in text (¹, ², ³)
   • Footnotes appear at bottom of page with correct numbering
   • Footnote text is properly formatted
   • Minimal spacing between separator line and footnote content

Cross-Context Testing:
Verified footnotes work correctly in:

• Regular paragraphs
• Headings (H1-H6)
• List items (ordered and unordered)
• Table cells
• Mixed formatting (bold, italic within footnotes)

Editor Testing:

• Inserted multiple footnotes and verified dynamic renumbering
• Deleted middle footnote and verified remaining footnotes renumber correctly
• Added footnote, typed more text, added another footnote
• Verified tooltip shows footnote content on hover over superscript number
• Tested undo/redo functionality with footnotes

Template Compatibility:

• Tested with default Ghostwriter template
• Tested with custom uploaded template containing existing separator footnotes
• Verified separator cleanup removes extra paragraphs without breaking template

PowerPoint Export:

• Generated PPTX report with footnotes
• Verified footnotes are silently ignored (no errors, no remnant text)
• Confirmed slide content renders normally without footnote references

Release Notes

Added footnote support in rich text editor with automatic superscript numbering and proper Word footnote export in DOCX reports