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. You can read more about profiles from this link.
The Markdown content is rendered based on the permissions of the page and/or space. Any attachment available in a public location can be accessed and the Markdown content can be rendered. Currently, any links or images in Markdown content referring to a private repository, or a location that must be logged in to, cannot be accessed and thus, rendered; watch this ticket for updates.
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.
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} |
Parameters
Macro specific parameters
| Macro Editor Label | Default | Description | Macro Parameter |
|---|---|---|---|
| Profile | Enter a profile name. 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.
| profile | |
| URL to markdown file | 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.
| url | |
| URL user | Enter the user name for the given URL to access the required Markdown file. | user | |
| URL password | Enter the user password for the given URL to access the required Markdown file. | password | |
| URL connection 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. | timeout | |
| File encoding | UTF-8 | Specify the encoding for an external file, if different from default system handling. | encoding |
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 | 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
The following parameters are available for all the Markdown macros:
Enter a comma-separated list of regex patterns to post-process the output for Markdown content with find and replace logic. Example: (href=)(/display) Enter a comma-separated list corresponding to find patterns via index position in the list. These are single quote entries containing a comma. Example: $1$base_url$2 Select this option to display content on separate lines. This is a GitHub Flavored Markdown extension and is selected by default. Specify the table class (CSS) to apply to render tables. Currently, Confluence Cloud does not support the use of custom user-defined styles.Macro Editor Label Default Description Macro Parameter Find regex patterns find replace Allow HTML tags false Select this option to allow HTML tags in the macro body. The option is deselected by default. allowHtml Hard wrap newlines true 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 Table class @default tableClass
Screenshot
The following example uses an absolute URL in URL to markdown file of the macro settings:
