### Install Dependencies and Start Local Docs Server

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/contributing.md

Install project dependencies and start a local development server to preview the documentation site. This command is used for local development and testing of documentation changes.

```bash
npm ci && npm start
```

--------------------------------

### Execute Get Configuration Key Commands

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-config.md

Provides examples for the 'get' command to retrieve configuration values. Shows retrieving a single key, a nested key, and an entire section, with expected output formats.

```bash
cme config get export.log_level  # Output: INFO
cme config get export.output_path
cme config get connection_config.max_workers  # Output: 20
cme config get connection_config  # Outputs the whole section as YAML
cme config get export  # Outputs all export settings
```

--------------------------------

### Verify Project Installation

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/CONTRIBUTING.md

Verifies the project installation by running the main command-line interface tool with the help flag. This confirms that the project is correctly installed and accessible.

```bash
uv run confluence-markdown-exporter --help
uv run cme --help
```

--------------------------------

### Install and Run Confluence Markdown Exporter with uv

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/intro.md

Installs the tool using uv or runs it directly without installation for a quick help command.

```bash
uv tool install confluence-markdown-exporter
# or, one-shot run without installing:
uvx confluence-markdown-exporter --help
```

--------------------------------

### Install uv Package Manager

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/CONTRIBUTING.md

Installs the uv package manager by downloading and executing an installation script. It's recommended to add shell completion for convenience.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```bash
echo 'eval "$(uv generate-shell-completion bash)"' >> ~/.bashrc
```

--------------------------------

### Install jq

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/CONTRIBUTING.md

Installs the jq command-line JSON processor using apt-get. This is a prerequisite for certain operations.

```bash
sudo apt-get install jq
```

--------------------------------

### Environment Variable Examples

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-config.md

Examples of environment variables for array, boolean, and string values.

```shell
CME_CONNECTION_CONFIG__RETRY_STATUS_CODES='[429,502,503]'

CME_EXPORT__SKIP_UNCHANGED=false

CME_EXPORT__LOG_LEVEL=DEBUG
```

--------------------------------

### Install and run Confluence Markdown Exporter with uv

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/installation.md

Installs the CLI into an isolated environment using 'uv tool install' or runs it ephemerally with 'uvx'. The 'uv tool install' command adds the CLI to your PATH, while 'uvx' is suitable for one-off commands or CI.

```bash
# Install as an isolated, self-managed tool
uv tool install confluence-markdown-exporter

# …or run it once without installing
uvx confluence-markdown-exporter --help
```

--------------------------------

### Install Project Dependencies with uv

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/CONTRIBUTING.md

Installs all project dependencies, including development dependencies, and sets up the project in editable mode using uv. This command also creates a virtual environment if one does not exist.

```bash
uv sync --all-groups
```

--------------------------------

### Install Confluence Markdown Exporter using pip

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/installation.md

Installs the tool from PyPI into your active Python environment. Requires Python version 3.10 or higher. For isolated installations, consider the uv or OS-specific installers.

```bash
pip install confluence-markdown-exporter
```

--------------------------------

### Pin Confluence Markdown Exporter installation with uv

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/installation.md

Installs a specific version (e.g., 5.2.0) of the tool into an isolated environment using 'uv tool install'.

```bash
uv tool install confluence-markdown-exporter==5.2.0
```

--------------------------------

### Example Output Directory Structure

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/usage.md

This illustrates the typical directory structure created by the exporter within the configured output path.

```text
output_path/
└── MYSPACE/
   ├── MYSPACE.md
   └── MYSPACE/
      ├── My Confluence Page.md
      └── My Confluence Page/
            ├── My nested Confluence Page.md
            └── Another one.md
```

--------------------------------

### Example: Export Single and Multiple Pages

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-main.md

Provides examples of how to use the 'pages' command to export a single Confluence page or multiple pages at once using their URLs.

```bash
# Export a single page
cme pages https://company.atlassian.net/wiki/spaces/KEY/pages/123/My+Page

# Export multiple pages at once
cme pages https://...page1 https://...page2
```

--------------------------------

### AuthConfig Example Structure

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/types.md

Illustrates the expected JSON structure for the AuthConfig, showing how Confluence and Jira credentials are organized.

```json
{
  "confluence": {
    "https://company.atlassian.net": {
      "username": "user@example.com",
      "api_token": "***",
      "cloud_id": "12345abc"
    },
    "https://confluence.company.com": {
      "pat": "***"
    }
  },
  "jira": {
    "https://company.atlassian.net": {
      "username": "user@example.com",
      "api_token": "***",
      "cloud_id": "12345abc"
    }
  }
}
```

--------------------------------

### Install Confluence Markdown Exporter (Windows)

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/README.md

Installs the exporter using a PowerShell script for Windows systems.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://uvx.sh/confluence-markdown-exporter/install.ps1 | iex"
```

