...

Markdown

1. Add the Markdown macro to the required Confluence page.

2. In cloud, paste your content into the macro editor or macro body, and in server, write/paste the content directly in the macro body.

   

3. Click Insert and publish the page.

Differences between server/DC and cloud macros

Feature	Server/DC	Cloud
Macro editor

...

Markdown from a URL

1. Add the Markdown from a URL macro to the required Confluence page. In cloud, the macro is displayed as a sidebar in the right (see the image in the table below).

2. Add your URL to the URL parameter. Make sure your URL is pointing to raw Markdown!
   In the cloud version, the changes made to the editor are always saved automatically. In server/DC, click Insert to add the macro to the page.

3. Publish the page to see the content.

Differences between server/DC and cloud macros

Feature	Server/DC	Cloud
Macro editor

Server/DC macro parameters

Accessing Markdown content with this macro

The steps to access your content using the Markdown from a URL macro are as follows:

1. Create the security token from the relevant hosting type. This is explained in detail in the Configuration screen. Administrators create these tokens which are then populated in the Security token dropdown list.

2. Enter the file path to the Markdown file to be displayed.

Before you begin

• Before you enter the URL for a repository, ensure that it is a raw URL.
  A raw URL is defined as the part of the URL following the domain information and includes the query string, if present. For example, in the URL string http://www.contoso.com/articles/recent.aspx , the raw URL is /articles/recent.aspx. 

• How to identify if a file is valid for the macro?

  Paste the file link into your browser's address bar. If the actual code is displayed in the browser, it is considered to be invalid or in an incorrect format. If the file downloads to your system, the macro can process the file and its contents.

• Know what is a complete URL.

  • A typical path for the raw file on GitLab looks like:
    /projects/:id/repository/files/:file_path/raw

  • Since the host address begins with:
    https://gitlab.com/api/v4

  • The complete URL, in this example, looks like: 
    https://gitlab.com/api/v4/projects/:id/repository/files/:file_path/raw?ref=master

• For private Bitbucket repositories (from third party applications):

  Use the following URL path to connect to a private Bitbucket repository if logging in from third party applications such as Google:

  https://api.bitbucket.org/2.0/repositories/$workspace/$repo/src/$commit/$filepath

  The path to be specified in the URL parameter looks like the following example:

  https://api.bitbucket.org/2.0/repositories/appfire/ac-app-dist/src/17f199444d1386c543ac642e9155b396aaeca403/README.md

Example

Let’s assume that you want to display a file from a private Bitbucket repository (sample URL: https://api.bitbucket.org/2.0/repositories/bobswift-test/private_test_repo/src/master/README.md).

...

If the selected token and the URL are valid, the specified Markdown file is displayed on the page. The process to display content from other hosting types are the same: select the security token and provide the raw URL.

Cloud macros

There are three cloud macros available with this app. They are:

• Markdown from Github

...

• Markdown from Bitbucket

• Markdown from Gitlab

Adding a cloud macro to a page

The process of adding a macro to a page is the same for all macros.

1. Add either of the macros to the required Confluence page.

2. Select the Github Token, Bitbucket Token, or, the Github tokenToken from the list and enter the path of the Markdown file to be displayed in URL.

   Image Removed

   Administrators configure these tokens from the Markdown Extensions Configuration page.

3. Click Insert and publish the page.

Markdown from Bitbucket - Cloud only

1. Add the Markdown from Bitbucket macro to the required Confluence page.

   Image Removed

2. Select the token in Bitbucket token and URL in the Enter URL tab. Click Check to check the connection.

3. Enter the required information in the Enter Repository Settings tab and click Insert.

4. Publish the page to view the accessed data.

The following table explains each parameter in the macro editor:

...

Parameter name

...

Description

...

Enter URL tab

...

Bitbucket token

...

Specify the Bitbucket account to be accessed. Administrators configure these tokens from the Markdown Extensions Configuration page. This parameter is common to both the tabs.

...

URL

...

Enter the full path to the required Markdown file. This is a mandatory field. If a URL is provided, the settings in the Enter Repository Settings tab can be skipped.

Click Check to test the connection and accessibility.

...

Enter Repository Settings tab

...

Username/Organization Name

...

Enter the username or organization name under which the repository is hosted. For example: mohamicorp

This is a mandatory field.

...

Repository

...

Specify the repository to be accessed. For example: search-for-stash

This is a mandatory field.

...

Branch or Commit Hash

...

Specify the branch from where the file is available. For example: master

This is a mandatory field.

...

File Path

...

Enter the directory path where the file is hosted. For example: src/main/resources/README.md

This is a mandatory field.

Markdown from Gitlab - Cloud only

1. Add the Markdown from Gitlab macro to the required Confluence page.

   Image Removed

2. Select the token in Gitlab token and URL in the Enter URL tab. Click Check to check the connection.

3. Enter the required information in the Enter Repository Settings tab and click Insert.

4. Publish the page to view the accessed data.

Each of the macros look similar and have similar parameters. For example, a Markdown from Bitbucket macro is as follows:

...

Common parameters

The only difference between the macros is the parameter where you must select the token. The following table explains each parameter in the macro editor:

Additional resources

• Configuring for Cloud

• Migration guide