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

Please note that the URL user and URL password parameters are deprecated and will be removed on March 31, 2022. We recommend using profiles to access your data from remote locations.

This article discusses the recommended way of how URLs must be used in correlation with profiles in the Markdown from a URL macro. This page also contains more information about the URLs that can be given, the order used to process URLs, and finally, how URLs must be used with profiles in the macros.

You can connect to an external application or location through a URL and display relevant Markdown content on your pages. For this purpose, the macro allows you to use profiles and URLs to specify the complete path to access the required application data. The best practice is to specify both, profile and a relative path, in macro configuration. This way, you can access multiple locations through the same profile, and render Markdown content on your pages.

Contact your Confluence administrator to know which profiles are available in your instance.

Click any of the links to know more:

URLs in macros

First, it is important to understand how the macro processes profiles and URLs. A URL provided in a macro can be:

an absolute URL that can be used to access the relevant Markdown file,
a relative path to the actual location of the file to be rendered, or
an application link (a link between Confluence and an external application such as Bitbucket, GitLab, or GitHub).

Precedence in URL processing

URLs given in the macros are processed in the following order as explained:

Priority given	URL type	Description
1	Application links	If the given URL is linked to a specific application like Bitbucket, GitLab, or GitLab, the macro does not require any user credentials, and processes and renders the given file. Refer to this article for information about application links.
2	Profiles	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 file.
3	Simple URLs	Lastly, if no application links or profiles were given, the URLs are processed as-is and the required file is rendered.

Importance of URLs with respect to profiles

The correlation between URLs and profiles with respect to the macro can be explained as:

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. To resolve this issue, contact your Confluence administrator for more information.

How it all works

Profile configuration

For this example, let’s assume the profile has the following values specified:

Here, the profile is to be linked with GitLab and the base URL of the application is taken automatically in the URL field. This URL is editable and can be changed according to your requirement.
In the given screenshot, an Access token is provided whereas the User and Password parameters are left empty. This is because the access token works almost like a direct link to the specified URL and thus, does not require user credentials. See the profile configuration documentation for more information about access tokens.
See the Additional links section for more information about profile creation.

Macro editor settings

Create or edit a page, add the Markdown from a URL macro, and edit it to open the macro editor.
Select the relevant profile in Profile.
Enter a relative path (partial URL) to access the required file in URL to markdown file.

As mentioned, the macro appends the relative path in the URL to markdown file with the base URL given in the profile. If this absolute path is valid, the file is read and the Markdown content is displayed, else, a network error is displayed.
Save the macro and publish the page to see the content.

Points to remember:

Profiles are a means to access and retrieve contents from external applications such as GitHub, GitLab, and so on.
A profile already contains the base URL and the required credentials (user credentials or an access token) to access the relevant application.
If you specify a profile in the macro editor, enter a relative path in URL to markdown file to access the required file(s).
You must specify a profile or a URL in the macro editor.
If you specify an absolute URL in URL to markdown file, the macro can directly access the Markdown content in the specified path.

Markdown for Confluence

How to use URLs in Markdown from a URL macro