Previously created media URLs should update if the matcher is changed from canonical to direct URL

Linkit provides a media "Matcher" configuration option to set whether links to media entities should display at the canonical URL (e.g., /media/1) or as the direct link to the file (e.g., /sites/default/files/myfile.png). For background, see #2866525: Direct link to file of linked media entity → and #2786049: Make entity URL substitutions pluggable to support a wider variety of use cases. →

However, this setting does not work retroactively for links inserted prior to configuring the Linkit matcher.

Similarly, if you change the setting after configuring it initially, the links do not take on the new configuration behavior.

This is because the markup stored includes either data-entity-substitution="media" or data-entity-substitution="canonical" and that value is not reevaluated against the current configuration setting in Linkit when the text filter runs.

Steps to reproduce

1. (Drupal core): Enable direct media links at /admin/config/media/media-settings
2. Add the "Linkit URL Converter" text filter to a text format.
3. Add a media item. From Step 1, its path should be /media/1
4. Create some content with you text format referencing a link to /media/1
5. When viewing the content, you should see a link to the canonical entity URL (e.g., /media/1)
6. Navigate to /content/linkit/manage/default/matchers/add
7. Add a new matcher for "Media"
8. Set the "Substitution type" to "Direct URL to media file entity"
9. Clear the cache and reload your content. You might expect to see the link to sites/default/files/myfile.png, but it remains with the original rendering of /media/1.

Next steps

Decide whether or not a change is even desirable. Specifically, should URLs be rendered in whatever form they were initially entered (data-entity-substitution "media" or "canonical"), or should Linkit override the data-entity-substitution value with whatever the current matcher configuration is set to?

Workarounds if the current behavior remains

From https://www.drupal.org/project/linkit/issues/2926655#comment-14971258 💬 Direct Link to File in Media Entity Document Fixed

If the value is 'canonical', it points to the Media entity. If you replace it with 'media', it points to to the file.

You could do a bulk Find and Replace (carefully) to save the pain of finding and replacing all your media links.