# Macros

http://asciidoc.org/userguide.html#_macros

# Linking to Local Documents

Hypertext links to files on the local file system are specified using the link inline macro.

    link:<target>[<caption>]

The link macro generates relative URLs. The link macro `<target>` is the target file name (relative to the file system location of the referring document). The optional `<caption>` is the link’s displayed text. If `<caption>` is not specified then `<target>` is displayed.

    link:get-started.html[]

Renders:

get-started.html

    link:get-started.html[Start]

Renders:

Start

If you want more enhancement and focus on specific link, you want probably to use buttons links as provided by Bootstrap.

It’s now possible with this major version 3 of AsciiDoc-Bootstrap backend.

Let’s restart our example, with the single link, and apply it a button style.

    link:get-started.html[role="primary"]

Renders:

get-started.html

Change the text

    link:get-started.html["Start Tour",role="primary"]

or with alternative

    link:get-started.html[caption="Start Tour",role="primary"]

Renders:

Start Tour

You have certainly understood that all button color style may be applied with the `role` attribute. (inverse, default, primary, info, success, warning, danger).

You want probably more than just a button. Adding an icon will improve again more the look and feel !

    link:get-started.html["Start Tour",role="info",icon="glyphicon-play-circle"]

Renders:

Start Tour

Icons are named with prefix glyphicon on Bootstrap 3, and with prefix icon on Bootstrap 2.

And finally, choose what side you want to put your icon.

    link:get-started.html["Whats wrong",role="danger",icon="glyphicon-remove-circle",options="right,white"]

Renders:

Whats wrong

On Bootstrap 2 icon color are black by default. So add white option to change it. This option is useless on Bootstrap 3.

# Images

Inline images are inserted into the output document using the image macro.

    image:<target>[<attributes>]

The contents of the image file `<target>` is displayed.

Image macro attributes

- The optional options attribute with value responsive provides a way for Bootstrap 3 to fluid IMG size. Images are not responsive by default.

It was not the case in Bootstrap 2. So this attribute is useless for this version.

    image::screenshots/bs2default-navbar-default-jumbotron-toc2.png[options="responsive"]

Renders:

Try several resolution and see what happens with or without responsive option.

# Icons

AsciiDoc-Bootstrap backend 3.1.0 introduces a new inline macro for inserting an icon at an arbitrary place in paragraph content.

Credit to AsciiDoctor GH-529 issue.
AsciiDoc-Bootstrap backend 4.0 has dropped this icon inline macro, to keep a better compatibility with other backends. Use then the image inline macro with additional attributes.

Right now we are blessed with many icon fonts that continue to grow with every release, like Glyphicons, Font-Awesome, Ionicons, and more again …

AsciiDoc-Bootstrap backend 4.0 support these three icon fonts. Valid `iconsfont` attribute values are : glyphicon, font-awesome, and ionicons.

Our inline image macro is similar to the standard Asciidoc inline image macro with one exception:

- If the `iconsfont` attribute is set, the macro will translate image to a font-based icon result.

    image:<target>[<attributes>]

The contents of the image `<target>` is displayed.

Our Image macro attributes

- The required iconsfont attribute tells which icons font to use. Possibles values are : glyphicon, font-awesome, ionicons.

- The optional size attribute scales the icon. Possible values are : lg (33% increase), 2x, 3x, 4x, 5x, 6x, 7x, 8x, 9x.

Standard Image macro attributes

- The optional title attribute provides a title for the icon.

- The optional width and height attributes scale the icon (image in png format) size and can be used in any combination. The units are pixels and default values are 48.

Here is an example that inserts a calendar icon in front of a blog entry and its published date.

    image:icons/font-awesome/calendar.png[alt="calendar",icon="calendar",size="4x",iconsfont="font-awesome"] by Laurent Laville, published on November 21, 2013

Renders:

by Laurent Laville, published on November 21, 2013

AsciiDoc-Bootstrap 4.0 did not used anymore the open block to simulate multi-columns. We used now the standard Bootstrap classes `col-md-*` and so on.

Here is another example that display two columns on medium device (greater than 992 pixels)

AsciiDoc Code

    [role="col-md-3"]
    ====
    [panel]
    --
    *About*
    http://glyphsearch.com/[GlyphSearch]

    image:icons/font-awesome/mobile.png[alt="mobile",icon="mobile",size="lg",iconsfont="font-awesome"]
    image:icons/font-awesome/tablet.png[alt="tablet",icon="tablet",size="2x",iconsfont="font-awesome"]
    image:icons/font-awesome/laptop.png[alt="laptop",icon="laptop",size="3x",iconsfont="font-awesome"]
    image:icons/font-awesome/desktop.png[alt="desktop",icon="desktop",size="3x",iconsfont="font-awesome"]
    --
    ====

    [role="col-md-9"]
    ====
    *GlyphSearch: Improving the Search for Icon Fonts*

    GlyphSearch is a site that allows you to search
    Font Awesome, Glyphicons, and Ionicons simultaneously.
    ====

    unfloat::[]

About GlyphSearch

GlyphSearch: Improving the Search for Icon Fonts

GlyphSearch is a site that allows you to search Font Awesome, Glyphicons, and Ionicons simultaneously.

And another example with three columns on medium device (greater than 992 pixels)

AsciiDoc Code

    [role="col-md-2"]
    ====
    [yellow]#image:icons/font-awesome/font.png[alt="font",icon="font",size="9x",iconsfont="font-awesome"]#
    ====

    [role="col-md-8"]
    [quote,http://fontello.com/]
    ____
    *Fontello*

    This http://fontello.com/[tool] lets you combine icon webfonts for your own project. With fontello you can:

    * shrink glyph collections, minimizing font size
    * merge symbols from several fonts into a single file
    * access large sets of professional-grade open source icons
    ____

    [role="col-md-2"]
    .About
    ****
    http://fontello.com/[Fontello], the icon font scissors.
    ****

    unfloat::[]

> Fontello

> This tool lets you combine icon webfonts for your own project. With fontello you can:

> - shrink glyph collections, minimizing font size

> - merge symbols from several fonts into a single file

> - access large sets of professional-grade open source icons

> http://fontello.com/

About

Fontello, the icon font scissors.

All icon fonts do not support same icon names. Be carefull if you switch to another icons font.

# Progress bars

AsciiDoc-Bootstrap backend 4.0.0 introduces a new inline macro that implement the Bootstrap Progress Component.

Stacked progress bar is not supported.

    progess:<target>[<attributes>]

The contents of the progress `<target>` is used to draw percent of progress bar completed (Must be numeric and between 0 and 100).

Progress macro attributes

- The optional caption attribute is the progress bar label.

- The optional role attribute is used as contextual class. Should be either `info`, `success`, `warning`, or `danger`.

- The optional striped attribute, with an empty content, is used to display striped effect progress bar.

- The optional animated attribute, with an empty content, is used to display animated effect progress bar.

There is no fallback strategy to build a progress bar with `html5` or any other backends.

Here are few examples :

Default progress bar at 55% complete

Progress bar with label

60%
Progress bar with contextual class

See more examples.