Questions answered by this recipe
How to set up and use Font Awesome Icons in PmWiki.
All sections are optional, you can remove those that do not apply to your recipe, and add new ones.
Font Awesome (FA for short) is a symbol webfont, that allows you to use scalable vector icons that are easily styled using CSS. This works just like styling fonts, and gives you much more freedom than fixed-size images, and much less overhead than SVG symbols.
Font Awesome is currently hosted by Github, and published under various open source licenses, please check the FA Project Homepage for details before you proceed.
If you have never heard of Font Awesome before, and you want to know what the symbols look and feel like, just have a look at the project.
Unless you haven't already done this, download and unpack the Font Awesome files into some directory inside your webspace. Just follow the links and directions on the Font Awesome Project Homepage.
The symbols can also be used by other HTML pages, (and even by your Text Editor), so find a suitable place.
Remember the path to the font-awesome.css file!
There is very little to configure or add to the PmWiki system. You have to include the Font Awesome CSS file into the PmWiki system, and add some custom markup to actually use the symbols in the wiki pages.
- If you already have a local.css in PmWiki's pub/css directory, add the following line to the beginning of the file:
- If you don't have a local.css yet, just create one, and add the above line. This will include Font Awesome's CSS definitions into PmWiki.
- Then, edit your local/config.php, and add a suitable custom markup.
Markup(";;;", "inline", "/;;;(.*?);;;/", "<i class=\"fa $1\"></i>");
If you read the Font Awesome docs, you will see that they are using some CSS tweak to the <i> element to include their symbols, by adding several special class names to the (otherwise empty) element, e.g. <i class="fa fa-info-circle"></i> will place the "fa-info-circle" symbol on your page. Note that class "fa" kind of activates the FA extensions, and must always be present (and that's why it is fixed in the markup).
The above custom markup just translates the ";;;fa-icon-name;;;" markup to the corresponding FA element.
- Just add the defined markup, e.g. ";;;fa-info-circle;;;" to your page, and the corresponding symbol will show up.
See the Font Awesome documentation for available symbols and their names.
As the Font Awesome symbols are styled by CSS, they will e.g. inherit some styles (color, size, etc.) from their parent elements, and can easily be individually styled (sized, colored, shadowed,...) as well.
The Font Awesome CSS even defines some special classes to add some convenient effects to the symbols, such as enlarged, flipped, or rotated symbols. You may want to read the FA documentation to make the most of it. The PmWiki markup should be transparent for most, if not all, FA classes, though this is not fully tested yet.
This recipe is so simple that I was hesitating to publish it. However, sometimes it is just the simple things that make life enjoyable. This is a simple recipe that uses no magic, and is easy to understand and to adjust to your own needs.
Hope this may become useful to somebody.
Change log / Release notes
(20140901) first release, tested with FA 4.2.0 and PmWiki 2.2.30 by JoBo
If the recipe has multiple releases, then release notes can be placed here. Note that it's often easier for people to work with "release dates" instead of "version numbers".