[jeryj]

What?

Closes #63683

Changes __experimentalFetchLinkSuggestions to rank results by type (content, taxonomies, post formats, and attachments) and keeps all search results instead of slicing multi-type searches to the perPage value.

Why?

Since 6.7 an unscoped link search covers every type at once, and the complaints in #63683 are consistent — from WordPress VIP, Human Made and several agencies — that editors can no longer find their content:

Every post with a related tag and every relevant attachment fills the search results and the post isn't there.

There are two separate causes.

1. Every type competes on equal terms, and the score favours short titles. sortResults scores a title by how many of its tokens match, divided by its own token count:

const exactMatchScore = ( exactMatchingTokens.length / titleTokens.length ) * 10;

Searching coffee, an attachment called coffee-beans scores the maximum 10, while a page called Coffee Roasting Guide For Beginners scores 1/5 * 10 = 2.00 — marked down purely for being long.

2. Results are discarded and nothing can ask for them again. Four endpoints are queried at per_page: perPage, merged, sorted and cut to perPage. 60 potential matches are discarded. page is passed to each endpoint, so "page 2" returns items 21–40 of each type — it skips straight over whatever the merge discarded. Those results are unreachable.

Points 1 and 2 compound the issue: the search favors short terms like attachments and taxonomy terms and also cuts at 20 with no pagination possible, so large sites frequently don't get the result they want.

How?

Improve Ordering

Ordering is done by a series of comparisons:

how many of the words typed does the title hold
  → does the title contain what was typed
    → what type is it
      → does the title begin with what was typed
        → how much of the search does the title cover (by word, not total length)

Let's assume a search of "coffee beans":

1. Number of word matches in the title: "coffee beans" matches above "coffee" in the title with "beans" in the body text of the post
2. Ordering of the title matches. "The best coffee beans today" will match above "For the best coffee, you need the best beans" because of the separation between words
3. Content Type: content > taxonomies > post formats > media
4. Starting with search: "Coffee beans, lightly roasted" will rank above "The freshest coffee beans"
5. Percentage of matched word: The search "cat" ranks the title "Cats" above the title "Caterpillar" since "cat" is 75% of "Cats" and only 27% of "Caterpillar"

Return all results

Instead of slicing by the perPage, we return all the pages from each query. This makes page work as well, and results are not lost.

Testing Instructions

Use a site with a media library, and images whose filenames share a word with some pages. I have been asking an agent to populate content to test this.

1. Open a post, select some text, press Cmd/Ctrl+K, and search a word that matches both.
2. Pages and posts now come first, with attachments below them — including attachments whose filenames start with the word.
3. Create pages Our Coffee and Coffee Roasting Guide For Beginners, then search coffee. The one that starts with the word now leads; on trunk it comes last.
4. Search two words that appear in a title but not together, such as coffee guide against Guide to Coffee. It is still returned, below the titles that hold the words together.
5. Search a word matching many things. The list is longer than 20, because nothing that answers the search is discarded.
6. Confirm a narrowed search is unchanged:

   ( await wp.coreData.__experimentalFetchLinkSuggestions( 'a', { type: 'term', perPage: 5 } ) ).length;  // 5

7. Open a Link UI without typing anything. The initial suggestions are still a short list.

Automated coverage

npm run test:unit:vitest -- --run packages/core-data/src/fetch

🤖 Generated with Claude Code

[github-actions]

🤖 PR meta 🤖

🎉 Props

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @swissky, @tonx, @devisan.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: swissky, tonx, devisan.

Co-authored-by: jeryj <jeryj@git.wordpress.org>
Co-authored-by: draganescu <andraganescu@git.wordpress.org>
Co-authored-by: noisysocks <noisysocks@git.wordpress.org>
Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org>
Co-authored-by: SainathPoojary <sainathpoojary@git.wordpress.org>
Co-authored-by: getdave <get_dave@git.wordpress.org>
Co-authored-by: t-hamano <wildworks@git.wordpress.org>
Co-authored-by: jasmussen <joen@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>
Co-authored-by: graylaurenm <oncecoupled@git.wordpress.org>
Co-authored-by: rickcurran <rickcurran@git.wordpress.org>
Co-authored-by: roborourke <sanchothefat@git.wordpress.org>
Co-authored-by: richtabor <richtabor@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

Updated as activity occurs, without notifying anyone named here. Add the props-bot label to refresh.

📦 Bundle size

Size Change: +246 B (0%)

Total Size: 8.25 MB

📦 View Changed

Filename	Size	Change
build/scripts/core-data/index.min.js	38 kB	+246 B (+0.65%)

_{174d158 Run}

⚡ Performance

Show the results

Client side metrics exclude the server response time.

front-end-block-theme

Metric	8233642	trunk	% Change
timeToFirstByte	59.35 ms +9.35% -3.54%	57.25 ms +13.71% -2.45%	3.67%
largestContentfulPaint	100 ms +4% -4%	100 ms +4% -8%	0%
lcpMinusTtfb	36.85 ms +22.66% -3.53%	36.7 ms +20.3% -8.04%	0.41%
wpBeforeTemplate	28.52 ms +16.23% -1.4%	28.27 ms +10.05% -1.49%	0.88%
wpTemplate	25.81 ms +3.33% -3.56%	24.6 ms +3.66% -1.46%	4.92%
wpTotal	55.45 ms +9.65% -3.62%	53.64 ms +13.42% -2.91%	3.37%
wpMemoryUsage	7.62 MB +0% -0%	7.59 MB +0% -0%	0.46%
wpDbQueries	17 +0% -0%	17 +0% -0%	0%

front-end-classic-theme

Metric	8233642	trunk	% Change
timeToFirstByte	42.85 ms +5.72% -0.7%	50.35 ms +2.98% -3.08%	-14.9%
largestContentfulPaint	92 ms +4.35% -0%	108 ms +0% -3.7%	-14.81%
lcpMinusTtfb	49.45 ms +4.55% -0.61%	56.2 ms +3.56% -2.4%	-12.01%
wpBeforeTemplate	26.14 ms +2.87% -1.42%	27.55 ms +5.84% -2%	-5.12%
wpTemplate	13.72 ms +2.62% -0.66%	18.66 ms +6.27% -1.71%	-26.47%
wpTotal	39.89 ms +6.49% -1.1%	47.01 ms +3.11% -3.21%	-15.15%
wpMemoryUsage	6.11 MB +0% -0%	6.20 MB +0% -0%	-1.57%
wpDbQueries	10 +0% -0%	14 +0% -0%	-28.57%

media-processing

Metric	8233642	trunk	% Change
mediaProcessingJpeg	401.1 ms +1.63% -0.85%	405.82 ms +2.84% -0.53%	-1.16%
mediaProcessingAvif	6042.41 ms +0.23% -0.1%	6081.83 ms +0.07% -0.39%	-0.65%
mediaProcessingJpegToAvif	4171.37 ms +0.49% -0.18%	4199.34 ms +0.16% -0.57%	-0.67%

media-upload

Metric	8233642	trunk	% Change
jpegUploadProcessing	1479.5 ms +29.96% -3.99%	1430.8 ms +1.57% -1.36%	3.4%
pngUploadProcessing	203.4 ms +25.29% -12.6%	182.36 ms +29.63% -3.11%	11.54%
largeJpegUploadProcessing	1412.92 ms +1.2% -0.64%	1419.44 ms +0.69% -1.12%	-0.46%
multipleImageUploadProcessing	1633.38 ms +8.63% -1.59%	1612.57 ms +0.5% -3.34%	1.29%

post-editor

Metric	8233642	trunk	% Change
serverResponse	528.14 ms +1.86% -7.14%	530.92 ms +1.16% -2.78%	-0.52%
firstPaint	244.62 ms +21.11% -27.1%	217.1 ms +9.07% -6.44%	12.68%
domContentLoaded	1137.95 ms +0.72% -3.49%	1116.09 ms +0.87% -2.48%	1.96%
loaded	1139.26 ms +0.73% -3.5%	1117.48 ms +0.87% -2.48%	1.95%
firstContentfulPaint	465.12 ms +2.7% -7.74%	455.64 ms +5.74% -11.72%	2.08%
firstBlock	3378.04 ms +1.37% -1.39%	3313.37 ms +1.3% -1.39%	1.95%
type	19.69 ms +3.66% -5.03%	18.57 ms +3.98% -6.89%	6.03%
typeWithoutInspector	18.7 ms +7.81% -4.49%	18.06 ms +6.87% -4.43%	3.54%
typeWithTopToolbar	24.72 ms +4.05% -9.1%	24.37 ms +4.6% -5.13%	1.44%
typeContainer	9.44 ms +6.25% -10.81%	8.99 ms +5.01% -12.24%	5.01%
focus	78.84 ms +7.5% -11.04%	74.63 ms +24.13% -6.2%	5.64%
firstFocus	222.34 ms +0% -0%	207.03 ms +0% -0%	7.4%
selectAll	561.43 ms +3.79% -3.63%	547.77 ms +0.74% -4.83%	2.49%
listViewOpen	65.4 ms +13.82% -12.29%	65.22 ms +8.23% -8.3%	0.28%
inserterOpen	25.62 ms +7.34% -17.1%	23.84 ms +11.37% -6.71%	7.47%
inserterHover	2.32 ms +4.74% -7.76%	2.31 ms +15.15% -9.52%	0.43%
inserterSearch	8.32 ms +2.64% -7.09%	8 ms +5.37% -7.37%	4%
loadPatterns	666.95 ms +3.3% -3.76%	658.37 ms +3.19% -1.98%	1.3%
wpTotal	517.1 ms +2.16% -7.12%	520.55 ms +1.21% -2.83%	-0.66%
wpMemoryUsage	13.17 MB +0% -0%	13.13 MB +0% -0%	0.28%
wpDbQueries	54 +0% -0%	54 +0% -0%	0%

site-editor

