Addons: add linkpreviews.selector field (#12301)

This field is used to allow users to customize the CSS selector used by
addons to grab all the links where they want to apply link previews
addons.

Required by readthedocs/addons#554

Author: humitos

readthedocs/projects/forms.py

@@ -687,6 +687,7 @@ class Meta:
             "hotkeys_enabled",
             "search_enabled",
             "linkpreviews_enabled",
+            "linkpreviews_selector",
             "notifications_enabled",
             "notifications_show_on_latest",
             "notifications_show_on_non_stable",
@@ -701,6 +702,7 @@ class Meta:
             "notifications_show_on_non_stable": _("Show a notification on non-stable versions"),
             "notifications_show_on_latest": _("Show a notification on latest version"),
             "linkpreviews_enabled": _("Enabled"),
+            "linkpreviews_selector": _("CSS link previews selector"),
             "options_root_selector": _("CSS main content selector"),
         }
 

readthedocs/projects/migrations/0151_addons_linkpreviews_selector.py

@@ -0,0 +1,36 @@
+# Generated by Django 5.2.3 on 2025-07-08 09:38
+
+from django.db import migrations
+from django.db import models
+from django_safemigrate import Safe
+
+
+class Migration(migrations.Migration):
+    safe = Safe.before_deploy()
+
+    dependencies = [
+        ("projects", "0150_add_ssh_key_with_write_access"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="addonsconfig",
+            name="linkpreviews_selector",
+            field=models.CharField(
+                blank=True,
+                help_text="CSS selector to select links you want enabled for link previews. Leave it blank for auto-detect all links in your main page content.",
+                max_length=128,
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="historicaladdonsconfig",
+            name="linkpreviews_selector",
+            field=models.CharField(
+                blank=True,
+                help_text="CSS selector to select links you want enabled for link previews. Leave it blank for auto-detect all links in your main page content.",
+                max_length=128,
+                null=True,
+            ),
+        ),
+    ]

readthedocs/projects/models.py

@@ -259,6 +259,12 @@ class AddonsConfig(TimeStampedModel):
 
     # Link Previews
     linkpreviews_enabled = models.BooleanField(default=False)
+    linkpreviews_selector = models.CharField(
+        null=True,
+        blank=True,
+        max_length=128,
+        help_text="CSS selector to select links you want enabled for link previews. Leave it blank for auto-detect all links in your main page content.",
+    )
 
 
 class AddonSearchFilter(TimeStampedModel):

readthedocs/proxito/tests/responses/v1.json

@@ -171,7 +171,8 @@
       "src": null
     },
     "linkpreviews": {
-      "enabled": false
+      "enabled": false,
+      "selector": null
     }
   }
 }

readthedocs/proxito/tests/test_hosting.py

@@ -742,6 +742,7 @@ def test_linkpreviews(self):
         )
         expected = {
             "enabled": True,
+            "selector": None,
         }
 
         assert r.status_code == 200

readthedocs/proxito/views/hosting.py

@@ -507,6 +507,7 @@ def _v1(self, project, version, build, filename, url, request):
                 },
                 "linkpreviews": {
                     "enabled": project.addons.linkpreviews_enabled,
+                    "selector": project.addons.linkpreviews_selector,
                 },
                 "hotkeys": {
                     "enabled": project.addons.hotkeys_enabled,