--------------------------------

### Handle AuthNotConfiguredError

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-api-clients.md

Example of how to catch and handle the AuthNotConfiguredError when attempting to get a Confluence instance. It prints a user-friendly message indicating the need for authentication configuration.

```python
try:
    client = get_confluence_instance("https://company.atlassian.net")
except AuthNotConfiguredError as e:
    print(f"Please configure {e.service} at {e.url}")
```

--------------------------------

### Execute Reset Configuration Commands

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-config.md

Provides examples of how to use the 'reset' command from the CLI. Demonstrates resetting the entire configuration, skipping confirmation, and resetting specific keys or sections.

```bash
cme config reset  # Reset everything (prompts for confirmation)
cme config reset --yes  # Skip confirmation
cme config reset export.log_level  # Reset a single key
cme config reset connection_config  # Reset a whole section
```

--------------------------------

### Install Specific Version (macOS/Linux)

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/README.md

Installs a specific version of the exporter using a curl script.

```bash
curl -LsSf uvx.sh/confluence-markdown-exporter/5.2.0/install.sh | sh
```

--------------------------------

### Execute List Configuration Commands

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-config.md

Demonstrates using the 'list' command to view the current configuration in different formats. Shows examples for default YAML output, JSON output, and explicit YAML output.

```bash
cme config list  # YAML output
cme config list -o json  # JSON output
cme config list -o yaml  # Explicit YAML
```

--------------------------------

### Pull and Run Help Command

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/docker.md

Pulls the latest Docker image and runs the help command to verify the installation.

```bash
docker pull spenhouet/confluence-markdown-exporter:latest
docker run --rm spenhouet/confluence-markdown-exporter --help
```

--------------------------------

### Pin Confluence Markdown Exporter installation on Windows

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/installation.md

Installs a specific version (e.g., 5.2.0) of the tool on Windows using PowerShell and uv.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://uvx.sh/confluence-markdown-exporter/5.2.0/install.ps1 | iex"
```

--------------------------------

### Install Confluence Markdown Exporter (macOS/Linux)

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/README.md

Installs the exporter using a curl script for macOS and Linux systems.

```bash
curl -LsSf uvx.sh/confluence-markdown-exporter/install.sh | sh
```

--------------------------------

### Execute Path Command for Configuration File

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-config.md

Shows how to execute the 'path' command to retrieve the configuration file path. Includes an example of overriding the default path using an environment variable.

```bash
cme config path
# Output: /home/user/.config/confluence-markdown-exporter/app_data.json

CME_CONFIG_PATH=/custom/path.json cme config path
# Output: /custom/path.json
```

--------------------------------

### Pin Confluence Markdown Exporter installation using pip

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/installation.md

Installs a specific version (e.g., 5.2.0) of the tool from PyPI into your active Python environment.

```bash
pip install confluence-markdown-exporter==5.2.0
```

--------------------------------

### Example: Export Single and Multiple Spaces

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-main.md

Shows how to use the 'spaces' command to export all pages from a single Confluence space or multiple spaces by providing their respective URLs.

```bash
# Export a single space
cme spaces https://company.atlassian.net/wiki/spaces/MYSPACE

# Export multiple spaces
cme spaces https://...SPACE1 https://...SPACE2
```

--------------------------------

### Define Get Configuration Key Command

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-config.md

Defines the 'get' command to retrieve the value of a specific configuration key using dot notation. Handles nested keys and different output formats based on value type.

```python
def get(
    key: Annotated[
        str,
        typer.Argument(
            help="Config key in dot notation.",
            metavar="KEY",
        ),
    ],
) -> None
```

--------------------------------

### version

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-main.md

Displays the installed version of the confluence-markdown-exporter.

```APIDOC
## Command: version

### Description
Displays the installed version of the confluence-markdown-exporter.

### Example
```bash
cme version
# Output: confluence-markdown-exporter 5.2.0
```
```

--------------------------------

### Display Confluence Markdown Exporter Version

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-main.md

Use the `version` command to display the installed version of the confluence-markdown-exporter. This command requires no arguments.

```python
def version() -> None
```

```bash
cme version
# Output: confluence-markdown-exporter 5.2.0
```

--------------------------------

### Export Pages Example

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-confluence.md

Demonstrates how to export multiple pages in parallel using the `export_pages` function. Ensure `Page` and `export_pages` are imported.

```python
from confluence_markdown_exporter.confluence import Page, export_pages

