{"id":37074569,"url":"https://github.com/foliant-docs/foliantcontrib.confluence","last_synced_at":"2026-01-14T08:47:17.019Z","repository":{"id":57431742,"uuid":"202544387","full_name":"foliant-docs/foliantcontrib.confluence","owner":"foliant-docs","description":"Confluence backend for Foliant documentation generator.","archived":false,"fork":false,"pushed_at":"2025-08-29T09:26:50.000Z","size":1061,"stargazers_count":3,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-28T21:59:42.530Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/foliant-docs.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-08-15T13:17:17.000Z","updated_at":"2025-08-29T09:25:55.000Z","dependencies_parsed_at":"2025-08-29T11:15:47.217Z","dependency_job_id":"2b218008-c769-470c-ac11-b872c617720a","html_url":"https://github.com/foliant-docs/foliantcontrib.confluence","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/foliant-docs/foliantcontrib.confluence","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.confluence","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.confluence/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.confluence/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.confluence/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foliant-docs","download_url":"https://codeload.github.com/foliant-docs/foliantcontrib.confluence/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.confluence/sbom","scorecard":{"id":406066,"data":{"date":"2025-08-11","repo":{"name":"github.com/foliant-docs/foliantcontrib.confluence","commit":"77c657b824c966381d83bc07edf8763b50e46bc4"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.8,"checks":[{"name":"Code-Review","score":0,"reason":"Found 1/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Token-Permissions","score":10,"reason":"GitHub workflow tokens follow principle of least privilege","details":["Info: topLevel 'contents' permission set to 'read': .github/workflows/python-publish.yml:17","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Pinned-Dependencies","score":2,"reason":"dependency not pinned by hash detected -- score normalized to 2","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/foliant-docs/foliantcontrib.confluence/python-publish.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/python-publish.yml:27: update your workflow using https://app.stepsecurity.io/secureworkflow/foliant-docs/foliantcontrib.confluence/python-publish.yml/master?enable=pin","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:32","Warn: pipCommand not pinned by hash: .github/workflows/python-publish.yml:33","Info:   0 out of   2 GitHub-owned GitHubAction dependencies pinned","Info:   1 out of   1 third-party GitHubAction dependencies pinned","Info:   0 out of   2 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/python-publish.yml:20"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 1 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-18T21:17:34.611Z","repository_id":57431742,"created_at":"2025-08-18T21:17:34.611Z","updated_at":"2025-08-18T21:17:34.611Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28414693,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T08:38:59.149Z","status":"ssl_error","status_checked_at":"2026-01-14T08:38:43.588Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T08:47:14.665Z","updated_at":"2026-01-14T08:47:17.002Z","avatar_url":"https://github.com/foliant-docs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Confluence backend for Foliant\n\n[![](https://img.shields.io/pypi/v/foliantcontrib.confluence.svg)](https://pypi.org/project/foliantcontrib.confluence/) [![](https://img.shields.io/github/v/tag/foliant-docs/foliantcontrib.confluence.svg?label=GitHub)](https://github.com/foliant-docs/foliantcontrib.confluence)\n\n![Confluence page built with Foliant](https://raw.githubusercontent.com/foliant-docs/foliantcontrib.confluence/master/img/confluence.png)\n\nConfluence 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.\n\nIt also has a feature of restoring the user inline comments, added for the article, even after the commented fragment was changed.\n\nThis backend adds the `confluence` target for your Foliant `make` command.\n\n## Installation\n\n```bash\n$ pip install foliantcontrib.confluence\n```\n\n\u003e The backend requires [Pandoc](https://pandoc.org/) to be installed on your system. Pandoc is needed to convert Markdown into HTML.\n\n## Usage\n\nTo upload a Foliant project to Confluence server use `make confluence` command:\n\n```bash\n$ foliant make confluence\nParsing config... Done\nMaking confluence... Done\n────────────────────\nResult:\nhttps://my_confluence_server.org/pages/viewpage.action?pageId=123 (Page Title)\n```\n\n## Config\n\nYou have to set up the correct config for this backend to work properly.\n\nSpecify all options in `backend_config.confluence` section:\n\n```yaml\nbackend_config:\n  confluence:\n    passfile: confluence_secrets.yml\n    host: 'https://my_confluence_server.org'\n    login: user\n    password: user_password\n    id: 124443\n    title: Title of the page\n    space_key: \"~user\"\n    parent_id: 124442\n    parent_title: Parent\n    test_run: false\n    notify_watchers: false\n    toc: false\n    nohead: false\n    restore_comments: true\n    resolve_if_changed: false\n    pandoc_path: pandoc\n    verify_ssl: true\n    cloud: false\n    attachments:\n        - license.txt\n        - project.pdf\n    codeblocks:\n        ...\n```\n\n`passfile`\n:   Path to YAML-file holding credentials. See details in **Supplying Credentials** section. Default: `confluence_secrets.yml`\n\n`host`\n:   **Required** Host of your confluence server.\n\n`login`\n:   Login of the user who has permissions to create and update pages. If login is not supplied, it will be prompted during the build.\n\n`password`\n:   Password of the user. If the password is not supplied, it will be prompted during the build.\n\n`id`\n:   ID of the page where the content will be uploaded. *Only for already existing pages*\n\n`title`\n:   Title of the page to be created or updated.\n\n\u003e Remember that page titles in one space must be unique.\n\n`space_key`\n:   The space key where the page(s) will be created/edited. *Only for not yet existing pages*.\n\n`parent_id`\n:   ID of the parent page under which the new one(s) should be created. *Only for not yet existing pages*.\n\n`parent_title`\n:   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*.\n\n`test_run`\n:   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`\n\n`notify_watchers`\n:   If `true` — watchers will be notified that the page has changed. Default: `false`\n\n`toc`\n:   Set to `true` to add a table of contents to the beginning of the document. Default: `false`\n\n`nohead`\n:   If set to `true`, first title will be removed from the page. Use it if you are experiencing duplicate titles. Default: `false`\n\n`restore_comments`\n:   Attempt to restore inline comments near the same places after updating the page. Default: `true`\n\n`resolve_if_changed`\n:   Delete inline comment from the source if the commented text was changed. This will automatically mark the comment as resolved. Default: `false`\n\n`pandoc_path`\n:   Path to Pandoc binary (Pandoc is used to convert Markdown into HTML).\n\n`verify_ssl`\n:   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`\n\n`cloud`\n:   If `true`, foliant will try to publish content without HTML code formatting, which introduces unwanted spaces and newlines when working with Confluence Cloud.\n\n`attachments`\n:   List of files (relative to project root) which should be attached to the Confluence page.\n\n`codeblocks`\n:   Configuration for converting Markdown code blocks into code-block macros. See details in **Code blocks processing** sections.\n\n## User's guide\n\n### Uploading articles\n\nBy default, if you specify `id` or `space_key` and `title` in foliant.yml, the whole project will be built and uploaded to this page.\n\nIf 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.\n\nMeta section is a YAML-formatted field-value section in the beginning of the document, which is defined like this:\n\n```yaml\n---\nfield: value\nfield2: value\n---\n\nYour chapter md-content\n```\n\nor like this:\n\n```html\n\u003cmeta\n    field=\"value\"\n    field2=\"value\"\u003e\n\u003c/meta\u003e\n\nYour chapter md-content\n```\n\n\u003e 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.\n\nIf you want to upload a chapter into confluence, add its properties under the `confluence` key like this:\n\n```yaml\n---\nconfluence:\n    title: My confluence page\n    space_key: \"~user\"\n---\n\nYou chapter md-content\n```\n\n\u003e **Important notice!**\n\u003e Both modes work together. If you specify the `id1` in foliant.yml and `id2` in chapter's meta — the whole project will be uploaded to the page with `id1`, and the specific chapter will also be uploaded to the page with `id2`.\n\n\u003e **Notice**\n\u003e You can omit `title` param in metadata. In this case section heading will be used as a title.\n\n\nIf you want to upload just a part of the chapter, specify meta tag under the heading, which you want to upload, like this:\n\n```html\n# My document\n\nLorem ipsum dolor sit amet, consectetur adipisicing elit. Explicabo quod omnis ipsam necessitatibus, enim voluptatibus.\n\n## Components\n\n\u003cmeta\n    confluence=\"\n        title: 'System components'\n        space_key: '~user'\n    \"\u003e\n\u003c/meta\u003e\n\nLorem ipsum dolor sit amet, consectetur adipisicing elit. Vel, atque!\n...\n```\n\nIn this example, only the **Components** section with all its content will be uploaded to Confluence. The **My document** heading will be ignored.\n\n### Creating pages\n\nIf you want a new page to be created for content in your Foliant project, just supply in foliant.yml the space key and a title that does not yet exist in this space. Remember that in Confluence page titles are unique inside one space. If you use a title of an already existing page, the backend will attempt to edit it and replace its content with your project.\n\nExample config for this situation is:\n\n```yaml\nbackend_config:\n  confluence:\n    host: https://my_confluence_server.org\n    login: user\n    password: pass\n    title: My unique title\n    space_key: \"~user\"\n```\n\nNow if you change the title in your config, confluence will *create a new page with the new title*, leaving the old one intact.\n\nIf you want to change the title of your page, the answer is in the following section.\n\n### Updating pages\n\nGenerally to update the page contents you may use the same config you used to create it (see the previous section). If the page with a specified title exists, it will be updated.\n\nAlso, you can just specify the id of an existing page. After build its contents will be updated.\n\n```yaml\nbackend_config:\n  confluence:\n    host: https://my_confluence_server.org\n    login: user\n    password: pass\n    id: 124443\n```\n\nThis 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:\n\n```yaml\nbackend_config:\n  confluence:\n    host: https://my_confluence_server.org\n    login: user\n    password: pass\n    id: 124443\n    title: New unique title\n```\n\n### Updating part of a page\n\nConfluence backend can also upload an article into the middle of a Confluence page, leaving all the rest of it intact. To do this you need to add an *Anchor* into your page in the place where you want Foliant content to appear.\n\n1. Go to Confluence web interface and open the article.\n2. Go to Edit mode.\n3. Put the cursor in the position where you want your Foliant content to be inserted and start typing `{anchor` to open the macros menu and locate the Anchor macro.\n4. Add an anchor with the name `foliant`.\n5. Save the page.\n\nNow if you upload content into this page (see two previous sections), Confluence backend will leave all text which was before and after the anchor intact, and add your Foliant content in the middle.\n\nYou can also add two anchors: `foliant_start` and `foliant_end`. In this case, all text between these anchors will be replaced by your Foliant content.\n\n\u003e **Known issue:** right now this mode doesn't work with *layout sections*. If you are using sections, whole content will be overwritten.\n\n### Inserting raw confluence tags\n\nIf you want to supplement your page with confluence macros or any other storage-specific HTML, you may do it by wrapping them in the `\u003craw_confluence\u003e\u003c/raw_confluence\u003e` tag.\n\nFor example, if you wish to add a table of contents into the middle of the document for some reason, you can do something like this:\n\n```html\nLorem ipsum dolor sit amet, consectetur adipisicing elit. Odit dolorem nulla quam doloribus delectus voluptate.\n\n\u003craw_confluence\u003e\u003cac:structured-macro ac:macro-id=\"1\" ac:name=\"toc\" ac:schema-version=\"1\"/\u003e\u003c/raw_confluence\u003e\n\nLorem ipsum dolor sit amet, consectetur adipisicing elit. Officiis, laboriosam cumque soluta sequi blanditiis, voluptatibus quaerat similique nihil debitis repellendus.\n```\n\nIn version 0.6.15 we've added an experimental feature of automatically escaping `\u003cac:...\u003e\u003c/ac:...\u003e` tags for you. So if you want to insert, say, an image with native Confluence tag `ac:image`, you don't have to wrap it in `raw_confluence` tag, but keep in mind following caveats:\n\n- singleton `ac:...` tags are not supported, so `\u003cac:emoticon ac:name=\"cross\" /\u003e` will not work, you will have to provide the closing tag: `\u003cac:emoticon ac:name=\"cross\"\u003e\u003c/ac:emoticon\u003e`,\n- only `ac:...` tags are escaped right now, other confluence tags like `ri:...` or `at:...` are left as is. If these tags appear inside `ac:...` tag, it's ok. If otherwise, `ac:...` tag appears inside `at:...` or `ri:...` tag, everything will break.\n\n### Attaching files\n\nTo attach an arbitrary file to Confluence page simply put path to this file in the `attachments` parameter in foliant.yml or in meta section.\n\nThis will just tell Foliant to attach this file to the page, but if you want to reference it in text, use the other approach:\n\nInsert Confluence `ac:link` tag to attachment right inside your Markdown document and put local path to your file in the `ri:filename` parameter like this:\n\n```\nPresentation in PDF:\n\n\u003cac:link\u003e\n  \u003cri:attachment ri:filename=\"presentation.pdf\"/\u003e\n\u003c/ac:link\u003e\n```\n\nIn this case Foliant will upload the `presentation.pdf` to the Confluence page and make a link to it in the text. The path in `ri:filename` parameter should be relative to current Markdown file, but you can use `!path`, `!project_path` modifiers to reference images relative to project root.\n\n### Advanced images\n\nConfluence has an `ac:image` tag which allows you to transform and format your attached images:\n\n- resize,\n- set alignment,\n- add borders,\n- etc.\n\nSince version `0.6.15` you have access to all these features. Now instead of plain Markdown-image syntax you can use native Confluence image syntax. Add an `ac:image` tag as if you were editing page source in Confluence interface and use local relative path to the image as if you were inserting Markdown-image.\n\nFor example, if you have an image defined like this:\n\n```\n![My image](img/picture.png)\n```\n\nand you want to resize it to 600px and align to center, replace it with following tag:\n\n```\n\u003cac:image ac:height=\"600\" ac:align=\"center\"\u003e\n    \u003cri:attachment ri:filename=\"img/picture.png\" /\u003e\n\u003c/ac:image\u003e\n```\n\nAs you noticed, you should put path to your image right inside the `ri:filename` param. This path should be relative to current Markdown file, but you can (since 0.6.16) use `!path`, `!project_path` modifiers to reference images relative to project root.\n\nHere's [a link to Confluence docs](https://confluence.atlassian.com/doc/confluence-storage-format-790796544.html#ConfluenceStorageFormat-Images) about `ac:image` tag and all possible options.\n\nIf you want to upload an external image, you can also use this approach, just insert that proper `ac:image` tag, no need for `raw_confluence`:\n\n```\nExternal image:\n\n\n\u003cac:image\u003e\n\u003cri:url ri:value=\"http://confluence.atlassian.com/images/logo/confluence_48_trans.png\" /\u003e\u003c/ac:image\u003e\n```\n\n\n### Code blocks processing\n\nSince 0.6.9 backend converts Markdown code blocks into Confluence code-block macros. You can tune the macros appearance by specifying some options in `codeblocks` config section of Confluence backend\n\n```yaml\nbackend_config:\n    confluence:\n        codeblocks:  # all are optional\n            theme: django\n            title: Code example\n            linenumbers: false\n            collapse: false\n```\n\n\n`theme`\n:   Color theme of the code blocks. Should be one of:\n\n* `emacs`,\n* `django`,\n* `fadetogrey`,\n* `midnight`,\n* `rdark`,\n* `eclipse`,\n* `confluence`.\n\n`title`\n:   Title of the code block.\n\n`linenumbers`\n:   Show line numbers in code blocks. Default: `false`\n\n`collapse`\n:   Collapse code blocks into a clickable bar. Default: `false`\n\nRight now Foliant only converts code blocks by backticks/tildes (tabbed code blocks are ignored for now):\n\n~~~\nThis code block will be converted:\n\n```python\ndef test2():\n    pass\n ```\n~~~\n\n```\nAnd this:\n~~~\ndef test3():\n    pass\n~~~\n```\n\nSyntax name, defined after backticks/tildes is converted into its Confluence counterpart. Right now following syntaxes are supported:\n\n* `actionscript`,\n* `applescript`,\n* `bash`,\n* `c`,\n* `c`,\n* `coldfusion`,\n* `cpp`,\n* `cs`,\n* `css`,\n* `delphi`,\n* `diff`,\n* `erlang`,\n* `groovy`,\n* `html`,\n* `java`,\n* `javascript`,\n* `js`,\n* `perl`,\n* `php`,\n* `powershell`,\n* `python`,\n* `xml`,\n* `yaml`.\n\n### Supplying Credentials\n\nThere are several ways to supply credentials for your confluence server.\n\n**1. In foliant.yml**\n\nThe most basic way is just to put credentials in foliant.yml:\n\n```yaml\nbackend_config:\n    confluence:\n        host: https://my_confluence_server.org\n        login: user\n        password: pass\n```\n\nIt's not very secure because foliant.yml is usually visible to everybody in your project's git repository.\n\n**2. Omit credentials in config**\n\nA slightly more secure way is to remove password or both login and password from config:\n\n```yaml\nbackend_config:\n    confluence:\n        host: https://my_confluence_server.org\n        login: user\n```\n\nIn this case Foliant will prompt for missing credentials during each build:\n\n```bash\n$ foliant make confluence\nParsing config... Done\nApplying preprocessor confluence_final... Done\nMaking confluence...\n\n!!! User input required !!!\nPlease input password for user:\n$\n```\n\n**3. Using environment variables**\n\nFoliant 1.0.12 can access environment variables inside config files with `!env` modifier.\n\n```yaml\nbackend_config:\n    confluence:\n        host: https://my_confluence_server.org\n        login: !env CONFLUENCE_USER\n        password: !env CONFLUENCE_PASS\n```\n\nNow you can add these variables into your command:\n\n```bash\nCONFLUENCE_USER=user CONFLUENCE_PASS=pass foliant make confluence\n```\n\nOr, if you are using docker:\n\n```bash\ndocker-compose run --rm -e CONFLUENCE_USER=user -e CONFLUENCE_PASS=pass foliant make confluence\n```\n\n**4. Using passfile**\n\nFinally, 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.\n\nTo use passfile, add a `passfile` option to foliant.yml:\n\n```yaml\nbackend_config:\n    confluence:\n        host: https://my_confluence_server.org\n        passfile: confluence_secrets.yaml\n```\n\nThe syntax of the passfile is the following:\n\n```yaml\nhostname:\n    login: password\n```\n\nFor example:\n\n```yaml\nhttps://my_confluence_server.org:\n    user1: wFwG34uK\n    user2: MEUeU3b4\nhttps://another_confluence_server.org:\n    admin: adminpass\n```\n\nIf 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:\n\n```yaml\nbackend_config:\n    confluence:\n        host: https://my_confluence_server.org\n        passfile: confluence_secrets.yaml\n        login: user2\n```\n\n## Credits\n\nThe following wonderful tools and libraries are used in foliantcontrib.confluence:\n\n- [Atlassian Python API wrapper](https://github.com/atlassian-api/atlassian-python-api),\n- [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/),\n- [PyParsing](https://github.com/pyparsing/pyparsing),\n- [Pandoc](https://pandoc.org/).\n\n# Confluence Preprocessor for Foliant\n\n[![](https://img.shields.io/pypi/v/foliantcontrib.confluence.svg)](https://pypi.org/project/foliantcontrib.confluence/) [![](https://img.shields.io/github/v/tag/foliant-docs/foliantcontrib.confluence.svg?label=GitHub)](https://github.com/foliant-docs/foliantcontrib.confluence)\n\nConfluence preprocessor allows inserting content from Confluence server into your Foliant project.\n\n## Installation\n\n```bash\n$ pip install foliantcontrib.confluence\n```\n\n## Config\n\nTo enable the preprocessor, add `confluence` to `preprocessors` section in the project config:\n\n```yaml\npreprocessors:\n    - confluence\n```\n\nThe preprocessor has a number of options:\n\n```yaml\npreprocessors:\n    - confluence:\n        passfile: confluence_secrets.yml\n        host: https://my_confluence_server.org\n        login: user\n        password: !CONFLUENCE_PASS\n        space_key: \"~user\"\n        pandoc_path: pandoc\n        verify_ssl: true\n```\n\n`passfile`\n:   Path to YAML-file holding credentials. See details in **Supplying Credentials** section. Default: `confluence_secrets.yml`\n\n`host`\n:   **Required** Host of your confluence server. If not stated — it would be taken from Confluence backend config.\n\n`login`\n:   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.\n\n`password`\n:   Password of the user. If password is not supplied, it would be taken from backend config, or prompted during the build.\n\n\u003e It is not secure to store plain text passwords in your config files. We recommend to use [environment variables](https://foliant-docs.github.io/docs/config/#env) to supply passwords\n\n`space_key`\n:   The space key where the page titles will be searched for.\n\n`pandoc_path`\n:   Path to Pandoc executable (Pandoc is used to convert Confluence content into Markdown).\n\n`verify_ssl`\n:   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`\n\n## Usage\n\nAdd a `\u003cconfluence\u003e\u003c/confluence\u003e` 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.\n\n```html\nThe following content is imported from Confluence:\n\n\u003cconfluence id=\"12345\"\u003e\u003c/confluence\u003e\n\nThis is from Confluence too, but determined by page title (space key is defined in preprocessor config):\n\n\u003cconfluence title=\"My Page\"\u003e\u003c/confluence\u003e\n\nHere we are overriding space_key:\n\n\u003cconfluence space_key=\"ANOTHER_SPACE\" title=\"My Page\"\u003e\u003c/confluence\u003e\n```\n\n### Supplying Credentials\n\nThere are two ways to supply credentials for your confluence server.\n\n**1. In foliant.yml**\n\nThe most basic way is just to put credentials in foliant.yml:\n\n```yaml\nbackend_config:\n    confluence:\n        host: https://my_confluence_server.org\n        login: user\n        password: pass\n```\n\nIt's not very secure because foliant.yml is usually visible to everybody in your project's git repository.\n\n**2. Using passfile**\n\nAlternatively, 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.\n\nTo use passfile, add a `passfile` option to foliant.yml:\n\n```yaml\nbackend_config:\n    confluence:\n        host: https://my_confluence_server.org\n        passfile: confluence_secrets.yaml\n```\n\nThe syntax of the passfile is the following:\n\n```yaml\nhostname:\n    login: password\n```\n\nFor example:\n\n```yaml\nhttps://my_confluence_server.org:\n    user1: wFwG34uK\n    user2: MEUeU3b4\nhttps://another_confluence_server.org:\n    admin: adminpass\n```\n\nIf 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:\n\n```yaml\nbackend_config:\n    confluence:\n        host: https://my_confluence_server.org\n        passfile: confluence_secrets.yaml\n        login: user2\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.confluence","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.confluence","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.confluence/lists"}