Confluence¶
Confluence backend generates confluence articles and uploads them on your confluence server. It can create and edit pages in Confluence with content 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 on 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 (Page Title)
Config¶
You have to set up the correct config for this backend to work properly.
Specify all options in backend_config.confluence
section:
backend_config:
confluence:
passfile: confluence_secrets.yml
host: 'https://my_confluence_server.org'
login: user
password: user_password
id: 124443
title: Title of the page
space_key: "~user"
parent_id: 124442
parent_title: Parent
test_run: false
notify_watchers: false
toc: false
nohead: false
restore_comments: true
resolve_if_changed: false
pandoc_path: pandoc
verify_ssl: true
cloud: false
attachments:
- license.txt
- project.pdf
codeblocks:
...
passfile
- Path to YAML-file holding credentials. See details in Supplying Credentials section. Default:
confluence_secrets.yml
host
- Required Host of your confluence server.
login
- Login of the user who has permissions to create and update pages. If login is not supplied, it will be prompted during the build.
password
- Password of the user. If the password is not supplied, it will be prompted during the build.
id
- ID of the page where the content will be uploaded. Only for already existing pages
title
- Title of the page to be created or updated.
Remember that page titles in one space must be unique.
space_key
- The space key where the page(s) will be created/edited. Only for not yet existing pages.
parent_id
- ID of the parent page under which the new one(s) should be created. Only for not yet existing pages.
parent_title
- Another way to define the parent of the page. Lower priority than
paren_di
. Title of the parent page under which the new one(s) should be created. The parent should exist under the space_key specified. Only for not yet existing pages. test_run
- If this option is true, Foliant will prepare the files for uploading to Confluence, but won't actually upload them. Use this option for testing your content before upload. The prepared files can be found in
.confluencecache/debug
folder. Default:false
notify_watchers
- If
true
— watchers will be notified that the page has changed. Default:false
toc
- Set to
true
to add a table of contents to the beginning of the document. Default:false
nohead
- If set to
true
, first title will be removed from the page. Use it if you are experiencing duplicate titles. Default:false
restore_comments
- Attempt to restore inline comments near the same places after updating the page. Default:
true
resolve_if_changed
- Delete inline comment from the source if the commented text was changed. This will automatically mark the comment as resolved. Default:
false
pandoc_path
- Path to Pandoc binary (Pandoc is used to convert Markdown into HTML).
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
cloud
- If
true
, foliant will try to publish content without HTML code formatting, which introduces unwanted spaces and newlines when working with Confluence Cloud. attachments
- List of files (relative to project root) which should be attached to the Confluence page.
codeblocks
- Configuration for converting Markdown code blocks into code-block macros. See details in Code blocks processing sections.
User's guide¶
Uploading articles¶
By default, if you specify id
or space_key
and title
in foliant.yml, the whole project will be built and uploaded to this page.
If you wish to upload separate chapters into separate articles, you need to specify the respective id
or space_key
and title
in meta section of the chapter.
Meta section is a YAML-formatted field-value section in the beginning of the document, which is defined like this:
---
field: value
field2: value
---
Your chapter md-content
or like this:
Your chapter md-content
The result of the above examples will be exactly the same. Just remember that first syntax, with three dashes --- will only work if it is in the beginning of the document. For all other cases use the meta-tag syntax.
If you want to upload a chapter into confluence, add its properties under the confluence
key like this:
---
confluence:
title: My confluence page
space_key: "~user"
---
You chapter md-content
Important notice! Both modes work together. If you specify the
id1
in foliant.yml andid2
in chapter's meta — the whole project will be uploaded to the page withid1
, and the specific chapter will also be uploaded to the page withid2
.Notice You can omit
title
param in metadata. In this case section heading will be used as a title.
If you want to upload just a part of the chapter, specify meta tag under the heading, which you want to upload, like this: