This article discusses the recommended way of how URLs must be used in correlation with profiles in the Markdown from a URL macro. The best practice is to specify both, profile and a relative path, in the macro's configuration. In this way, you can access multiple locations through the same profile and render Markdown content on your pages.
Description
With the Markdown from a URL macro, you can connect to an external application or location through a URL and display relevant content on your page. For this purpose, the macro allows you to use profiles and URLs to specify the complete path to access the required application data.
Contact your Confluence administrator to know which profiles are available in your instance.
First, it is important to understand how the macro behaves with profiles and URLs. 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 | Y | Appends the URL mentioned in the URL to markdown file parameter to the URL configured in the profile. Thus, the macro creates a relative 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 the macro works
Create or edit a page and add the Markdown from a URL macro.
Edit the macro and the macro editor appears.
Enter a profile name in Profile. For this example, let’s assume the profile has the following values specified:
Here, the profile is linked to GitLab and the URL shown is the base URL of the application that the macro fills automatically. See the 70629097 section for more information about GitHub and GitLab profile creation.
Create or edit a page, add the Markdown from a URL macro, and, edit it to open the macro editor.
Enter a relative path (partial URL) to an attachment 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 path is valid, the file(s) are 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 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 accesses the content in the specified path.
- Take a look at the existing documentation such as the user guide and the admin guide to know more about the macro itself and its usage.
