Feedback

Author: smnandre

src/Icons/doc/index.rst

@@ -168,8 +168,8 @@ a subdirectory, the *name* will be ``subdirectory:icon_name``.
 On-Demand Open Source Icons
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Add your SVG icons to the ``assets/icons/`` directory and commit them.
-The name of the file is used as the _name_ of the icon (``name.svg`` will be named ``name``).
-If located in a subdirectory, the _name_ will be ``sub-dir:name``.
+The name of the file is used as the *name* of the icon (``name.svg`` will be named ``name``).
+If located in a subdirectory, the *name* will be ``sub-dir:name``.
 
 .. code-block:: text
 
@@ -243,13 +243,18 @@ the ``assets/icons/`` directory. You can think of importing an icon as *locking
 Rendering Icons
 ---------------
 
-.. code-block:: html+twig
+.. code-block:: twig
 
-    {{ ux_icon('user-profile', {class: 'w-4 h-4'}) }} <!-- renders "user-profile.svg" -->
+    {# includes the contents of the 'assets/icons/user-profile.svg' file in the template #}
+    {{ ux_icon('user-profile') }}
 
-    {{ ux_icon('sub-dir:user-profile', {class: 'w-4 h-4'}) }} <!-- renders "sub-dir/user-profile.svg" (sub-directory) -->
+    {# icons stored in subdirectories must use the 'subdirectory_name:file_name' syntax
+       (e.g. this includes 'assets/icons/admin/user-profile.svg') #}
+    {{ ux_icon('admin:user-profile') }}
 
-    {{ ux_icon('flowbite:user-solid') }} <!-- renders "flowbite:user-solid" from ux.symfony.com -->
+    {# this downloads the 'user-solid.svg' icon from the 'Flowbite' icon set via ux.symfony.com
+       and embeds the downloaded SVG contents in the template #}
+    {{ ux_icon('flowbite:user-solid') }}
 
 HTML Syntax
 ~~~~~~~~~~~
@@ -378,7 +383,7 @@ Caching
 On-Demand VS Import
 ^^^^^^^^^^^^^^^^^^^
 
-While *on-demand* icons are great during development, they require http requests to fetch the icon
+While *on-demand* icons are great during development, they require HTTP requests to fetch the icon
 and always use the *latest version* of the icon. It's possible the icon could change or be removed
 in the future. Additionally, the cache warming process will take significantly longer if using
 many _on-demand_ icons. You can think of importing the icon as *locking it* (similar to how