page1 = Page.from_id(123, "https://company.atlassian.net")
page2 = Page.from_id(456, "https://company.atlassian.net")
export_pages([page1, page2])  # Exports in parallel
```

--------------------------------

### Attachment Link Generation Examples

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/configuration/options.md

Shows how different `export.attachment_href` settings impact the generation of links to attachments and images in Markdown.

```markdown
[file.pdf](../path/to/file.pdf) / ![alt](../path/to/image.png)
```

```markdown
[file.pdf](/space/attachments/file.pdf) / ![alt](/space/attachments/image.png)
```

```markdown
[[file.pdf|File Title]] / ![[]]
```

--------------------------------

### Setup Logging Configuration

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Initializes the logging configuration for the exporter. It sets the log level and can optionally write logs to a file. This function also suppresses rich formatting in CI environments.

```python
def setup_logging(
    level: str,
    log_file: Path | None = None,
) -> None:
```

--------------------------------

### Python _parse_value Examples

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-config.md

Demonstrates how the _parse_value function handles various input strings, including JSON, Python booleans, numbers, and plain strings.

```python
_parse_value("true")           # → True (bool)
_parse_value("True")           # → True (bool)
_parse_value("false")          # → False (bool)
_parse_value("42")             # → 42 (int)
_parse_value("[1,2,3]")        # → [1, 2, 3] (list)
_parse_value("hello")          # → "hello" (str)
```

--------------------------------

### Example: Export Page Tree

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-main.md

Demonstrates how to use the 'pages-with-descendants' command to export a root Confluence page and all its child pages, or multiple root pages and their respective trees.

```bash
# Export a page tree
cme pages-with-descendants https://company.atlassian.net/wiki/spaces/KEY/pages/123/Root

# Export multiple trees
cme pages-with-descendants https://...root1 https://...root2
```

--------------------------------

### Get Specific Configuration Value

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/README.md

Retrieves the value of a specific configuration setting. Useful for checking individual parameters.

```bash
cme config get export.output_path
```

--------------------------------

### Image Caption Rendering Example

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/configuration/options.md

Demonstrates how Confluence image captions are rendered in Markdown when the `export.image_captions` option is enabled.

```markdown
![](image.png)
_Caption text_
```

--------------------------------

### Get Application Settings

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Loads application settings from configuration files and environment variables. Creates a default config file if one is missing and re-reads settings on each call.

```python
from confluence_markdown_exporter.utils.app_data_store import get_settings

