Sphinx项目中CSS自定义字体无法生效问题求助

Let’s work through why your custom Linux Biolinum Keyboard font isn’t loading in your Sphinx project. Here are the key checks and fixes to try:

1. Verify the Font File Path in CSS #

Your current @font-face uses a relative path (../fonts/LinBiolinum_Kah.ttf), which might not resolve correctly once deployed on Read the Docs. Try switching to an absolute path relative to your site’s root instead:

@font-face {
    font-family: "Linux Biolinum Keyboard";
    src: url('/_static/fonts/LinBiolinum_Kah.ttf') format('truetype');
}

This ensures the browser looks directly in the deployed _static/fonts directory, regardless of where the CSS file is located.

2. Double-Check Your conf.py Setup Function #

Make sure your setup function is properly adding the custom CSS file. It should look like this in conf.py:

def setup(app):
    app.add_css_file('css/custom.css')

The path css/custom.css is relative to your _static directory, which matches your file structure (_static/css/custom.css). If this function is missing or has an incorrect path, your CSS won’t load at all.

3. Confirm the Font File Is in Your GitHub Repository #

Sometimes font files get overlooked in git commits. Check that _static/fonts/LinBiolinum_Kah.ttf is actually present in your GitHub repo—if it’s missing, Read the Docs won’t be able to deploy it. You can verify this by navigating to the _static/fonts folder in your repo through the GitHub interface.

4. Check for Browser Caching #

Your browser might be holding onto an old version of the CSS that doesn’t include the font declaration. Force a full refresh (Ctrl+F5 on Windows/Linux, Cmd+Shift+R on Mac) to bypass the cache and load the latest styles.

5. Add Cross-Browser Font Format Support #

TTF files aren’t universally supported across all browsers. To improve compatibility, convert your TTF font to WOFF2 and WOFF formats (these are smaller and more widely supported) and update your @font-face rule:

@font-face {
    font-family: "Linux Biolinum Keyboard";
    src: url('/_static/fonts/LinBiolinum_Kah.woff2') format('woff2'),
         url('/_static/fonts/LinBiolinum_Kah.woff') format('woff'),
         url('/_static/fonts/LinBiolinum_Kah.ttf') format('truetype');
    font-weight: normal;
    font-style: normal;
}

You can use free online tools to convert TTF to these formats easily.

6. Debug with Browser Developer Tools #

Open your site in Chrome/Firefox Developer Tools (F12) to diagnose further:

• Go to the Network tab, filter by "Fonts", and reload the page. Check if the font file is being requested successfully (status code 200) or if it’s returning a 404 (file not found).
• Inspect an element with the .keys class, go to the Styles tab, and verify that font-family: "Linux Biolinum Keyboard", sans-serif; is applied and not being overridden by other styles.

Start with the first three checks—those are the most common culprits for this issue. If you still run into problems, the developer tools should give you clear clues about what’s going wrong.

内容的提问来源于stack exchange，提问作者Ivan Viper Navarro