How to Add Internal Links in the Gutenberg Editor

Adding internal links inside the WordPress block editor seems simple on the surface: highlight text, press a shortcut, search for a post, and click insert. Yet if you produce content regularly, you know how frustrating the native link popup can be when your site holds hundreds of articles.

When you need to add internal links gutenberg provides native keyboard shortcuts, inline search queries, and specific block settings. But if you do not understand how Gutenberg formats link markup, you can easily waste valuable writing time or accidentally break block validation when switching between visual and code modes.

This tutorial breaks down the fastest ways to insert links inside the WordPress block editor. You will learn essential keyboard shortcuts, how to link directly to specific section headings, how to format button blocks properly, and how to avoid the common errors that corrupt block content.

The fastest way to insert links using keyboard shortcuts

Reaching for the mouse every time you want to insert a link disrupts your writing flow. Gutenberg includes built-in keyboard shortcuts that let you add hyperlinks in under three seconds without taking your fingers off the keyboard.

Here is the standard workflow:

1. Highlight the word or phrase you want to turn into anchor text using Shift + Arrow Keys.
2. Press Cmd + K on macOS or Ctrl + K on Windows. The inline link popup opens immediately.
3. Type two or three letters of your target article title. Gutenberg performs a quick AJAX query against your published posts.
4. Use the down arrow key to select the correct post from the dropdown list.
5. Press Enter to apply the link, then press Escape or continue typing to close the dialog.

If you already have the destination URL copied to your clipboard, the process is even faster: simply highlight the text and press Cmd + V or Ctrl + V. Gutenberg automatically converts the highlighted text into a link pointing to the URL on your clipboard without opening the popup.

How Gutenberg formats links inside block markup

Understanding how the block editor stores your links helps you troubleshoot formatting issues before they cause problems. Unlike legacy editors that stored raw HTML directly, Gutenberg separates block controls from paragraph markup.

When you insert a link into a standard paragraph, WordPress wraps the anchor tag directly inside the paragraph markup:

<!-- wp:paragraph -->
<p>Check our comprehensive guide to <a href="https://linkcortex.in/blog/internal-linking-wordpress/">internal linking in WordPress</a> for full strategy details.</p>
<!-- /wp:paragraph -->

Notice that the link attributes remain plain HTML within the block boundaries. However, in more complex blocks such as buttons, cards, or cover blocks, the link target is often stored twice: once inside the rendered HTML and once within the block delimiter comment as JSON attributes:

<!-- wp:button {"url":"https://linkcortex.in/","className":"is-style-fill"} -->
<div class="wp-block-button is-style-fill">
  <a class="wp-block-button__link" href="https://linkcortex.in/">Explore LinkCortex</a>
</div>
<!-- /wp:button -->

If you manually edit this code in code editor view and change the URL in the href tag without updating the JSON attribute in the comment, WordPress will report that the block contains unexpected or invalid content. To learn more about block standards, consult the official WordPress documentation on the block editor.

Linking directly to headings using HTML anchors

Long guides often benefit from jump links that send readers directly to a specific subtopic or comparison table. Gutenberg makes this easy using native HTML anchors on heading blocks:

1. Click on the target heading block (H2 or H3) you want to link to.
2. In the right-hand block settings panel, expand the Advanced accordion.
3. In the HTML anchor field, enter a short identifier using lowercase letters and hyphens (for example, audit-steps). Do not include spaces or hash symbols.
4. Return to your body text where you want to place the jump link.
5. Select your anchor text, press Cmd + K, and enter #audit-steps as the URL.

When clicked, the browser smoothly scrolls the visitor directly to that heading. This improves user experience on in-depth pillar guides and helps search engines generate jump-to links in search snippets.

Configuring link settings: new tabs and nofollow attributes

The Gutenberg link popup includes an advanced settings toggle that gives you granular control over link behaviors. When you click the link toolbar and select Advanced, you have access to three toggles:

• Open in new tab: Adds target="_blank" and rel="noreferrer noopener". Keep this turned off for internal links on your own site. Only use it when linking to external resources.
• Search engines should ignore this link (nofollow): Adds rel="nofollow". Never enable this for internal links between your own blog posts. Nofollow prevents equity from passing to your target article.
• Mark as sponsored: Adds rel="sponsored". Use this strictly for affiliate links or paid sponsorships.

Connecting unlinked articles from the block editor

A common operational challenge in WordPress is remembering which older posts need links. When drafting an article in Gutenberg, writers rarely take the time to run database queries or check spreadsheet trackers. Over time, this leads to accumulated unlinked content across your site.

As detailed in our breakdown of orphan pages and their impact on SEO, unlinked posts miss out on critical crawl budget and search authority. While Gutenberg provides a clean editing experience, it does not tell you which articles across your site need links.

This is where native WordPress tools like LinkCortex streamline the workflow. Rather than manually switching tabs to look up old slugs, a smart link suggester highlights relevant link opportunities directly within your editor sidebar. You can review natural anchor suggestions and insert them into paragraph blocks with a single click.

Troubleshooting broken block links

If you encounter issues where links fail to save or trigger block errors in Gutenberg, check these three common causes:

1. Nested anchor tags: HTML strictly prohibits placing an anchor tag inside another anchor tag. If you accidentally highlight text that already contains a link and insert another, Gutenberg can freeze or generate corrupt markup. Always remove existing links before applying new ones.
2. Trailing spaces in URLs: Pasting a URL with an accidental leading or trailing space can cause 404 errors or broken relative paths. Gutenberg usually trims whitespace, but custom blocks might not.
3. Relative link mismatches: Entering /post-slug/ works well in most browsers, but if your site structure changes or you view content in RSS feeds, full absolute URLs (https://linkcortex.in/post-slug/) are more reliable.

Frequently asked questions

What is the keyboard shortcut to insert a link in Gutenberg?

Highlight the text and press Cmd + K on Mac or Ctrl + K on Windows. If you already have the destination URL copied to your clipboard, simply highlight the text and press Cmd + V or Ctrl + V to apply the link instantly.

Can I link to WordPress media files like PDFs in the block editor?

Yes. Upload the PDF to your Media Library, copy its file URL, highlight your anchor text in Gutenberg, and paste the URL. You can also use the native File block, which includes an automatic download button.

Why does my Gutenberg block say it contains invalid content after editing a link?

This happens when block markup is edited in code view and the HTML does not match the JSON attributes stored in the comment delimiter. Click the three dots on the block and choose Attempt Block Recovery to restore it.

Next steps in the editor

During your next writing session in WordPress, practice using Cmd + K or Ctrl + K for every link you insert. Eliminating manual mouse clicks will save you hours of editing time every month and make internal linking a natural part of your content workflow.