Skip to content

Improve ICON description with link to guide.joomla.org icon list#627

Open
ThomasFinnern wants to merge 5 commits into
joomla:mainfrom
ThomasFinnern:improve/icon-description
Open

Improve ICON description with link to guide.joomla.org icon list#627
ThomasFinnern wants to merge 5 commits into
joomla:mainfrom
ThomasFinnern:improve/icon-description

Conversation

@ThomasFinnern

Copy link
Copy Markdown
Contributor

This pull request improves the documentation for Joomla standard icons.

  • Added overview
  • Each icon type has its own section
  • Link to guide.joomla.org icon list guide.joomla.org
  • Better IcoMoon icon replacement documentation

This is my first article for manual.joomla.org. Please support me with style or other needed fixes for release of the pull request

@qodo-code-review

Copy link
Copy Markdown
Contributor

Review Summary by Qodo

Enhance icon documentation with structured sections and examples

📝 Documentation

Grey Divider

Walkthroughs

Description
• Restructured icon documentation with clear sections
• Added overview and link to guide.joomla.org icon list
• Expanded FontAwesome usage examples with standard and brand icons
• Added IcoMoon replacement documentation with function parameter examples
• Included accessibility tips and styling guidance
Diagram
flowchart LR
  A["Icon Documentation"] --> B["Overview Section"]
  A --> C["FontAwesome Icons"]
  A --> D["IcoMoon Replacement"]
  A --> E["Other Icon Sets"]
  C --> C1["Standard Icons"]
  C --> C2["Brand Icons"]
  D --> D1["Direct HTML Use"]
  D --> D2["Function Parameters"]
  B --> B1["Link to guide.joomla.org"]
Loading

Grey Divider

File Changes

1. docs/general-concepts/icons.md 📝 Documentation +67/-19

Restructure and expand icon documentation with examples

• Added "Overview" section with link to guide.joomla.org icon reference
• Reorganized content into logical sections: FontAwesome icons, Standard icons, Brand icons, IcoMoon
 replacement, and Other icon sets
• Expanded code examples showing <i> and <span> element usage with proper class prefixes
• Added accessibility guidance with aria-hidden="true" attribute documentation
• Documented IcoMoon replacement compatibility with icon-* prefix and function parameter usage
• Added tip section explaining how to use FontAwesome icons as fallback in Joomla functions
• Included styling examples with font-size attributes

docs/general-concepts/icons.md


Grey Divider

Qodo Logo

@qodo-code-review

qodo-code-review Bot commented May 17, 2026

Copy link
Copy Markdown
Contributor

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Grey Divider


Action required

1. Invalid fa-brand class ✓ Resolved 🐞 Bug ≡ Correctness
Description
The docs say fab is short for fa-brand, but the document (and existing versioned docs) use
fa-brands; fa-brand is not a valid class and copied examples will fail to render icons. This is
also internally inconsistent because the example immediately below uses fa-brands.
Code

docs/general-concepts/icons.md[41]

+The prefix part is ```fab``` which is short for ```fa-brand``` which can be used instead
Evidence
The updated doc explicitly claims fa-brand is the corresponding class, but both the example in the
same doc and the existing versioned documentation use fa-brands, demonstrating the new statement
is incorrect/inconsistent.

docs/general-concepts/icons.md[39-47]
versioned_docs/version-6.1/general-concepts/icons.md[30-41]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`docs/general-concepts/icons.md` incorrectly states that the brands style class is `fa-brand`.
### Issue Context
The same document and the repo’s versioned docs use `fa-brands` (plural). Keeping `fa-brand` will cause readers to copy a non-working class name.
### Fix Focus Areas
- docs/general-concepts/icons.md[39-47]
- versioned_docs/version-6.1/general-concepts/icons.md[30-41]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


