Confluence Import Markdown



Find the latest information on the improvements made in the new Confluence Cloud editor. Import Markdown files with tables and code block You can import files in bulk, thus you save time and increase productivity. It replaces old add-on: Universal Importer for Confluence. Import almost any file format to Confluence. Spend less time hunting things down and more time making things happen. Organize your work, create documents, and discuss everything in one place.

Macro - Import import Imports content from another source and renders it from the perspective of the current page. Categories: development Usage This macro imports the contents of another page into. Import confluence page in a course Macro. Import confluence page in a course Macro. Adding a Confluence page as a lesson.

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¶

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:

Config¶

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

Specify all options in backend_config.confluence section:

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
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:

or like this:

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:

Important notice!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.

NoticeYou 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:

In this example, only the Components section with all its content will be uploaded to Confluence. The My document heading will be ignored.

Creating pages¶

If 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.

Example config for this situation is:

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

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

Updating pages¶

Generally 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.

Also, you can just specify the id of an existing page. After build its contents will be updated.

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:

Updating part of a page¶

Confluence 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.

Go to Confluence web interface and open the article.
Go to Edit mode.
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.
Add an anchor with the name foliant.
Save the page.

Now 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.

You 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.

Known issue: right now this mode doesn't work with layout sections. If you are using sections, whole content will be overwritten.

Inserting raw confluence tags¶

If you want to supplement your page with confluence macros or any other storage-specific HTML, you may do it by wrapping them in the <raw_confluence></raw_confluence> tag.

For 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:

In version 0.6.15 we've added an experimental feature of automatically escaping <ac:...></ac:...> 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:

singleton ac:... tags are not supported, so <ac:emoticon ac:name='cross' /> will not work, you will have to provide the closing tag: <ac:emoticon ac:name='cross'></ac:emoticon>,
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.

Attaching files¶

To attach an arbitrary file to Confluence page simply put path to this file in the attachments parameter in foliant.yml or in meta section.

This will just tell Foliant to attach this file to the page, but if you want to reference it in text, use the other approach:

Insert 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:

In 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.

Advanced images¶

Confluence has an ac:image tag which allows you to transform and format your attached images:

resize,
set alignment,
add borders,
etc.

Since 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.

For example, if you have an image defined like this:

and you want to resize it to 600px and align to center, replace it with following tag:

As 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.

Here's a link to Confluence docs about ac:image tag and all possible options.

If 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:

Code blocks processing¶

Since 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

theme: Color theme of the code blocks. Should be one of:

emacs,
django,
fadetogrey,
midnight,
rdark,
eclipse,
confluence.

title: Title of the code block.
linenumbers: Show line numbers in code blocks. Default: false
collapse: Collapse code blocks into a clickable bar. Default: false

Right now Foliant only converts code blocks by backticks/tildes (tabbed code blocks are ignored for now):

Syntax name, defined after backticks/tildes is converted into its Confluence counterpart. Right now following syntaxes are supported:

Confluence Import Markdown Command

actionscript,
applescript,
bash,
c,
c,
coldfusion,
cpp,
cs,
css,
delphi,
diff,
erlang,
groovy,
html,
java,
javascript,
js,
perl,
php,
powershell,
python,
xml,
yaml.

Supplying Credentials¶

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

1. In foliant.yml

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

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

2. Omit credentials in config

A slightly more secure way is to remove password or both login and password from config:

In this case Foliant will prompt for missing credentials during each build:

3. Using environment variables

Foliant 1.0.12 can access environment variables inside config files with !env modifier.

Now you can add these variables into your command:

Or, if you are using docker:

4. Using passfile

Finally, 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:

The syntax of the passfile is the following:

For example:

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:

Credits¶

The following wonderful tools and libraries are used in foliantcontrib.confluence:

Atlassian Python API wrapper,
BeautifulSoup,
PyParsing,
Pandoc.

We are migrating from Redmine to the product suite of Atlassian.

We successfully migrated the tickets from Redmine into Jira + Jenkins data into Bamboo.The only thing I'm not able to import is the wiki data from Redmine into confluence.

Confluence Api Import Markdown

Does anyone have/know a solution for this. (Manual import is not an option => +1500 pages)

Grtz & thanks Ilias

1 answer

