Using Linkilo with Gutenberg (Block Editor)

Gutenberg is Linkilo's native home

If you're using the default WordPress block editor (Gutenberg), Linkilo runs in its most native mode. Suggestions appear inline, the metabox sits right below the editor, and "Apply" writes a clean <a> tag into the actual block content — no special configuration needed.

This is the path the rest of the documentation assumes by default.

How Linkilo reads Gutenberg posts

The block editor stores content in post_content as a mix of HTML and block markers like <!-- wp:paragraph -->. Linkilo:

1. Reads post_content.
2. Walks the block tree using WordPress's parse_blocks() function — without rendering shortcodes or running PHP, so it stays fast.
3. Expands reusable blocks (wp:block references) up to a few levels deep, so a link inside a reusable block is found just like a link in regular content.
4. Skips over block-level wrappers and reads the actual text inside each paragraph, heading, or list block.

If a block contains a shortcode that only renders something at view time, Linkilo skips that shortcode and reads what's directly in the block.

Where the metabox appears

Open any post in the block editor. The AI Link Suggestions metabox sits below the editor canvas, in the standard metabox area. Two tabs at the top: AI Suggestions (with the OPENAI badge) and Legacy Suggestions (with the FREE — NO API KEY badge).

If you don't see the metabox:

1. Click the three-dot menu (top-right of the editor) → Preferences → Panels → confirm Linkilo's metabox is checked.
2. Or open Screen Options at the top of the post-edit screen (visible when the block editor shifts the screen-options bar to the top).
3. Confirm the post type is enabled in Linkilo → Settings → General → Find suggested URLs in these post types only.

How "Apply" works on a Gutenberg post

When you click Apply:

1. Linkilo finds the source sentence in the block content.
2. Wraps the anchor text in an <a> tag (block-syntax-aware — heading blocks stay heading blocks; list items keep their <li> wrapper).
3. Writes the modified post_content back.
4. Triggers a linkilo_gutenberg_restart meta hint so the editor knows to refresh if you're currently editing the post.

When you reload the editor, the link is present in the right block — not a separate paragraph, not a stray wrapper.

Reusable blocks

Links Linkilo writes into the body of a post live in the post's own content. Linkilo does not edit the source of a reusable block — that would cascade the change to every other post using that block, which is rarely what you want.

If a reusable block contains a link suggestion, Linkilo will surface it as a candidate (during scanning it expands the block to find the text) but Apply will write the link to the post's own content, not back into the reusable block's source.

Working with full-site editing (FSE) themes

Linkilo scans posts and pages, not template parts. If you're using an FSE theme with wp_template and wp_template_part post types, those aren't scanned by default. You usually don't want them scanned — templates are layout, not content. Leave them disabled in Settings → General.

Troubleshooting

The metabox appears but is empty

Click Get AI Suggestions (or Get Legacy Suggestions) explicitly. The metabox doesn't auto-fetch on page load — it waits for you to ask.

After clicking Apply, the editor still shows the old content

Reload the post. The block editor caches the loaded post in memory and doesn't auto-refresh when content changes outside the editor. After reload, the link is in the correct block.

"Get AI Suggestions" hangs forever

Usually an OpenAI key or outbound HTTPS issue. See Troubleshooting → Per-Post Suggestions (Metabox) for the full checklist.

See also

• Using Linkilo with Elementor
• Using Linkilo with Divi
• Using Linkilo with the Classic Editor
• AI Suggestions