Skip to content

Confluence

Confluence preprocessor allows inserting content from Confluence server into your Foliant project.

Installation

$ pip install foliantcontrib.confluence

Config

To enable the preprocessor, add confluence to preprocessors section in the project config:

preprocessors:
    - confluence

The preprocessor has a number of options:

preprocessors:
    - confluence:
        passfile: confluence_secrets.yml
        host: https://my_confluence_server.org
        login: user
        password: !CONFLUENCE_PASS
        space_key: "~user"
        pandoc_path: pandoc
        verify_ssl: true
passfile
Path to YAML-file holding credentials. See details in Supplying Credentials section. Default: confluence_secrets.yml
host
Required Host of your confluence server. If not stated — it would be taken from Confluence backend config.
login
Login of the user who has permissions to create and update pages. If login is not supplied, it would be taken from backend config, or prompted during the build.
password
Password of the user. If password is not supplied, it would be taken from backend config, or prompted during the build.

It is not secure to store plain text passwords in your config files. We recommend to use environment variables to supply passwords

space_key
The space key where the page titles will be searched for.
pandoc_path
Path to Pandoc executable (Pandoc is used to convert Confluence content into Markdown).
verify_ssl
If false, SSL verification will be turned off. Sometimes when dealing with Confluence servers in Intranets it's easier to turn this option off rather than fight with admins. Not recommended to turn off for public servers in production. Default: true

Usage

Add a <confluence></confluence> tag at the position in the document where the content from Confluence should be inserted. The page is defined by its id or title. If you are specifying page by title, you will also need to set space_key either in tag or in the preprocessor options.

The following content is imported from Confluence:

<confluence id="12345"></confluence>

This is from Confluence too, but determined by page title (space key is defined in preprocessor config):

<confluence title="My Page"></confluence>

Here we are overriding space_key:

<confluence space_key="ANOTHER_SPACE" title="My Page"></confluence>

Supplying Credentials

There are two ways to supply credentials for your confluence server.

1. In foliant.yml

The most basic way is just to put credentials in foliant.yml:

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

It's not very secure because foliant.yml is usually visible to everybody in your project's git repository.

2. Using passfile

Alternatively, you can use a passfile. Passfile is a yaml-file which holds all your passwords. You can keep it out from git-repository by storing it only on your local machine and production server.

To use passfile, add a passfile option to foliant.yml:

backend_config:
    confluence:
        host: https://my_confluence_server.org
        passfile: confluence_secrets.yaml

The syntax of the passfile is the following:

hostname:
    login: password

For example:

https://my_confluence_server.org:
    user1: wFwG34uK
    user2: MEUeU3b4
https://another_confluence_server.org:
    admin: adminpass

If there are several records for a specified host in passfile (like in the example above), Foliant will pick the first one. If you want specific one of them, add the login parameter to your foliant.yml:

backend_config:
    confluence:
        host: https://my_confluence_server.org
        passfile: confluence_secrets.yaml
        login: user2
Back to top