ccandle

ccandle is a toolset for Confluence power users to coax their Confluence pages to be more findable and maintainable. See also some info on how it works.

goals

• CLI tool to sync user local offline db with their Confluence Cloud instance
• processor to strip plain text from HTML, get analytics (word count, page type), and add other useful metadata
• statistical analyzer of spaces, to give visibility on quality and basic dimensions

getting started

installation

• Install uv package manager: curl -LsSf https://astral.sh/uv/install.sh | sh
• Clone repo: git clone git@github.com:escher2hands/ccandle.git, then cd ccandle
• Install dependencies uv sync

authentication to your Confluence instance

• enter values for ccandle connection email, url, and token, so you can connect to your Confluence Cloud instance.

Note: manage API tokens from Atlassian at: https://id.atlassian.com/manage/api-tokens

tracking spaces

• run ccandle spaces list to find the space id of any spaces you are interested in tracking
• run ccandle spaces add SPACE_ID to add a space (or spaces) to track
• run ccandle sync to scrape the space, and process the scraped pages

do things

• run ccandle overview to get at-a-glance appraisal of quality and navigability metrics in your tracked Confluence spaces
• dive deeper with ccandle stats to find specific information on most popular (linked-to) pages, orphans, duplicate pages, and more
• run ccandle sql query YOUR_QUERY to run arbitrary queries on your processed offline page mirror
• run ccandle labels add LABEL_NAME PAGE_ID_LIST to add labels to a bulk set of pages, and ... remove LABEL_NAME PAGE_ID_LIST to remove
• run ccandle excerpts add SOURCE_PAGE_ID TO_PAGE_ID_LIST to add navbox excerpts to a bulk set of pages, and ... remove PAGE_ID_LIST to remove

See more info on the brief features overview.

roadmap

• Link and label suggestions (via fancy embeddings and statistical methods)
• Gap explorer (find topics mentioned across pages, but for which no authoritative page exists)
• Space content distribution explorer (find parts of the page tree with unexpectedly dense documentation, and filter out those parts with mostly template and blank pages)

ccandle, a Confluence toolset to shine light on the quality and navigability of technical documentation.