Compatible with DokuWiki

• 2025-05-14 "Librarian" yes
• 2024-02-06 "Kaos" yes
• 2023-04-04 "Jack Jackrum" yes
• 2022-07-31 "Igor" yes

• Download
• Report bugs
• Donate

Insert a gravatar into a wiki page, also needed by the discussion plugin.

Last updated on

2025-06-30

Provides

Syntax, Helper

Repository

Source

Tagged with avatar, discussion, embed, images, media

By Daniel "Nerun" Rodrigues (previous authors: Dokufreaks, Michael Hamann, Esther Brunner, Gina Häußge, Michael Klier)

• parserfunctions
• templater

Displays avatar images from Gravatar when a valid email address is available (falling back to Gravatar default avatar) or displays local avatar images when available (falling back to a local monsterid implementation).

Please, help to translate: translate.dokuwiki.org/plugin/avatar

  {{avatar>[identity]?[size]|[title]}}

The {{gravatar>...}} syntax is deprecated but still supported by backward compatibility, but is not encouraged.

By padding the e-mail address with spaces you can define the alignment like with images:

The size attribute (?xl) was used to make it clear that spaces must be inserted before other attributes.

Gravatar (a portmanteau of globally recognized avatar) is a high-availability service for providing globally unique avatars.

Gravatar lets you use the same profile picture across different websites. Instead of uploading your photo every time you comment or sign up somewhere, you just link your email to a Gravatar image — and it automatically appears on supported sites (like blogs, forums, WordPress, or DokuWiki).

• You sign up at gravatar.com and upload a photo (or “avatar”).
• Link it to your email — this ties your image to your email address.
• When you use that email on a Gravatar-supported site, your picture shows up next to your name.

Just as explained: {{avatar>your@email.com}}. Plugin will request the avatar corresponding to the email provided on the Gravatar server:

• If found — i.e., if the user registered that email address with Gravatar — the corresponding avatar will be displayed.
• If it is not found — i.e., the email is not registered or has a spelling error — Gravatar itself handles these failures by falling back to a default image.

But the wiki administrator is not limited to the default image (see Settings, below).

If you don't want to use Gravatar, you can upload your own avatars (either JPG, PNG or GIF) into the namespace defined in the Configuration Manager, Plugins Settings, Avatar section, in “Default namespace for local avatars” (default is user:).

For example, for a user named foo, the path of the image would be user:foo.jpg (plugin will try all valid image extensions), using this syntax:

{{avatar>foo}}

The username must be in lowercase and follow the pagename naming rules.

In ACL rules, @ALL must have at least Read permissions on the user:* namespace.

Or alternatively, if you want to keep the user namespace inaccessible to non-authenticated users, set another default namespace for avatars.

If the Avatar plugin cannot find a local avatar (e.g., user:foo.jpg), it uses monsterid.php to generate a deterministic avatar based on the username (which acts as a seed).

• Consistency: The same username always produces the same avatar (since the seed is fixed).
• Automatic Save: To optimize performance, the plugin saves the generated avatar in the default namespace (e.g., user:foo.jpg). This avoids regenerating the image on future requests.
• Efficiency: Reduces CPU/memory usage by caching the avatar locally.

• Avatars are only saved for the user's own requests (e.g., user foo requesting {{avatar>foo}}).
• Requests for other users (e.g., user bar requesting {{avatar>foo}}) will display the avatar but not save it.
• If a local avatar exists (e.g., user:foo.jpg), it will be displayed to all users (both foo and bar), either created by monsterid or uploaded by the user foo himself.

• It depends on the PHP GD extension (GD means Graphics Draw)
• On Debian-like distros:
  • sudo apt install php-gd
  • sudo phpenmod -v 8.4 -s apache2 gd
  • sudo phpenmod -v 8.4 -s cli gd
  • sudo systemctl restart apache2

If local avatars are missing, the system falls back to the monsterid.php script, which requires the PHP-GD extension. If PHP-GD is also unavailable, it defaults to the mystery man avatar.

images
├── default_20.png
├── default_40.png
├── default_80.png
└── default_120.png

You can reverse the fallback order in the Settings (below). You can set mystery man as the default. However, mystery man will always be monsterid's fallback.

