Document the usage of icons in templates

diff --git a/docs/migration/wsc55/icons.md b/docs/migration/wsc55/icons.md
new file mode 100644 (file)
index 0000000..3ded995
--- /dev/null
+++ b/docs/migration/wsc55/icons.md
@@ -0,0 +1,35 @@
+# Migrating from WoltLab Suite 5.5 - Icons
+
+WoltLab Suite 6.0 introduces Font Awesome 6.0 which is a major upgrade over the previously used Font Awesome 4.7 icon library.
+The new version features not only many hundreds of new icons but also focused a lot more on icon consistency, namely the proper alignment of icons within the grid.
+
+The previous implementation of Font Awesome 4 included shims for Font Awesome 3 that was used before, the most notable one being the `.icon` notation instead of `.fa` as seen in Font Awesome 4 and later.
+In addition, Font Awesome 5 introduced the concept of different font weights to separate icons which was further extended in Font Awesome 6.
+
+In WoltLab Suite 6.0 we have made the decision to make a clean cut and drop support for the Font Awesome 3 shim as well as a Font Awesome 4 shim in order to dramatically reduce the CSS size and to clean up the implementation.
+Brand icons had been moved to a separate font in Font Awesome 5, but since more and more fonts are being added we have stepped back from relying on that font.
+We have instead made the decision to embed brand icons using inline SVGs which are much more efficient when you only need a handful of brand icons instead of loading a 100kB+ font just for a few icons.
+
+## Using Icons in Templates
+
+The new template function `{icon}` was added to take care of generating the HTML code for icons, including the embedded SVGs for brand icons.
+Icons in HTML should not be constructed using the actual HTML element, but instead always use `{icon}`.
+
+```smarty
+<button class="button">{icon size=16 name='bell'} I‘m a button with a bell icon</button>
+```
+
+Unless specified the icon will attempt to use a non-solid variant of the icon if it is available.
+You can explicitly request a solid version of the icon by specifying it with `type='solid'`.
+
+```smarty
+<button class="button">{icon size=16 name='bell' type='solid'} I‘m a button with a solid bell icon</button>
+```
+
+### Brand Icons
+
+The syntax for brand icons is very similar, but you are required to specifiy parameter `type='brand'` to access them.
+
+```smarty
+<button class="button">{icon size=16 name='facebook' type='brand'} Share on Facebook</button>
+```

diff --git a/mkdocs.yml b/mkdocs.yml
index 70b6fc97a43a1bc9868bd93fec856ff83cd4e892..e6796a0901df9170ee55ba97e49e0c0fc9689907 100644 (file)
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -114,6 +114,7 @@ nav:
       - 'PHP API': 'migration/wsc55/php.md'
       - 'TypeScript and JavaScript': 'migration/wsc55/javascript.md'
       - 'Templates': 'migration/wsc55/templates.md'
+      - 'Icons': 'migration/wsc55/icons.md'
       - 'Third Party Libraries': 'migration/wsc55/libraries.md'
       - 'Deprecations and Removals': 'migration/wsc55/deprecations_removals.md'
     - 'From WoltLab Suite 5.4':