Add Folder Export Feature with URL Support

[AlessandroAnnini]

Add Folder Export Feature with URL Support

Summary

This PR adds a new folders command that enables exporting all pages within a Confluence folder and its subfolders to Markdown. The feature includes:

Core Functionality

• Recursive folder export: Automatically downloads all pages from a folder and all nested subfolders at any depth
• Flexible input methods: Supports both folder IDs and folder URLs (e.g., https://company.atlassian.net/wiki/spaces/MYSPACE/folders/123456)
• Confluence REST API v2 integration: Uses /api/v2/folders/ endpoints for folder operations
• Cursor-based pagination: Handles large folders with many children efficiently
• Error resilience: Continues processing even if some subfolders are inaccessible

Usage

Export folder by ID:

confluence-markdown-exporter folders 3491123 ./output/

Export folder by URL (same as pages command):

confluence-markdown-exporter folders https://company.atlassian.net/wiki/spaces/MYSPACE/folders/3491123 ./output/

Export multiple folders (mixing IDs and URLs):

confluence-markdown-exporter folders 3491123 https://company.atlassian.net/wiki/spaces/MYSPACE/folders/3491456 ./output/

Implementation Details

New Folder class (confluence_markdown_exporter/confluence.py):

• from_id(folder_id): Fetch and create Folder from ID
• from_url(folder_url): Parse folder URL and create Folder from extracted ID (supports multiple URL patterns)
• export(): Export all pages with warning for empty folders
• pages property: Recursively collects all page IDs from folder hierarchy

API helper functions:

• get_folder_by_id(): Fetches folder metadata using REST API v2
• get_folder_children(): Fetches all children (pages and subfolders) with pagination

CLI integration (confluence_markdown_exporter/main.py):

• New folders command following the same pattern as pages and spaces commands
• Automatic detection of IDs vs URLs (checks for http:// or https:// prefix)
• Optional --output-path parameter

Documentation:

• Updated README.md with folder export section and examples
• Clear explanation that export is recursive
• Instructions on finding folder IDs in Confluence URLs

Test Plan

Unit Tests

• ✅ 89 unit tests passing (added 16 new tests)
• TestGetFolderById: Tests for folder fetching and 404 handling
• TestGetFolderChildren: Tests for pagination, empty folders, and HTTP errors
• TestFolderClass: Tests for Folder class methods including:
  • from_json() and from_id() creation methods
  • from_url() with multiple URL patterns (/spaces/SPACE/folders/ID, /spaces/SPACE/pages/folders/ID, generic patterns)
  • Invalid URL handling (raises ValueError)
  • pages property with recursive traversal
  • export() method with and without pages
  • Empty folder warning logging

Code Quality

• ✅ All linting checks passed (ruff)
• ✅ Google-style docstrings on all new functions
• ✅ Type hints throughout
• ✅ 100 character line length maintained
• ✅ Follows existing code patterns and conventions

Manual Testing

The feature has been tested with:

• Single folders with pages
• Nested folder structures (multiple levels deep)
• Empty folders (logs warning as expected)
• Large folders requiring pagination
• Mixed ID and URL inputs
• Invalid folder URLs (proper error handling)

Test Infrastructure

• Fixed tests/conftest.py to mock the module-level Confluence instance during test collection
• Ensures tests don't require actual Confluence authentication

Changes

Modified files:

• README.md: Added folder export documentation and examples
• confluence_markdown_exporter/confluence.py: Added Folder class and API helpers (~160 lines)
• confluence_markdown_exporter/main.py: Added folders command (~20 lines)
• tests/conftest.py: Fixed test infrastructure for module-level imports
• tests/unit/test_confluence.py: Added comprehensive test suite (~250 lines)
• tests/unit/test_main.py: Updated command list test

Backward Compatibility

✅ This feature is fully backward compatible:

• No changes to existing commands or APIs
• No breaking changes to configuration
• Existing exports continue to work unchanged
• New command follows established patterns

[AlessandroAnnini]

Fixed!

[Spenhouet]

@AlessandroAnnini Thanks for this PR. Can you solve the merge conflict and adjust the code to the latest version? As was done for the other commands, can you also add an additional singular "folder" command.