A Kirby plugin that automatically transforms social handles into links to their profiles

Installs: 24

Dependents: 0

Suggesters: 0

Security: 0

Stars: 1

Watchers: 1

Forks: 0

Open Issues: 0

Type:kirby-plugin

0.0.5 2025-06-24 21:12 UTC

This package is auto-updated.

Last update: 2025-06-24 21:12:41 UTC


README

A Kirby plugin that automatically transforms social handles (like @user@instance) into clickable links to their profiles. Supports Unicode characters, custom services, and comprehensive configuration options.

Installation

Download

Download and place this plugin in /site/plugins/handle.

Composer

composer require alienlebarge/handle

Git

git submodule add https://github.com/alienlebarge/handle.git site/plugins/handle

Usage

Field Method

<?= $page->text()->kirbytext()->handleLinks() ?>

Automatic

The plugin automatically processes all texts passed through kirbytext.

KirbyTag

(handle: @user@instance)

or

(handle: user: username instance: bsky.app)

Configuration

Configure the plugin in your config.php file:

return [
  // Global plugin settings
  'alienlebarge.handle.enabled' => true,
  'alienlebarge.handle.maxTextLength' => 100000,
  'alienlebarge.handle.logErrors' => true,
  'alienlebarge.handle.enableFediverse' => true,
  
  // Service configurations
  'alienlebarge.handle.services' => [
    'bsky.app' => [
      'enabled' => true,
      'urlPrefix' => 'https://bsky.app/profile/',
      'urlSuffix' => '',
      'class' => 'bsky-link',
      'displayUsername' => true,
      'name' => 'Bluesky'
    ],
    // Add custom services...
  ]
];

See CONFIG.md for detailed configuration options and examples.

Default Supported Services

  • Fediverse (Mastodon, etc.)
  • Bluesky (bsky.app)
  • Flickr
  • GitHub
  • Instagram
  • LinkedIn
  • Micro.blog
  • Reddit
  • YouTube
  • Vimeo

Migration from v0.0.3

If upgrading from v0.0.3, update your configuration:

Before:

'handle.services' => [
  'github.com' => [
    'urlPrefix' => 'https://github.com/',
    'class' => 'github-link'
  ]
]

After:

'alienlebarge.handle.services' => [
  'github.com' => [
    'enabled' => true,           // New required field
    'urlPrefix' => 'https://github.com/',
    'class' => 'github-link',
    'displayUsername' => true,   // New optional field
    'name' => 'GitHub'          // New optional field
  ]
]

License

MIT

Features

  • Automatic Processing: Transforms handles via kirbytext:before hook
  • Unicode Support: Works with international usernames and domains
  • Security: XSS protection with input validation and sanitization
  • Performance: Optimized with early returns and configurable text size limits
  • Extensible: Easy to add custom services and configure behavior
  • Code Protection: Preserves handles in code blocks and backticks

Requirements

  • PHP >= 7.4
  • Kirby CMS >= 3.0

Advanced Usage

In your templates

The plugin works in several ways:

  1. Automatically (via the kirbytext:before hook):

    <?= $page->text()->kirbytext() ?>
  2. Manually (via the field method):

    <?= $page->text()->handleLinks() ?>
  3. Via KirbyTag:

    (handle: @heydon@social.lol)
    

    or

    (handle: user: heydon instance: social.lol)
    

Adding Custom Services

'alienlebarge.handle.services' => [
  'mastodon.social' => [
    'enabled' => true,
    'urlPrefix' => 'https://mastodon.social/@',
    'urlSuffix' => '',
    'class' => 'mastodon-link',
    'displayUsername' => true,
    'name' => 'Mastodon Social'
  ],
  'custom-platform.com' => [
    'enabled' => true,
    'urlPrefix' => 'https://custom-platform.com/users/',
    'urlSuffix' => '/profile',
    'class' => 'custom-platform-link',
    'displayUsername' => false, // Show @username@instance
    'name' => 'Custom Platform'
  ]
]

Service Configuration Options:

  • enabled (bool): Enable/disable this service
  • urlPrefix (string, required): Base URL for user profiles
  • urlSuffix (string): Optional suffix added to URLs
  • class (string, required): CSS class for styling links
  • displayUsername (bool): Show only @username (true) or @username@instance (false)
  • name (string): Human-readable service name for documentation

Validation Rules:

  • URL Format: Must be valid HTTP/HTTPS URLs
  • CSS Classes: Must follow CSS naming conventions ([a-zA-Z][a-zA-Z0-9\-_]*)
  • Required Fields: urlPrefix and class are mandatory