AsciiDoc-Bootstrap

Macros

http://www.methods.co.nz/asciidoc/userguide.html#_macros

Table of Contents

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:images/screenshots/bs2default-navbar-default-jumbotron-toc2.png[options="responsive"]

Renders:

images/screenshots/bs2default-navbar-default-jumbotron-toc2.png

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.

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

AsciiDoc-Bootstrap backend 3.1.0 support these four icon fonts. Valid iconsfont attribute values are : glyphicon, font-awesome, ionicons and icomoon.

A good location for iconsfontdir could be (outdir)/fonts. See also the File Structure of AsciiDoc-Bootstrap distribution.

The inline icon macro is similar to the inline image macro with two exceptions:

  • If the icons attribute has the value font, the macro will translated to a font-based icon.

    e.g: <span class="glyphicon glyphicon-calendar"></span>, <span class="fa fa-calendar"></span>, <span class="icon ion-calendar"></span>, or <span class="icomoon icon-calendar"></span>

  • If the icons attribute is not set or has the value image, the macro will insert an image (PNG format) into the document that resolves to a file in the iconsdir directory.

    e.g: <span class="image"><img width="48" height="48" alt="calendar" src="./images/icons/calendar.png"></span>

icon:<target>[<attributes>]

The contents of the icon <target> is displayed.

Icon macro attributes

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

Icon macro attributes when icons attribute is not set or has the value image

  • 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.

icon:calendar[] by Laurent Laville, published on November 21, 2013

With icons attribute set to font, and iconsfontdir set to location of Font-Awesome 4 distribution (css/ and fonts/ folders).

Renders:

by Laurent Laville, published on November 21, 2013

Here is another example that used Open Blocks design to display a simple blog. More concrete examples on our expo.

[role="timeline",citetitle="http://glyphsearch.com/"]
.icon:mobile[size="lg"] icon:tablet[size="2x"]
--
*GlyphSearch: Improving the Search for Icon Fonts*

http://glyphsearch.com/[GlyphSearch] is a site that allows you to search
Font Awesome, Glyphicons, and Ionicons simultaneously.
--
[role="timeline",citetitle="http://fontello.com/"]
.[yellow]#icon:font[size="5x"]#
--
*Fontello - icon font scissors*

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
--

GlyphSearch: Improving the Search for Icon Fonts

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

http://glyphsearch.com/

Fontello - icon font scissors

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/
All icon fonts that not support same icon names. Be advised that switching icon fonts may results of unexpected values.

About this document

How to build the source code
[https://raw.github.com/llaville/asciidoc-bootstrap-backend/master/docs/macros.asciidoc]
.