2. Wrong fa/fas mapping ✓ Resolved 🐞 Bug ≡ Correctness
Description
The docs claim fa is short for fas (and fa-solid) and provide an example using `class="fa
fa-envelope", which conflicts with the repo’s established guidance to use fa-solid/fa-brands`.
This inconsistency will cause readers to use deprecated/unsupported class combinations depending on
what Joomla ships.
Code

docs/general-concepts/icons.md[R31-36]

+The Prefix part is ```fa``` which is short for ```fas``` which is short for ```fa-solid``` which can be used instead.
+
+The icon name part begins with ```fa-``` and the name. Example: 
+```php
+<i class="fa fa-envelope"></i>
+<i class="fa-solid fa-save" aria-hidden="true"></i> <?php echo Text::_('JSAVE') ?> 
Evidence
The new page states fa is a shorthand chain leading to fa-solid and uses fa fa-envelope, while
the existing versioned doc explicitly documents fa-solid/fa-brands and shows fa-solid usage;
this directly demonstrates the inconsistency introduced by the PR.

docs/general-concepts/icons.md[29-37]
versioned_docs/version-6.1/general-concepts/icons.md[30-35]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The documentation describes Font Awesome prefixing in a way that conflicts with the repo’s existing guidance and even with other examples in the same page.
### Issue Context
`fa-solid` / `fa-brands` is the convention documented in versioned docs; the new text claims `fa` -> `fas` -> `fa-solid` and shows `fa fa-envelope`.
### Fix Focus Areas
- docs/general-concepts/icons.md[29-37]
- versioned_docs/version-6.1/general-concepts/icons.md[30-35]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



Remediation recommended

3. Mislabelled code fences ✓ Resolved 🐞 Bug ⚙ Maintainability
Description
Several code blocks are fenced as php while containing only HTML, reducing readability and
producing incorrect syntax highlighting in Docusaurus. This page previously used html fences for
HTML-only examples in the repo’s versioned docs.
Code

docs/general-concepts/icons.md[R19-22]

```php
-    <span class="icon-cancel" aria-hidden="true"></span> <?php echo Text::_('JCANCEL') ?> 
+<i style="font-size: 2rem;" class="fa fa-!name!"></i>
+<span class="fa fa-!name! "></span>
Evidence
The new doc uses a php fence for a snippet that is purely HTML, whereas the versioned
documentation demonstrates the expected convention of using an html fence for HTML-only snippets.

docs/general-concepts/icons.md[17-22]
versioned_docs/version-6.1/general-concepts/icons.md[33-35]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
Code fences are labeled `php` even when the snippet contains only HTML.
### Issue Context
This affects syntax highlighting and consistency with other docs pages.
### Fix Focus Areas
- docs/general-concepts/icons.md[19-22]
- versioned_docs/version-6.1/general-concepts/icons.md[33-35]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools



Advisory comments

4. Non-canonical guide URL ✓ Resolved 🐞 Bug ⚙ Maintainability
Description
The guide.joomla.org link includes a highlight=... query parameter that appears to be UI state and
not part of a canonical documentation permalink. Keeping this parameter makes the docs link noisier
and potentially less stable over time.
Code

docs/general-concepts/icons.md[14]

+The source list of available icons can be found in joomla file ```media/templates/administrator/atum/css/vendor/fontawesome-free.css```. A visible representation of all icons with additional information see our [guide.joomla.org](https://guide.joomla.org/user-manual/templates/standard-icons?highlight=WyJpY29ucyJd)
Evidence
The PR introduces the external URL with an additional highlight query parameter, which is visible
directly in the source.

docs/general-concepts/icons.md[14-14]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The external guide link includes a `highlight=...` query parameter that looks like a transient highlight/search state.
### Issue Context
Using a canonical URL (without highlight state) is typically preferred for documentation links.
### Fix Focus Areas
- docs/general-concepts/icons.md[14-14]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Qodo Logo

Comment thread docs/general-concepts/icons.md Outdated
Comment thread docs/general-concepts/icons.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant