URL Macro
If you’re familiar with the AsciiDoc syntax, you may notice that a URL almost looks like an inline macro. All that’s missing is the pair of the trailing square brackets. In fact, if you add them, then a URL is treated as an inline macro. We call this a URL macro.
This page introduces the URL macro, when you would want to use it, and how it differs from the link macro.
From URL to macro
To transform a URL into a macro, add a pair of square brackets to the end of the URL. For example:
https://asciidoctor.org[]Since no text is specified, this macro behaves the same as an autolink. In this case, the link automatically gets assigned the “bare” role.
When the URL is followed by a pair of square brackets, the URL scheme dually serves as the macro name.
AsciiDoc recognizes all the URL schemes for autolinks as macro names (e.g., https).
That’s why we say “URL macros” and not just “URL macro”.
It’s a family of macros.
With the exception of the mailto macro, all the URL macros behave the same, and also behave the same as the link macro.
So why might you upgrade from a URL to a URL macro? One reason is to force the URL to be parsed when it would not normally be recognized, such as if it’s enclosed in double quotes:
Type "https://asciidoctor.org[]" into the location bar of your browser.The more typical reason, however, is to specify custom link text.
Custom link text
Instead of displaying the URL, you can configure the link to display custom text. When the reader clicks on the text, they are directed to the target of the link, the URL.
To customize the text of the link, insert that text between the square brackets of the URL macro.
Chat with other Fedora users in the irc://irc.freenode.org/#fedora[Fedora IRC channel].Since the text is subject to normal substitutions, you can apply formatting to it.
Ask questions in the https://chat.asciidoc.org[*community chat*].Link attributes
You can use the attribute list to further customize the link, such as to make it target a new window and apply a role to it.
Chat with other AsciiDoc users in the https://chat.asciidoc.org[*project chat*^,role=green].To understand how the text between the square brackets of a URL macro is parsed, see attribute parsing.