Heading font sizes are very similar (and big)

[tony]

@pradyunsg you are a legend

Issue: the size of the headers are difficult to distinguish (in my eyes? nobody else has made an issue on this yet), esp. when next to each other

example

page: https://vcspull.git-pull.com/history.html
markdown source: https://raw.githubusercontent.com/vcs-python/vcspull/v1.9.0/CHANGES

Screenshots

screenshot in furo:

comparison: github styling

comparison: docusaurus' defaults

example page: https://docusaurus.io/docs/i18n/crowdin#advanced-crowdin-topics
gh markdown view: https://github.com/facebook/docusaurus/blob/v2.0.0-beta.16/website/docs/i18n/i18n-crowdin.mdx
gh markdown source: https://raw.githubusercontent.com/facebook/docusaurus/v2.0.0-beta.16/website/docs/i18n/i18n-crowdin.mdx

next step?
If this is a wontfix, I suppose the solution would be custom CSS? 🤷 Any suggestions on that? I may simply attempt to use GitHub's as it seems nice

Judging by the sass files, I assume it's not eligible for css variable overriding via html_theme_options's {dark,light}_css_variables.

[tony]

Brainstorming:

_static/css/custom.css:

h2 {
  font-size: 2rem;
}

h3 {
  font-size: 1.5rem;
}

h4 {
  font-size: 1.25rem;
}

conf.py: html_css_files = ["css/custom.css"]

This is based on sizes from docusaurus (no spacing considered)

[pradyunsg]

I've editted this add <details> to collapse the large block of code and image, since otherwise these will bury any discussion that takes place here.

[tony]

@pradyunsg You beat me to it 😆

[pradyunsg]

Which headings do you consider "very similar" in font size? Please use h1/h2/h3/h4/h5/h6 in your reply to identify them.

See also https://pradyunsg.me/furo/kitchen-sink/typography/ for the rendered page and https://github.com/pradyunsg/furo/blob/main/src/furo/assets/styles/base/_typography.sass for the relevant Sass code.

[pradyunsg]

--ifm-h1-font-size: 2rem;
--ifm-h2-font-size: 1.5rem;
--ifm-h3-font-size: 1.25rem;
--ifm-h4-font-size: 1rem;
--ifm-h5-font-size: 0.875rem;
--ifm-h6-font-size: 0.85rem;

What docasaurus uses.

[pradyunsg]

h1
  font-size: 2.5em
  margin-top: 1.75rem
  margin-bottom: 1rem
h2
  font-size: 2em
  margin-top: 1.75rem
h3
  font-size: 1.75em
h4
  font-size: 1.5em
h5
  font-size: 1.25em
h6
  font-size: 1.125em

What Furo uses.

[tony]

h2, h3

2em and 1.75em. Partly its the size, its also the spacing.

When right next to each other

You won't see the above image on my site, I've since push the changes from #385 (reply in thread) to https://vcspull.git-pull.com/history.html, so the custom theme is there now

[tony]

Variation of above:

This is based on sizes and spacing from docusaurus (example page)

Brainstorming:

_static/css/custom.css:

h2 {
  font-size: 2rem;
  margin-bottom: 1.25rem;
  margin-top: 1.25rem;
  scroll-margin-top: 0.5rem;
}

h3 {
  font-size: 1.5rem;
  margin-bottom: 1.25rem;
  margin-top: 1.25rem;
  scroll-margin-top: 0.5rem;
}

h4 {
  font-size: 1.25rem;
  margin-bottom: 1.25rem;
  scroll-margin-top: 0.5rem;
}

conf.py: html_css_files = ["css/custom.css"]

[tony]

This tweak to h2 made the heading jut out even more (based on github's style, example)

diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css
index 6f123be..0f8edc7 100644
--- a/docs/_static/css/custom.css
+++ b/docs/_static/css/custom.css
@@ -3,6 +3,9 @@ h2 {
   margin-bottom: 1.25rem;
   margin-top: 1.25rem;
   scroll-margin-top: 0.5rem;
+
+  padding-bottom: 0.3rem;
+  border-bottom: 1px solid hsla(210,18%,87%,1);
 }

 h3 {

[pradyunsg]

Fair enough! I was waiting to see if anyone had concerns like this.

I've bumped the sizes for everything after h2 down a knotch: 3a19c5e

[pradyunsg]

Is this something we'll ever see configurable via CSS variables, potentially?

Nope.

or is does the design guideline want them to be fixed?

Not sure what this means!

[tony]

What's the reason that font-sizes for headers won't be configurable vs CSS variables?

[pradyunsg]

Why do you want them to be? I don’t think there’s any point in providing such a knob, for the similar reasons that there aren’t knobs to change what the border on block quotes. And, as you’ve seen, it’s not a lot of code to override this.

Furo isn’t designed as a give-you-all-the-knobs theme, but rather as a bunch of sane choices with a few knobs for branding.

[tony]

Just saying what I ran into configuring furo for the first time.

I was surprised there wasn't css variables for headers. Due to using other styling frameworks elsewhere and seeing variables in _fonts.scss to find there wasn't a way to configure headers.

In my case I ended up doing the custom css route for now: css, conf.py

I ran into a long development loop styling once custom css files came into play

It's a nuisance to edit stylesheets with sphinx-autobuild.

I am wiping _build/ and rebuilding with every edit.

Likely related: sphinx-doc/sphinx-autobuild#34

Edit: My workaround for anyone who hits google via this: poetry run sphinx-autobuild "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) --port ${HTTP_PORT} --watch "." -a $(O)

After doing frontend development (grunt, gulp, webpack, etc) - it hits you like a brick wall to find that stylesheets don't reload on saving when a watcher is running. An example of that expectation coming more and more commonplace can be seen in docusaurus (project of mine: https://social-embed.git-pull.com/)

When your latest change is published to pypi perhaps it will remedy the issue I originally posted about

[pradyunsg]

It's a nuisance to edit stylesheets with sphinx-autobuild.

See https://github.com/executablebooks/sphinx-autobuild#working-on-a-sphinx-html-theme