Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Load several css files in theme.conf #10444

Closed
tischrei opened this issue May 11, 2022 · 4 comments · Fixed by #10465
Closed

Load several css files in theme.conf #10444

tischrei opened this issue May 11, 2022 · 4 comments · Fixed by #10465
Labels
good first issue html theme type:enhancement enhance or introduce a new feature
Milestone
5.1.0

Comments

@tischrei
Copy link

Is your feature request related to a problem? Please describe.
We have our own Sphinx theme called otcdocstheme. In this theme we are loading our own (specific) css file: otcdocstheme.css and some unspecific ones like bootstrap.min.css etc. The specific one is mentioned in theme.conf as it should be and the unspecific ones like bootstrap.min.css are loaded in the (layout-) .html files. This leads to the fact that the unspecific css files are loaded after the specific ones and this causes several issues due to the order, for instance overwriting elements (especially with !important flag). We also derive from the theme with some subprojects having their own .conf files which are also loaded after the theme-specific css files, as you can see in the listing below

<head>
...
  <link rel="stylesheet" type="text/css" href="_static/css/pygments.css">
  <link rel="stylesheet" type="text/css" href="_static/css/otcdocstheme.css">
  <link rel="stylesheet" type="text/css" href="_static/css/subtheme.css">
  ...
  <link rel="stylesheet" type="text/css" href="_static/css/bootstrap.min.css">
  <link rel="stylesheet" type="text/css" href="_static/css/fontsawesome-all.min.css">
...
</head>

Describe the solution you'd like
It would like to have the option to specify more than one .css file in the theme.conf section to overcome this issue.

Describe alternatives you've considered
The alternative would be to load the unspecific css files in our specific one like bootstrap.min.css in otcdocstheme.css , but this is somehow strange in my opinion.
@tischrei tischrei added the type:enhancement enhance or introduce a new feature label May 11, 2022
@mgeier
Copy link
Contributor

mgeier commented May 11, 2022

I think that's a great idea!

I've also struggled with managing multiple CSS files in my own theme. This also led to awkward instructions for people who want to derive their own theme from mine: https://insipid-sphinx-theme.readthedocs.io/en/0.3.0/customization.html#derive-your-own-theme

I think it would be great if we could write something like this in theme.conf:

stylesheet = base.css, otcdocstheme.css, subtheme.css, bootstrap.min.css

I don't see why this shouldn't work, for example sidebars is also a list of comma-separated files.

People who want to derive from an existing theme can just define their whole list of CSS files, and they can decide which files of the original theme they do and don't want to use.

What do you think?

But until then, this is what I am using as a work-around in layout.html:

{% block css %}
    <link rel="stylesheet" type="text/css" href="{{ pathto('_static/my-before-file.css', 1) }}" />
{{- super() }}
    <link rel="stylesheet" type="text/css" href="{{ pathto('_static/my-after-file.css', 1) }}" />
{%- endblock %}

Would that work for you?

@tischrei tischrei mentioned this issue May 12, 2022
Merged
@tischrei
Copy link
Author

Yes, the mentioned list is what I am also talking about. That would be a nice improvement and make the code also more straight forward, because you can avoid writing css files at all in the template html files:

stylesheet = base.css, otcdocstheme.css, subtheme.css, bootstrap.min.css

I am trying to find out, what super() does in this case. But thanks for the hint.

@tk0miya tk0miya added this to the 5.x milestone May 14, 2022
@tk0miya
Copy link
Member

tk0miya commented May 14, 2022 •
edited

+1; Reasonable.

@tk0miya tk0miya modified the milestones: 5.x, 5.1.0 May 15, 2022
tk0miya added a commit to tk0miya/sphinx that referenced this issue May 22, 2022
@tk0miya
Close sphinx-doc#10444: html theme: Allow to specify multiple CSS fil…
eef2114 
…es via "stylesheet" setting
@tk0miya tk0miya mentioned this issue May 22, 2022
Merged
@AA-Turner
Copy link
Member

Thanks, Sphinx 5.1 will allow specifying multiple stylesheets in theme.conf and html_style!

A

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Aug 17, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
good first issue html theme type:enhancement enhance or introduce a new feature
Projects
None yet
Milestone
5.1.0
Development

Successfully merging a pull request may close this issue.

Allow specifying multiple CSS files in themes tk0miya/sphinx
4 participants
@mgeier @tk0miya @AA-Turner @tischrei