refactor: Move CSS tags in basic/layout.html to `css_files` variable

To make CSS customizable, all CSS files in basic/layout.html has their
priority: 200.  Therefore, extensions and users can insert their own
custom CSS files before or just after them.

As a side effect, the CSS tags in basic/layout.html are removed.  These
CSS files will be rendered via `css_files` template variable.

refs: #8634, c5f0398010

CHANGES

@@ -20,6 +20,7 @@ Incompatible changes
   :confval:`man_make_section_directory`)
 * #8380: html search: search results are wrapped with ``<p>`` instead of
   ``<div>``
+* html theme: Move CSS tags in basic/layout.html to ``css_files`` variable
 * #8508: LaTeX: uplatex becomes a default setting of latex_engine for Japanese
   documents
 

sphinx/application.py

@@ -983,6 +983,8 @@ class Sphinx:
 
            * - Priority
              - Main purpose in Sphinx
+           * - 200
+             - default priority for built-in CSS files
            * - 500
              - default priority for extensions
            * - 800

sphinx/builders/html/__init__.py

@@ -250,6 +250,14 @@ class StandaloneHTMLBuilder(Builder):
                 return jsfile
         return None
 
+    def _get_style_filename(self) -> str:
+        if self.config.html_style is not None:
+            return self.config.html_style
+        elif self.theme:
+            return self.theme.get_config('theme', 'stylesheet')
+        else:
+            return 'default.css'
+
     def get_theme_config(self) -> Tuple[str, Dict]:
         return self.config.html_theme, self.config.html_theme_options
 
@@ -285,6 +293,9 @@ class StandaloneHTMLBuilder(Builder):
             self.dark_highlighter = None
 
     def init_css_files(self) -> None:
+        self.add_css_file('pygments.css', priority=200)
+        self.add_css_file(self._get_style_filename(), priority=200)
+
         for filename, attrs in self.app.registry.css_files:
             self.add_css_file(filename, **attrs)
 
@@ -470,13 +481,6 @@ class StandaloneHTMLBuilder(Builder):
                 rellinks.append((indexname, indexcls.localname,
                                  '', indexcls.shortname))
 
-        if self.config.html_style is not None:
-            stylename = self.config.html_style
-        elif self.theme:
-            stylename = self.theme.get_config('theme', 'stylesheet')
-        else:
-            stylename = 'default.css'
-
         self.globalcontext = {
             'embedded': self.embedded,
             'project': self.config.project,
@@ -499,7 +503,7 @@ class StandaloneHTMLBuilder(Builder):
             'language': self.config.language,
             'css_files': self.css_files,
             'sphinx_version': __display_version__,
-            'style': stylename,
+            'style': self._get_style_filename(),
             'rellinks': rellinks,
             'builder': self.name,
             'parents': [],

sphinx/themes/basic/layout.html

@@ -95,8 +95,6 @@
 {%- endmacro %}
 
 {%- macro css() %}
-    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
-    <link rel="stylesheet" href="{{ pathto('_static/' + style, 1)|e }}" type="text/css" />
     {%- for css in css_files %}
       {%- if css|attr("filename") %}
     {{ css_tag(css) }}

tests/test_build_html.py

@@ -1219,7 +1219,7 @@ def test_assets_order(app):
     content = (app.outdir / 'index.html').read_text()
 
     # css_files
-    expected = ['_static/pygments.css', '_static/alabaster.css', '_static/early.css',
+    expected = ['_static/early.css', '_static/pygments.css', '_static/alabaster.css',
                 '_static/normal.css', '_static/late.css', '_static/css/style.css',
                 'https://example.com/custom.css', '_static/lazy.css']
     pattern = '.*'.join('href="%s"' % f for f in expected)
@@ -1357,8 +1357,8 @@ def test_alternate_stylesheets(app, cached_etree_parse, fname, expect):
 def test_html_style(app, status, warning):
     app.build()
     result = (app.outdir / 'index.html').read_text()
-    assert '<link rel="stylesheet" href="_static/default.css" type="text/css" />' in result
+    assert '<link rel="stylesheet" type="text/css" href="_static/default.css" />' in result
-    assert ('<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />'
+    assert ('<link rel="stylesheet" type="text/css" href="_static/alabaster.css" />'
             not in result)
 
 

tests/test_theming.py

@@ -127,7 +127,7 @@ def test_dark_style(app, status, warning):
     assert (app.outdir / '_static' / 'pygments_dark.css').exists()
 
     result = (app.outdir / 'index.html').read_text()
-    assert '<link rel="stylesheet" href="_static/pygments.css" type="text/css" />' in result
+    assert '<link rel="stylesheet" type="text/css" href="_static/pygments.css" />' in result
     assert ('<link id="pygments_dark_css" media="(prefers-color-scheme: dark)" '
             'rel="stylesheet" type="text/css" '
             'href="_static/pygments_dark.css" />') in result