====== icon Plugin ======

---- plugin ----
description: Easily use SVG icon sets as images
author     : Andreas Gohr 
email      : dokuwiki@cosmocode.de
type       : action
lastupdate : 2022-09-29
compatible : Igor
depends    : 
conflicts  : 
similar    : icons
tags       : icon

downloadurl: https://github.com/cosmocode/dokuwiki-plugin-icon/zipball/master
bugtracker : https://github.com/cosmocode/dokuwiki-plugin-icon/issues
sourcerepo : https://github.com/cosmocode/dokuwiki-plugin-icon/
donationurl: 

screenshot_img : 
----

This plugin allows you to reference icons from popular icon sets simply by name to include them as images into your wiki pages. The icons can easily be resized and colored.

===== Installation =====

  * This plugin requires the [[https://www.php.net/manual/en/book.dom.php|PHP DOM extension]]

Install the plugin using the [[plugin:plugin|Plugin Manager]] and the download URL above, which points to latest version of the plugin. Refer to [[:Plugins]] on how to install plugins manually.

===== Examples/Usage =====

Icons are used just like any other image. The prefix ''icon:'' specifies that an icon is wanted.

  {{icon:cow.svg}}

:!: This means you no longer can have a real media namespace called ''icon''!


Since the linked icon is not an existing local image, you probably want to prevent the default linking. Just use the ''nolink'' flag:

  {{icon:cow.svg?nolink}}


Of course you can also use standard image resizing:

  {{icon:cow.svg?nolink&100x100}}

And of course the standard title mechanism (for hover tooltips) works and the icon can be used with the link syntax as usual:

  [[animal:cow|{{icon:cow.svg|This is a cow link}}]]

==== Advanced configuration ====

Additional pseudo-namespaces can be used to further configure the icon. Just make sure the icon itself is at the end.

  {{icon:twbs:link:w-3em:h-auto:cup-hot.svg?nolink}}


You can pick the **icon set** to be used, by specifying one of the following keywords. The example above uses a Twitter Bootstrap icon.

^ Namespace ^ Repository ^
| ''mdi''   | [[https://pictogrammers.com/library/mdi/|Material Design Icons]] (default when none is given) |
| ''fab''   | [[https://fontawesome.com/icons?d=gallery&p=2&s=brands&m=free|Font Awesome Brands]] |
| ''fas''   | [[https://fontawesome.com/icons?d=gallery&p=2&s=solid&m=free|Font Awesome Solid]] |
| ''fa''    | [[https://fontawesome.com/icons?d=gallery&p=2&s=regular&m=free|Font Awesome Regular]] |
| ''twbs''  | [[https://icons.getbootstrap.com/|Twitter Bootstrap Icons]] |

You can define a **color** by either giving a hex color or a color from the template's style.ini. The example above refers to the default ''link'' color. To create a red icon you could use:

  {{icon:ff0000:cow.svg}}


Instead of using the standard pixel based resizing syntax, you can also use any valid SVG unit to specify **height** and **width**. Prefix them with ''w-'' and ''h-''. You can also use the ''auto'' keyword. The example above will resize the icon to a width of ''3em'' and adjust the height automatically.