Confluence preprocessor allows inserting content from Confluence server into your Foliant project.
$ pip install foliantcontrib.confluence
To enable the preprocessor, add
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
- Path to YAML-file holding credentials. See details in Supplying Credentials section. Default:
- Required Host of your confluence server. If not stated — it would be taken from Confluence backend config.
- 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 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
- The space key where the page titles will be searched for.
- Path to Pandoc executable (Pandoc is used to convert Confluence content into Markdown).
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:
<confluence></confluence> tag at the position in the document where the content from Confluence should be inserted. The page is defined by its
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>
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
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