feat: add folder URL support to folder export command

- Add Folder.from_url() method to parse folder URLs and extract IDs
- Support multiple URL patterns: /spaces/SPACE/folders/ID, /spaces/SPACE/pages/folders/ID
- Update folders command to accept both IDs and URLs with automatic detection
- Add comprehensive unit tests for URL parsing (4 new tests covering different patterns)
- Update README.md with folder URL usage examples
- Fix test infrastructure in conftest.py to handle module-level Confluence instance

All 89 unit tests passing. Folder export now supports the same flexible input
methods as page exports, allowing users to easily export folders by copying
URLs from their browser.

Author: AlessandroAnnini

README.md

@@ -99,6 +99,12 @@ Export all Confluence pages within a folder and all its subfolders by folder ID:
 confluence-markdown-exporter folders <folder-id e.g. 3491123> <output path e.g. ./output_path/>
 ```
 
+or by URL:
+
+```sh
+confluence-markdown-exporter folders <folder-url e.g. https://company.atlassian.net/wiki/spaces/MYSPACE/folders/3491123> <output path e.g. ./output_path/>
+```
+
 This command **recursively exports all pages** from the specified folder and any nested subfolders within it. You can find the folder ID in the Confluence URL when viewing a folder, or from the folder's properties in Confluence.
 
 #### 2.5. Export all Spaces

confluence_markdown_exporter/confluence.py

@@ -259,6 +259,41 @@ def from_id(cls, folder_id: str) -> "Folder":
             msg = f"Could not access folder with ID {folder_id}: {e}"
             raise ValueError(msg) from e
 
+    @classmethod
+    def from_url(cls, folder_url: str) -> "Folder":
+        """Retrieve a Folder object given a Confluence folder URL.
+
+        Supports URL patterns like:
+        - https://company.atlassian.net/wiki/spaces/SPACE/folders/123456
+        - https://company.atlassian.net/wiki/spaces/SPACE/pages/folders/123456
+        """
+        url = urllib.parse.urlparse(folder_url)
+        hostname = url.hostname
+        if hostname and hostname not in str(settings.auth.confluence.url):
+            global confluence  # noqa: PLW0603
+            set_setting("auth.confluence.url", f"{url.scheme}://{hostname}/")
+            confluence = get_confluence_instance()  # Refresh instance with new URL
+
+        path = url.path.rstrip("/")
+
+        # Try pattern: /wiki/spaces/SPACE/folders/123456
+        if match := re.search(r"/wiki/spaces/[^/]+/folders/(\d+)", path):
+            folder_id = match.group(1)
+            return Folder.from_id(folder_id)
+
+        # Try pattern: /wiki/spaces/SPACE/pages/folders/123456
+        if match := re.search(r"/wiki/spaces/[^/]+/pages/folders/(\d+)", path):
+            folder_id = match.group(1)
+            return Folder.from_id(folder_id)
+
+        # Try pattern: /wiki/.+?/folders/123456 (generic)
+        if match := re.search(r"/wiki/.+?/folders/(\d+)", path):
+            folder_id = match.group(1)
+            return Folder.from_id(folder_id)
+
+        msg = f"Could not parse folder URL {folder_url}."
+        raise ValueError(msg)
+
 
 class Label(BaseModel):
     id: str

confluence_markdown_exporter/main.py

@@ -81,7 +81,7 @@ def spaces(
 
 @app.command(help="Export all Confluence pages within one or more folders to Markdown.")
 def folders(
-    folder_ids: Annotated[list[str], typer.Argument(help="Folder ID(s)")],
+    folders: Annotated[list[str], typer.Argument(help="Folder ID(s) or URL(s)")],
     output_path: Annotated[
         Path | None,
         typer.Option(
@@ -91,11 +91,16 @@ def folders(
 ) -> None:
     from confluence_markdown_exporter.confluence import Folder
 
-    with measure(f"Export folders {', '.join(folder_ids)}"):
-        for folder_id in folder_ids:
+    with measure(f"Export folders {', '.join(folders)}"):
+        for folder in folders:
             override_output_path_config(output_path)
-            folder = Folder.from_id(folder_id)
-            folder.export()
+            # Detect if it's a URL or ID
+            _folder = (
+                Folder.from_url(folder)
+                if folder.startswith(("http://", "https://"))
+                else Folder.from_id(folder)
+            )
+            _folder.export()
 
 
 @app.command(help="Export all Confluence pages across all spaces to Markdown.")

tests/conftest.py

@@ -5,6 +5,7 @@
 from pathlib import Path
 from typing import Any
 from unittest.mock import MagicMock
+from unittest.mock import patch
 
 import pytest
 from pydantic import AnyHttpUrl
@@ -17,6 +18,22 @@
 from confluence_markdown_exporter.utils.app_data_store import ExportConfig
 
 
+def pytest_configure(config: pytest.Config) -> None:  # noqa: ARG001
+    """Configure pytest by mocking the Confluence instance before import."""
+    # Mock get_confluence_instance to avoid authentication during test collection
+    # This is needed because confluence.py creates a module-level instance
+    patcher = patch("confluence_markdown_exporter.api_clients.get_confluence_instance")
+    mock = patcher.start()
+    mock_client = MagicMock()
+    mock.return_value = mock_client
+
+    # Import the module now with the mock in place
+    import confluence_markdown_exporter.confluence  # noqa: F401
+
+    # Stop the patcher after the module is loaded so individual tests can mock as needed
+    patcher.stop()
+
+
 @pytest.fixture
 def temp_config_dir() -> Generator[Path, None, None]:
     """Create a temporary directory for test configuration."""

tests/unit/test_confluence.py

@@ -164,6 +164,65 @@ def test_from_id(
         assert folder.title == "Test Folder"
         mock_get_folder.assert_called_once_with("123456")
 
+    @patch("confluence_markdown_exporter.confluence.Folder.from_id")
+    @patch("confluence_markdown_exporter.confluence.settings")
+    def test_from_url_spaces_folders_pattern(
+        self, mock_settings: MagicMock, mock_from_id: MagicMock
+    ) -> None:
+        """Test creating Folder from URL with /spaces/SPACE/folders/ pattern."""
+        mock_settings.auth.confluence.url = "https://company.atlassian.net/"
+
+        mock_folder = MagicMock()
+        mock_from_id.return_value = mock_folder
+
+        url = "https://company.atlassian.net/wiki/spaces/MYSPACE/folders/123456"
+        result = Folder.from_url(url)
+
+        mock_from_id.assert_called_once_with("123456")
+        assert result == mock_folder
+
+    @patch("confluence_markdown_exporter.confluence.Folder.from_id")
+    @patch("confluence_markdown_exporter.confluence.settings")
+    def test_from_url_pages_folders_pattern(
+        self, mock_settings: MagicMock, mock_from_id: MagicMock
+    ) -> None:
+        """Test creating Folder from URL with /pages/folders/ pattern."""
+        mock_settings.auth.confluence.url = "https://company.atlassian.net/"
+
+        mock_folder = MagicMock()
+        mock_from_id.return_value = mock_folder
+
+        url = "https://company.atlassian.net/wiki/spaces/MYSPACE/pages/folders/789012"
+        result = Folder.from_url(url)
+
+        mock_from_id.assert_called_once_with("789012")
+        assert result == mock_folder
+
+    @patch("confluence_markdown_exporter.confluence.Folder.from_id")
+    @patch("confluence_markdown_exporter.confluence.settings")
+    def test_from_url_generic_folders_pattern(
+        self, mock_settings: MagicMock, mock_from_id: MagicMock
+    ) -> None:
+        """Test creating Folder from URL with generic /folders/ pattern."""
+        mock_settings.auth.confluence.url = "https://company.atlassian.net/"
+
+        mock_folder = MagicMock()
+        mock_from_id.return_value = mock_folder
+
+        url = "https://company.atlassian.net/wiki/x/folders/345678"
+        result = Folder.from_url(url)
+
+        mock_from_id.assert_called_once_with("345678")
+        assert result == mock_folder
+
+    @patch("confluence_markdown_exporter.confluence.settings")
+    def test_from_url_invalid_url(self, mock_settings: MagicMock) -> None:
+        """Test that invalid folder URL raises ValueError."""
+        mock_settings.auth.confluence.url = "https://company.atlassian.net/"
+
+        with pytest.raises(ValueError, match="Could not parse folder URL"):
+            Folder.from_url("https://company.atlassian.net/wiki/invalid/path")
+
     @patch("confluence_markdown_exporter.confluence.get_folder_children")
     def test_pages_property_with_pages(self, mock_get_children: MagicMock) -> None:
         """Test pages property returns page IDs."""