Confluence Markdown Import



Atlassian’s Confluence is a nice wiki platform, but it can be confusing at times when working with attachments and video. Of course, as a wiki platform, the whole point is to have the content on wiki pages, but there are all sorts of circumstances when attachments are needed regardless.

A script to import a named markdown document into Confluence. It handles inline images as well as code blocks. Also there is support for some custom markdown tags for use with commonly used Confluence macros. The file will be converted into HTML or Confluence storage markup when required. Markdown to Confluence Convertor. Recently in Confluence 4.0 the Wiki Markup Editor was removed for various engineering reasons.

In this post, I will detail some basic, and some advanced, lessons learned from using Confluence when it comes to attachments and video.

If it helps, you can think of a Confluence page as a folder on a hard drive. The attachments are located on the pages, so all attachments on a single page have to have a unique name and there is no way to create further subdivision among attachments on a page.

Confluence

You can drag-and-drop files to a page (you do not need to be in edit mode) to save them as attachments to that page. This way you can easily save multiple files at once. Combine this with a Gallery macro on a page and multiple image files to quickly create an album of images.

Advanced:You can create multiple Attachments macros on a page and have them display attachments based on file name patterns, labels, or location (so you can display attachments from multiple pages). The Browse button used for file upload on these macros gets slightly confusing, though, because you are not really uploading the content to the macro, but to the page, so the content you upload may not even be displayed by the macro.

There is version control in Confluence, although it is very basic. Any file you upload to a page with the same file name as an existing attachment becomes a new revision of the attachment. Old revisions can be accessed from the attachments list (Tools – Attachments).

Because of this, you may need to rename attachment from time to time. You can rename an attachment from the Properties menu of that attachment from the attachments list. You can also move attachments from one page to another and add comments to attachments from the same menu.

Advanced: If you remove a page in Confluence, an administrator can return it. If you remove an attachment, it is gone for good. It is sometimes a good idea to not give all users the rights to remove attachments, but instead create a specific page, let’s call it Trash, where the users can move unneeded attachments. This page can then be periodically emptied.

If your attachments are Office documents, you can place an Office Word/Excel/Powerpoint macro on a page to display the content directly on the page. On top of the content there will be an Edit in Office button which will launch the appropriate application to edit the document. When you save it, it is saved as a new revision of the attachment in Confluence. The same button is available in the attachments list if you choose not to display the content of the file on the page.

You can also import a Word document to Confluence as a page instead of an attachment (Tools – Import Word Document).

Advanced: Importing a Word document function can be used to delete a page and all its child pages (which, ironically, cannot be done in any other way). Instructions on how to do that can be found here.

Confluence has a rather good macro, Widget Connector, with which you can embed video from Youtube and Vimeo, among other things.

However, sometimes you just need to upload the video files locally. This is a not-so-good part of Confluence. The file size limit for attachments can be configured by the Confluence administrator: the default size is 10 MB (we use 24 MB to give a bit more options while still limiting the size – it can go up to gigabytes).

You can upload video files as attachments and display them on the page with the Multimedia macro. Unfortunately, the Multimedia macro has two major drawbacks: it often fails to recognize the resolution of the video (you need to configure it manually) and it loads the entire video file before you are able to play it.

Configure the Multimedia macro to be slightly taller than the video file to ensure that the play controls at the bottom are visible. For example, for a 1280×720 video, set the size of the Multimedia macro to 1280×740.

Because the video is loaded in its entirety before playing, make the video file as small as possible. My preferred tool to do this is Handbrake, and here are some very simple instructions on how to use it. I also prefer to resize the video to a bit smaller size, which can also be done with this software. As an example, I transcoded a Full HD (1920×1080) video taken with a tablet into 1280×720 resolution and MPEG-4 encoding without any other changes to quality, and it resulted in file size reduction from 166 MB to 12 MB. That’s pretty significant, I would say.

Confluence is not a content management system. However, in many use cases it is possible to live with the basic features it offers as long as you know a little bit about how it works. The methods detailed above are some of the things I get asked about the most, and knowledge of these simple methods usually helps.

Of course, if you really need to manage lots of file content, you need a content management system. However, the vast majority of content can really be handled as wiki pages once you have the mindset to do so, and the little that cannot, can usually be handled even with the basic tools offered by Confluence.

Photo: Atlassian party by Dmitry Baranovskiy @ Flickr (CC, cropped)

Confluence Md File

Repositories Import and Export

Note: Importing repositories is supported for all users whereas exporting repositories is only available for non-SaaS users.

To access import and export of repositories, in the Administration module, select Artifactory |Import & Export | Repositories.

Export

When exporting, you need to specify the following parameters:

Import Markdown Into Confluence

