minor #20212 [WebLink] improve web_link (garak)

javiereguiluz · javiereguiluz · commit 6ff94910f0af · 2024-09-19T16:39:26.000+02:00
This PR was submitted for the 7.1 branch but it was merged into the 6.4 branch instead. Discussion ---------- [WebLink] improve web_link The current doc for generating the proper lines in the `head` section is quite misleading, acting as if it could be enough to use a single line to include a style/script, while two lines each are needed. Moreover, despite mentioning the need for the `as` attribute, if fails to add it in the examples. The proposed changes should fix both problems. Commits ------- 35c94bc improve web_link
diff --git a/web_link.rst b/web_link.rst
@@ -59,7 +59,8 @@ correct prioritization and the content security policy:
 
     <head>
         <!-- ... -->
-        <link rel="preload" href="{{ preload('/app.css', { as: 'style' }) }}">
+        <link rel="preload" href="{{ preload('/app.css', {as: 'style'}) }}" as="style">
+        <link rel="stylesheet" href="/app.css">
     </head>
 
 If you reload the page, the perceived performance will improve because the
@@ -74,7 +75,8 @@ requested the HTML page.
 
         <head>
             <!-- ... -->
-            <link rel="preload" href="{{ preload(asset('build/app.css')) }}">
+            <link rel="preload" href="{{ preload(asset('build/app.css')) }}" as="style">
+            <!-- ... -->
         </head>
 
 Additionally, according to `the Priority Hints specification`_, you can signal
@@ -84,7 +86,8 @@ the priority of the resource to download using the ``importance`` attribute:
 
     <head>
         <!-- ... -->
-        <link rel="preload" href="{{ preload('/app.css', { as: 'style', importance: 'low' }) }}">
+        <link rel="preload" href="{{ preload('/app.css', {as: 'style', importance: 'low'}) }}" as="style">
+        <!-- ... -->
     </head>
 
 How does it work?
@@ -108,7 +111,8 @@ issuing an early separate HTTP request, use the ``nopush`` option:
 
     <head>
         <!-- ... -->
-        <link rel="preload" href="{{ preload('/app.css', { as: 'style', nopush: true }) }}">
+        <link rel="preload" href="{{ preload('/app.css', {as: 'style', nopush: true}) }}" as="style">
+        <!-- ... -->
     </head>
 
 Resource Hints
@@ -142,7 +146,8 @@ any link implementing the `PSR-13`_ standard. For instance, any
     <head>
         <!-- ... -->
         <link rel="alternate" href="{{ link('/index.jsonld', 'alternate') }}">
-        <link rel="preload" href="{{ preload('/app.css', { as: 'style', nopush: true }) }}">
+        <link rel="preload" href="{{ preload('/app.css', {as: 'style', nopush: true}) }}" as="style">
+        <!-- ... -->
     </head>
 
 The previous snippet will result in this HTTP header being sent to the client:
