README

ParagraphLinks is a MediaWiki extension that adds hover link icons to paragraphs, allowing users to easily copy direct links to specific content within wiki pages without needing to inspect the page source or manually add anchors.

Features

Hover Link Icons: Shows a link icon (🔗) when hovering over paragraphs
Automatic Anchor Generation: Creates meaningful anchor IDs based on paragraph content
One-Click Copy: Click the link icon to copy the full URL with anchor to clipboard
Mobile Friendly: Adapts to touch devices where hover isn't available
Accessible: Full keyboard navigation and screen reader support
Configurable: Enable/disable per namespace and global settings
No Database Changes: Pure client-side implementation with no schema modifications

Installation

You can install ParagraphLinks in two ways:

Manual Installation

Clone into your extensions/ directory:

cd /path/to/mediawiki/extensions/
git clone https://github.com/lucamauri/ParagraphLinks.git ParagraphLinks

Enable the extension in LocalSettings.php:
```
wfLoadExtension( 'ParagraphLinks' );
```
Update your wiki database schema (if prompted):
```
php maintenance/update.php
```

Composer Installation (Local without Packagist)

in your composer.local.json file create or add the following to require section:
```
"require": {
   "lucamauri/paragraphlinks": "~1.0",
}
```
and run
```
composer update --no-dev
```
Load the extension in LocalSettings.php:
```
wfLoadExtension( 'ParagraphLinks' );
```
Run schema updates if needed:
```
php maintenance/update.php
```

Configuration

The extension provides several configuration options:

// Enable or disable the extension globally (default: true)
$wgParagraphLinksEnabled = true;

// Namespaces where paragraph links are enabled
// Default: [0, 4, 10, 12, 14] (Main, Project, Template, Help, Category)
$wgParagraphLinksNamespaces = [
    NS_MAIN,        // 0 - Main namespace
    NS_PROJECT,     // 4 - Project namespace  
    NS_TEMPLATE,    // 10 - Template namespace
    NS_HELP,        // 12 - Help namespace
    NS_CATEGORY     // 14 - Category namespace
];

How It Works

Automatic Detection: The extension scans all paragraphs in the main content area
Anchor Generation: Creates unique anchor IDs based on the first few words of each paragraph
Visual Feedback: Shows a link icon on hover (always visible on mobile)
Clipboard Integration: Uses modern Clipboard API with fallback for older browsers
User Notification: Shows success/error messages when copying links

Browser Support

Modern Browsers: Full support with Clipboard API
Older Browsers: Fallback using document.execCommand
Mobile Devices: Touch-optimized interface
Accessibility: Screen reader and keyboard navigation support

File Structure

ParagraphLinks/
├── extension.json                        # Extension configuration
├── includes/
│   └── ParagraphLinksHooks.php           # Server-side hooks
├── resources/
│   ├── ext.paragraphlinks.js             # Client-side JavaScript
│   └── ext.paragraphlinks.css            # Styles
├── i18n/
│   ├── en.json                           # English messages
│   └── qqq.json                          # Message documentation
├── tests/
│   └── phpunit/
│       └── ParagraphLinksHooksTest.php   # Unit tests
├── README.md
└── LICENSE

Development

Requirements

MediaWiki 1.35.0 or higher
PHP 7.4 or higher
Modern browser with JavaScript enabled

Running Tests

# Run PHPUnit tests
php tests/phpunit/phpunit.php extensions/ParagraphLinks/tests/phpunit/

# Run with coverage
php tests/phpunit/phpunit.php --coverage-html coverage extensions/ParagraphLinks/tests/phpunit/

Development Setup

Clone the repository into your MediaWiki extensions/ directory

Enable developer mode in MediaWiki:

$wgShowExceptionDetails = true;
$wgDevelopmentWarnings = true;
$wgShowDBErrorBacktrace = true;

Disable caching during development:

$wgMainCacheType = CACHE_NONE;
$wgCacheDirectory = false;

Contributing

Fork the repository
Create a feature branch: git checkout -b feature/your-feature
Make your changes and add tests
Ensure all tests pass
Submit a pull request

Code Standards

Follow MediaWiki coding conventions
Use tabs for indentation in PHP, spaces in JavaScript/CSS
Add PHPDoc comments for all public methods
Write unit tests for new functionality
Ensure accessibility compliance

Security Considerations

The extension only operates on the client-side
No user input is processed server-side
Generated anchor IDs are sanitized
No database modifications are made
Uses secure clipboard API when available

Troubleshooting

Link icons not appearing:

Check that the extension is enabled in configuration
Verify the current page's namespace is in $wgParagraphLinksNamespaces
Ensure JavaScript is enabled in your browser

Copy to clipboard not working:

Modern browsers require HTTPS for clipboard access
Check browser console for JavaScript errors
Verify clipboard permissions are granted

Performance issues:

The extension only processes paragraphs with substantial content (>10 characters)
Client-side processing is minimal and cached
No server-side performance impact

License

This extension is licensed under the GPL-2.0-or-later license. See the LICENSE file for details.

lucamauri / paragraphlinks

Maintainers

Details