Target Local Repository
You can specify a single repository to export, or All Repositories
Export Path on Server
The export target directory on your server
Exclude Metadata
When set, repository metadata is excluded from the export. (Maven 2 metadata is unaffected by this setting)
Create .m2 Compatible Export
When set, includes Maven 2 repository metadata and checksum files as part of the export
Output Verbose Log

When set, lowers the log level to 'debug' and redirects the output from the standard log to the import-export log.

Monitoring the log

Import

To disable the system import option, set the artifactory.system.import.enabled property in the artifactory.system.propertiesfile to false.

To access import and export of your entire system, in theAdministrationmodule, selectImport & Export | System


You can import repositories from a server-side folder, or by zipping a repository and uploading it to Artifactory.

When importing, you need to specify the following parameters:

Target Local Repository
You can specify a single repository to import, or All Repositories. The repository layout should be different depending on your selection. Please refer to Import Layout.
Server Path for Import
The import source directory on your server
Repository Zip File
Applicable when importing repo from zip file. Drop the repository zip file
Exclude Metadata
When set, repository metadata are excluded from the import
Output Verbose Log

When set, lowers the log level to 'debug' and redirects the output from the standard log to the import-export log.

Monitoring the log

Don't exclude metadata for Docker

To work with a Docker repository, it must have its metadata intact. Therefore, when importing to/exporting from a Docker repository make sure that Exclude Metadata is not checked.

Confluence Markdown Import

Importing into a Remote Repository Cache

You can take advantage of remote repositories you have already downloaded to your local environment, and import them directly into a local repository.

For example, you can take your local Maven repository (usually located under ~/.m2) and upload it into Artifactory so that all the artifacts you have already downloaded are now available on the server.


Import Layout

An imported repository needs to be formatted using a Maven 2 repository layout.

When importing a single repository, the file structure within the import folder (or zip file) should be as follows:

When importing all repositories, the file structure within the import folder should be as follows:

Confluence Markdown Important

Confluence Markdown Import

When importing all repositories, you need to ensure that the names of the directories representing the repositories in the archive match the names of the target repositories in Artifactory.


System Import and Export

Confluence Api Import Markdown

Artifactory maintains all security entities (users, groups, permissions and access tokens) when doing a system import.

Note: The System Import and Export feature is not available for Artifactory Cloud users.

To access import and export of your entire system, in the Administration module, select Artifactory | Import & Export | System.

Confluence api import markdown
Export Path on Server
The target directory for the exported files. You may browse your file system to select the directory
Exclude Content

Export: When set, repository binaries are excluded from the export.

Import: When set, binaries and metadata are excluded from the import. Only builds and configuration files are imported.

Exclude Metadata

When set, repository metadata are excluded from the import/export.
(Maven 2 metadata is unaffected by this setting)

Docker repositories must have metadata

For Docker repositories to work they must have their metadata intact. Therefore, if you have Docker repositories, make sure that Exclude Metadata is not checked when doing a system export or import.

Create .m2 Compatible Export
When set, includes Maven 2 repository metadata and checksum files as part of the export
Create a Zip Archive (Slow and CPU Intensive!)
When set, creates and exports to a Zip archive
Output Verbose Log

When set, lowers the log level to 'debug' and redirects the output from the standard log to the import-export log.

Monitoring the log

The source/target of the import/export operations are folders (Zip archives are not recommended) on the Artifactory server itself.

You can use the built-in server-side browsing inside Artifactory to select server-side source/target folders:

Importing or exporting a large amount of data may be time consuming. During the import/export operation you can browse away from the page and sample the System Logsto monitor progress.

Markdown

Confluence Markdown Importance

System Import and Export for an HA Cluster

When performing a system export and subsequent import for an HA cluster, you need to follow the procedure below to ensure that the cluster is able to correctly synchronize its nodes.

Setting a Target Artifactory

  1. Perform a normal system export from the source cluster as described above.
  2. In the target cluster, keep only one node running, and perform a graceful shutdown to all the rest of the nodes
  3. Perform normal system import to the target cluster (which now has only one node running) as described above.
  4. Perform a graceful shutdown of the running node and then restart it
  5. For each additional node:
    1. Delete the following folders

      • $JFROG_HOME/artifactory/var/etc/access

      • $JFROG_HOME/artifactory/var/etc/security

      • $JFROG_HOME/artifactory/var/etc/ui

      • $JFROG_HOME/artifactory/var/etc/plugins

    2. Copy the $JFROG_HOME/artifactory/var/etc/security/master.key from the running node to the additional nodes.

      Master Key

      Copying the $JFROG_HOME/artifactory/var/etc/security/master.key is a critical step in the import process.

    3. Start up the additional nodes.

Once you have completed the import, we recommend verifying that your HA cluster is up and running normally as described in Testing your HA Configuration.

Confluence Import Markdown From Bitbucket