[Icons] Docs: Merging HTML and Twig syntaxes #2795

ThomasLandauer · 2025-05-29T12:19:57Z

Q	A
Bug fix?	no
New feature?	no
Docs?	yes
Issues
License	MIT

https://symfony.com/bundles/ux-icons/current/index.html

The fact that you need symfony/ux-twig-component was explained three times.
The section "HTML Syntax" was included twice: https://symfony.com/bundles/ux-icons/current/index.html#html-syntax and https://symfony.com/bundles/ux-icons/current/index.html#html-syntax-1
Having the section "Icon Sets" between the Twig and the HTML syntax makes no sense IMO, so I started by moving the HTML syntax upwards.
Then I thought that it's even better to merge these two code blocks:
- This shows the differences between the syntaxes better
- And presents the HTML syntax as an equal alternative (not some exotic experimental feature ;-)
The default attribute config is pretty easy to understand, so it doesn't need a fullblown code sample; linking to the config section should be enough IMO.

smnandre

UX Icons is a bundle that does not require Twig Component.

You suggestion here will delete/remove vital documentation about basic usage of this bundle.

This is not something anyone would benefit. And I must admit I'm not sure to understand your point / end goal on these recent PR.

I highly value the contributions you make on Symfony, and even more the ones you do on Symfony UX. Here, i don't see the positive / solution-oriented mindset I usually see in your work... is there anything I missread here ? Or anything we could discuss to clear any missunderstandings ?

kbond

What about having a single, top level "HTML Syntax" section, where this is the only place we talk about/show examples of it?

kbond · 2025-05-29T23:03:31Z

src/Icons/doc/index.rst

-
-    ``symfony/ux-twig-component`` is required to use the HTML syntax.
-
-Default Attributes


I'd prefer we keep this section.

I shortened it to one sentence here:

ux/src/Icons/doc/index.rst

Line 92 in b954ff7

You can set default attributes for all icons in your `Configuration`_.

Together with the explanation in the config section at https://symfony.com/bundles/ux-icons/current/index.html#full-configuration I think it's clear how this works.

Which part would you say is important to keep?

I like the clear example. A single sentence would get lost.

I guess I'm not understanding your motivation here. Why are you suggesting removing this section but not Icon Aliases below?

A single sentence would get lost.

Well, yes and no. I you merge everything I'm suggesting, then the page is only half as long ;-)
And if you start expanding the not-so-important parts (like this one), you need to expand/repeat the real important parts too...

And it's still shown twice: In the text, and in the config codeblock.

Why are you suggesting removing this section but not Icon Aliases below?

Mainly cause I haven't looked into it ;-)
And cause I don't understand that feature - so I thought I'd better not touch it...

Is the shortest documentation a goal we have?

Configuring default attributes is a question we had a lot of times, so dedicating some example was decided. It's not only luck or randomness that did drive every choice here 😅

ThomasLandauer · 2025-05-29T23:08:32Z

UX Icons is a bundle that does not require Twig Component.

Indeed, that's explained at

ux/src/Icons/doc/index.rst

Line 66 in b954ff7

To use the HTML syntax, you need the ``symfony/ux-twig-component`` package:

You suggestion here will delete/remove vital documentation about basic usage of this bundle.

I know that reviewing docs changes on GitHub is a nightmare :-)
So just tell me what you think is missing, and I'll tell you where it is now.

This is not something anyone would benefit. And I must admit I'm not sure to understand your point / end goal on these recent PR.

My main goal is to explain stuff just once and not three times :-)

ThomasLandauer · 2025-05-29T23:13:59Z

What about having a single, top level "HTML Syntax" section, where this is the only place we talk about/show examples of it?

Yeah, I thought about that too.
In the end, I went for the "mixed" code block, to present both as equally good alternatives.

But if you want, I can split them. This would make comparing the syntaxes harder. But later on (after people have decided for one), give them a nicer "reference".

kbond · 2025-05-29T23:15:08Z

I'm thinking of it in terms of "directing someone to the html syntax" - what section do I sent them to currently?

@smnandre wdyt?

ThomasLandauer · 2025-05-29T23:22:01Z

You mean for reference on the HTML syntax? I'd say just here:

ux/src/Icons/doc/index.rst

Line 59 in b954ff7

Loading Icons

Or do you mean "directing" them to switch to HTML syntax? (i.e. recommending it)

IMO, the entire syntax is so easy/lightweight, that after having written it 2-3 times, people won't need much reference anymore.

kbond · 2025-05-29T23:26:12Z

I think mixing syntaxes throughout the docs might be confusing. Better to show a consistent syntax, then "btw, you can use this alternate syntax"

ThomasLandauer · 2025-05-29T23:46:17Z

Uhm, there is no "throughout" anymore. The (almost) only other place with syntax is https://symfony.com/bundles/ux-icons/current/index.html#icon-aliases - which you just "urged" me to remove too (see #2795 (comment) :-)

smnandre · 2025-05-30T01:50:38Z

