md2confluence 1.1.1__py3-none-any.whl

md2confluence-1.1.1.dist-info/METADATA

@@ -0,0 +1,216 @@
+Metadata-Version: 2.4
+Name: md2confluence
+Version: 1.1.1
+Summary: Sync Markdown documentation to Confluence Cloud
+License: MIT
+Project-URL: Repository, https://pypi.org/project/md2confluence/
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.32.0
+Dynamic: license-file
+
+# md2confluence
+
+<p align="center">
+  <img src="img/MD2C.png" alt="md2confluence" width="400">
+</p>
+
+[![Python](https://img.shields.io/badge/Python-3.9+-blue?style=flat-square&logo=python)](https://www.python.org/)
+[![PyPI](https://img.shields.io/pypi/v/md2confluence?style=flat-square&logo=pypi)](https://pypi.org/project/md2confluence/)
+[![Version](https://img.shields.io/badge/version-1.1.1-green?style=flat-square)](https://pypi.org/project/md2confluence/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+
+A Python tool to sync Markdown documentation to Confluence Cloud.
+
+## Features
+
+- **Markdown to Confluence conversion** - Headers, lists, tables, code blocks, info panels, task lists, and more
+- **Front-matter support** - Per-document settings via YAML/JSON front-matter
+- **Emoji shortcodes** - `:smile:` → 😄, `:rocket:` → 🚀
+- **Subscript/superscript** - `H~2~O` → H₂O, `x^2^` → x²
+- **Page labels** - Set Confluence labels via front-matter tags
+- **Image handling** - Automatically uploads local images as attachments
+- **Local output mode** - Generate Confluence Storage Format files without API calls
+- **Config-driven** - Define document mappings in a simple config file
+- **Dry-run mode** - Preview changes before syncing
+- **Retry logic** - Exponential backoff for transient failures
+- **Rate limiting** - Avoid API throttling
+
+## Installation
+
+```bash
+# From PyPI (recommended)
+pip install md2confluence
+
+# For development
+git clone <repository-url>
+cd md2confluence
+pip install -e .
+```
+
+## Dependencies
+
+- Python 3.9+
+- `requests` library (installed automatically)
+
+## Quick Start
+
+1. **Create an API token** (see [Authentication](#authentication) below)
+
+2. **Set environment variables:**
+
+   ```bash
+   export CONFLUENCE_API_TOKEN="your-api-token"
+   export CONFLUENCE_USER_EMAIL="your-email@example.com"
+   ```
+
+3. **Create a config file** (`.confluence-sync.conf`):
+
+   ```bash
+   CONFLUENCE_BASE_URL="https://your-domain.atlassian.net/wiki"
+   CONFLUENCE_SPACE_KEY="DOCS"
+   CONFLUENCE_TECH_PARENT_ID="123456789"
+   
+   # Document mappings: "Title|path/to/file.md|parent_page_id"
+   CONFLUENCE_DOC_README="README|README.md|${CONFLUENCE_TECH_PARENT_ID}"
+   ```
+
+4. **Run the sync:**
+
+   ```bash
+   md2confluence
+   ```
+
+## Usage
+
+```bash
+# Sync all configured documents
+md2confluence
+
+# Dry-run (preview without changes)
+md2confluence --dry-run
+
+# List configured documents
+md2confluence --list
+
+# Verify config and connectivity
+md2confluence --verify
+
+# Sync a single document
+md2confluence --single "Page Title" path/to/doc.md parent_page_id
+
+# Convert markdown to Confluence format (stdout)
+echo "# Hello" | md2confluence --stdin
+
+# Local output (generate .csf files without API calls)
+md2confluence --local ./output
+```
+
+## Authentication
+
+### Creating an API Token
+
+1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
+2. Click **Create API token**
+3. Enter a label (e.g., "md2confluence") and click **Create**
+4. Copy the token immediately (you won't see it again)
+
+### Required Permissions
+
+The user account associated with the API token needs:
+
+- **Space permissions:**
+  - View space
+  - Add pages
+  - Update pages
+  - Add attachments
+
+- **Page permissions:**
+  - View, Edit on target pages/parent pages
+
+For organization-managed accounts, ensure the user has appropriate Confluence access in your Atlassian admin settings.
+
+### Auth Modes
+
+| Mode   | Variables Required                               | Use Case                       |
+| ------ | ------------------------------------------------ | ------------------------------ |
+| Basic  | `CONFLUENCE_USER_EMAIL` + `CONFLUENCE_API_TOKEN` | Standard Atlassian Cloud       |
+| Bearer | `CONFLUENCE_API_TOKEN` only                      | OAuth tokens, service accounts |
+
+Auth mode is auto-detected based on whether `CONFLUENCE_USER_EMAIL` is set.
+
+## Configuration
+
+See `confluence-sync.conf.example` for all available options.
+
+### Document Mappings
+
+Define documents to sync using `CONFLUENCE_DOC_*` variables:
+
+```bash
+CONFLUENCE_DOC_MYPAGE="Page Title|path/to/file.md|parent_page_id"
+```
+
+### Edge Case Handling
+
+| Option                             | Values                   | Default     |
+| ---------------------------------- | ------------------------ | ----------- |
+| `CONFLUENCE_MISSING_FILE_BEHAVIOR` | skip, fail               | skip        |
+| `CONFLUENCE_IMAGE_FAILURE_BEHAVIOR`| placeholder, skip, fail  | placeholder |
+| `CONFLUENCE_TITLE_SPECIAL_CHARS`   | sanitize, encode, fail   | sanitize    |
+
+## Front-Matter
+
+Documents can include YAML or JSON front-matter to override settings:
+
+```yaml
+---
+title: Custom Page Title
+tags: [documentation, api, v2]
+space: DOCS
+parent_id: "123456789"
+add_disclaimer: false
+max_image_width: 600
+synchronized: true
+---
+
+# Document content starts here
+```
+
+### Supported Front-Matter Fields
+
+| Field                    | Type    | Description                    |
+| ------------------------ | ------- | ------------------------------ |
+| `title`                  | string  | Override page title            |
+| `tags` / `labels`        | array   | Confluence page labels         |
+| `space` / `space_key`    | string  | Target Confluence space        |
+| `parent_id` / `parent`   | string  | Parent page ID                 |
+| `add_disclaimer`         | boolean | Add auto-generated notice      |
+| `max_image_width`        | integer | Image width constraint (px)    |
+| `image_failure_behavior` | string  | Override error handling        |
+| `title_special_chars`    | string  | Override title sanitization    |
+| `synchronized` / `sync`  | boolean | Set `false` to skip document   |
+
+Front-matter settings take precedence over config file and environment variables.
+
+## Markdown Support
+
+- Headers (h1-h6)
+- Bold, italic, strikethrough
+- Subscript (`~text~`) and superscript (`^text^`)
+- Ordered and unordered lists
+- Nested lists
+- Task lists (checkboxes)
+- Tables
+- Fenced code blocks with syntax highlighting
+- Inline code
+- Links (inline and reference-style)
+- Images (uploaded as attachments)
+- Blockquotes → Confluence panels (Note/Warning/Tip/Info)
+- Horizontal rules
+- Emoji shortcodes (`:smile:`, `:rocket:`, `:thumbsup:`, etc.)
+
+## License
+
+MIT

md2confluence-1.1.1.dist-info/RECORD

@@ -0,0 +1,7 @@
+md2confluence.py,sha256=GRFMjipDVQdvaRFR8O5dRlRNXpDbucJ2q7K3w43ilUI,71263
+md2confluence-1.1.1.dist-info/licenses/LICENSE,sha256=KT0oY-DP5eupdY4_dK2abw4fig4GX4KNtNwx_I1NvvY,1117
+md2confluence-1.1.1.dist-info/METADATA,sha256=WGfwIBVGx7XG4oh703OsamSwz_4k0Rbsz2srzGnJ3Qc,6664
+md2confluence-1.1.1.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+md2confluence-1.1.1.dist-info/entry_points.txt,sha256=PCZ3g9f6QyfiSwW2-YQtP6YRWg3keo--PjhvB6lDa74,53
+md2confluence-1.1.1.dist-info/top_level.txt,sha256=N6pqie-mz5bhsFju6C_sQUa3DZymrMBevSkpDleH1zo,14
+md2confluence-1.1.1.dist-info/RECORD,,

md2confluence-1.1.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

md2confluence-1.1.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+md2confluence = md2confluence:main

md2confluence-1.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cody Lusk <cody.lusk@bibliocommons.com>, BiblioCommons Corp.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

md2confluence-1.1.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+md2confluence