docs: add avatar drivers guide for User extender#498
docs: add avatar drivers guide for User extender#498datlechin wants to merge 9 commits intoflarum:mainfrom
Conversation
Documents the new avatar driver system introduced in flarum/framework#4130. Includes implementation guide, examples, and admin configuration.
Documents the new avatar driver system introduced in flarum/framework#4130. Includes implementation guide, examples, and admin configuration.
- Use more direct, technical language - Remove verbose explanations and marketing-style wording - Simplify code examples with minimal comments - Remove redundant sections - Match tone and word choices from mail.md, filesystem.md, notifications.md - Reduce file length from ~300 to ~75 lines
There was a problem hiding this comment.
Pull request overview
This PR adds comprehensive documentation for the avatar driver system introduced in flarum/framework#4130. The documentation enables extension developers to create custom avatar providers as alternatives to Gravatar or to integrate with external services like Discord, GitHub, and Steam.
- Documents the avatar driver interface and fallback chain
- Provides complete code examples for implementing and registering custom avatar drivers
- Explains automatic admin panel integration without requiring additional frontend code
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| sidebars.js | Adds the avatars documentation to the Advanced Guides section in alphabetical order |
| docs/extend/avatars.md | Comprehensive new documentation covering avatar driver implementation, registration, and admin configuration with practical Discord example |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
datlechin
changed the title
imorland
left a comment
imorland
left a comment
There was a problem hiding this comment.
The documentation is well-written and clear for extension authors. A few issues need addressing.
Reference to Gravatar driver
The docs mention a built-in Gravatar driver and link to a GravatarDriver.php that doesn't exist yet — the Gravatar driver is planned as a follow-up PR. The wording should reflect that the Gravatar driver is coming soon (not shipped yet) so readers of the docs in their current state aren't confused.
Locale labels for custom drivers are not mentioned
The docs say "No additional frontend code is required" for admin configuration, but extension authors won't be able to set a human-readable label for their driver in the admin dropdown — it will fall back to the raw identifier string (e.g. discord). This limitation should be documented so authors know what to expect.
- Correct intro to reflect only DefaultDriver exists (Gravatar is planned) - Add note about raw driver identifier and BasicsPage.driverLocale override - Link to existing DefaultDriver instead of non-existent GravatarDriver
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
2 participants
Documents the avatar driver system introduced in flarum/framework#4130.
This PR adds comprehensive documentation for extension developers who want to create custom avatar providers (Gravatar alternatives, OAuth-based avatars, external services).