Commit dd0ce583 authored by Dan Allen's avatar Dan Allen

remove obsolete files

parent 86776b9d
= AsciiDoc Elements
There are two kinds of elements in AsciiDoc, block elements and inline elements.
[#block-element]
== Block elements
A [.term]*block element* is stacked vertically (by line) above or below other block elements.
Block elements are typically referred to simply as [.term]*blocks*.
Examples of blocks include sections, paragraphs, lists delimited blocks, tables, and block macros.
Blocks are easy to identify because they're usually separated from other blocks by a blank line (though not always required).
Some blocks, such as sections and delimited blocks, can nest other blocks inside of them.
Every block can have one or more lines of block metadata.
This metadata can be in the form of block attributes, a block anchor, or a block title.
These metadata lines should be directly adjacent to the block itself.
[#inline-element]
== Inline elements
An [.term]*inline element* performs an operation on a span of content within a <<block-element,block element>>.
Inline elements include inline macros such as the icon macro (`icon:[]`) and xref macro (`<< >>`, `xref:[]`), attribute references, and text marked up by inline formatting (italic, bold, etc.).
= Font-Based Icons
:url-fontawesome-icons: https://fontawesome.com/icons?d=gallery
Asciidoctor can use the Font Awesome icon set.
You can see the available icons and their names on the {url-fontawesome-icons}[Font Awesome icons page^].
Using the Font Awesome icons requires online access by default.
IMPORTANT: The default CSS stylesheet is required when using font-based icons.
== Use the Font Awesome icons
To use Font Awesome's icons in your document, set the value of the `icons` document attribute to `font` in the document header.
[source]
----
= Document Title
:icons: font <.>
icon:tags[] ruby, asciidoctor <.>
----
<.> Set `icons` to `font` to use the Font Awesome icons.
<.> Enter the name of the Font Awesome icon in the target field of the inline icon macro, followed by a pair of square brackets (`[]`).
.Result: Use Font Awesome tags icon
icon:tags[] ruby, asciidoctor
When font-based icons are activated, Asciidoctor adds a reference to the Font Awesome stylesheet and font files served from a CDN to the document header:
[source,xml]
----
<link rel="stylesheet"
href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css">
----
Here's how the HTML converter converts the above syntax when the `icons` attribute is assigned the `font` value.
.Result: HTML output
[source,xml]
----
<div class="paragraph">
<p><span class="icon"><i class="fa fa-tags"></i></span> ruby, asciidoctor</p>
</div>
----
== Icon macro attributes for Font Awesome icons
The icon macro has a few attributes that modify the size and orientation of a Font Awesome icon.
These attributes are specific to Font Awesome and only apply to the HTML output when `icons` is assigned the `font` value.
`size`::
First positional attribute; scales the icon; values: `1x` (default), `2x`, `3x`, `4x`, `5x`, `lg`, `fw`
`rotate`::
Rotates the icon; values: `90`, `180`, `270`
`flip`::
Flips the icon; values: `horizontal`, `vertical`
=== Change the size of an icon
The first unnamed positional attribute is `size`.
For instance, to make the icon twice the size as the default, enter `2x` inside the square brackets.
[source]
----
icon:heart[2x]
----
This is equivalent to:
[source]
----
icon:heart[size=2x]
----
And this is how icon:heart[size=2x] displays.
The previous example emits the following HTML:
[source,html]
----
<span class="icon"><i class="fa fa-heart fa-2x"></i></span>
----
[TIP]
====
If you want to line up icons so that you can use them as bullets in a list, use the `fw` size as follows:
----
[%hardbreaks]
icon:bolt[fw] bolt
icon:heart[fw] heart
----
====
=== Rotate and flip an icon
To rotate and flip an icon, specify these options using named attributes:
[source]
----
icon:shield[rotate=90, flip=vertical]
----
The icon icon:shield[rotate=90, flip=vertical] is rotated 90{deg} and flipped vertically.
////
The previous example emits the following HTML:
[source,xml]
----
<span class="icon"><i class="fa-shield fa-rotate-90 fa-flip-vertical"></i></span>
----
////
== Link and window attributes
It's possible to add additional metadata to an inline icon.
The `link` and `window` attributes apply to both font-based and image-based icons.
`link`::
The URI target used for the icon, which will wrap the converted icon in a link
`window`::
The target window of the link (when the `link` attribute is specified) (HTML converter)
Here's an example of an icon with a link:
[source]
----
icon:download[link="https://rubygems.org/downloads/asciidoctor-2.0.10.gem"]
----
The previous example emits the following HTML:
[source,html]
----
<span class="icon"><a class="image" href="https://rubygems.org/downloads/asciidoctor-2.0.10.gem"><i class="fa-download"></i></a></span>
----
== Default font-based admonition icons
When font-based icons are enabled, Asciidoctor will draw the icons for the 5 built-in admonition types using Font Awesome.
To use the default font-based admonition icons for admonitions, set the value of the `icons` document attribute to `font` in the document header.
[source]
----
= Document Title
:icons: font
NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!
----
// We need to explain that the default admonition icons have different names (i.e., `icon-note` instead of `fa-note`, because they're built in to the stylesheet.
Asciidoctor will emit HTML markup that selects the appropriate font character from the Font Awesome font for each admonition block.
For instance, Asciidoctor selects the Font Awesome icon `icon-note` for `NOTE` admonition blocks.
.Result: HTML output when the icons attribute is set to font
[source,html]
----
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<i class="fa icon-note" title="Note"></i>
</td>
<td class="content">
Asciidoctor supports font-based admonition icons, powered by Font Awesome!
</td>
</tr>
</table>
</div>
----
This is how the admonition looks rendered.
NOTE: Asciidoctor supports font-based admonition icons, powered by Font Awesome!
The icons chosen are selected by the stylesheet.
The default stylesheet maps icons to the following 5 CSS classes:
* .admonitionblock td.icon .icon-note
* .admonitionblock td.icon .icon-tip
* .admonitionblock td.icon .icon-warning
* .admonitionblock td.icon .icon-caution
* .admonitionblock td.icon .icon-important
If you want to customize the icon or the color that is used, you'll need to provide a custom stylesheet or override the styles using a docinfo file.
Here's an example that shows how to change the icon for the note admonition to sticky note:
[source,css]
----
.admonitionblock td.icon .icon-note::before {
content: "\f24a";
color:black;
}
----
= Icons and the Icon Macro
Asciidoctor can display icons as text, images, or characters selected from an icon font.
== icons attribute syntax
How an icon is displayed is based on the value assigned to the document attribute `icons`.
By default, the document attribute `icons` is not set.
If `icons` isn't set, features that use built-in icons, such as callout numbers and admonition blocks, use their fallback text.
Admonitions are displayed with their label (e.g., CAUTION) and callout numbers are displayed as plain text.
However, Asciidoctor will still process any icon macros and look for icon files in the icons directory (`iconsdir`).
By default, `iconsdir` is set to [.path]_./images/icons/_.
//The icon file extension is set using the `icontype` attribute, which defaults to PNG (`.png`).
When the `icons` attribute is set, its value can be left blank or be `font`.
_empty_:: When `icons` is set and its value field is empty, Asciidoctor looks for icon images in the icons directory (`iconsdir`).
Additionally, the DocBook converter provides built-in images for the admonition and callout icons.
+
[source]
----
= Document Title
:icons:
----
`font`:: When `icons` is set and its value field is assigned `font`, the Asciidoctor HTML converter uses the Font Awesome icon set for admonition labels, callout numbers, and inline symbols.
DocBook does not support font-based icons, so the DocBook output is not affected if the value `font` is assigned to the `icons` attribute.
+
[source]
----
= Document Title
:icons: font
----
When an image or font-based icon isn't available, Asciidoctor displays the icon macro's fallback text.
== Icon macro syntax
An icon can be inserted at an arbitrary place in your content with the icon macro.
[source]
----
icon:file-name[]
----
Enter the file name of the icon in the target field of the icon macro, followed by a pair of square brackets (`[]`).
Depending on the value of `icons` and the converter, Asciidoctor will look for the icon file (e.g., [.path]_file-name_) in the icons directory (`iconsdir`) or in the font icon set.
The file extension (e.g., _.png_) doesn't have to be specified as long as it matches the value of the `icontype` attribute.
`icontype` is set to `.png` by default.
You can also assign one or more attributes to an icon.
[source]
----
icon:file-name[optional-attribute=value, optional-attribute=value]
----
Attributes are assigned inside the macro's square brackets (`[]`) in a comma-separated list.
The available attributes depend on the value assigned to the `icons` attribute.
////
.Relationship to the inline image macro
--
The inline icon macro is similar to the inline image macro with a few exceptions:
* If the icons attribute has the value font, the macro will translate to a font-based icon in the HTML converter (e.g., `<i class="icon-tags"></i>`)
* If the icons attribute does not have the value font, or the converter is DocBook, the macro will insert an image into the document that resolves to a file in the iconsdir directory (e.g., `<img src="./images/icons/tags.png">`)
The file resolution strategy when using image-based icons is the same used to locate images for the admonition icons.
The file extension is set using the `icontype` attribute, which defaults to PNG (`png`).
--
////
= Image Icons
To display icons using your own images, set the `icons` attribute to an empty value in the document header.
This strategy is recommended if you are converting to DocBook or you want an easy way to make HTML for viewing offline.
The DocBook toolchain provides images for the admonition and callout icons, which you can replace with your own custom icons.
If you use the inline icon macro, you'll need to provide the images for those icons.
== Using the inline icon macro with an image
An icon can be inserted at an arbitrary place in paragraph content with an inline macro.
Here's an example that inserts an icon named _tags_ in front of a list of tag names.
.Inline icon macro syntax
[source]
----
icon:tags[] ruby, asciidoctor
----
Here's how the HTML converter converts an icon macro when the `icons` attribute is not set or empty.
.Result: HTML output
[source,html]
----
<div class="paragraph">
<p><span class="image"><img src="./images/icons/tags.png" alt="tags"></span> ruby, asciidoctor</p>
</div>
----
Here's how it looks.
.Result: Inline icon macro
====
icon:tags[] ruby, asciidoctor
====
Here's how the DocBook converter converts an icon macro.
.Result: DocBook output
[source,xml]
----
<inlinemediaobject>
<imageobject>
<imagedata fileref="./images/icons/tags.png"/>
</imageobject>
<textobject><phrase>tags</phrase></textobject>
</inlinemediaobject> ruby, asciidoctor
----
When the image for an icon can't be located in the icons directory, Asciidoctor displays the icon macro's fallback text.
== Icon macro attributes for images
The attributes listed below are only apply when font-based icons are not in use.
`alt`::
The alternative text on the `<img>` tag (HTML backend) or text for `<inlinemediaobject>` (DocBook converter)
`width`::
The width applied to the image
`height`::
The height applied to the image
`title`::
The title of the image displayed when the mouse hovers over it (HTML converter)
`role`::
The role applied to the element that surrounds the icon
For example, here's how the icon color is specified by assigning it a role.
.Inline icon macro and role syntax
[source]
----
icon:tags[role="blue"] ruby, asciidoctor
----
.Result: Inline icon macro and role
====
icon:tags[role=blue] ruby, asciidoctor
====
The inline icon macro doesn't support any options to change its physical position (such as alignment).
== Link and window attributes
It's possible to add additional metadata to an inline icon.
The `link` and `window` attributes apply to both font-based and image-based icons.
`link`::
The URI target used for the icon, which will wrap the converted icon in a link
`window`::
The target window of the link (when the `link` attribute is specified) (HTML converter)
Here's an example of an icon with a link:
[source]
----
icon:download[link="https://rubygems.org/downloads/asciidoctor-2.0.10.gem"]
----
= Unicode Icons
You can use Unicode glyphs as icons.
== Use Unicode characters as admonition icons
Since Unicode characters are classified as text, *don't set the `icons` attribute*.
If the `icons` attribute is not set on the document, Asciidoctor outputs an admonition's label as text (e.g., CAUTION).
The text for this label comes from an AsciiDoc attribute.
The name of the attribute is `<type>-caption`, where `<type>` is the admonition type in lowercase.
For example, the attribute for a tip admonition is `tip-caption`.
Instead of a word, you can assign a Unicode glyph to this attribute:
[source]
----
:tip-caption: 💡
[TIP]
It's possible to use Unicode glyphs as admonition icons.
----
Here's the HTML that Asciidoctor outputs for the icon cell:
[source,html]
----
<td class="icon">
<div class="title">💡</div>
</td>
----
Instead of entering the glyph directly, you can enter a character reference instead.
However, since you're defining the character reference in an attribute entry, you (currently) have to disable substitutions on the value.
[source]
----
:tip-caption: pass:[&#128161;]
[TIP]
It's possible to use Unicode glyphs as admonition icons.
----
On GitHub, the HTML output that Asciidoctor emits is run through a postprocessing filter that substitutes emoji shortcodes with emoji symbols.
That means you can use these shortcodes in the value of the attribute:
[source]
----
\ifdef::env-github[]
:tip-caption: :bulb:
\endif::[]
[TIP]
It's possible to use emojis as admonition icons on GitHub.
----
When the document is processed through the GitHub interface, the shortcodes get replaced with real emojis.
This is the only known way to get admonition icons to work on GitHub.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment