Use native font stack / remove vendored open-sans + lato fonts #285

jorisvandenbossche · 2020-11-19T15:42:08Z

Closes #247

jorisvandenbossche · 2020-11-19T16:48:19Z

See https://pydata-sphinx-theme--285.org.readthedocs.build/en/285/ for a preview

cc @pradyunsg @choldgraf @hoetmaaiers
(Chris, note that this will change the look for jupyter-book users)

If we want this, I should still remove the vendored Lato fonts.

choldgraf · 2020-11-19T18:55:57Z

FYI here's the comparison of how it looks in the Jupyter Book theme:

CURRENT VERSION:

THIS PR:

FWIW I don't see a huge difference and in general I am a big fan of not shipping our own font stack

pradyunsg · 2020-11-19T19:03:20Z

\o/

I like it.

Thanks for getting to this @jorisvandenbossche! Turns out, preparing for a dependency resolver, triaging a flurry of issues thanks to a beta, while also moving to a new country for a new job... means that you don't have much free time. I wish me-but-two-weeks-back was smarter and more pro-active about things. :)

hoetmaaiers · 2020-11-24T20:10:52Z

I am also fine with use a native font stack 👍

jorisvandenbossche · 2020-12-29T15:46:26Z

Updated to remove the vendored fonts.
We should probably give an example (and test) on how to switch back to Lato / open-sans yourself in your documentation.

One thing I noticed which I couldn't figure out yet is that the text doesn't seem to be centered anymore vertically.

For example, in the navbar, on master:

versus on this branch:

One can also notice it for the admonition titles (with this PR):

jorisvandenbossche · 2021-03-09T20:56:09Z

The issue I mentioned above about alignment being a bit "off" seems to be a general Firefox+Linux issue (I see the same issue on GitHub as well ..), see eg chakra-ui/chakra-ui#2314 or primer/css#1209 for some discussion about it.

jorisvandenbossche · 2021-03-09T20:59:40Z

One of the suggestions in that thread is to use "Helvetica Neue" instead of "Helvetica", so that Firefox doesn't use the wrong fallback for "Helvetica". On Firefox+Linux, that makes things look better indeed, and Chrome+Linux, that doesn't seem to make a difference (so that's good).

@choldgraf could you do a check that the demo docs with the latest commit also look OK for you?

choldgraf · 2021-03-09T21:06:56Z

They look good to me 👍

choldgraf · 2021-03-10T01:41:30Z

Is this ready to merge?

pydata_sphinx_theme/static/css/theme.css

bollwyvl · 2021-03-10T02:08:21Z

So much beautiful red!

I dropped the quick note about quoting spaced font-family names, and potentially storing the fallback chain in its own variable, but otherwise LGTM.

docs/contributing.rst

bollwyvl

❤️

jorisvandenbossche · 2021-03-10T13:44:39Z

@bollwyvl thanks for the feedback!

There is one item remaining, which is the outdated documentation. Currently, we say that you can create a custom layout.html template file to override the fonts blocks:

{% extends "pydata_sphinx_theme/layout.html" %}

{% block fonts %}
    <!-- add `style` or `link` tags with your CSS `@font-face` declarations here -->
    <!-- ... and a `style` tag with setting `font-family` in `body` and `.header-style` -->
    <!-- ... and optionally preload the `woff2` for snappier page loads -->
    <!-- or add a `style` tag with a font fallback chain with good cross-platform coverage -->
    <style>
        body {
            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;
        }
        .header-style {
            font-family: Cambria, Cochin, Georgia, Times, 'Times New Roman', serif;
        }
    </style>
{% endblock %}

See https://pydata-sphinx-theme--285.org.readthedocs.build/en/285/user_guide/customizing.html#replacing-removing-fonts

Now, the <style> tag is not longer needed, as the above could be achieved with a custom.css file with

:root {
    --pst-font-family-base: Cambria, Cochin, Georgia, Times, 'Times New Roman', serif;
}

but you might still need to override the template if you want to include/download a custom font?

bollwyvl · 2021-03-10T13:46:13Z

LGTM! After this lands, we may be able to bump some performance thresholds, as loading n x [family, weight, style] files certainly wasn't free. This could be handled over #294 which adjusts some other audit-related things.

jorisvandenbossche · 2021-03-10T13:46:44Z

but you might still need to override the template if you want to include/download a custom font?

For example if you want to add back Lato from a url? You could add

<link href='http://fonts.googleapis.com/css?family=Lato:400,700' rel='stylesheet' type='text/css'>

in the fonts block of the template?

jorisvandenbossche · 2021-03-10T13:49:47Z

Although it seems that eg numpy does that inside the CSS: https://github.com/numpy/numpy/blob/2ea7ebdc4294868ec982ad6310d0daf6477fabfc/doc/source/_static/numpy.css#L1 (not sure which method is preferred, EDIT: although <link ..> is probably faster to load)

bollwyvl · 2021-03-10T13:53:22Z

ahh, yes, always docs-about-docs-about-docs...

but you might still need to override the template if you want to include/download a custom font?

Generally, fonts a site maintainer grabs off GF or whatever come as a bundle, and they'd want to download and unpack that into _static, then link to it, which could be done in custom.css with an @import. If they're doing npm... they've chosen their own path, and we can't anticipate what they'll do.

However, fonts (as we've learned) are special, and a maintainer may wish to preload them, etc. which cannot be specified in CSS directly. I don't see a big win to doing that on the config.py side of the house, so perhaps updating that section is all the guidance we need.

bollwyvl · 2021-03-10T13:56:10Z

<link ..> is probably faster to load)

Well, GF, or worse some of the "free fontz now" sites, are a rather large privacy leak. I don't think we'd want to recommend hot-linking to any resource, from a best practices point of view.

jorisvandenbossche · 2021-03-10T16:05:08Z

OK, not really sure what I should put in our docs now .. ;)

Is it someting like:

Do you want to use a different font as default that is already available? -> Override the --pst-font-family variables in a custom.css
Do you want to use another custom font?
- Include the source files in your repo (eg in _static)
- Extend the layout.html template to load the font sources in the fonts block (using <link rel="stylesheet" href="{{ pathto('_static/..yourcustomfont..', 1) }}">)
- And then specify the --pst-font-family variablesin a custom.css to use those fonts

?

bollwyvl · 2021-03-11T05:07:32Z

Started this sub-PR, but might be losing steam this evening 💤

jorisvandenbossche#1

Feel free to merge/copy/update as you see fit if i don't finish up!

jorisvandenbossche · 2021-03-11T12:56:15Z

Thanks @bollwyvl ! I merged the PR to included it here.

Further, I did an attempt to update the customization section about how to change the default font (based on your updates and on what we discussed above). Could you take a look at that?

jorisvandenbossche · 2021-03-11T13:19:14Z

For some reason, with one of the latest changes, the css is not loading anymore, see https://pydata-sphinx-theme--285.org.readthedocs.build/en/285/ (or not properly included in the build result, not sure, it gives a 404 not found). No idea what went wrong ..

jorisvandenbossche · 2021-03-11T13:21:06Z

Update: forgot to git add the css/js ... 🤦
(but strange that our CI didn't catch that)

bollwyvl · 2021-03-11T13:30:56Z

I did see it thrashing a tad, but was only touching docs so I didn't do anything 😊 .

So question: while i was updating that, i talked about new icons... is there a compelling reason to not update to the latest fontawesome? the adobe icon was removed (in accordance with their brand stuff) and some unicode ranges got fixed. Also if a release is pending, the other JS deps? This could be a separate PR, of course, but the fonts at least seem germane to this topic.

jorisvandenbossche · 2021-03-11T15:08:13Z

Let's keep updating other things for another PR, I would say (but don't hesitate to open one ;))

jorisvandenbossche · 2021-03-11T15:09:12Z

docs/user_guide/customizing.rst

+    both better performance, and better script/glyph coverage than custom fonts,
+    and is recommended in most cases.
+
+The default body and header fonts can be changed as follows:


@bollwyvl if you could take a quick look at this section (the text below here), that would be great

bollwyvl · 2021-03-11T15:35:51Z

docs/user_guide/customizing.rst

+- If the font you want to specify in the section above is not generally available
+  by default, you will additionally need to ensure the font is loaded.
+  For example, you could download and vendor the font in the ``_static`` directory
+  of your sphinx site, and then update the base template to load the font resources:


Capitalize sphinx? I don't know.

bollwyvl · 2021-03-11T15:47:19Z

docs/user_guide/customizing.rst

-    {% endblock %}
+        <link rel="stylesheet" href="{{ pathto('_static/vendor/lato_latin-ext/1.44.1/index.css', 1) }}">
+
+      {% endblock %}


Perhaps concretely add:

To reduce the `Flash of Unstyled Content`, you may wish to explore various options for `preloading content <https://developer.mozilla.org/en-US/docs/Web/HTML/Preloading_content>`__, specifically the binary font files. This ensure the files will be loaded before waiting for the CSS to be parsed, but should be used with care.

and then in the code block

<link rel="preload" href="{{ pathto('_static/vendor/lato_latin-ext/1.44.1/files/lato-latin-ext-100-italic.woff2', 1) }}" as="font" type="font/woff2" crossorigin>

bollwyvl · 2021-03-11T15:48:31Z

The updates look good: I added a few small comments... the preload example can be dropped, but the MDN link is probably good to work in.

choldgraf · 2021-03-11T15:49:34Z

Once @bollwyvl is happy then I am happy to merge! I agree we should scope this PR cleanly and discuss other vendoring options as well 👍 let's get this merged! 🚀

jorisvandenbossche · 2021-03-11T19:27:53Z

Thanks @bollwyvl, I added your suggested text

bollwyvl · 2021-03-11T19:32:45Z

Hooray!

Use native font stack

bb1f084

remove vendored opensans / lato fonts

8324057

jorisvandenbossche changed the title ~~Use native font stack~~ Use native font stack / remove vendored open-sans + lato fonts Dec 29, 2020

jorisvandenbossche marked this pull request as ready for review December 29, 2020 09:02

update contributing.rst

476f153

jorisvandenbossche mentioned this pull request Jan 22, 2021

MRG, MAINT: new website theme [skip github][skip azp][circle front] mne-tools/mne-python#8757

Merged

7 tasks

Merge remote-tracking branch 'upstream/master' into native-font-stack

dc9b75c

use Helvetica Neue

e3dc9e8

bollwyvl reviewed Mar 10, 2021

View reviewed changes

pydata_sphinx_theme/static/css/theme.css Show resolved Hide resolved

bollwyvl reviewed Mar 10, 2021

View reviewed changes

docs/contributing.rst Outdated Show resolved Hide resolved

base system variable + update FontAwesome note

69badd6

bollwyvl approved these changes Mar 10, 2021

View reviewed changes

fix monospace variable

52cd67a

bollwyvl and others added 3 commits March 11, 2021 13:15

propose updated contributing documentation (#1)

d37f88d

update customization section on how to change the font

2aece60

rst formatting

1ccda07

fixup rst take 2

b133dbb

fix include css

1c6f62b

jorisvandenbossche commented Mar 11, 2021

View reviewed changes

bollwyvl reviewed Mar 11, 2021

View reviewed changes

add suggestion of Nicholas

73d0efb

jorisvandenbossche merged commit 89d3885 into pydata:master Mar 11, 2021

jorisvandenbossche deleted the native-font-stack branch March 11, 2021 19:28

dataframing mentioned this pull request Mar 25, 2021

Cannot find open-sans-all-{300,600,700,800} jupyter-book/jupyter-book#1282

Closed

choldgraf mentioned this pull request Mar 6, 2022

Remove double-linking of theme CSS #598

Merged

hugovk mentioned this pull request May 1, 2023

Infra: improve text readability and webpage performance python/peps#3132

Merged

hugovk mentioned this pull request Mar 16, 2024

Modernise font: use system font stack to improve text readability and webpage performance python/python-docs-theme#176

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use native font stack / remove vendored open-sans + lato fonts #285

Use native font stack / remove vendored open-sans + lato fonts #285

jorisvandenbossche commented Nov 19, 2020

jorisvandenbossche commented Nov 19, 2020

choldgraf commented Nov 19, 2020

pradyunsg commented Nov 19, 2020

hoetmaaiers commented Nov 24, 2020

jorisvandenbossche commented Dec 29, 2020

jorisvandenbossche commented Mar 9, 2021

jorisvandenbossche commented Mar 9, 2021

choldgraf commented Mar 9, 2021

choldgraf commented Mar 10, 2021

bollwyvl commented Mar 10, 2021

bollwyvl left a comment

jorisvandenbossche commented Mar 10, 2021

bollwyvl commented Mar 10, 2021

jorisvandenbossche commented Mar 10, 2021 •

edited

Loading

jorisvandenbossche commented Mar 10, 2021 •

edited

Loading

bollwyvl commented Mar 10, 2021

bollwyvl commented Mar 10, 2021

jorisvandenbossche commented Mar 10, 2021

bollwyvl commented Mar 11, 2021

jorisvandenbossche commented Mar 11, 2021

jorisvandenbossche commented Mar 11, 2021 •

edited

Loading

jorisvandenbossche commented Mar 11, 2021 •

edited

Loading

bollwyvl commented Mar 11, 2021

jorisvandenbossche commented Mar 11, 2021

jorisvandenbossche Mar 11, 2021

bollwyvl Mar 11, 2021

bollwyvl Mar 11, 2021 •

edited

Loading

bollwyvl commented Mar 11, 2021

choldgraf commented Mar 11, 2021

jorisvandenbossche commented Mar 11, 2021

bollwyvl commented Mar 11, 2021 via email

Use native font stack / remove vendored open-sans + lato fonts #285

Use native font stack / remove vendored open-sans + lato fonts #285

Conversation

jorisvandenbossche commented Nov 19, 2020

jorisvandenbossche commented Nov 19, 2020

choldgraf commented Nov 19, 2020

pradyunsg commented Nov 19, 2020

hoetmaaiers commented Nov 24, 2020

jorisvandenbossche commented Dec 29, 2020

jorisvandenbossche commented Mar 9, 2021

jorisvandenbossche commented Mar 9, 2021

choldgraf commented Mar 9, 2021

choldgraf commented Mar 10, 2021

bollwyvl commented Mar 10, 2021

bollwyvl left a comment

Choose a reason for hiding this comment

jorisvandenbossche commented Mar 10, 2021

bollwyvl commented Mar 10, 2021

jorisvandenbossche commented Mar 10, 2021 • edited Loading

jorisvandenbossche commented Mar 10, 2021 • edited Loading

bollwyvl commented Mar 10, 2021

bollwyvl commented Mar 10, 2021

jorisvandenbossche commented Mar 10, 2021

bollwyvl commented Mar 11, 2021

jorisvandenbossche commented Mar 11, 2021

jorisvandenbossche commented Mar 11, 2021 • edited Loading

jorisvandenbossche commented Mar 11, 2021 • edited Loading

bollwyvl commented Mar 11, 2021

jorisvandenbossche commented Mar 11, 2021

jorisvandenbossche Mar 11, 2021

Choose a reason for hiding this comment

bollwyvl Mar 11, 2021

Choose a reason for hiding this comment

bollwyvl Mar 11, 2021 • edited Loading

Choose a reason for hiding this comment

bollwyvl commented Mar 11, 2021

choldgraf commented Mar 11, 2021

jorisvandenbossche commented Mar 11, 2021

bollwyvl commented Mar 11, 2021 via email

jorisvandenbossche commented Mar 10, 2021 •

edited

Loading

jorisvandenbossche commented Mar 10, 2021 •

edited

Loading

jorisvandenbossche commented Mar 11, 2021 •

edited

Loading

jorisvandenbossche commented Mar 11, 2021 •

edited

Loading

bollwyvl Mar 11, 2021 •

edited

Loading