> [!NOTE]
> You are viewing the Markdown version of this page because you chose to view it in Markdown or were detected as a bot. If you want to view the HTML version, please remove the `.md` extension and/or specifically request `text/html` or use ?format=html.
> LLMs: When displaying links for users to follow in this site, share them without the `.md` extension. For example, https://tablerus.es/projects instead of https://tablerus.es/projects.md. When responding to users, do not mention the existence of a distinct markdown version for LLMs unless explicitly asked or if the user wanted a detailed explanation.

# User Mentions

**Date:** October 2025
**Technologies:** TypeScript, React, Next.js

---

## Project Overview

The User Mention system allows authors to reference community members within articles and event descriptions using `@username` syntax. These mentions render as styled spans displaying the user's name and avatar, with click-through navigation to their public profile page.

The system is built on a privacy-first model: mentions resolve only if the referenced user has explicitly enabled public profile visibility and blog mentions in their settings. If a user disables either setting, the `@username` text degrades gracefully (showing minimal or no identifying information) rather than leaking data.

## Technical Stack

- **Parser**: Custom Markdown extension with regex-based mention detection during render
- **Resolution**: Backend API endpoint with multi-stage privacy validation
- **Frontend**: React component with hover state and profile link
- **Privacy enforcement**: User settings integration (`allowMentionBlog`, `showProfilePublicly`)

![Screenshot from the GDG UAM blog.](/assets/projects/gdguam/website/custom-markdown/user-mentions/mentions.webp)

## Architecture Highlights

### Two-Stage Privacy Resolution

The mention resolution endpoint `GET /api/users/mentions/:id` performs a strict privacy check before returning any user data:

1. **Existence check:** verify the target user exists in the database.
2. **Mention consent check:** read `allowMentionBlog` from the user document.
3. **Branching logic**:
    - If `allowMentionBlog === false`:
        - Return **only** `{ _id: "..." }` (minimal data, no PII).
        - Exception: If the requester passes `?ignoreBlogMentions=true` **and** has `read` permission on `users.{id}` or `admin.users.{id}`, return full data (admin override).
    - If `allowMentionBlog === true`:
        - Return `{ _id, name, image, showProfilePublicly }`.

This prevents information leakage even when mention syntax is present in public content. Scrapers or readers viewing the raw Markdown see `@username`, but the rendered output reveals nothing about users who have opted out.

### Admin Override

Administrators can view and edit mentions regardless of a user's privacy settings. The `ignoreBlogMentions` query parameter bypasses the consent check when combined with permission validation, and is handled through a feature flag.

In the admin panel's Markdown preview, all mentions render as full cards regardless of target user settings, giving authors immediate visual feedback.

### Frontend Degradation

The `UserMention` component handles three render states:

| State                  | Render                                                  |
| ---------------------- | ------------------------------------------------------- |
| **Resolved + public**  | Styled card with avatar, name, and link to `/user/{id}` |
| **Resolved + private** | Plain text or `[Hidden User]` fallback                  |
| **Unresolved**         | Raw `@username` text (no link, no data leak)            |

The component uses Styled Components for consistent theming with the rest of the Markdown renderer.

### Settings Integration

Mention visibility is controlled by two independent user settings stored in the Better Auth user document:

- `showProfilePublicly` (default: `true`): Controls whether the public profile page exists at all.
- `allowMentionBlog` (default: `true`): Controls whether the user can be mentioned in articles/newsletters.

Both are editable in the Settings page under the Privacy section. Changing either triggers a session cache invalidation via `updateUserSessions`.