Block Editor Integration

Overview

GT Link Manager adds a link search tool directly into the Gutenberg block editor toolbar. When you’re writing content in any rich text block (paragraphs, headings, list items, etc.), you can search your link library and insert a branded link without leaving the editor.

The integration registers as a custom RichText format type using the WordPress @wordpress/rich-text API. It appears in the block editor toolbar as a standard toolbar button with a link icon.

Using the link inserter

Select some text in any rich text block — this is the text that will become the link anchor. With text selected, look for the GT Links button in the block toolbar. It appears alongside the standard Bold, Italic, and Link buttons.

Clicking the button opens a popover panel positioned near the selected text. The popover contains a search field.

If you had text selected when you opened the popover, the search field is pre-populated with the selected text. This makes the common workflow — “select the product name, search for it, click the result” — frictionless.

Type in the search field to search your links by name or slug. Results appear as a list below the search field after a short debounce. Each result shows the link name and slug.

Click a result to insert it. The selected text becomes a hyperlink pointing to the branded URL. The rel attributes configured on that link are automatically applied to the inserted link’s rel attribute. The popover closes.

What gets inserted

The inserted link uses the core/link RichText format, which is WordPress’s standard link format. This means the link renders as a normal <a> element in the post content. It’s not a special shortcode or custom block.

The href attribute is set to the full branded URL — yoursite.com/go/slug. The rel attribute is set using space-separated values derived from the link’s configured rel field.

Because the link is stored as a standard WordPress link in the post content, it works correctly across all themes and anywhere rich text content is rendered.

How search works

Search queries go to the GT Link Manager REST API endpoint GET /wp-json/gt-link-manager/v1/links with the search parameter. Results are limited to 20 items per search. The search is debounced by a short interval so it doesn’t fire on every keystroke.

The search operates across link name and slug simultaneously. It’s case-insensitive. There’s no relevance ranking — results are returned in the default sort order (newest first by ID).

If the search returns no results, the popover shows a “No links found” message.

Loading state

While the search request is in flight, the popover shows a spinner. If the request fails (network error, server error), the popover shows an error notice with a message.

Enqueuing and dependencies

The block editor assets are only enqueued when the block editor is active. The GT_Link_Block_Editor class hooks into enqueue_block_editor_assets to load the compiled JavaScript.

The JavaScript bundle is compiled from blocks/link-inserter/src/index.js using @wordpress/scripts. The build output at blocks/link-inserter/build/index.js has an associated index.asset.php file that declares the runtime dependencies. These dependencies are automatically loaded by WordPress — they include @wordpress/rich-text, @wordpress/block-editor, @wordpress/components, and @wordpress/element.

The plugin passes configuration data to the script via wp_localize_script as window.gtLinkManagerEditor. This includes the REST API base URL and a nonce for authenticated requests.

Building the assets

If you’re developing GT Link Manager or need to recompile the block editor JavaScript, use the build script:

bash build.sh

This runs @wordpress/scripts build targeting blocks/link-inserter/src/index.js and outputs to blocks/link-inserter/build/. It also regenerates the index.asset.php dependency manifest.

You need Node.js and npm installed, with @wordpress/scripts available as a package dependency.

For active development with hot reloading, you can run:

cd blocks/link-inserter && npx wp-scripts start

Compatibility

The block editor integration works in the standard WordPress post and page editor, and in any context where Gutenberg’s block editor is active. It works in the site editor (FSE/Full Site Editing) for editing patterns and templates.

It doesn’t appear in the Classic Editor, as that editor doesn’t use the RichText format type API.

It also doesn’t appear in block previews or front-end rendering contexts. The script is only enqueued in admin block editor contexts.