Removal notice (applicable for Markdown from a URL macro):

Please note that the URL user and URL user password parameters were removed in 3.8.2 (see Deprecation notice: URL user and URL user password parameters). We recommend using profiles to access external data.

The Markdown from a URL macro renders Markdown content from URLs or from profiles. Profiles are a means of retrieving data from other external sources such as other applications or even databases.

Markdown content containing links or images referring to a public location can be accessed and then rendered. Currently, any links or images that refer to a private repository, or a location that must be logged in to, cannot be accessed and thus, rendered.

Points to remember!

Only raw URLs must be given in either, the URL field in profiles or the URL to markdown file field, in the macros. 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.
It is recommended to specify absolute URLs to access files from public locations and to use profiles to access files from private sources. For example, a raw URL that can access a Markdown file in a public Bitbucket repository is valid. But to render a Markdown file located in a private repository, we recommend using a profile.
Profiles are a means to access and retrieve contents from external applications such as Bitbucket, GitLab or GitHub. A profile already contains the base URL and the required credentials (user credentials or an access token) to access the relevant application.
This method allows multiple users to access a profile across pages and instances of the macro.

Parameters

Macro editor label	Parameter	Default	Description
Profile	profile		Specify a profile to be used with the macro. Administrators set up profiles to connect to other applications such as GitHub or GitLab. Profiles contain a basic set of parameters used to access a remote location such as the type of URL, user credentials, and so on. Some profiles may be restricted. Since 2.0. Contact your administrator to know more about the profiles used in your instance. If a profile is specified, it is recommended to provide the relative path to the location of the Markdown file to be rendered.
URL to Markdown file	url		Enter the relative path to the Markdown file to be displayed. If a valid path is entered here, the macro accesses the given location and processes the Markdown content accordingly. A profile comprises a base URL and other credentials that are required to access a specific application. These details point to the actual location where the required Markdown file is available. The contents are then accessed and displayed through the macro. For Markdown files available on apps linked to Confluence, entering the username and password parameters may not be necessary. If you are rendering the file in the Markdown macro for the first time, you are asked to authorize the app via Click to authorize link. For subsequent requests, the app works seamlessly. File permissions are applied based on the user profiles and respective levels of access in the linked app. To know more about linking apps with Confluence, refer to Application links. Since 3.4 Specify only raw URLs referring to a Markdown file in a public location (that does not require to be logged in) here! 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. If an absolute URL is entered here, the macro reads content from the specified URL. If a profile is also specified, the macro ignores the given profile and processes the Markdown content through the given URL. URLs are processed using a fixed precedence explained as follows: If the given URL is linked to a specific application like Bitbucket, GitLab, or GitLab with application links, the macro does not require any user credentials, and processes and renders the given Markdown file. If Profile is specified, the macro appends the URL given here with the URL specified in the profile configuration, and accesses the location to render the required Markdown file. Lastly, if application link or profile is not specified, the given URL is processed as-is and the required Markdown file is rendered.
URL user	user		Enter the user name for the given URL to access the required Markdown file. Removal notice (applicable for Markdown from a URL macro): Please note that the URL user and URL user password parameters were removed in 3.8.2 (see Deprecation notice: URL user and URL user password parameters). We recommend using profiles to access external data.
URL password	password		Enter the user password for the given URL to access the required Markdown file. Removal notice (applicable for Markdown from a URL macro): Please note that the URL user and URL user password parameters were removed in 3.8.2 (see Deprecation notice: URL user and URL user password parameters). We recommend using profiles to access external data.
URL connection timeout	timeout		Enter time in milliseconds such that URL connections does not disconnect before getting data. Use this to increase the access time needed for slow connections. Note that if a zero is given the connection may wait infinitely.
File encoding	encoding	UTF-8	Specify the encoding for an external file, if different from default system handling.
Show URL	showURL	Off	Enable this option to display the absolute path of the Markdown file. The URL given in the URL to markdown file parameter is appended to the URL given in the specified profile to form the absolute path of the required Markdown file.

It is mandatory to specify either a profile or a URL for this macro.

How profiles and URLs are processed in the macro

Depending on the values provided for the Profile and URL to Markdown file parameters, the following process applies:

Is Profile given?

(Y - Yes, N - No)

Is URL to markdown file given?

(Y - Yes, N - No)

Macro behavior

Y

N

Accesses the URL specified in the profile through the pre-configured information.

N

Y

Accesses the URL specified and renders the Markdown content as required.

Y

Appends the URL mentioned in the URL to Markdown file parameter to the URL configured in the profile. Thus, the macro creates an absolute path to the Markdown file. If this path is not valid, a network error message is displayed. Contact your Confluence administrator to know how you can resolve the issue.

Common parameters

Macro browser label Default Description Macro parameter

Id generated value Enter the HTML ID of the div element surrounding the content. id

Find regex patterns

Enter a comma-separated list of regex patterns to dynamically update the output for Markdown content with find and replace logic.

Example: (href=)(/display)

find

Replacement strings

Enter a comma-separated list of positions to search for patterns in the output content. Note that the positions are indexed beginning at "1". If a comma is a part of the search, use single quotes (') around it.

Example: http://www.google.com/$1

replace

Allow HTML tags false Enable this option to allow embedded HTML tags in Markdown macros. This is a potential security exposure, so it is disabled by default. The Confluence administrator must explicitly authorize users or groups using Macro Security for Confluence. allowHtml

Hard wrap newlines

true

Determines how newlines are treated. This is a GitHub Flavored Markdown extension that defaults to being turned on.

Text	Hard wrap (selected)	Soft wrap (Hard wrap not selected)
Roses are red Violets are blue	Roses are red Violets are blue	Roses are red Violets are blue

hardwrap

Anchor links for headings false Enable this option to automatically add anchor links for headings. headerLinks

Table class

@default

Enter the CSS to be applied to rendered tables.

@default - Apply default Confluence table class to rendered tables.
@none - Do not apply any style for rendered tables.
userDefinedClass - Use a custom user-defined style for rendering Tables.

tableClass

Basic use

This macro can be deployed using one of the following methods:

Selected from the macro browser	Markdown from a URL
Markup shortcut	{markdown-url}

Screenshot

Example using a public Bitbucket file: https://bitbucket.org/bob_swift/gint/raw/tip/README.md