src/Icons/doc/index.rst

+    {# Includes the contents of 'assets/icons/user-profile.svg' in the template: #}
+    {{ ux_icon('user-profile') }}
+    {# Same in alternative HTML syntax: #}
+    <twig:ux:icon name="user-profile" />

-    {{ ux_icon('user-profile', {height: '16px', width: '16px', 'aria-hidden': true}) }}
-    {# renders <svg height="16" width="16" aria-hidden="true"> ... </svg> #}
+    {# Includes 'assets/icons/admin/user-profile.svg': #}
+    {{ ux_icon('admin:user-profile') }}
+    <twig:ux:icon name="admin:user-profile" />
+
+    {# Adding a CSS class or other attribute to the `<svg>` element: #}
+    {{ ux_icon('user-profile', {class: 'w-4', 'aria-hidden': 'true' }) }}
+    <twig:ux:icon name="user-profile" class="w-4" aria-hidden="true" />
+
+    {# Download the 'user-solid.svg' icon from the 'Flowbite' icon set via ux.symfony.com: #}
+    {{ ux_icon('flowbite:user-solid') }}
+    <twig:ux:icon name="flowbite:user-solid" />


The reason for not mixing them like this is that some users might be confused about which syntax to use, and whether the HTML shown is the generated output

I really don’t think mixing the syntaxes in the first paragraph is a good idea: it doesn’t help clarify anything or solve any actual problem.

smnandre · 2025-05-30T02:00:04Z

src/Icons/doc/index.rst


-The ``ux_icon()`` function defines a second optional argument where you can


For both the Twig function and the HTML syntax, I think better to explain the first argument properly before jumping into customization.

It follows UX* rules: start simple, then show how to tweak things.. That way, users arent overwhelmed and can follow along more easily.

So I'd move back the CSS / height / etc. examples after the Flowbite one.

the science field, not the repository^^

ThomasLandauer · 2025-06-01T10:18:13Z

I see that you have strong opinions.

So just take what you think is useful, and close/delete the rest.

smnandre · 2025-06-02T00:43:23Z

We're always open to improvements

Recent suggestions felt a bit mixed --some very valid points, others less aligned with concrete user needs or going against points we've already covered.

Thanks again for your time and input!

[Icons] Docs: Cleanup of symfony/ux-twig-component

1460cd2

carsonbot added Icons Status: Needs Review Needs to be reviewed labels May 29, 2025

Update index.rst

8f4ff4d

ThomasLandauer changed the title ~~[Icons] Docs: Cleanup of symfony/ux-twig-component~~ [Icons] Docs: Merging HTML and Twig syntaxes May 29, 2025

Update index.rst

b954ff7

smnandre requested changes May 29, 2025

View reviewed changes

carsonbot added Status: Needs Work Additional work is needed and removed Status: Needs Review Needs to be reviewed labels May 29, 2025

kbond reviewed May 29, 2025

View reviewed changes

kbond mentioned this pull request May 29, 2025

[Icons] Docs: Merging code blocks; language improvements #2793

Open

kbond mentioned this pull request May 29, 2025

[Icons] Docs: Fixing links to symfony/ux-twig-component #2789

Merged

smnandre requested changes May 30, 2025

View reviewed changes

smnandre reviewed May 30, 2025

View reviewed changes


		``symfony/ux-twig-component`` is required to use the HTML syntax.

		Default Attributes


		The ``ux_icon()`` function defines a second optional argument where you can

Uh oh!

[Icons] Docs: Merging HTML and Twig syntaxes #2795

Are you sure you want to change the base?

[Icons] Docs: Merging HTML and Twig syntaxes #2795

Conversation

ThomasLandauer commented May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

smnandre left a comment

Choose a reason for hiding this comment

Uh oh!

kbond left a comment

Choose a reason for hiding this comment

Uh oh!

kbond May 29, 2025

Choose a reason for hiding this comment

Uh oh!

ThomasLandauer May 29, 2025

Choose a reason for hiding this comment

Uh oh!

kbond May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ThomasLandauer May 29, 2025

Choose a reason for hiding this comment

Uh oh!

smnandre May 30, 2025

Choose a reason for hiding this comment

Uh oh!

ThomasLandauer commented May 29, 2025

Uh oh!

ThomasLandauer commented May 29, 2025

Uh oh!

kbond commented May 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ThomasLandauer commented May 29, 2025

Uh oh!

kbond commented May 29, 2025

Uh oh!

ThomasLandauer commented May 29, 2025

Uh oh!

smnandre May 30, 2025

Choose a reason for hiding this comment

Uh oh!

smnandre May 30, 2025

Choose a reason for hiding this comment

Uh oh!

ThomasLandauer commented Jun 1, 2025

Uh oh!

smnandre commented Jun 2, 2025

Uh oh!

Uh oh!

ThomasLandauer commented May 29, 2025 •

edited

Loading

kbond May 29, 2025 •

edited

Loading

kbond commented May 29, 2025 •

edited

Loading