text-transform: uppercase breaks some documentation.

[cjw296]

On an internal project, I use headers of the following form to document the nested keys of a hierarchical yaml configuration file:

section.option
~~~~~~~~~~~~~~~

The casing of these is important (uppercase won't work!), but it appears h4, h5, h6 in furo have a text-transform: uppercase which makes it unusable for this project, which is a shame, as I'd like to switch to it!

Is there an easy way to disable that text transform per-project?

[jdknight]

If there is a desire to override the styling chosen by this theme, a developer can override the header manipulation on these entries by injecting a custom style sheet in the project's conf.py:

def setup(app):
    app.add_css_file('theme_overrides.css')

And having _static/theme_overrides.css with the contents:

h4, h5, h6 {
    text-transform: unset !important;
}

[cjw296]

Nice! That'll certainly do as a workaround, but I wonder if @pradyunsg would consider changing this? Technical docs often end up having headers where case sensitivity is important, so upper-casing a bunch of them seems like it might cause problems for others too...

[pradyunsg]

Broadly, I don't think there's any reason that I'd try to make Furo's design compatible with all potential documentation sets. There's a lot of nuance here but, overall, the content structure and the theme need to be compatible. I'm not going to cater to all potential content structures in this theme -- it'll reflect my biases for what works well. :)

The reason Furo has the heading styling that it has, is because I want to nudge people away from deeply nested headings -- especially on techinical documents like the kind you're describing. If you're at that heading and care about the casing, IMO that's an indicator that you need to break up the page.

If Furo's current header approach pushes authors away from deeper headings for their technical documentation, I see that as a good thing. If someone else does not, they're free to use other themes or Sphinx's deep control over what is spewed out as described in @jdknight's post above.

[cjw296]

All agreed!

I will say that force-upper-casing in a tool focused on programming documentation where most languages are cases sensitive feels like a mistake, and I do hope you'll reconsider at some point.

But, it's your theme and I totally respect assertive choices :-)