{"id":49052388,"url":"https://github.com/jeckyl2010/mkdocs2confluence","last_synced_at":"2026-05-27T13:02:02.327Z","repository":{"id":352375894,"uuid":"1214904260","full_name":"jeckyl2010/mkdocs2confluence","owner":"jeckyl2010","description":"CLI tool that compiles MkDocs markdown into native Confluence storage XHTML and publishes to Confluence Cloud.","archived":false,"fork":false,"pushed_at":"2026-05-23T08:23:11.000Z","size":23322,"stargazers_count":5,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-23T10:29:15.397Z","etag":null,"topics":["atlassian","cli","confluence","confluence-cloud","doc-as-code","documentation","everything-as-code","markdown","mkdocs","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeckyl2010.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-19T07:52:31.000Z","updated_at":"2026-05-23T08:21:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jeckyl2010/mkdocs2confluence","commit_stats":null,"previous_names":["jeckyl2010/mkdocs2confluence"],"tags_count":157,"template":false,"template_full_name":null,"purl":"pkg:github/jeckyl2010/mkdocs2confluence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeckyl2010%2Fmkdocs2confluence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeckyl2010%2Fmkdocs2confluence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeckyl2010%2Fmkdocs2confluence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeckyl2010%2Fmkdocs2confluence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeckyl2010","download_url":"https://codeload.github.com/jeckyl2010/mkdocs2confluence/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeckyl2010%2Fmkdocs2confluence/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33566873,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-27T02:00:06.184Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["atlassian","cli","confluence","confluence-cloud","doc-as-code","documentation","everything-as-code","markdown","mkdocs","python"],"created_at":"2026-04-19T21:12:48.179Z","updated_at":"2026-05-27T13:02:02.321Z","avatar_url":"https://github.com/jeckyl2010.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mk2conf — MkDocs / Zensical to Confluence\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![PyPI](https://img.shields.io/pypi/v/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)\n[![Downloads](https://img.shields.io/pypi/dm/mkdocs2confluence)](https://pypi.org/project/mkdocs2confluence/)\n[![Latest Release](https://img.shields.io/github/v/release/jeckyl2010/mkdocs2confluence)](https://github.com/jeckyl2010/mkdocs2confluence/releases/latest)\n[![CI](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/ci.yml)\n[![Release](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml/badge.svg)](https://github.com/jeckyl2010/mkdocs2confluence/actions/workflows/release.yml)\n[![codecov](https://codecov.io/gh/jeckyl2010/mkdocs2confluence/graph/badge.svg)](https://codecov.io/gh/jeckyl2010/mkdocs2confluence)\n[![Ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n[![mypy](https://img.shields.io/badge/type--checked-mypy-blue.svg)](https://mypy-lang.org/)\n[![security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)\n[![SLSA Level 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev)\n[![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/jeckyl2010/mkdocs2confluence/badge)](https://securityscorecards.dev/viewer/?uri=github.com/jeckyl2010/mkdocs2confluence)\n\nA Python CLI tool that compiles MkDocs-flavoured Markdown into **native Confluence storage XHTML** and publishes it directly to Confluence Cloud. It is a **compiler/transpiler**, not an HTML converter — every construct maps to its native Confluence equivalent, so pages look and behave like hand-authored Confluence content.\n\n- **Publish** — compiles your full `nav:` tree and pushes only changed pages (SHA-256 skip, no unnecessary version bumps or notifications).\n- **What's New page** — designate a `CHANGELOG.md` with `confluence.changelog` and mk2conf publishes it as a pinned top-level page on every run, so Confluence readers always have one place to see what changed.\n- **AI changelog skill** — `mk2conf install-skill` installs a bundled AI skill into your editor (Claude Code, Copilot, Cursor, Hermes). It extracts git changes deterministically, decides whether they are significant, and drafts a dated entry in `CHANGELOG.md` — with selective links to the pages that carry the main changes. Bootstrap a project with `--since 2026-05-01` to generate the initial changelog from a date.\n- **Review bridge** — `sync-comments` turns open Confluence page comments into GitHub pull request review threads and auto-resolves them in Confluence when the PR is merged.\n\n\u003e **Zensical compatible** — [Zensical](https://zensical.org/) is the modern successor to MkDocs + Material for MkDocs. Since it uses the same `mkdocs.yml` format and Python Markdown extensions, your Zensical project works with mk2conf today with no changes required.\n\n---\n\n## Installation\n\nRequires Python 3.12+. The PyPI package is `mkdocs2confluence`; the CLI command is `mk2conf`.\n\n```bash\npip install mkdocs2confluence\n# or, for an isolated install:\npipx install mkdocs2confluence\n```\n\n**From source** (see [Setup.md](Setup.md)):\n\n```bash\ngit clone https://github.com/jeckyl2010/mkdocs2confluence.git\ncd mkdocs2confluence \u0026\u0026 uv sync\n```\n\n---\n\n## GitHub Actions\n\nPublish docs automatically on every push — no local install needed:\n\n```yaml\n- name: Publish docs to Confluence\n  uses: jeckyl2010/mkdocs2confluence@v1\n  with:\n    token: ${{ secrets.CONFLUENCE_API_TOKEN }}\n```\n\n**Full workflow** — triggers on changes to `docs/` or `mkdocs.yml`:\n\n```yaml\nname: Publish docs\n\non:\n  push:\n    branches: [main]\n    paths: ['docs/**', 'mkdocs.yml']\n\njobs:\n  publish:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: jeckyl2010/mkdocs2confluence@v1\n        with:\n          token: ${{ secrets.CONFLUENCE_API_TOKEN }}\n          prune: 'true'\n```\n\nAvailable inputs: `token` (required), `config`, `version`, `dry-run`, `section`, `page`, `prune`, `quiet`. See [docs/commands.md](docs/commands.md) for details.\n\n---\n\n## Quick start\n\n```bash\n# Preview a page locally (no Confluence API calls)\nmk2conf preview --page index.md --watch\n\n# Dry-run: see what would be published\nmk2conf publish --dry-run\n\n# Publish all nav pages (and the changelog page if configured)\nmk2conf publish\n\n# Export a section to PDF\nmk2conf pdf --section Guide --out guide.pdf\n\n# Install the changelog AI skill into your editor\nmk2conf install-skill\n\n# Sync Confluence comments to GitHub PR review threads\nmk2conf sync-comments\n```\n\n---\n\n## Configuration\n\nAdd a `confluence:` block to your `mkdocs.yml`:\n\n```yaml\nconfluence:\n  base_url: https://yourorg.atlassian.net\n  space_key: TECH\n  email: user@example.com\n  token: !ENV CONFLUENCE_API_TOKEN   # never hardcode the token\n  parent_page_id: \"123456\"           # optional root page\n  mermaid_render: kroki              # \"kroki\" (default) | \"kroki:https://your-kroki\" | \"none\"\n  full_width: true                   # default: true\n  changelog: CHANGELOG.md           # optional: publish as a top-level \"What's New\" page\n```\n\nThe `confluence:` block is also accepted under `extra:` for MkDocs strict-mode compatibility. The API token is read from `token:` in `mkdocs.yml`, then `CONFLUENCE_API_TOKEN`, then `MK2CONF_TOKEN`.\n\n### Changelog / What's New page\n\nSet `changelog:` to a Markdown file path (relative to `docs_dir`) to have mk2conf publish it as a permanent top-level page on every full `mk2conf publish` run. The page title comes from YAML front matter `title:`; it defaults to `\"What's New\"` if absent.\n\n```yaml\nconfluence:\n  changelog: CHANGELOG.md   # relative to docs_dir\n```\n\n- The page does **not** need to appear in `nav:` — it is always placed at the top level of the space (or under `parent_page_id` if set).\n- If it also appears in `nav:`, it is published once; no duplication.\n- `--prune` never deletes it — it is a pinned page, not a nav-derived page.\n- Partial runs (`--page` / `--section`) skip the changelog page, consistent with other publish behaviour.\n- Omit the key, or set it to an empty string, to disable the feature entirely.\n\nRun `mk2conf install-skill` once after setting `changelog:` to install the changelog AI skill into your AI tool (Claude Code, Copilot, Cursor, Hermes). The skill analyses git changes to your docs since the last `CHANGELOG.md` commit and drafts an entry when the changes qualify as significant.\n\n**Your first publish:**\n\n```bash\nexport CONFLUENCE_API_TOKEN=your_api_token_here\nmk2conf preview --page docs/index.md --watch   # verify output locally\nmk2conf publish --dry-run                       # check the plan\nmk2conf publish                                 # go live\n```\n\n---\n\n## Documentation\n\n| | |\n|---|---|\n| [docs/commands.md](docs/commands.md) | Full flag reference for all five commands |\n| [docs/features.md](docs/features.md) | Supported Markdown / Material features and known limitations |\n| [Setup.md](Setup.md) | Development environment setup |\n\n---\n\n## Architecture\n\n![Architecture](https://raw.githubusercontent.com/jeckyl2010/mkdocs2confluence/main/docs/architecture.png)\n\nPipeline stages: **loader → preprocess → IR → transforms → emitter → publisher**.\n\nThe publisher is split into two phases:\n- `planner.py` builds a nav-ordered publish plan, compiles pages, and makes the read-side API calls needed to decide create vs update vs skip.\n- `executor.py` applies that plan, performs the write-side API calls, uploads attachments, and wires parent/child relationships in nav order so parent pages always exist before their children.\n\n`publisher/pipeline.py` remains a compatibility facade that re-exports the public publish surface used by the CLI and tests.\n\n---\n\n## Development\n\n```bash\nuv run pytest -q\nuv run ruff check src tests\nuv run mypy src\nuv run vulture src --min-confidence 80\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeckyl2010%2Fmkdocs2confluence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeckyl2010%2Fmkdocs2confluence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeckyl2010%2Fmkdocs2confluence/lists"}