Configuration Manager > Plug-ins Configuration > Avatar

The Gravatar “fall back” can be changed from default image to other methods, as explained here. The methods are:

• 404: do not load any image if none is associated with the email hash, instead return an HTTP 404 (File Not Found) response.
• initials: uses the Gravatar profile name as initials, with a generated background and foreground color (beta).
• color: a generated color (beta).
• mp: (mystery-person) a simple, cartoon-style silhouetted outline of a person (does not vary by email hash).
• identicon: a geometric pattern based on an email hash.
• monsterid: a generated “monster” with different colors, faces, etc.
• wavatar: generated faces with differing features and backgrounds.
• retro: awesome generated, 8-bit arcade-style pixelated faces.
• robohash: a generated robot with different colors, faces, etc.
• blank: a transparent PNG image (border added to HTML below for demonstration purposes).

Content rating for audience. If the Gravatar has a content rating above the maximum allowed, it will not be displayed, the default image will be displayed instead. Rating varies:

• G: suitable for display on all websites with any audience type.
• PG: may contain rude gestures, provocatively dressed individuals, the lesser swear words, or mild violence.
• R: may contain such things as harsh profanity, intense violence, nudity, or hard drug use.
• X: may contain sexual imagery or extremely disturbing violence.

Plugin Avatar default content rating for Gravatar is PG, which is suitable for most wikis.

The default avatar size is 80×80 pixels (M-edium), which is the default for both Gravatar and Local Avatars. Even if not set, the Gravatar server defaults to 80. Other sizes: 20, 40 and 120 pixels.

The default namespace is user, that can be changed in Configuration Manager too.

The default fallback for local avatars is monsterid, but you can also change this in the settings to mystery_man.

• Adds configurable local avatar fallback (monsterid/mystery_man) (2025-06-30 21:49)
• fix(monsterid.php): restored color the body (2025-06-30 16:51)
• fix(monsterid.php): license MIT, not GPL; updated copyrights (2025-06-30 16:20)
• Updated settings descriptions (en, pt, pt-br) (2025-06-30 15:38)
• plugin.info update date (2025-06-30 05:06)
• fix(helper): avatar "title" and "alt" (2025-06-30 05:04)
• fix(helper): http_build_query for gravatar (2025-06-30 04:07)
• helper.php saves generated monsterid avatars to default namespace to … (2025-06-29 21:00)

Personally, I would prefer a slightly higher degree of control over the fallback avatars, in two main areas. I'm not knocking what is a great plugin, but I believe that it can be more things to more people by making a few modifications

Instead of avatars coming from a fixed namespace, I would like to be able to specify a tokenized filename for the avatar. For example, I have my DW set up so that each user has a “user namespace” in which they have full permissions, and I would like that avatar to come from that namespace.

This is a lot easier to manage since there is no a-priori avatar, and thus ACL permission cannot be granted to upload the file - I want users to be able to change their own avatars without other users being able to; since you can't grant delete permission to a namespace, there is no way to stop users overwriting each others' avatars unless they are in separate protected namespaces.

This can be achieved by changing the namespace conf setting so that it looks something like user/@USER@/avatar (perhaps even renaming so that it is called filename, since that is a more meaningful description of the setting under this proposal). This is then resolved in _getAvatarURL into the right form, e.g. user/my_user_name/avatar, and then the files user/my_user_name/avatar.jpg etc are searched for.

i.e. changing the line $avatar = $this→getConf('namespace').':'.$user; to read

$avatar = str_replace( '@USER@', $user, $this->getConf('filename') );

Of course, the status quo can be achieved through this new system also, by setting the namespace/filename conf setting to user/@USER@.

This subsection was deleted since altready implemented in 4c5c7bd (Jun 30, 2025).
— Daniel "Nerun" Rodrigues 2025-06-30 22:08

– Andy Turner 2009-07-14 15:10

• http://pavatar.com/ - similar gravatar
• http://sourceforge.net/projects/pavatar/ - php lib (as examples)

— 212.80.36.74 2010-10-18 09:25

• config carddav URL & credentials and attributes to retrieve
• lookup carddav URL as you do for gravatar and Display those

— 46.223.93.65 2016-04-27 14:43