answered 2014-03-31 12:30
This is a solution we have come up with recently. There are two scripts, first allows you to prepare data for conversion by exporting wikis and attachments. Second can push (almost) everything into confluence wiki, keeping links, most of the tables. It is not perfect, so DO expect some reasonable damage to content.

Confluence Wiki Import Markdown

Convert Confluence To Markdown

I am creating a page on wikipedia
I trying to arange a list of lists like this.Here is the screenshot of the page like which I am trying to display my contents how can I arange my contents to like the contents of image.I am using wikipedia visual editing option not the source editing option.Thanks in advance.
Location extraction from wikidata dump
How do I extract location entity from wikidata dump? I need a Python code for it. I have tried some that I came across online but no success. I followed this: https://pypi.org/project/wiki-dump-parser/#:~:text=%20There%20are%20several%20ways%20to%20get%20the,dumpgenerator.py%20script.%20You%20have%20a%20simple...%20More%20. please, can some one direct me to one that I can use.
AzDo wiki review/lock to avoid accidental edits
In my project , I have a wiki which has user guides for build contributors in my org. I have given right to contributors to edit it but at the same time I do not want them to edit without my knowledge (to avoid accidental edit) something like a review request. Apart from forcing this manually as a procedure what else can be done? Some wiki policy that I am unaware about? Some tricks?
Is it achievable?
Timer2Ticket: Redmine and Toggl Track syncing
New sync app between Redmine and Toggl Track! It synchronizes all your projects, issues and time entries across those systems in the background. It is still under development and free to use. Feel free to reach out to me to find out more. You can start using it here (Timer2Ticket). And it is open source (GitHub)!
Redmine Python - get all priorities
I am trying to get all available priorities in a project / from an issue.With other fields like target version or status I did the following...
My question is, if there is something similar for priorities - Low, Normal, High, ...?Thank you!
Redmine is down after attempt to setup smtp configuration
Today I set up a Redmine instance on Ubuntu Server 20.04 for the first time. That worked out quite well so far. So afterwards I set up a Mattermost instance and installed the Redmine Messenger plugin to receive status updates from Redmine in Mattermost. That also worked brilliantly.
Then I wanted to activate email notifications. That unfortunately did not work.
I did the following:
and added the following content (with my information)
Then I restarted apache and then redmine was down. See image
So I deleted the configuration.yml file and restarted apache. Unfortunately that didn't help. I couldn't take any usable information from the logs. (Which doesn't mean there aren't any)
If anyone has an idea how to get Redmine working again, I would be very grateful.
Last lines of redmine production log:
Jenkins Groovy Declarative Script fails to publish files to Confluence with 'bad types' error
Is anyone able to make sense of this error? This script to publish files to Confluence during Jenkins jobs was working just fine as recently as a week ago. Now it is throwing errors and my googling hasn't been able to reveal what it's complaining about.
The code (Groovy in a declarative script):
And the error:
e: Confluence version is 7.4.8 btw
Accessing web page (Jira, Confluence) via Rstudio with httr
I would like to download content from Jira/Confluence via Rstudio with package httr, namely using function GET. However i am having the following problem. If i open http page in Chrome, chrome does some authomatic company authentication, and afterwards shows me full content (api content). But when i try to do the same with GET function i get success, but the content says like it cannot go through the authentication of the company.
So main problem is, manually in chrome works, via R doesnt. Does anyone have any idea on how to tell R to do before extracting information from web page this automatic authentication?
Is there a good example of recursing through the results of a Jira Macro in confluence and conditionally formatting rows?
I have a set of Jira Epics and stories that look like this:
1. Epic1
  1. Story1
  2. Story2
2. Epic2
  1. Story3
  2. Story4
I've been using the Table Formatter Macro to wrap a Jira Issues Macro to customize the formatting of the Jira issues table that is returned, but I repeat it for every Epic.
E.g. for Epic1, I have the following SQL in the Table Formatter macro
Then I copy that Jira Macro, change the JQL to include Story1 and Story2, and have a different SQL to format those a little differently.
I have about 30 Epics with many stories under them. It's a pain when I have to change formatting to edit all Macros, or view the HTML and Search and Replace.
Ideally, I could provide 1 JQL that returns the whole Jira tree, if it's issue type Epic, it could use FormatWiki in a certain way, then if Story issue type, use FormatWiki in a different way.
I just haven't been able to find a way to traverse the results of a Jira Query and conditionally return the formatted content.
Any help would be very much appreciated!