Skip to main content

Confluence backend for Foliant

Confluence backend generates a confluence article and uploads it into your confluence server. With it you can create and edit pages in Confluence based on your Foliant project.

It also has a feature of restoring the user inline comments, added for the article, even after the commented fragment was changed.

This backend adds the confluence target for your Foliant make command.

Installation

$ pip install foliantcontrib.confluence

The backend requires Pandoc to be installed in your system. Pandoc is needed to convert Markdown into HTML.

Usage

To upload a Foliant project to Confluence server use make confluence command:

$ foliant make confluence
Parsing config... Done
Making confluence... Done
────────────────────
Result: https://my_confluence_server.org/pages/viewpage.action?pageId=123

Config

You have to set up a config for this backend to work properly.

Specify all options in backend_config.confluence section:

backend_config:
  confluence:
    host: 'https://my_confluence_server.org'
    login: user
    password: pass
    mode: single
    toc: false
    id: 124443
    title: Title of the page
    space_key: "~user"
    parent_id: 124442
    pandoc_path: pandoc

host : Required Host of your confluence server.

login : Login of the user who has the rights to create and update pages. If login is not supplied, it will be prompted during build

password : Password of the user. If password is not supplied, it will be prompted during build

mode : One of: single, multiple. In single mode backend uploads the whole Foliant project into specified Confluence page. In multiple mode backend uploads several chapters into separate Confluecnce pages defined with metadata. More info in the Modes section. Default: single.

toc : Set to true to add table of contents into the beginning of the document. Default: false

id : ID of the page into which the content will be uploaded (use only with single mode). Only for already existing pages

title : Title of the page to be created or updated (use only with single mode).

Remember that titles of the pages in one space are unique in Confluence.

space_key : The key of the space where the page(s) will be created/edited.

parent_id : ID of the parent page under which the new one(s) should be created. Only for not yet existing pages.

pandoc_path : Path to Pandoc executable (Pandoc is used to convert Markdown into HTML).

Modes

Backend confluence can work in two modes:

single — the whole project is flattened and uploaded into a single Confluence page; multiple — you may upload several chapters of your project into separate Confluence pages.

single mode

To use single mode first supply an option mode: single in foliant.yml, and then specify all the page properties (id or title & space) in the same foliant.yml config file. The project will be built, flattened into a single page and uploaded under the defined properties.

multiple mode

With the power of multiple mode you may create or update several Confluence pages with just one make command.

To switch on multiple mode, add an option mode: multiple to your foliant.yml file. Next, add properties defining the confluence page (like id or title & space) to the meta section of each chapter that you want to upload.

Meta section is a YAML field-value section in the beginning of the document, which is defined like this:

---
field: value
field2: value
---

Your chapter md-content

So if you want to upload a chapter into confluence, add something like this into the beginning of it:

---
title: My confluence page
space_key: "~user"
confluence: true  # this is required
---

You chapter md-content

Notice that we've also added a confluence: true key, which is required for chapter to be uploaded. If the key is false or is not defined, the backend will ignore this chapter.

After you've added properties to every page you want to be uploaded, run the same make confluence command:

$ foliant make confluence
Parsing config... Done
Making confluence... Done
────────────────────
Result:
https://my_confluence_server.org/pages/viewpage.action?pageId=1231
https://my_confluence_server.org/pages/viewpage.action?pageId=1232
https://my_confluence_server.org/pages/viewpage.action?pageId=1233

Creating pages with confluence backend

If you want a new page to be created for content in your Foliant project, just supply the title and the space key in the config. Remember that in Confluence page titles are unique inside one space. If you use a title of already existing page, the backend will attempt to edit it and replace its content with your project.

Example config for this situation is:

backend_config:
  confluence:
    host: 'https://my_confluence_server.org'
    login: user
    password: pass
    title: My unique title
    space_key: "~user"

Now if you change the title in your config, confluence will create a new page with the new title, the old one remaining intact.

If you want to change the title of your page, the answer is in the following section.

Updating pages with confluence backend

Generally to update the page contents you may use the same config you used to create it (see previous section).

Also, you can just specify the id of your page, this way after build its contents will be updated.

backend_config:
  confluence:
    host: 'https://my_confluence_server.org'
    login: user
    password: pass
    id: 124443

This is also the only way to edit a page title. If title param is specified, the backend will attempt to change the page's title to the new one:

backend_config:
  confluence:
    host: 'https://my_confluence_server.org'
    login: user
    password: pass
    id: 124443
    title: New unique title

Metadata

Release files for foliantcontrib.confluence 0.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for foliantcontrib.confluence 0.4.1
File Size Uploaded Provenance Actions
foliantcontrib.confluence-0.4.1.tar.gz 13.1 kB Without provenance Details for foliantcontrib.confluence-0.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for foliantcontrib.confluence 0.4.1
File Interpreter ABI Platform Actions
foliantcontrib.confluence-0.4.1-py3-none-any.whl Python 3 none any Details for foliantcontrib.confluence-0.4.1-py3-none-any.whl

Total release size: 25.6 kB

Release files / foliantcontrib.confluence-0.4.1.tar.gz

Download URL foliantcontrib.confluence-0.4.1.tar.gz
Size 13.1 kB
Tags Source
SHA-256 checksum
How to use checksums
56897c245a46370fbaf9d5eb116104d8c0f15969f75b02d53bd95683b1f54049
BLAKE2b-256 checksum
How to use checksums
17c22f52ba9084de5d793758e27e912098d3604f977bf4d167566c9e2d25c099
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.12.1 pkginfo/1.4.2 requests/2.22.0 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.25.0 CPython/3.6.1

Release files / foliantcontrib.confluence-0.4.1-py3-none-any.whl

Download URL foliantcontrib.confluence-0.4.1-py3-none-any.whl
Size 12.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
90c878365e380361095ed6635a7b564129d2684c4faec46a62db74bd8b6079ac
BLAKE2b-256 checksum
How to use checksums
a3f14b1f7acc21cda3f7ce49cebc2cfe226e081b61913da457178eb7f4377d9e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/1.12.1 pkginfo/1.4.2 requests/2.22.0 setuptools/40.6.2 requests-toolbelt/0.8.0 tqdm/4.25.0 CPython/3.6.1

Security for foliantcontrib.confluence 0.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page