Reorder CSS files

[akhmerov]

I have a very basic confusion. Looking at the CSS ordering at the docs website, I see

  <link href="../_static/css/theme.css" rel="stylesheet">
  <link href="../_static/css/index.2f45af5bc641f38ae0d8d4c41ce8a4b2.css" rel="stylesheet">

    
  <link rel="stylesheet"
    href="../_static/vendor/fontawesome/5.13.0/css/all.min.css">
  <link rel="preload" as="font" type="font/woff2" crossorigin
    href="../_static/vendor/fontawesome/5.13.0/webfonts/fa-solid-900.woff2">
  <link rel="preload" as="font" type="font/woff2" crossorigin
    href="../_static/vendor/fontawesome/5.13.0/webfonts/fa-brands-400.woff2">

    
      

    
    <link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="../_static/basic.css" />
    <link rel="stylesheet" type="text/css" href="../_static/jupyter-sphinx.css" />
    <link rel="stylesheet" type="text/css" href="../_static/thebelab.css" />
    <link rel="stylesheet" type="text/css" href="https://assets.readthedocs.org/static/css/badge_only.css" />

Note how the theme files are included first. That is the reason why the theme can't override a bunch of styling in basic.css. That, in turn leads to the excessive use of !important, and further complicates customization.

Therefore I wonder if it would be possible to include the theme assets after the sphinx basic assets.

[jorisvandenbossche]

It seems that I changed this at some point: #144

But that was mainly to ensure that custom css files added by the end user are inserted after our own css (eg with sphinx' html_css_files option in conf.py). If there is a way to have the css files from sphinx before ours and custom ones after, that would be good as well. But we would need to check how sphinx injects those css files.

[akhmerov]

To insert the theme CSS in the proper location, https://www.sphinx-doc.org/en/master/development/theming.html suggests specifying a single CSS file in theme.conf, and using CSS @import to drag in other files if necessary.

[akhmerov]

I'll give it a shot

[akhmerov]

This would do the trick: No longer relevant, I found a simpler way.

diff --git a/pydata_sphinx_theme/layout.html b/pydata_sphinx_theme/layout.html
index c9220e02..94610c2d 100644
--- a/pydata_sphinx_theme/layout.html
+++ b/pydata_sphinx_theme/layout.html
@@ -12,7 +12,6 @@
 {% endmacro %}
 
 {%- block css %}
-    {{ _webpack.head_pre_bootstrap() }}
     {{ _webpack.head_pre_icons() }}
     {% block fonts %}
       {{ _webpack.head_pre_fonts() }}
diff --git a/pydata_sphinx_theme/static/css/theme.css b/pydata_sphinx_theme/static/css/theme.css
index 3f6e79da..7368afdd 100644
--- a/pydata_sphinx_theme/static/css/theme.css
+++ b/pydata_sphinx_theme/static/css/theme.css
@@ -1,3 +1,6 @@
+@import "../basic.css";
+@import "index.2f45af5bc641f38ae0d8d4c41ce8a4b2.css";
+
 :root {
   /*****************************************************************************
   * Theme config
diff --git a/pydata_sphinx_theme/theme.conf b/pydata_sphinx_theme/theme.conf
index 60f48f73..4f736d2c 100644
--- a/pydata_sphinx_theme/theme.conf
+++ b/pydata_sphinx_theme/theme.conf
@@ -1,5 +1,6 @@
 [theme]
 inherit = basic
+stylesheet = css/theme.css
 pygments_style = tango
 sidebars = search-field.html, sidebar-nav-bs.html, sidebar-ethical-ads.html

However since the name of compiled assets contains the hash, I'd also need to apply a pre-commit hook to replace the include in theme.css. Does that sound like the right way to go?