mkdocs2confluence 0.5.25__tar.gz → 0.5.26__tar.gz

mkdocs2confluence-0.5.26/PKG-INFO

@@ -0,0 +1,380 @@
+Metadata-Version: 2.4
+Name: mkdocs2confluence
+Version: 0.5.26
+Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
+Author: Anders Hybertz
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/jeckyl2010/mkdocs2confluence
+Project-URL: Repository, https://github.com/jeckyl2010/mkdocs2confluence
+Project-URL: Issues, https://github.com/jeckyl2010/mkdocs2confluence/issues
+Project-URL: Changelog, https://github.com/jeckyl2010/mkdocs2confluence/releases
+Keywords: mkdocs,confluence,atlassian,documentation,publishing,material-for-mkdocs,markdown,storage-format
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: tinycss2>=1.5.1
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: bandit; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# mk2conf — MkDocs to Confluence
+
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Latest Release](https://img.shields.io/github/v/release/jeckyl2010/mkdocs2confluence)](https://github.com/jeckyl2010/mkdocs2confluence/releases/latest)
+[![CI](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml)
+[![Release](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml)
+[![codecov](https://codecov.io/gh/jeckyl2010/mkdocs2confluence/graph/badge.svg)](https://codecov.io/gh/jeckyl2010/mkdocs2confluence)
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![mypy](https://img.shields.io/badge/type--checked-mypy-blue.svg)](https://mypy-lang.org/)
+[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+
+A Python CLI tool that compiles MkDocs-flavoured Markdown into native Confluence storage XHTML and publishes it to Confluence.
+
+It is a **compiler/transpiler**, not an HTML converter — every Markdown construct is mapped to the equivalent native Confluence macro or element, so pages look and behave like hand-authored Confluence content.
+
+---
+
+## Architecture
+
+```mermaid
+flowchart LR
+    subgraph Input
+        A[mkdocs.yml\nconf config + nav]
+        B[Markdown files\n+ assets]
+    end
+
+    subgraph Loader
+        C[Config loader\nMkDocsConfig\nConfluenceConfig]
+        D[Nav resolver\nNavNode tree]
+    end
+
+    subgraph Preprocess
+        E[Front matter\nIncludes / snippets\nAbbreviations\nIcon shortcodes\nLink definitions]
+    end
+
+    subgraph IR
+        F[Markdown → IR\nDocument node tree]
+    end
+
+    subgraph Transforms
+        G[Mermaid → PNG\nInternal links\nAsset paths\nAbbrev expansion\nEdit link\nCSS styles]
+    end
+
+    subgraph Emitter
+        H[IR → Confluence\nstorage XHTML]
+    end
+
+    subgraph Publisher
+        I[Plan\ncreate / update / skip\nper nav node]
+        J[Execute\nPages · Folders\nStub pages · Assets]
+        K[Confluence Cloud\nREST API v2]
+    end
+
+    A --> C
+    A --> D
+    B --> E
+    C --> E
+    D --> I
+    E --> F
+    F --> G
+    G --> H
+    H --> I
+    I --> J
+    J --> K
+```
+
+Each stage is a separate Python module under `src/mkdocs_to_confluence/`. The **plan** phase makes all API read calls (find existing pages); the **execute** phase makes all write calls, ensuring parents always exist before children.
+
+---
+
+## Installation
+
+Requires Python 3.12+.
+
+**From PyPI:**
+
+```bash
+pip install mkdocs2confluence
+```
+
+Or with `pipx` for an isolated install:
+
+```bash
+pipx install mkdocs2confluence
+```
+
+**From source** (see [Setup.md](Setup.md)):
+
+```bash
+git clone https://github.com/jeckyl2010/mkdocs2confluence.git
+cd mkdocs2confluence
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick start
+
+```bash
+# Print Confluence storage XHTML to stdout
+mk2conf preview --config mkdocs.yml --page index.md
+
+# Open a browser-friendly HTML preview
+mk2conf preview --config mkdocs.yml --page index.md --html --out /tmp/preview.html
+
+# Dry-run: see what would be published without touching Confluence
+mk2conf publish --config mkdocs.yml --dry-run
+
+# Publish all nav pages to Confluence
+CONFLUENCE_API_TOKEN=your_token mk2conf publish --config mkdocs.yml
+```
+
+---
+
+## Commands
+
+### `mk2conf preview`
+
+Compile a single page and inspect the output — no network connection required.
+
+```
+mk2conf preview [--config PATH] --page PATH [--out FILE] [--html]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config PATH` | `./mkdocs.yml` | Path to your `mkdocs.yml` |
+| `--page PATH` | *(required)* | Relative path to the Markdown file |
+| `--out FILE` | stdout | Write output to a file |
+| `--html` | off | Render macros as styled HTML for local browser review |
+
+The `--html` flag renders Confluence macros as visual HTML panels so you can review a page locally without a Confluence instance. It is for review only — the actual storage XHTML is always the `--html`-free output.
+
+---
+
+### `mk2conf publish`
+
+Compile all pages listed in `nav:` and publish them to Confluence Cloud.
+
+```
+mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config PATH` | `./mkdocs.yml` | Path to your `mkdocs.yml` |
+| `--page PATH` | *(all nav pages)* | Publish a single page only |
+| `--section PATH` | *(whole nav)* | Publish only a nav subtree (e.g. `Guide` or `Guide/Setup`) |
+| `--dry-run` | off | Print the publish plan without making any API calls |
+| `--report FILE` | *(none)* | Write a JSON publish report to `FILE` |
+
+#### Configuration
+
+Add a `confluence:` block to your `mkdocs.yml`:
+
+```yaml
+confluence:
+  base_url: https://yourorg.atlassian.net
+  space_key: TECH
+  email: user@example.com
+  token: !ENV CONFLUENCE_API_TOKEN   # never hardcode the token
+  parent_page_id: "123456"           # optional root page
+  mermaid_render: kroki              # optional: "kroki" (default), "kroki:https://your-kroki" or "none"
+  full_width: true                   # optional: publish pages in full-width layout (default: true)
+```
+
+The API token is read from (in priority order):
+1. The `token:` field in `mkdocs.yml` (typically via `!ENV CONFLUENCE_API_TOKEN`)
+2. `CONFLUENCE_API_TOKEN` environment variable
+3. `MK2CONF_TOKEN` environment variable
+
+#### Publish rules
+
+- **Only pages in `nav:` are published** — the nav is the publish gate. Pages not listed in the nav are never touched, keeping drafts and WIP content private.
+- Pages with `ready: false` in their YAML front matter are **skipped**, even if listed in the nav.
+- Section nodes (nav groups without a page) become empty parent pages in Confluence, mirroring the nav hierarchy.
+- All locally linked assets are uploaded as Confluence page attachments automatically.
+
+#### Mermaid rendering
+
+| `mermaid_render` value | Behaviour |
+|---|---|
+| `kroki` *(default)* | Render via `https://kroki.io`. PNGs are cached in `~/.cache/mk2conf/mermaid/`. |
+| `kroki:https://your-kroki` | Render via a self-hosted Kroki instance. |
+| `none` | Skip rendering — fall back to a `code` macro labelled `mermaid`. |
+
+If Kroki is unreachable the run continues, falling back to the `code` macro for affected diagrams.
+
+#### Styling from extra.css
+
+If your `mkdocs.yml` has an `extra_css:` list, mk2conf reads those files and applies a whitelisted set of CSS properties as inline `style="..."` attributes in the Confluence output.
+
+| Selector | Applied to |
+|---|---|
+| `th`, `thead th` | Table header cells |
+| `td` | Table body cells |
+| `h1` – `h6` | Headings |
+| `code` (not `pre code`) | Inline code spans |
+
+Supported properties: `background-color`, `color`, `font-weight`, `font-style`, `font-size`, `text-align`, `border`.
+
+CSS custom properties (`var(--name)`) are resolved automatically, including chained variables and `var(--name, fallback)` syntax.
+
+**Works best with simple, flat CSS.** Complex Material for MkDocs theme overrides — compound selectors (`.md-typeset table:not([class]) thead th`), `color-mix()`, `@media` blocks, `:has()` etc. — are silently skipped. For these, maintain a small separate file:
+
+```css
+/* confluence-overrides.css */
+:root { --primary: #d20014; }
+th  { background-color: var(--primary); color: white; font-weight: 600; }
+h1, h2, h3 { color: var(--primary); }
+code { background-color: #f5f5f5; }
+```
+
+```yaml
+extra_css:
+  - stylesheets/extra.css             # full Material theme
+  - stylesheets/confluence-overrides.css  # simple Confluence-targeted styles
+```
+
+---
+
+## Supported Markdown features
+
+### Block elements
+
+| Feature | Confluence output |
+|---|---|
+| ATX headings `#` – `######` | `<h1>` – `<h6>` |
+| Paragraphs | `<p>` |
+| Fenced code blocks | `code` macro with language, title, and line numbers |
+| Bullet lists | `<ul>/<li>` |
+| Ordered lists | `<ol>/<li>` |
+| Task lists `- [x]` / `- [ ]` | Native `<ac:task-list>` / `<ac:task>` macros |
+| Tables (GFM pipe syntax) | `<table>` with header and column alignment |
+| Blockquotes | `<blockquote>` |
+| Horizontal rules `---` | `<hr/>` |
+
+### Inline elements
+
+| Feature | Confluence output |
+|---|---|
+| `**bold**` / `__bold__` | `<strong>` |
+| `*italic*` | `<em>` |
+| `~~strikethrough~~` | `<s>` |
+| `` `inline code` `` | `<code>` |
+| `[text](url)` | `<a href="...">` |
+| `[text](file.pdf)` | `<ac:link><ri:attachment .../>` (uploaded as attachment) |
+| `![alt](src)` | `<ac:image>` with `<ri:attachment>` (local) or `<ri:url>` (remote) |
+| `![alt](src){ width="400" }` | `<ac:image ac:width="400">` — also supports `height` and `align` |
+| `<br>` / `<br/>` | `<br />` |
+| `<sub>` / `<sup>` / `<u>` / `<small>` | Direct XHTML passthrough |
+| `<mark>text</mark>` | `<span style="background-color: yellow;">` |
+| `<kbd>text</kbd>` | `<code>` |
+| `++ctrl+alt+del++` | `<code>Ctrl</code>+<code>Alt</code>+<code>Del</code>` (pymdownx.keys) |
+| `<s>text</s>` / `<del>text</del>` | `<span style="text-decoration: line-through;">` |
+
+### MkDocs / Material extensions
+
+| Feature | Confluence output |
+|---|---|
+| `--8<--` file includes | Resolved before parsing |
+| Admonitions `!!! type "title"` | `info` / `tip` / `warning` / `note` macro |
+| Danger admonitions (`danger`, `error`, `bug`) | Red `panel` macro with 🚨 prefix |
+| Collapsible admonitions `??? type` | `expand` macro |
+| Content tabs `=== "Label"` | `expand` macros (one per tab) |
+| Details blocks `??? "title"` | `expand` macro |
+| Footnotes `[^1]` | Superscript anchor links + *Footnotes* section at page bottom |
+| Mermaid diagrams | PNG via Kroki, uploaded as attachment (`<ac:image ac:align="center">`) |
+| Internal links `[text](page.md)` | Native Confluence page link; `#fragment` anchors preserved |
+| `awesome-pages` nav (`.pages` files) | Fully supported |
+| Edit link banner | `info` macro linking back to source in GitHub/GitLab |
+
+### YAML front matter → Page Properties
+
+A YAML front matter block is converted to a Confluence **Page Properties** macro, making it queryable via the Page Properties Report macro.
+
+```yaml
+---
+title: "Architecture Proposal – IAM"
+subtitle: "Hybrid Identity Hub"
+documentId: AP-IAM-2026
+version: "0.1"
+lastUpdated: 2026-01-12
+author: "Anders Hybertz"
+tags: [architecture, iam]
+ready: true
+---
+```
+
+| Field | Notes |
+|---|---|
+| `title` | Used as the Confluence page title on publish |
+| `subtitle` | Rendered as italic lead paragraph above the properties table |
+| `tags` | Also applied as Confluence page labels |
+| `ready` | `true` → ✅ Ready · `false` → 📝 Draft (skips publish) |
+| `source` | Stripped (internal tooling field) |
+| *other fields* | Title-cased key, value stringified |
+
+If `repo_url` + `edit_uri` are set in `mkdocs.yml`, an **Edit Source** row links to the source file. If `site_url` is set, a **Published Page** row links to the rendered MkDocs site.
+
+### Abbreviation expansion
+
+MkDocs abbreviation definitions (`*[ABBR]: Full term`) are expanded inline — Confluence has no native `<abbr>` tooltip. The **first occurrence** in body text is expanded as `IAM (Identity and Access Management)`; subsequent occurrences are left as-is. Abbreviations that only appear in headings or code are collected into an auto-appended **Glossary** section.
+
+### Graceful degradation
+
+Any unrecognised block is preserved as a visible `warning` macro — no content is silently lost.
+
+`<div class="grid" markdown>` (Material grid cards) has no Confluence equivalent. The wrapper is stripped; inner admonitions render sequentially.
+
+---
+
+## Known limitations
+
+| Feature | Behaviour |
+|---|---|
+| **Admonition styling** | Native macros (`tip`, `info`, `warning`, `note`) use Confluence's fixed theme styling — no custom header/body colours. |
+| **Abbreviation tooltips** | No native tooltip support. First occurrence expanded inline; remainder left as-is. |
+| **Grid cards** | Wrapper stripped; inner admonitions rendered individually. |
+| **Page width** | Confluence defaults to a narrow fixed-width column. mk2conf publishes with `fullWidth: true` by default (configurable). |
+| **Page ordering** | Confluence sorts child pages alphabetically. The v2 REST API has no write endpoint for child ordering; nav order cannot be enforced. |
+| **Code language aliases** | Pygments short aliases (`py`, `js`, `yml`, `ts`, `sh`) are passed through as-is; Confluence requires full language names for syntax highlighting. |
+
+---
+
+## Roadmap
+
+- [ ] **Delete orphaned pages** — detect and remove Confluence pages that were previously published but have since been removed from `nav:`.
+
+---
+
+## Development
+
+See [Setup.md](Setup.md) for environment setup.
+
+```bash
+pytest              # run tests
+ruff check src      # lint
+mypy src            # type-check
+bandit -r src -ll   # security scan
+```

{mkdocs2confluence-0.5.25 → mkdocs2confluence-0.5.26}/pyproject.toml

@@ -1,16 +1,46 @@
 [project]
 name = "mkdocs2confluence"
-version = "0.5.25"
-description = "Compile MkDocs markdown to Confluence storage format"
+version = "0.5.26"
+description = "Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more"
+readme = "README.md"
 license = { text = "GPL-3.0-or-later" }
 authors = [{ name = "Anders Hybertz" }]
 requires-python = ">=3.12"
+keywords = [
+  "mkdocs",
+  "confluence",
+  "atlassian",
+  "documentation",
+  "publishing",
+  "material-for-mkdocs",
+  "markdown",
+  "storage-format",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Documentation",
+  "Topic :: Software Development :: Documentation",
+  "Topic :: Text Processing :: Markup",
+  "Topic :: Utilities",
+]
 dependencies = [
   "PyYAML>=6.0.3",
   "httpx>=0.27",
   "tinycss2>=1.5.1",
 ]
 
+[project.urls]
+Homepage = "https://github.com/jeckyl2010/mkdocs2confluence"
+Repository = "https://github.com/jeckyl2010/mkdocs2confluence"
+Issues = "https://github.com/jeckyl2010/mkdocs2confluence/issues"
+Changelog = "https://github.com/jeckyl2010/mkdocs2confluence/releases"
+
 [project.optional-dependencies]
 dev = [
   "pytest",

mkdocs2confluence-0.5.26/src/mkdocs2confluence.egg-info/PKG-INFO

@@ -0,0 +1,380 @@
+Metadata-Version: 2.4
+Name: mkdocs2confluence
+Version: 0.5.26
+Summary: Publish MkDocs Material pages to Confluence Cloud — admonitions, Mermaid diagrams, tabs, page properties and more
+Author: Anders Hybertz
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/jeckyl2010/mkdocs2confluence
+Project-URL: Repository, https://github.com/jeckyl2010/mkdocs2confluence
+Project-URL: Issues, https://github.com/jeckyl2010/mkdocs2confluence/issues
+Project-URL: Changelog, https://github.com/jeckyl2010/mkdocs2confluence/releases
+Keywords: mkdocs,confluence,atlassian,documentation,publishing,material-for-mkdocs,markdown,storage-format
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup
+Classifier: Topic :: Utilities
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: httpx>=0.27
+Requires-Dist: tinycss2>=1.5.1
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: types-PyYAML; extra == "dev"
+Requires-Dist: bandit; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Dynamic: license-file
+
+# mk2conf — MkDocs to Confluence
+
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![Latest Release](https://img.shields.io/github/v/release/jeckyl2010/mkdocs2confluence)](https://github.com/jeckyl2010/mkdocs2confluence/releases/latest)
+[![CI](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml)
+[![Release](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml)
+[![codecov](https://codecov.io/gh/jeckyl2010/mkdocs2confluence/graph/badge.svg)](https://codecov.io/gh/jeckyl2010/mkdocs2confluence)
+[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
+[![mypy](https://img.shields.io/badge/type--checked-mypy-blue.svg)](https://mypy-lang.org/)
+[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)
+
+A Python CLI tool that compiles MkDocs-flavoured Markdown into native Confluence storage XHTML and publishes it to Confluence.
+
+It is a **compiler/transpiler**, not an HTML converter — every Markdown construct is mapped to the equivalent native Confluence macro or element, so pages look and behave like hand-authored Confluence content.
+
+---
+
+## Architecture
+
+```mermaid
+flowchart LR
+    subgraph Input
+        A[mkdocs.yml\nconf config + nav]
+        B[Markdown files\n+ assets]
+    end
+
+    subgraph Loader
+        C[Config loader\nMkDocsConfig\nConfluenceConfig]
+        D[Nav resolver\nNavNode tree]
+    end
+
+    subgraph Preprocess
+        E[Front matter\nIncludes / snippets\nAbbreviations\nIcon shortcodes\nLink definitions]
+    end
+
+    subgraph IR
+        F[Markdown → IR\nDocument node tree]
+    end
+
+    subgraph Transforms
+        G[Mermaid → PNG\nInternal links\nAsset paths\nAbbrev expansion\nEdit link\nCSS styles]
+    end
+
+    subgraph Emitter
+        H[IR → Confluence\nstorage XHTML]
+    end
+
+    subgraph Publisher
+        I[Plan\ncreate / update / skip\nper nav node]
+        J[Execute\nPages · Folders\nStub pages · Assets]
+        K[Confluence Cloud\nREST API v2]
+    end
+
+    A --> C
+    A --> D
+    B --> E
+    C --> E
+    D --> I
+    E --> F
+    F --> G
+    G --> H
+    H --> I
+    I --> J
+    J --> K
+```
+
+Each stage is a separate Python module under `src/mkdocs_to_confluence/`. The **plan** phase makes all API read calls (find existing pages); the **execute** phase makes all write calls, ensuring parents always exist before children.
+
+---
+
+## Installation
+
+Requires Python 3.12+.
+
+**From PyPI:**
+
+```bash
+pip install mkdocs2confluence
+```
+
+Or with `pipx` for an isolated install:
+
+```bash
+pipx install mkdocs2confluence
+```
+
+**From source** (see [Setup.md](Setup.md)):
+
+```bash
+git clone https://github.com/jeckyl2010/mkdocs2confluence.git
+cd mkdocs2confluence
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick start
+
+```bash
+# Print Confluence storage XHTML to stdout
+mk2conf preview --config mkdocs.yml --page index.md
+
+# Open a browser-friendly HTML preview
+mk2conf preview --config mkdocs.yml --page index.md --html --out /tmp/preview.html
+
+# Dry-run: see what would be published without touching Confluence
+mk2conf publish --config mkdocs.yml --dry-run
+
+# Publish all nav pages to Confluence
+CONFLUENCE_API_TOKEN=your_token mk2conf publish --config mkdocs.yml
+```
+
+---
+
+## Commands
+
+### `mk2conf preview`
+
+Compile a single page and inspect the output — no network connection required.
+
+```
+mk2conf preview [--config PATH] --page PATH [--out FILE] [--html]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config PATH` | `./mkdocs.yml` | Path to your `mkdocs.yml` |
+| `--page PATH` | *(required)* | Relative path to the Markdown file |
+| `--out FILE` | stdout | Write output to a file |
+| `--html` | off | Render macros as styled HTML for local browser review |
+
+The `--html` flag renders Confluence macros as visual HTML panels so you can review a page locally without a Confluence instance. It is for review only — the actual storage XHTML is always the `--html`-free output.
+
+---
+
+### `mk2conf publish`
+
+Compile all pages listed in `nav:` and publish them to Confluence Cloud.
+
+```
+mk2conf publish [--config PATH] [--page PATH] [--section PATH] [--dry-run] [--report FILE]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--config PATH` | `./mkdocs.yml` | Path to your `mkdocs.yml` |
+| `--page PATH` | *(all nav pages)* | Publish a single page only |
+| `--section PATH` | *(whole nav)* | Publish only a nav subtree (e.g. `Guide` or `Guide/Setup`) |
+| `--dry-run` | off | Print the publish plan without making any API calls |
+| `--report FILE` | *(none)* | Write a JSON publish report to `FILE` |
+
+#### Configuration
+
+Add a `confluence:` block to your `mkdocs.yml`:
+
+```yaml
+confluence:
+  base_url: https://yourorg.atlassian.net
+  space_key: TECH
+  email: user@example.com
+  token: !ENV CONFLUENCE_API_TOKEN   # never hardcode the token
+  parent_page_id: "123456"           # optional root page
+  mermaid_render: kroki              # optional: "kroki" (default), "kroki:https://your-kroki" or "none"
+  full_width: true                   # optional: publish pages in full-width layout (default: true)
+```
+
+The API token is read from (in priority order):
+1. The `token:` field in `mkdocs.yml` (typically via `!ENV CONFLUENCE_API_TOKEN`)
+2. `CONFLUENCE_API_TOKEN` environment variable
+3. `MK2CONF_TOKEN` environment variable
+
+#### Publish rules
+
+- **Only pages in `nav:` are published** — the nav is the publish gate. Pages not listed in the nav are never touched, keeping drafts and WIP content private.
+- Pages with `ready: false` in their YAML front matter are **skipped**, even if listed in the nav.
+- Section nodes (nav groups without a page) become empty parent pages in Confluence, mirroring the nav hierarchy.
+- All locally linked assets are uploaded as Confluence page attachments automatically.
+
+#### Mermaid rendering
+
+| `mermaid_render` value | Behaviour |
+|---|---|
+| `kroki` *(default)* | Render via `https://kroki.io`. PNGs are cached in `~/.cache/mk2conf/mermaid/`. |
+| `kroki:https://your-kroki` | Render via a self-hosted Kroki instance. |
+| `none` | Skip rendering — fall back to a `code` macro labelled `mermaid`. |
+
+If Kroki is unreachable the run continues, falling back to the `code` macro for affected diagrams.
+
+#### Styling from extra.css
+
+If your `mkdocs.yml` has an `extra_css:` list, mk2conf reads those files and applies a whitelisted set of CSS properties as inline `style="..."` attributes in the Confluence output.
+
+| Selector | Applied to |
+|---|---|
+| `th`, `thead th` | Table header cells |
+| `td` | Table body cells |
+| `h1` – `h6` | Headings |
+| `code` (not `pre code`) | Inline code spans |
+
+Supported properties: `background-color`, `color`, `font-weight`, `font-style`, `font-size`, `text-align`, `border`.
+
+CSS custom properties (`var(--name)`) are resolved automatically, including chained variables and `var(--name, fallback)` syntax.
+
+**Works best with simple, flat CSS.** Complex Material for MkDocs theme overrides — compound selectors (`.md-typeset table:not([class]) thead th`), `color-mix()`, `@media` blocks, `:has()` etc. — are silently skipped. For these, maintain a small separate file:
+
+```css
+/* confluence-overrides.css */
+:root { --primary: #d20014; }
+th  { background-color: var(--primary); color: white; font-weight: 600; }
+h1, h2, h3 { color: var(--primary); }
+code { background-color: #f5f5f5; }
+```
+
+```yaml
+extra_css:
+  - stylesheets/extra.css             # full Material theme
+  - stylesheets/confluence-overrides.css  # simple Confluence-targeted styles
+```
+
+---
+
+## Supported Markdown features
+
+### Block elements
+
+| Feature | Confluence output |
+|---|---|
+| ATX headings `#` – `######` | `<h1>` – `<h6>` |
+| Paragraphs | `<p>` |
+| Fenced code blocks | `code` macro with language, title, and line numbers |
+| Bullet lists | `<ul>/<li>` |
+| Ordered lists | `<ol>/<li>` |
+| Task lists `- [x]` / `- [ ]` | Native `<ac:task-list>` / `<ac:task>` macros |
+| Tables (GFM pipe syntax) | `<table>` with header and column alignment |
+| Blockquotes | `<blockquote>` |
+| Horizontal rules `---` | `<hr/>` |
+
+### Inline elements
+
+| Feature | Confluence output |
+|---|---|
+| `**bold**` / `__bold__` | `<strong>` |
+| `*italic*` | `<em>` |
+| `~~strikethrough~~` | `<s>` |
+| `` `inline code` `` | `<code>` |
+| `[text](url)` | `<a href="...">` |
+| `[text](file.pdf)` | `<ac:link><ri:attachment .../>` (uploaded as attachment) |
+| `![alt](src)` | `<ac:image>` with `<ri:attachment>` (local) or `<ri:url>` (remote) |
+| `![alt](src){ width="400" }` | `<ac:image ac:width="400">` — also supports `height` and `align` |
+| `<br>` / `<br/>` | `<br />` |
+| `<sub>` / `<sup>` / `<u>` / `<small>` | Direct XHTML passthrough |
+| `<mark>text</mark>` | `<span style="background-color: yellow;">` |
+| `<kbd>text</kbd>` | `<code>` |
+| `++ctrl+alt+del++` | `<code>Ctrl</code>+<code>Alt</code>+<code>Del</code>` (pymdownx.keys) |
+| `<s>text</s>` / `<del>text</del>` | `<span style="text-decoration: line-through;">` |
+
+### MkDocs / Material extensions
+
+| Feature | Confluence output |
+|---|---|
+| `--8<--` file includes | Resolved before parsing |
+| Admonitions `!!! type "title"` | `info` / `tip` / `warning` / `note` macro |
+| Danger admonitions (`danger`, `error`, `bug`) | Red `panel` macro with 🚨 prefix |
+| Collapsible admonitions `??? type` | `expand` macro |
+| Content tabs `=== "Label"` | `expand` macros (one per tab) |
+| Details blocks `??? "title"` | `expand` macro |
+| Footnotes `[^1]` | Superscript anchor links + *Footnotes* section at page bottom |
+| Mermaid diagrams | PNG via Kroki, uploaded as attachment (`<ac:image ac:align="center">`) |
+| Internal links `[text](page.md)` | Native Confluence page link; `#fragment` anchors preserved |
+| `awesome-pages` nav (`.pages` files) | Fully supported |
+| Edit link banner | `info` macro linking back to source in GitHub/GitLab |
+
+### YAML front matter → Page Properties
+
+A YAML front matter block is converted to a Confluence **Page Properties** macro, making it queryable via the Page Properties Report macro.
+
+```yaml
+---
+title: "Architecture Proposal – IAM"
+subtitle: "Hybrid Identity Hub"
+documentId: AP-IAM-2026
+version: "0.1"
+lastUpdated: 2026-01-12
+author: "Anders Hybertz"
+tags: [architecture, iam]
+ready: true
+---
+```
+
+| Field | Notes |
+|---|---|
+| `title` | Used as the Confluence page title on publish |
+| `subtitle` | Rendered as italic lead paragraph above the properties table |
+| `tags` | Also applied as Confluence page labels |
+| `ready` | `true` → ✅ Ready · `false` → 📝 Draft (skips publish) |
+| `source` | Stripped (internal tooling field) |
+| *other fields* | Title-cased key, value stringified |
+
+If `repo_url` + `edit_uri` are set in `mkdocs.yml`, an **Edit Source** row links to the source file. If `site_url` is set, a **Published Page** row links to the rendered MkDocs site.
+
+### Abbreviation expansion
+
+MkDocs abbreviation definitions (`*[ABBR]: Full term`) are expanded inline — Confluence has no native `<abbr>` tooltip. The **first occurrence** in body text is expanded as `IAM (Identity and Access Management)`; subsequent occurrences are left as-is. Abbreviations that only appear in headings or code are collected into an auto-appended **Glossary** section.
+
+### Graceful degradation
+
+Any unrecognised block is preserved as a visible `warning` macro — no content is silently lost.
+
+`<div class="grid" markdown>` (Material grid cards) has no Confluence equivalent. The wrapper is stripped; inner admonitions render sequentially.
+
+---
+
+## Known limitations
+
+| Feature | Behaviour |
+|---|---|
+| **Admonition styling** | Native macros (`tip`, `info`, `warning`, `note`) use Confluence's fixed theme styling — no custom header/body colours. |
+| **Abbreviation tooltips** | No native tooltip support. First occurrence expanded inline; remainder left as-is. |
+| **Grid cards** | Wrapper stripped; inner admonitions rendered individually. |
+| **Page width** | Confluence defaults to a narrow fixed-width column. mk2conf publishes with `fullWidth: true` by default (configurable). |
+| **Page ordering** | Confluence sorts child pages alphabetically. The v2 REST API has no write endpoint for child ordering; nav order cannot be enforced. |
+| **Code language aliases** | Pygments short aliases (`py`, `js`, `yml`, `ts`, `sh`) are passed through as-is; Confluence requires full language names for syntax highlighting. |
+
+---
+
+## Roadmap
+
+- [ ] **Delete orphaned pages** — detect and remove Confluence pages that were previously published but have since been removed from `nav:`.
+
+---
+
+## Development
+
+See [Setup.md](Setup.md) for environment setup.
+
+```bash
+pytest              # run tests
+ruff check src      # lint
+mypy src            # type-check
+bandit -r src -ll   # security scan
+```

mkdocs2confluence-0.5.25/PKG-INFO

@@ -1,20 +0,0 @@
-Metadata-Version: 2.4
-Name: mkdocs2confluence
-Version: 0.5.25
-Summary: Compile MkDocs markdown to Confluence storage format
-Author: Anders Hybertz
-License: GPL-3.0-or-later
-Requires-Python: >=3.12
-License-File: LICENSE
-Requires-Dist: PyYAML>=6.0.3
-Requires-Dist: httpx>=0.27
-Requires-Dist: tinycss2>=1.5.1
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Requires-Dist: types-PyYAML; extra == "dev"
-Requires-Dist: bandit; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Dynamic: license-file

mkdocs2confluence-0.5.25/src/mkdocs2confluence.egg-info/PKG-INFO

@@ -1,20 +0,0 @@
-Metadata-Version: 2.4
-Name: mkdocs2confluence
-Version: 0.5.25
-Summary: Compile MkDocs markdown to Confluence storage format
-Author: Anders Hybertz
-License: GPL-3.0-or-later
-Requires-Python: >=3.12
-License-File: LICENSE
-Requires-Dist: PyYAML>=6.0.3
-Requires-Dist: httpx>=0.27
-Requires-Dist: tinycss2>=1.5.1
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: mypy; extra == "dev"
-Requires-Dist: types-PyYAML; extra == "dev"
-Requires-Dist: bandit; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Dynamic: license-file