settings = get_settings()
print(settings.export.output_path)
print(settings.connection_config.max_workers)
```

--------------------------------

### Page Link Generation Examples

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/configuration/options.md

Illustrates how different `export.page_href` settings affect the generation of links to Confluence pages in Markdown.

```markdown
[Page Title](../path/to/page.md)
```

```markdown
[Page Title](/space/path/to/page.md)
```

```markdown
[[Page Title]]
```

--------------------------------

### Confluence Authentication - Cloud with API Token

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/configuration.md

Example configuration for authenticating with an Atlassian Cloud Confluence instance using a username and API token. Ensure the correct cloud_id is provided.

```json
{
  "auth": {
    "confluence": {
      "https://company.atlassian.net": {
        "username": "user@example.com",
        "api_token": "ATATT3xFfGF0_fake_token_example",
        "cloud_id": "12345abc"
      }
    }
  }
}
```

--------------------------------

### Confluence Authentication - Self-Hosted with PAT

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/configuration.md

Example configuration for authenticating with a self-hosted Confluence instance using a Personal Access Token (PAT). This method is an alternative to using API tokens.

```json
{
  "auth": {
    "confluence": {
      "https://confluence.company.com": {
        "pat": "MzMwMDYzNTE4ODQzOmRm_fake_pat_example"
      }
    }
  }
}
```

--------------------------------

### Get a Single Configuration Value

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/configuration/index.md

Retrieves and prints the current value of a specified configuration key. Nested sections are displayed in YAML format.

```sh
cme config get export.log_level
cme config get connection_config.max_workers
```

--------------------------------

### Example Confluence Lock File JSON Structure

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/types.md

Illustrates the expected JSON format for the Confluence lock file, detailing organization and space export information.

```json
{
  "lockfile_version": 2,
  "last_export": "2024-01-15T10:30:00Z",
  "orgs": {
    "https://company.atlassian.net": {
      "spaces": {
        "MYSPACE": {
          "pages": {
            "12345": {
              "title": "My Page",
              "version": 3,
              "export_path": "MySpace/My Page.md",
              "attachments": {
                "67890": {
                  "version": 1,
                  "path": "MySpace/attachments/file-id-1234.png"
                }
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### List All Configuration

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/configuration.md

Displays all current configuration settings in YAML or JSON format.

```bash
# Show all config as YAML
cme config list

# Show all config as JSON
cme config list -o json
```

--------------------------------

### setup_logging

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Initializes the logging configuration. This function sets the log level and can optionally direct logs to a file.

```APIDOC
## setup_logging()

### Description
Initialize logging configuration. This function configures Python logging to the specified level and optionally writes to both console and a log file. It also suppresses rich formatting in CI environments.

### Method Signature
`def setup_logging(level: str, log_file: Path | None = None) -> None`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **level** (`str`) - Required - Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`)
- **log_file** (`Path | None`) - Optional - Optional log file path
```

--------------------------------

### Activate Virtual Environment and Run

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/CONTRIBUTING.md

Activates the project's virtual environment and then runs the confluence-markdown-exporter application directly. This is an alternative to using uv for running the application.

```bash
# Or activate the virtual environment
source .venv/bin/activate
confluence-markdown-exporter [commands]
```

--------------------------------

### Build Production Version of Documentation Site

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/contributing.md

Build the production-ready version of the documentation site, including all versioned documentation. This command is used to generate the final site for deployment.

```bash
npm run build:versioned
```

```bash
npm run serve
```

--------------------------------

### Initialize Typer Application for Config

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-config.md

Sets up the main Typer application for the config subcommand. It enables rich markdown support for help messages and allows invocation without a subcommand to open an interactive menu.

```python
app = typer.Typer(
    rich_markup_mode="markdown",
    invoke_without_command=True,
    help="Manage configuration interactively or via subcommands."
)
```

--------------------------------

### get_confluence_instance

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-api-clients.md

Get an authenticated Confluence API client for a given URL.

```APIDOC
## Function: get_confluence_instance

### Description
Get authenticated Confluence API client for a URL.

### Signature
```python
def get_confluence_instance(url: str) -> ConfluenceApiSdk
```

### Parameters
#### Path Parameters
- **url** (str) - Required - Confluence instance URL

### Returns
- **ConfluenceApiSdk** - Authenticated client

### Behavior
- Creates a new client if one doesn't exist for that URL.
- Caches clients by normalized URL.
- Looks up authentication from configuration.
- Auto-fetches and stores Cloud ID for standard Atlassian Cloud instances.
- Routes through API gateway when Cloud ID is configured.

### Throws
- **AuthNotConfiguredError** - if no valid auth is configured for the URL

### Caching
Clients are cached in `_confluence_clients` dict (thread-safe with lock).

### Example
```python
client = get_confluence_instance("https://company.atlassian.net")
spaces = client.get_all_spaces()
```
```

--------------------------------

### Run with Mounted Configuration File

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/docker.md

Runs the Docker container, mounting a local JSON configuration file and an output directory. Exports specified pages.

```bash
docker run --rm \
  -v "$PWD/app_data.json:/data/config/app_data.json:ro" \
  -v "$PWD/output:/data/output" \
  spenhouet/confluence-markdown-exporter \
  pages <page-url>
```

--------------------------------

### List Current Configuration

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/configuration/index.md

Prints the entire current configuration. The output defaults to YAML format, but can be changed to JSON using the `-o json` flag.

```sh
cme config list           # YAML (default)
cme config list -o json   # JSON
```

--------------------------------

### PageTitleRegistry.reset

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Clears all registered page ID to title mappings. This is useful for starting with a clean registry between export runs.

```APIDOC
## PageTitleRegistry.reset()

### Description
Clears all registered mappings. This is used between export runs to start with a clean registry.

### Method Signature
`@staticmethod def reset() -> None`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None
```

--------------------------------

### Open Interactive Configuration Menu

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/configuration/index.md

Use this command to open a full interactive menu for managing all configuration options, including authentication and nested sections. It allows for easy selection and modification of settings.

```sh
cme config
```

--------------------------------

### Load Configuration Settings in Python

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/INDEX.md

Use the 'get_settings' function from 'confluence_markdown_exporter.utils.app_data_store' to load the application's configuration. Access specific settings, like the output path, as attributes of the returned settings object.

```python
from confluence_markdown_exporter.utils.app_data_store import get_settings
settings = get_settings()
print(settings.export.output_path)
```

--------------------------------

### Python API: Load Configuration and Export Page

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/README.md

Demonstrates loading exporter settings and exporting a single Confluence page using the Python API. Requires importing Page and get_settings.

```python
from confluence_markdown_exporter.confluence import Page
from confluence_markdown_exporter.utils.app_data_store import get_settings

# Load configuration
settings = get_settings()
print(f"Output: {settings.export.output_path}")
print(f"Workers: {settings.connection_config.max_workers}")

# Export a page
page = Page.from_url("https://company.atlassian.net/wiki/spaces/KEY/pages/123/Title")
attachment_entries = page.export()
```

--------------------------------

### Project File Hierarchy

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/MANIFEST.md

Illustrates the directory structure and the relationship between the MANIFEST.md file and other documentation files within the project.

```markdown
MANIFEST.md (this file)
  │
  └─ INDEX.md (navigation guide)
      │
      ├─ README.md (overview & quick start)
      │
      ├─ configuration.md (config guide)
      │
      ├─ api-reference-main.md (CLI commands)
      ├─ api-reference-confluence.md (content models)
      ├─ api-reference-config.md (config commands)
      ├─ api-reference-api-clients.md (auth & clients)
      ├─ api-reference-utilities.md (helpers)
      │
      └─ types.md (type definitions)
```

--------------------------------

### Included Project Files

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/MANIFEST.md

Lists the files included in the project's output directory, providing a clear overview of the available documentation and source files.

```bash
/workspace/home/output/
├── MANIFEST.md (this file)
├── INDEX.md (navigation guide)
├── README.md (project overview & quick start)
├── configuration.md (complete configuration reference)
├── api-reference-main.md (CLI commands)
├── api-reference-confluence.md (content models)
├── api-reference-config.md (configuration commands)
├── api-reference-api-clients.md (authentication & clients)
├── api-reference-utilities.md (utility functions)
└── types.md (type definitions)
```

--------------------------------

### get_settings

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Loads current application settings from configuration files and environment variables. It prioritizes config files, then applies environment variable overrides, and creates a default config file if none exists. Settings are re-read on each call to reflect the latest changes.

```APIDOC
## Function: get_settings

**Location:** `confluence_markdown_exporter/utils/app_data_store.py`

Load current application settings from config file and environment.

```python
def get_settings() -> AppSettings
```

**Returns:** `AppSettings` instance with current config

**Behavior:**
- Loads from config file first
- Applies environment variable overrides
- Creates config file with defaults if missing
- Re-reads on each call (reflects latest config changes)

**Example:**

```python
from confluence_markdown_exporter.utils.app_data_store import get_settings

settings = get_settings()
print(settings.export.output_path)
print(settings.connection_config.max_workers)
```
```

--------------------------------

### Measure Operation Execution Time

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

A context manager that logs the start of an operation and its total execution time in seconds. Handles exceptions gracefully.

```python
from confluence_markdown_exporter.utils.measure_time import measure

with measure("Export pages"):
    # Do work
    pass
# Logs: "Measuring: Export pages" ... "Completed in X.XXs"
```

--------------------------------

### Clear Page Title Registry

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Clears all registered page ID to title mappings. Use this between export runs to start with a clean registry.

```python
@staticmethod
def reset() -> None:
```

--------------------------------

### Get Export Statistics

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Retrieves the current export statistics instance. This instance tracks total pages, exported pages, skipped pages, and more.

```python
def get_stats() -> ExportStats:
```

--------------------------------

### Environment Variable Overrides

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/configuration.md

Demonstrates how to override configuration settings using environment variables with a specific format.

```bash
# String values
export CME_EXPORT__OUTPUT_PATH=/tmp/export
export CME_EXPORT__LOG_LEVEL=DEBUG

# Boolean values
export CME_EXPORT__SKIP_UNCHANGED=true
export CME_CONNECTION_CONFIG__VERIFY_SSL=false

# Number values
export CME_CONNECTION_CONFIG__MAX_WORKERS=5

# Array values (JSON)
export CME_CONNECTION_CONFIG__RETRY_STATUS_CODES='[429,502,503]'

# Run export with env overrides
CME_EXPORT__OUTPUT_PATH=/data CME_CONNECTION_CONFIG__MAX_WORKERS=10 cme spaces https://...
```

--------------------------------

### Space.export()

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-confluence.md

Exports all pages within a specific Confluence space to Markdown. This method fetches all pages starting from the space homepage and logs the page count.

```APIDOC
## Space.export()

### Description
Exports all pages within a specific Confluence space to Markdown. This method fetches all pages starting from the space homepage and logs the page count.

### Method
`export(self)`

### Parameters
None

### Returns
`None`

### Behavior
- Fetches all pages starting from the space homepage
- Calls `export_pages()` with all discovered pages
- Logs page count

### Example
```python
space = Space.from_key("MYSPACE", "https://company.atlassian.net")
space.export()  # Exports all pages in MYSPACE
```
```

--------------------------------

### Run Application with uv

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/CONTRIBUTING.md

Executes the confluence-markdown-exporter application using uv, passing any necessary commands. This is the recommended way to run the application during development.

```bash
# Run with uv (recommended)
uv run confluence-markdown-exporter [commands]
uv run cme [commands]
```

--------------------------------

### Python Test Function Example

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/CONTRIBUTING.md

Provides a basic structure for a Python test function using pytest. It includes Arrange, Act, and Assert steps for clarity.

```python
def test_feature_description() -> None:
    """Test that the feature works as expected."""
    # Arrange
    input_data = "test input"

    # Act
    result = function_under_test(input_data)

    # Assert
    assert result == expected_output
```

--------------------------------

### Configure Obsidian Wiki Links

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/configuration.md

Sets configuration options for generating Obsidian-compatible wiki links. This includes setting the href format for pages and attachments, and defining the output file path structure.

```bash
cme config set page_href=wiki attachment_href=wiki
cme config set page_path="{space_name}/{page_title}.md"
```

--------------------------------

### Reset Configuration to Defaults

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/configuration/index.md

Resets the entire configuration to factory defaults after a confirmation prompt. Use the `--yes` flag to skip the confirmation.

```sh
cme config reset
cme config reset --yes   # skip confirmation
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/CONTRIBUTING.md

Clones the confluence-markdown-exporter repository from GitHub and changes the current directory into the cloned repository.

```bash
git clone https://github.com/Spenhouet/confluence-markdown-exporter.git
cd confluence-markdown-exporter
```

--------------------------------

### Get Confluence Instance

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-api-clients.md

Obtains an authenticated Confluence API client for a given URL, caching clients by normalized URL. Handles authentication lookup and Cloud ID auto-fetching.

```python
def get_confluence_instance(url: str) -> ConfluenceApiSdk:
    # ... implementation details ...
    pass

client = get_confluence_instance("https://company.atlassian.net")
spaces = client.get_all_spaces()
```

--------------------------------

### Configuration File Structure

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/configuration.md

The main configuration file is structured into four key sections: auth, export, and connection_config. The auth section further breaks down into confluence and jira.

```yaml
auth:
  confluence: { URL: ApiDetails }
  jira: { URL: ApiDetails }
export: { ExportConfig }
connection_config: { ConnectionConfig }
```

--------------------------------

### Configure Authentication for Multiple Instances

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/README.md

Allows setting up credentials for multiple Confluence instances. The exporter matches credentials to instance URLs by hostname.

```bash
cme config edit auth.confluence
# Add credentials for https://company1.atlassian.net
# Add credentials for https://company2.atlassian.net
# Add credentials for https://confluence.company.com
```

--------------------------------

### Get Rich Console Instance

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Retrieves the Rich Console instance used for formatted output. This instance automatically detects CI environments and respects the NO_COLOR environment variable to disable colors when necessary.

```python
def get_rich_console() -> Console:
```

--------------------------------

### Get Thread-Local Confluence Client

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-api-clients.md

Retrieves or creates a thread-local Confluence client for a given URL. Each worker thread maintains its own client instance to ensure thread safety, as `requests.Session` is not thread-safe. This function caches clients per thread.

```python
def get_thread_confluence(base_url: str) -> ConfluenceApiSdk:
    # ... implementation details ...
    pass
```

```python
# In a worker thread
def export_page(page_id: int, base_url: str):
    client = get_thread_confluence(base_url)  # Thread-local
    page = client.get_page_by_id(page_id)
```

--------------------------------

### measure

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

A context manager for measuring the execution time of an operation. It logs the start of the measurement with a provided label and logs the elapsed time upon completion. It handles exceptions gracefully, ensuring that timing information is logged even if errors occur.

```APIDOC
## Function: measure

**Location:** `confluence_markdown_exporter/utils/measure_time.py`

Context manager for measuring execution time of an operation.

```python
@contextmanager
def measure(label: str) -> Generator[None, None, None]
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `label` | `str` | Description of the operation being measured |

**Returns:** Context manager

**Behavior:**
- Logs start with "Measuring: {label}"
- Logs end with elapsed time in seconds
- Handles exceptions gracefully

**Example:**

```python
from confluence_markdown_exporter.utils.measure_time import measure

with measure("Export pages"):
    # Do work
    pass
# Logs: "Measuring: Export pages" ... "Completed in X.XXs"
```
```

--------------------------------

### Get Jira API Client

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-api-clients.md

Obtains an authenticated Jira API client for a specified URL. This function caches clients by normalized URL in a thread-safe manner and can auto-convert Confluence gateway URLs to Jira gateway URLs. It may raise `AuthNotConfiguredError` if no valid Jira authentication is configured.

```python
def get_jira_instance(url: str) -> JiraApiSdk:
    # ... implementation details ...
    pass
```

```python
jira_client = get_jira_instance("https://company.atlassian.net")
projects = jira_client.get_all_projects()
```

--------------------------------

### Show Configuration File Path

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/configuration/index.md

Prints the absolute path to the configuration file. This is helpful for locating the file for backups or inspection, especially when `CME_CONFIG_PATH` is set.

```sh
cme config path
```

--------------------------------

### Default Application Configuration

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/configuration.md

The default JSON structure used to initialize the application's configuration when it first runs.

```json
{
  "auth": {
    "confluence": {},
    "jira": {}
  },
  "export": {
    "log_level": "INFO",
    "save_log_to_file": false,
    "output_path": "./",
    "page_path": "{space_name}/{homepage_title}/{ancestor_titles}/{page_title}.md",
    "attachment_path": "{space_name}/attachments/{attachment_file_id}{attachment_extension}",
    "page_href": "relative",
    "attachment_href": "relative",
    "include_document_title": false,
    "include_toc": true,
    "include_macro": "inline",
    "page_breadcrumbs": true,
    "skip_unchanged": true,
    "cleanup_stale": true,
    "attachments_export": "referenced",
    "image_captions": false,
    "comments_export": "none",
    "convert_status_badges": true,
    "convert_text_highlights": true,
    "convert_font_colors": true,
    "page_metadata_in_frontmatter": false,
    "confluence_url_in_frontmatter": "none",
    "page_properties_format": "frontmatter_and_table",
    "page_properties_report_format": "frozen",
    "filename_length": 255,
    "filename_encoding": "",
    "enable_jira_enrichment": false
  },
  "connection_config": {
    "max_workers": 20,
    "use_v2_api": false,
    "backoff_and_retry": true,
    "backoff_factor": 2,
    "max_backoff_seconds": 60,
    "max_backoff_retries": 5,
    "retry_status_codes": [413, 429, 502, 503, 504],
    "verify_ssl": true,
    "timeout": 30
  }
}
```

--------------------------------

### Project Structure Overview

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/CONTRIBUTING.md

Provides a visual representation of the project's directory and file organization.

```text
confluence-markdown-exporter/
├── .github/workflows/      # CI/CD workflows
├── confluence_markdown_exporter/  # Main package
│   ├── __init__.py
│   ├── main.py            # CLI entry point
│   ├── confluence.py      # Core functionality
│   ├── api_clients.py     # API integrations
│   └── utils/             # Utility modules
├── tests/                 # Test suite
├── .ruff.toml            # Ruff configuration
├── pyproject.toml        # Project configuration
├── uv.lock              # Dependency lock file
└── CONTRIBUTING.md       # This file
```

--------------------------------

### Reset Configuration to Defaults

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Resets configuration settings to their factory defaults. Can reset a specific key or the entire configuration.

```python
reset_to_defaults("export.log_level")
reset_to_defaults()
```

--------------------------------

### List Current Configuration

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/00_START_HERE.txt

Display the current configuration settings of the Confluence Markdown Exporter. This helps in verifying settings and troubleshooting.

```bash
cme config list
```

--------------------------------

### ApiClientFactory Initialization

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-api-clients.md

Initializes the ApiClientFactory with connection configuration, including retry, timeout, and SSL settings.

```python
class ApiClientFactory:
    """Factory for creating authenticated Confluence and Jira API clients with retry config."""
    
    def __init__(self, connection_config: AtlassianSdkConnectionConfig) -> None
```

--------------------------------

### Reset Configuration to Defaults

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/configuration.md

Resets the entire configuration or specific keys/sections back to their default values.

```bash
# Reset entire config to defaults
cme config reset
cme config reset --yes  # Skip confirmation

# Reset a single key
cme config reset export.log_level

# Reset a section
cme config reset export
cme config reset connection_config
```

--------------------------------

### Initialize Typer Application

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-main.md

Initializes the root Typer application instance for the Confluence Markdown Exporter. It configures rich markup for help text and intercepts authentication failures to prompt for configuration.

```python
app = _CmeTyper(
    rich_markup_mode="markdown",
    no_args_is_help=True,
    help="Export Confluence pages, spaces, or entire organizations to Markdown files."
)
```

--------------------------------

### Python API: Export Organization

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/README.md

Demonstrates exporting an entire Confluence organization using the Python API. Requires importing the Organization class.

```python
from confluence_markdown_exporter.confluence import Organization

# Export an organization
org = Organization.from_url("https://company.atlassian.net")
org.export()
```

--------------------------------

### Configure Exporter for Azure DevOps Wikis

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/configuration/target-systems.md

Sets export options for Azure DevOps Wikis, ensuring absolute attachment links and placing attachments in a .attachments/ folder. It also sanitizes and caps filenames to comply with ADO's restrictions.

```sh
cme config set \
  export.attachment_href=absolute \
  'export.attachment_path=.attachments/{attachment_file_id}{attachment_extension}' \
  'export.filename_encoding={" ":"-","\"":"%22","*":"%2A","-":"%2D",":":"%3A","<":"%3C",">":"%3E","?":"%3F","|":"%7C","\\":"_","#":"_"," ":"_"}' \
  export.filename_length=200
```

--------------------------------

### Create Organization from URL

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-confluence.md

Retrieves an Organization from a base URL, fetching the space list via the Confluence API and caching results. Automatically establishes an authenticated connection.

```python
org = Organization.from_url("https://company.atlassian.net")
print(f"Found {len(org.spaces)} space(s)")
```

--------------------------------

### Configure Self-Hosted with Context Path

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/README.md

Specifies how to configure the exporter for self-hosted Confluence instances that use a context path in their URL. Ensure the context path is included in the URL when setting authentication.

```bash
cme config set export.output_path=/data/export
# Config auth for: https://confluence.company.com/confluence
# (include the context path in the URL)
```

--------------------------------

### Initialize Lock File

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Initializes the lock file at the beginning of an export process. It loads an existing lock file or creates a new one and sets up a thread-safe lock.

```python
@staticmethod
def init() -> None
```

--------------------------------

### Define List Configuration Command

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-config.md

Defines the 'list_config' command to display the current configuration. Supports outputting in YAML (default) or JSON format. Secret values are shown in plaintext.

```python
def list_config(
    output: Annotated[
        str,
        typer.Option(
            "--output", "-o",
            help="Output format. Accepted values: `yaml` (default) or `json`.",
            metavar="FORMAT",
        ),
    ] = "yaml",
) -> None
```

--------------------------------

### Save Content to File

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Saves string or binary content to a specified file path, creating parent directories as needed. Writes strings as UTF-8 and logs file size upon success.

```python
from pathlib import Path
from confluence_markdown_exporter.utils.export import save_file

save_file(Path("./output/page.md"), "# My Page\n\nContent here")
save_file(Path("./output/image.png"), binary_data)
```

--------------------------------

### Set Configuration Values

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/docs/configuration/index.md

Sets one or more configuration key-value pairs directly. Values are parsed as JSON where possible (e.g., booleans, numbers), otherwise treated as plain strings.

```sh
cme config set export.log_level=DEBUG
cme config set export.output_path=/tmp/export
cme config set export.skip_unchanged=false
```

--------------------------------

### Set Export Output Path

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/00_START_HERE.txt

Configure the directory where exported files will be saved. Ensure this path is accessible and has the necessary write permissions.

```bash
cme config set export.output_path=/data/export
```

--------------------------------

### Run Full Test Suite Before PR

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/CONTRIBUTING.md

Executes all code quality checks and tests before submitting a pull request. This ensures that the code adheres to project standards and passes all tests.

```bash
uv run ruff check
uv run pytest
uv build --no-sources  # Test build
```

--------------------------------

### Confluence Markdown Exporter CLI Commands

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/INDEX.md

Overview of the main CLI commands available for exporting pages, spaces, and organizations, as well as managing configuration and diagnostics.

```text
Export commands: pages, spaces, orgs
Configuration commands: list, get, set, edit, reset
Diagnostic commands: version, bugreport
```

--------------------------------

### LockfileManager.init

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Initializes the lock file at the beginning of an export process. This static method loads an existing lock file or creates a new one if it doesn't exist, and also sets up a thread-safe lock for managing concurrent access.

```APIDOC
## Static Method: init

### Description
Initialize the lock file at the start of an export run.

### Returns
None

### Behavior
- Loads existing lock file or creates new
- Initializes thread-safe lock
```

--------------------------------

### Set Application Setting

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Updates a single configuration value in the config file using dot notation. Validates the value against its type schema and performs an atomic write.

```python
set_setting("export.log_level", "DEBUG")
set_setting("connection_config.max_workers", 5)
set_setting("export.skip_unchanged", False)
```

--------------------------------

### Create Jira API Client

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-api-clients.md

Creates an authenticated Jira API client using the provided URL and authentication details. Supports the same authentication methods as Confluence client creation. Validates the connection by fetching all projects.

```python
def create_jira(self, url: str, auth: ApiDetails) -> JiraApiSdk
```

--------------------------------

### set_setting

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-utilities.md

Sets a single configuration value using dot-notation for keys. This function updates the configuration file on disk, validates the value against its type schema, and performs an atomic write. It throws `ValueError` for invalid keys or values, and `KeyError` if the key path does not exist.

```APIDOC
## Function: set_setting

**Location:** `confluence_markdown_exporter/utils/app_data_store.py`

Set a single configuration value.

```python
def set_setting(key: str, value: object) -> None
```

**Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `key` | `str` | Dot-notation config key (e.g., `export.log_level`) |
| `value` | `object` | Value to set |

**Behavior:**
- Updates the config file on disk
- Uses dot notation to navigate nested structure
- Validates value against type schema
- Atomically writes to file

**Throws:**
- `ValueError` — if key is invalid or value fails validation
- `KeyError` — if key path doesn't exist

**Example:**

```python
set_setting("export.log_level", "DEBUG")
set_setting("connection_config.max_workers", 5)
set_setting("export.skip_unchanged", False)
```
```

--------------------------------

### Create Space from URL

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/api-reference-confluence.md

Instantiate a Space object by providing a Confluence space URL. The method automatically handles URL parsing and authentication.

```python
space = Space.from_url("https://company.atlassian.net/wiki/spaces/MYSPACE")
space.export()
```

--------------------------------

### Configure Self-Hosted Server Authentication

Source: https://github.com/spenhouet/confluence-markdown-exporter/blob/main/_autodocs/README.md

Sets up authentication for self-hosted Confluence instances using a Personal Access Token (PAT). Leave the username blank when prompted.

```bash
cme config edit auth.confluence
# Enter: https://confluence.company.com
# Leave username blank
# Enter: Personal Access Token
```