Linkit
Provides an enriched linking experience for internal and external linking with editors by using an autocomplete field.
linkit
Install
composer require 'drupal/linkit:^7.0'
Overview
Linkit provides an enhanced interface for creating internal and external links within WYSIWYG editors by using an autocomplete field. The module supports nodes, users, taxonomy terms, files, comments, and basic support for all entity types that define a canonical link template.
The module works through configurable profiles that define which matcher plugins to use for generating autocomplete suggestions. Each profile can have multiple matchers configured with different settings, allowing fine-grained control over what content appears in link suggestions.
Linkit integrates with CKEditor 5 to replace the standard link dialog with an enhanced version featuring autocomplete functionality. When users type in the link field, Linkit queries the configured matchers and displays relevant suggestions with metadata such as content type, creation date, and author information.
The module includes a text format filter that transforms entity references (stored as entity:type/id format) into actual URLs when content is rendered, ensuring that links stay up-to-date even when URL aliases change.
Features
- Autocomplete linking in WYSIWYG editors using customizable profiles
- Multiple built-in matchers for nodes, users, files, taxonomy terms, emails, external URLs, front page, and contact forms
- Generic entity matcher with automatic deriver for all entity types with canonical link templates
- Configurable metadata display with token support for each entity type in autocomplete suggestions
- Bundle filtering and grouping options for entity matchers
- URL substitution system to control how entity URLs are generated (canonical, direct file URL, media file URL)
- CKEditor 5 integration with enhanced link dialog
- Linkit field widget for link fields with autocomplete functionality
- Linkit field formatter for proper URL substitution when rendering links
- Linkit text format filter to convert entity references to current URLs
- Support for published/unpublished content filtering in suggestions
- Support for role-based user filtering
- File extension filtering and image thumbnail display options
- Automatic title attribute population from entity labels
- Pluggable and alterable architecture for custom matchers and substitutions
- Query and fragment preservation in links
Use Cases
Enriched content authoring
Content editors can quickly find and link to existing content by typing a few characters. The autocomplete shows content titles, types, creation dates, and authors, making it easy to identify the correct content to link to without leaving the editor.
Linking to files and media
Instead of copying file URLs manually, editors can search for files by name and create links directly to the file. For media entities, the substitution can be configured to link to the actual file rather than the media page.
Multi-site or multi-language content management
Linkit properly handles translated content by showing suggestions in the current language context and generates URLs that work with path aliases in any language.
Controlled linking by user role
The user matcher can be configured to only show users with specific roles, useful for creating links to staff profiles on an intranet or public-facing site.
Email link creation
When editors type an email address, Linkit automatically suggests creating a mailto: link, streamlining the process of adding email links to content.
Link field autocomplete
Using the Linkit widget on link fields provides the same autocomplete experience outside of WYSIWYG editors, useful for menu links, call-to-action buttons, or any link field.
Maintaining URL integrity
Links created through Linkit store entity UUIDs, so even if path aliases change, the Linkit filter ensures links always resolve to the correct, current URL when content is displayed.
Tips
- Use descriptive metadata in matcher settings with tokens like '[node:content-type:name] by [node:author]' to help editors identify content
- Create multiple profiles for different use cases - one for general content linking, another restricted to specific content types
- Set appropriate result limits to improve performance on sites with large amounts of content
- The matcher order in profiles determines the order of suggestions - place most commonly linked content types first
- Use bundle grouping to organize suggestions when linking to entity types with many bundles
- Enable automatic link text population in the Linkit widget to speed up content editing when using link fields
- Ensure the Linkit formatter profile matches the widget profile for consistent URL handling on link fields
Technical Details
Admin Pages 6
/admin/config/content/linkit
Lists all Linkit profiles with their descriptions. From here you can create, edit, or delete profiles, and access matcher management for each profile.
/admin/config/content/linkit/add
Create a new Linkit profile that defines how autocomplete suggestions are generated for links.
/admin/config/content/linkit/manage/{linkit_profile}
Edit the basic settings of an existing Linkit profile including its name and description.
/admin/config/content/linkit/manage/{linkit_profile}/matchers
Configure the matchers that define how autocomplete suggestions are generated for this profile. Matchers can be reordered by dragging and dropping. The order determines the order of suggestions in the autocomplete list.
/admin/config/content/linkit/manage/{linkit_profile}/matchers/add
Select a matcher plugin to add to this profile. Available matchers include entity-specific matchers (Content, User, File, Taxonomy term, etc.) and special matchers (Email, External URL, Front page).
/admin/config/content/linkit/manage/{linkit_profile}/matchers/{plugin_instance_id}
Configure the settings for a specific matcher instance. Settings vary by matcher type but commonly include metadata configuration, bundle restrictions, and limit settings.
Permissions 1
Hooks 2
hook_linkit_matcher_alter
Alter the definitions of all Linkit matcher plugins.
hook_linkit_substitution_alter
Alter the definitions of all Linkit substitution plugins.
Troubleshooting 5
Enable the 'Linkit URL converter' filter in the text format settings. Make sure it runs before the 'Limit allowed HTML tags' filter.
If using 'Limit allowed HTML tags', add data-entity-type, data-entity-uuid, and data-entity-substitution attributes to the allowed <a> tag configuration.
Verify that matchers are configured in the selected Linkit profile. Check that the profile is correctly selected in the text format's CKEditor configuration.
Edit the Content matcher settings and enable 'Include unpublished nodes'. Users must also have permission to view unpublished content.
Enable the 'Automatically set the title attribute' option in the Linkit filter settings. If using HTML restrictions, ensure the title attribute is allowed on <a> tags.
Security Notes 3
- The autocomplete endpoint respects entity access - users only see entities they have permission to view
- Unpublished content visibility in suggestions follows Drupal's standard permission system
- Entity UUIDs in stored links do not expose internal IDs to end users when properly filtered