docs: document custom icon functionality for docs.yml and navigation #1703
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
- Add documentation for custom icons using file: prefix for local files - Document inline SVG icon support using < > wrapper - Update navbar-links section with icon format examples - Update sidebar icons section with comprehensive examples for all three formats - Update products section with detailed icon format documentation - Add examples showing Font Awesome, custom image files, and inline SVG usage Co-Authored-By: Catherine Deskur <[email protected]>
Contributor
Author
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| ``` | ||
| </CodeBlock> | ||
|
|
||
| #### Inline SVG icons |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Inline SVG icons' should use sentence-style capitalization.
| - **Custom image files**: Use `file:` prefix followed by the file ID (e.g., `file:my-icon`). The file must be uploaded to your docs assets. | ||
| - **Inline SVG**: Provide an SVG string wrapped in `< >` (e.g., `<svg>...</svg>`). | ||
|
|
||
| ### Font Awesome icons |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Font Awesome icons' should use sentence-style capitalization.
| ``` | ||
| {/* <!-- vale on --> */} | ||
|
|
||
| ### Inline SVG icons |
Contributor
There was a problem hiding this comment.
📝 [vale] reported by reviewdog 🐶
[FernStyles.Headings] 'Inline SVG icons' should use sentence-style capitalization.
Contributor
- Change from file: prefix to relative paths (./assets/icons/...) - Update navbar-links icon examples to use ./assets/icons/ - Update sidebar icons examples to use relative paths - Update product icons examples to use relative paths - Add note that paths are relative to the YAML file where declared - Wrap inline SVG examples in quotes for proper YAML parsing Co-Authored-By: Catherine Deskur <[email protected]>
Contributor
Contributor
devalog
approved these changes
Nov 3, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Document custom icon functionality for docs.yml and navigation
Summary
This PR documents the new custom icon functionality that allows users to specify icons using three formats across docs.yml and navigation configurations:
fa-solid fa-rocket./assets/icons/icon.svg"<svg>...</svg>"Updated three documentation files:
what-is-docs-yml.mdx- navbar linksiconandrightIconparametersnavigation/overview.mdx- sidebar icons (sections, pages) and tabsnavigation/products.mdx- product iconsEach section includes comprehensive examples showing all three icon formats with syntax details.
Note: Initial commit incorrectly used
file:prefix syntax. Second commit corrected to relative paths (e.g.,./assets/icons/) based on Catherine's feedback and existing docs.yml examples.Review & Testing Checklist for Human
Test custom image icon examples end-to-end - Create a test docs site with custom icon files and verify the documented relative path syntax works correctly (e.g.,
icon: ./assets/icons/my-icon.svg). This is critical since all examples are synthetic and untested.Verify path resolution for nested YAML files - Test that icons declared in
products/*.ymlorversions/*/*.ymlfiles resolve paths correctly relative to those files (as documented: "Paths are relative to the YAML file where the icon is declared"). The implementation details weren't fully verified.Consider adding file upload workflow documentation - The docs explain icon SYNTAX but not WHERE/HOW users place icon files or what "docs assets folder" means. This could confuse users about the complete workflow.
Decide on Vale style warnings - Vale flagged heading capitalization: "Font Awesome icons" and "Inline SVG icons" should use sentence case. CI passed (warnings only), but you may want to fix for consistency with style guide.
Notes
88c8c2850(branchorigin/cd/custom-icons)