Versions Compared

Old Version 1

changes.mady.by.user Smita Nair

Saved on

compared with

New Version Current

changes.mady.by.user Smita Nair

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Updated content as per MARK-371

This article contains information about each macro available in the app.

You can pull Markdown from other applications like GitHub, Bitbucket, or GitLab, or, from a URL, or directly in the macro body. You can find information about both cloud and server/datacenter (DC) versions here.

Feature

Server/DC

Cloud

Authorizing app to access data

You must create a personal access token to be able to access your data. Read more in the Configuration page.

You need to authorize the app to be able to access your data stored in other applications. Read more in the Configuration page.

Adding a macro to the page

Image AddedmdExt_cld_macrosList.pngImage Added

Select any of the links to learn more:

  • Markdown

  • Markdown from Github

  • Markdown from Bitbucket

  • Markdown from Gitlab

  • Markdown from a URL

@How to use

You can pull Markdown from Bitbucket, from a URL, or through direct entry.

...

Table of Contents
minLevel1
maxLevel6
include
outlinefalse
indent
styledefault
exclude
typelist
class
printablefalse

Markdown

  1. Add the Markdown macro to the required Confluence page

...

...

  1. .

  2. In cloud, paste your content into the macro editor

...

  1. or macro body, and in server, write/paste the content directly in the macro

...

  1. body.

    Image Added

  2. Click Insert and publish the page.

Differences between server/DC and cloud macros

Feature

Server/DC

Cloud

Macro editor

Image AddedImage Added

Server/DC macro parameters

Parameter name

Description

Enable extended Markdown properties:

Select the checkbox to use a different parser, flexmark-java, to display Markdown content on your page. For more details about the parser, read the flexmark-java article.

Linkify Headers

Select the checkbox to allow headers in your content to be clickable.

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

...

Markdown from Github

Now simply select Markdown from Github on the macro page and select your desired token:

...

Markdown from Bitbucket

Now simply select Markdown from Bitbucket on the macro page and select your desired token:

...

Here's a breakdown of each field:

...

Field

...

Description

...

Username/Organization Name

...

The username or organization name in which the repository is hosted under. For example, if the URL for your repository was:

https://bitbucket.org/ mohamicorp/search-for-stash

The username would be mohamicorp

...

Repository

...

The username the repository is hosted under. For example, if the URL for your repository was:

https://bitbucket.org/mohamicorp/ search-for-stash

The repository would be search-for-stash

...

Branch or Commit Hash

...

The Branch which you want to pull documentation from. A good example is master

...

File Path

...

The directory the file is hosted under. A good example might be:

src/main/resources/README.md

Markdown from Gitlab

Now simply select Markdown from Gitlab on the macro page and select your desired token:

...

Here's a breakdown of each field:

...

Field

...

Description

...

URL

URL of the markdown file you want to get pulled to Confluence. Can be a link to either regular or raw file. If URL is provided configuration bellow is not required.

  1. parameter. Make sure your URL is pointing to raw Markdown!

...


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

  2. Publish the page to see the content.

Differences between server/DC and cloud macros

Feature

Server/DC

Cloud

Macro editor

Image AddedmdExt_cld_macro_URL.pngImage Added

Server/DC macro parameters

Parameter name

Description

URL

Enter the URL of the Markdown file to be rendered. Ensure the URL points to the raw Markdown file.

Enable extended Markdown properties:

Select the checkbox to use a different parser, flexmark-java, to display Markdown content on your page. For more details about the parser, read the flexmark-java article.

Linkify Headers

Select the checkbox to allow headers in your content to be clickable.

Security token

Select the token to be used to access the required Markdown file at the relevant location. Administrators configure the tokens in the Configuration screen.

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

On the relevant page:

...

  1. Add the macro, and select the required security token.

  2. Enter the URL of the required Markdown file.

  3. Select/deselect the Enable extended Markdown properties: and/or Linkify Headers as required.

  4. Insert the macro and publish the page.

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 Token from the list and enter the path of the Markdown file to be displayed in URL.

  3. Click Check to check the connection.

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

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

Parameter name

Description

Enter URL tab

Github Token
Bitbucket Token
Gitlab Token

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

URL

Enter the URL of the Markdown file to be displayed. The URL can be a link to either a regular or a raw file. If a URL is provided, the settings in the Enter Repository Settings tab can be skipped.

For example: https://gitlab.com/mohami/smarter-search-for-bitbucket/-/blob/master/README.md

This is a mandatory field.

Enter Repository Settings tab

Username/Organization Name

The Enter the username or organization name in under which the repository is hosted under. For example, if the URL for your repository was:

https://gitlab.com/mohami/smarter-search-for-bitbucket

The username would be mohami

Repository

The username the repository is hosted under. For example, if the URL for your repository was:

https://gitlab.com/mohami/: mohami

This is a mandatory field.

Repository

Specify the repository name to be accessed. For example: smarter-search-for-bitbucketThe repository would be smarter-search-for-bitbucket

This is a mandatory field.

Branch or Commit HashThe

Branch which you want to pull documentation from. A good example is masterEnter the branch name where the file is located. For example: master

This is a mandatory field.

File Path

The Enter the directory path where the file is hosted under. A good For example might be: src/main/resources/http://README.md

This is a mandatory field.

Additional resources