Metric	8233642	trunk	% Change
serverResponse	506.03 ms +2.44% -7.76%	486.28 ms +5.95% -4.47%	4.06%
firstPaint	238.93 ms +7.19% -17.21%	300.24 ms +52.26% -29.71%	-20.42%
domContentLoaded	1139.96 ms +2.21% -1.01%	1138.24 ms +3.04% -1.25%	0.15%
loaded	1141.26 ms +2.22% -1.03%	1139.4 ms +3.03% -1.23%	0.16%
firstContentfulPaint	457.23 ms +5.45% -5.21%	464.62 ms +2.13% -1.61%	-1.59%
firstBlock	4117.71 ms +1.6% -0.38%	4221.45 ms +0.62% -0.55%	-2.46%
type	18.53 ms +3.24% -3.18%	17.64 ms +8.5% -4.31%	5.05%
navigate	118.57 ms +1.65% -3.94%	102.97 ms +2.9% -1.79%	15.15%
loadPatterns	1444.67 ms +8.36% -8.7%	1322.45 ms +3.73% -2.87%	9.24%
loadPages	1052.55 ms +0.9% -1.38%	1056.66 ms +5.84% -3.2%	-0.39%
wpTotal	496.67 ms +2.41% -8.02%	476.57 ms +6.05% -4.6%	4.22%
wpMemoryUsage	12.14 MB +0% -0%	12.09 MB +0% -0%	0.41%
wpDbQueries	43 +2.33% -0%	43 +2.33% -0%	0%

_{174d158 Run}

[draganescu]

There are some nits but the big nit which may not be a nit is that perPage now is controlling:

• page size sent to endpoints
• a signal to cap the merged list
• a signal to keep body only matches

This is not the best shape. perPage should only be page size sent to endpoints.

Second, the ranking and the body only thing could be separated. Only because discarding body only matches is unexpected - it is a bad UX to show unrelated titles, but instead of discarding results we could put it in the UI that the match is NOT in the title but in the body (like a snippet match +/- some chars?).

[draganescu]

This could result in up to 80 items scrolling in the tiny link popover. Nit.

[jeryj]

Yeah, but at least you can find them. Most of the time you'd never scroll that far, and since it's overflow hidden, the only people that would encounter that far of a scroll is if they needed those results.

[draganescu]

We could decide that we don't want body only matches from a word being typed, or through a separate condition and let page limit only be that.

[jeryj]

Body results only come back because of how WordPress queries with an AND across post_title, post_content and post_excerpt columns. core data didn't offer a post_title only column option til recently, so when this code was written it wasn't possible to only search a title. #78683 reinforces the decision to only search from a title.

I would have been fine leaving this behavior as is (returning content matches), but it made the code more complicated to bring a behavior that was already iffy. So, I decided to cut it rather than make it work, only to remove it in a follow up PR.

[draganescu]

#78683 is about a page parent listing and the enforcement is done by specifying this in query. When linking it's not clear we should be looking for only titles.

[jeryj]

perPage now is controlling:

• page size sent to endpoints
• a signal to cap the merged list
• a signal to keep body only matches

This is not the best shape. perPage should only be page size sent to endpoints.

I agree, and am also unsure how to rework the API to provide the behavior in this PR, which is definitely a better end user experience than trunk. I'm very open to adding a new prop to communicate the behavior, but perPage is already a broken prop as it cannot accurately paginate on multi-type searches (default).

In its current form on trunk:

fetchLinkSuggestions( {
  perPage: 20,
  page: 1
} );

This performs a search for 20 results from four different areas (post-type, term, post-format, media) to return up to 80 results from page 1 of each type. Then, the 20 best matches are returned with up to 60 cut as low matches.

fetchLinkSuggestions( {
  perPage: 20,
  page: 2
} );

Fetching page 2 does not search from those 60 discarded results which might have been the results you wanted. It searches { perPage: 20, page: 2 } of each type, and those 60 lost are unreachable.

So, I went with, if perPage is not passed explicitly, we have no contract to honor, and return up to 80 matches. If someone wants the old behavior again, they can pass an explicit perPage: 20. This isn't ideal, but trying to make the most of a bad situation :)

I also considered adding an additional prop instead of relying on the absence of a perPage value:

1. limit: allow perPage to be set and it operates as it does today. It searches 20 from each bucket but you can limit the results that come back. It's a bit odd since you'd think perPage was already the limit. limit could default to the perPage value. In this PR to get our desired behavior, we'd pass limit as 80 or maybe -1 to return everything.
2. kind or behavior: Some kind of enum to allow you to use perPage as a limit or to allow more results to come through.
3. ???? what else could be a good prop name?

[draganescu]

I noticed this behaviour of double scrolling on this branch

double-scroll.mp4

[jeryj]

@draganescu

I noticed this behaviour of double scrolling on this branch

I've noticed that before too, and I believe it's on trunk too. This PR doesn't touch any UI.

[draganescu]

a nit and a UI issue above but otherwise we can roll with this

[draganescu]

We don't use this result as a weight so maybe getTypeRank ? And also the doc is talking about a weight but a.type - b.type (since getTypeWeight is assigned later to type in scored) is just a rank

[draganescu]

Hmm, I did checkout trunk to see if the double scrollbar repros and it wasn't but I agree it may be a fluke.
🚢