A massive GIF says more than a thousand words:

Describe the bug
{insert title here}. The font sizing seems to be off.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://pradyunsg.me/furo/reference/admonitions/ on Chrome for Android, with non-default base-font size.
2. Scroll down to the list of admonition's supported types.
3. See weird title sizing.

Expected behavior

The admonitions in the admonition demo have the correct font-size, that's not relative to the admonition's font size, instead of the page's font-size.

Device

• Browser: Chrome on Android

• Device: @webknjaz's phone. :P

  It's a custom MIUI packaged by xiaomi.eu, looks like there's Android 10 underneath

  

  

Additional context

This seems to be due to Chrome on Android taking the 100% font-size to be relative to the "base" font size (i.e. the one set in html) instead of the one set in the parent element.

Currently there is no whitespace between an element and it's corresponding ¶ character.
Also was wondering if it'd make sense for the ¶ character to be faded / not visible unless you hover.

Is your feature request related to a problem? Please describe.
Lack of contrast for logos when used for both dark and light more.

Describe the solution you'd like
Ability to select different logo in dark mode.

Describe alternatives you've considered
Telling users to adapt their SVG based on state (bad idea).

Additional context
@hynek flagged this on Twitter a little while back, and I can't find the tweet. :)

Sorry for not using your template but I think this screenshot speaks for itself:

This happens when I resize the window such that the menu doesn't fit anymore.

(I've found it while using web inspector.)

Describe the bug
A clear and concise description of what the bug is.

The docs version selector floats a bit too high up.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://www.attrs.org/en/stable/ on Chrome on Android (Samsung S8)
2. Check the location of the version selector

Expected behavior
A clear and concise description of what you expected to happen.

The selector is perhaps flush with the bottom of the screen, or in the left menu.

Screenshots
If applicable, add screenshots to help explain your problem.

Smartphone (please complete the following information):

• Device: Samsung S8
• OS: Android
• Browser: Chrome
• Version: 85

Describe the bug
The furo_asset_hash variable changes hashes for the same resource in the same build.

To Reproduce
Steps to reproduce the behavior:

1. build any docs
2. grep furo.css docs/_build/html/*.html | head

docs/_build/html/adaptation.html:      <link rel="stylesheet" href="_static/styles/furo.css?state=cee7d01cd83c5f569d94bbb7">
docs/_build/html/connection.html:      <link rel="stylesheet" href="_static/styles/furo.css?state=11c4ff532c780a855f77bef8">
docs/_build/html/cursor.html:      <link rel="stylesheet" href="_static/styles/furo.css?state=b71df5d38afc2bca89011307">
docs/_build/html/errors.html:      <link rel="stylesheet" href="_static/styles/furo.css?state=898b0ed01020906787d65ca4">
docs/_build/html/from_pg2.html:      <link rel="stylesheet" href="_static/styles/furo.css?state=dce1277c6407b08d176e7d16">
docs/_build/html/genindex.html:      <link rel="stylesheet" href="_static/styles/furo.css?state=c09859bfc41dac5b6e5709be">

Expected behavior
The hash of the resource shouldn't change.

Additional context

pip freeze | grep furo
furo==2020.11.19b18

Describe the bug

Remove underline from ¶ links.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://pradyunsg.me/furo/quickstart/
2. Hover over "Quickstart" or ¶

Expected behavior

There's usually no underline under the ¶ character.

Screenshots

Desktop (please complete the following information):

• OS: macOS
• Browser Chrome
• Version 86

Additional context

Happens for both light and dark modes.

URL: https://pradyunsg.me/furo/

What is missing or inaccurate about the content on this page?

Add a list of projects that are using Furo theme template, to show various example of Furo utilizations and promote it.

Example:

• urllib3
• psycopg3

The subsection revealed doesn't look right:

Step to reproduce:

1. Open any site using this theme and having nested ToC
2. Click on that section

My guess would be there's something wrong with CSS but I don't know for sure.

Off-topic: Congrats on getting furo adopted by urllib3! Overall I like the esthetic (the color, line break after Parameters in :function:, etc.), so feed me with updates on Twitter!

Describe the bug

Multiple glossary terms for same definition appear on the same line.

To Reproduce

Use the following RST or equivalent markdown

.. glossary::

   term 1
   term 2
      Definition of both terms.

Expected behavior

both terms should appear on different lines

Screenshots

Desktop (please complete the following information):

• OS: Kubuntu 20.04
• Browser: any

Describe the bug

I ran into the issue I mentioned at python-pillow/Pillow#4968 (comment):

On mobile with the advert shows at the bottom of the page rather than hidden in the left menu.

To Reproduce
Steps to reproduce the behavior:

1. Go to https://pillow-hugovk.readthedocs.io/en/furo/ on mobile
2. Hope you get served ads this time
3. The advert is placed at the bottom of the screen

Expected behavior

The ad is tucked away in the side menu like with sphinx_rtd_theme

Screenshots

Smartphone (please complete the following information):

• Device: Samsung S10
• OS: Android
• Browser Chrome
• Version 86

Additional context

This is also the HTML downloaded from Chrome on the phone. Looks like it gets monkeyed with a bit by Chrome's HTML downloader, but hopefully you can still see the important structure.

Home - Pillow (PIL Fork) 8.1.0.dev0 documentation.html.zip

(I'm not getting ads now, will do a view source and grab that if it happens again.)

The right-hand-side navigation doesn't have a way to go on top of page.

Example: https://pradyunsg.me/furo/customisation/

By using the right links, you can go at "Theme options" most. If there is a lot of content between Customisation and Theme options you cannot access that section of page via that menu.

Would you feel useful to have "Customisation" there too?

Is your feature request related to a problem? Please describe.
I've been trying to customize/extend furo via Sphinx's html_css_files directive, but custom stylesheets do unfortunately get inserted into the document's head node first, before furo's own stylesheets. This makes it unnecessarily difficult to override certain styles, because the theme's default ones take precedence due to this stylesheet order. The only solution to this is setting !important flags on the properties, or defining stronger CSS selectors, or extending the theme_styles block in the base.html template and not using the html_css_files directive, which is all non-ideal and rather painful.

Describe the solution you'd like
It would be much easier to override the theme's CSS properties (or even CSS variables which are not defined via the theme options) if the custom CSS stylesheets were inserted after furo's own stylesheets.

Describe the bug

The generated index, module index, and search pages don't render.
The search page has the sidebar, but the other two are completely blank.

To Reproduce
Steps to reproduce the behavior:

Add these refs to your index page (sphinx-quickstart adds these automatically).

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Set html_theme = 'furo' in conf.py.
Generate Sphinx docs with make html.
Open in browser and click on each link from these refs.

Expected behavior

If you remove the html_theme = 'furo' in conf.py it renders with the default alabaster theme. When you click these three links, you get to their corresponding pages and they're not blank. Furo's generated pages should have the same content, but with different styling.

Desktop (please complete the following information):

Tested on Microsoft Edge.

It would be nice if glossary items like in https://www.attrs.org/en/latest/glossary.html could by styled. E.g. bold would be great:

Describe the bug
As mentioned in #32, both sidebars still have issues with the scrollbars.

On the current page's TOC sidebar on the right, overflow: auto gets set on hover. This is a big problem here, as it reduces the available horizontal space of the content when the scrollbar appears, and text lines can be wrapped when the space shrinks, which results in the entire content below of that line moving a couple of pixels, which is very annoying.

The main menu sidebar on the left does have the same problem when the available vertical space of the document window changes. This is especially a problem when there's content in the sidebar which is center-aligned, like for example a logo.

Demonstration
https://youtu.be/LH7llgLyIXs

Expected behavior
Both sidebars' content should have a width set, so that the scrollbar, once it appears, doesn't shrink the available space.

This worked for me as a simple workaround, but unfortunately requires defining the sidebar width myself, as it's hardcoded in a SASS variable:

:root {
  --sidebar-width: 15rem;
  --sidebar-content-width: calc(var(--sidebar-width) - 1rem);
}
.sidebar-container,
.toc-drawer {
  width: var(--sidebar-width);
}
.sidebar-scroll > *,
.toc-title-container,
.toc-tree-container {
  width: var(--sidebar-content-width);
}
.sidebar-brand {
  padding: var(--sidebar-item-spacing-vertical) 0;
}

The problem with this is that it assumes that the scrollbar width is 1rem, but this should be fine in most cases.

Desktop (please complete the following information):

• Arch Linux
• Chromium
• 87

Smartphone (please complete the following information):

Not tested

When hovering an item on macOS Safari (or tapping it on iOS Safari), you get a weird artifact on the left side, that's not there on other browsers:

URL: https://pradyunsg.me/furo/customisation/colors/#code-block-styling

What is missing or inaccurate about the content on this page?

This section suggests using a Pygments option for Sphinx that doesn't exist, and it seems that no matter what I set this value to, Furo uses its own color scheme for code segments in dark mode.

Is there a known-working mechanism for choosing the Pygments style used in dark mode, or does this require overriding the dark mode CSS variables in the Fure stylesheet?

Describe the bug
On firefox, when starting scrolling a page with a massive number of TOC entries (40 in my case), the page does not stop to scroll to the end of the page.

To Reproduce

1. Create a page with at least 40 entries in TOC (TOC height must be greater than window height)
2. Start to scroll down the page on firefox
3. Javascript keeps scrolling to the end of the page

Expected behavior
Should behave like on safari

Desktop (please complete the following information):

• OS: Catalina
• Browser firefox
• Version 81.0.1

Describe the bug

Cross-referenced content like sections and terms are hidden under the navbar in mobile view.

To Reproduce

Steps to reproduce the behavior:

0. Open a browser on mobile or resize it similarly
1. Go to https://urllib3.readthedocs.io/en/latest/user-guide.html#response-content

Expected behavior

The page should be scrolled down a little to

Screenshots

Non-essential since the problem was perfectly described in words, however I want to flex my new phone a little:

Desktop

• OS: Debian GNU/Linux testing
• Browser: Firefox ESR 68 and Chromium 83

Smartphone

• Device: Pinephone 1.2a
• OS: Mobian
• Browser: Firefox ESR 68 and Epiphany 3.36.3

Additional context

It looks alright on wide screens, so IIUC using fixed navbar instead of sticky would fixes the issue.

As described in

Is your feature request related to a problem? Please describe.

The default RTD theme has a handy little pop-up bottom left that lets you pick the version of the docs to see, and also links to the project and builds on rtd.

Describe the solution you'd like

It would be great if that functionality could be surfaced in Furo, of course, I have no idea if or how it could be implemented.

Describe the bug

Longer API (autodoc) documentation looks squeezed.

To Reproduce

Use something like .. automethod with a params that are multiple paragraphs, possibly contain ordered or unordered lists.

Expected behavior

It would be great to get some spacing.

Screenshots

It looks especially unfortunate when having multiple short paragraphs:

Lists also look unhappy without any social distancing:

Desktop (please complete the following information):

• OS: macOS
• Browser Safari
• Version 14

Otherwise great work!

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Dark mode is the new thing!

Not only that, they can improve accessibility, ease eye strain, and save battery power.

Describe the solution you'd like
A clear and concise description of what you want to happen.

Use the prefers-color-scheme media query to detect whether the user has requested dark mode, and provide a darker colour scheme.

• https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme
• https://web.dev/prefers-color-scheme/
• https://caniuse.com/?search=prefers-color-scheme

For comparison, see this dark theme issue and PR at the Python Docs Sphinx Theme:

• python/python-docs-theme#43
• python/python-docs-theme#44

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

1. There are Chrome plugins and the like to invert colours, but it's better for the dark colour theme to be chosen manually to make sure there's no odd things. And using a widely-supported media query means it's available for more people.

2. Stick with the bright theme.

Clicking this link will highlight the definition linked by the anchor:

https://docs.python.org/3/library/functools.html#functools.partial

Clicking this link does not currently highlight the definition linked by the anchor:

https://documen.tician.de/pyopencl/runtime_queue.html#pyopencl.CommandQueue

(generated with Furo 2020.12.9b21 according to this build log)

Describe the solution you'd like

There should be anchor highlighting just like for the majority of other sphinx themes. (default, alabaster, ...).

URL: https://pradyunsg.me/furo/customisation/colors/#code-block-styling

What is missing or inaccurate about the content on this page?

Not sure if this is a doc issue or a bug. Instructions to change the dark mode code block styling don't work. (They do work for light mode.) Tested using Sphinx==3.3.1 and furo==2020.12.9b21, the latest versions released on PyPI.

I pasted these lines in my docs/conf.py used by Sphinx.

pygments_style = "sphinx"
pygments_dark_style = "monokai"

Changing pygments_style to another valid Pygments style affects the syntax highlighting in light mode when I rebuild the docs with Sphinx, but changing pygments_dark_style doesn't do anything. Dark mode is always the same style.

Is your feature request related to a problem? Please describe.

Currently a large image is placed in the documentation by resizing it down with a simple max-width: 100%; height: auto. For images containing text this can often leave the text unreadable, especially on smaller devices.

Should this be something that an author should be expected to handle (ie get them to supply a :target: to the image directive that links to the image, which would open the image in a new tab), or should the theme be able to handle the problem or at least assist with it?

Describe the solution you'd like

If the theme were to deal with it, my preferred approach would be option 1 as described below

Describe alternatives you've considered

1. Do a "simple zoom" when clicked on. For example: https://github.com/francoischalifour/medium-zoom
   1a. This only really works for images up to a certain size but I don't think it's unreasonable for an author to have to deal with this situation.
2. Have a "zoom" button that shows over a resized image when hovered over. When clicked, the image is opened in some overlay. The downside here is that it would require some javascript in a theme that otherwise works well without it.
   2a. Just opening the image sized to the window would be an improvement but this approach would inevitably lead to feature requests for adding zoom and pan controls.
3. Don't resize the image and instead have a max-height and overflow: scroll. I think that the scroll bars would add visual clutter though.
   3a. This situation is difficult to deal with as an author because whether scroll bars are appropriate or not would vary depending on the image content, the size of the image, and the screen size. We could pick scrolls bars or not depending on the screen size, but I think it's impossible to map media queries to match all cases.

Additional context

None.

It would be nice if there was a way to customize the depth of headers you want displayed in the contents bar of a given page.

For example, the below image shows the contents from a reference section of documentation.

I would like to be able to only list the top-level headers and not see the subheaders (command syntax, and options).

Is your feature request related to a problem? Please describe.
Google Chrome (Mac OS X) respects system wide dark mode setting. However, the tab bar becomes barely readable for me when Chrome is in dark mode, so I disabled dark mode for Chrome.

Quoting furo docs on dark mode, it seems I won't be able do view dark furo projects without putting my whole browser in dark mode (unwanted):

Furo is in light mode by default, switching to the dark mode when requested by the user’s browser (through prefers-color-scheme: dark).

As a consequence of this design, the dark mode inherits the variable definitions from the light mode, only overriding specific values to adapt the theme. While the mechanism for switching between light/dark mode is not configurable, the exact CSS variable definitions used in this process can be configured.

Describe the solution you'd like
A nice solution would be to keep this behaviour, but to additionally give the user the option to override the CSS prop with a toggle, like for instance Docker docs have on every page.

Describe alternatives you've considered
Alternatively, I could somehow attempt hack my Chrome set up to emulate this CSS prop on all websites by default, essentially putting my Chrome in dark mode only for the content and not for Chrome's own UI.

Additional context
Docker docs example dark mode toggle on the right:

The current Gulp-based setup doesn't allow for JS imports, and is generally a bit hacked-together. It works well-enough so I haven't been touching it. However, I definitely know that this is suboptimal. Ideally, we can replace/enhance the pipeline would to allow for JS imports from node_modules.

As it stands, it's an open question where we need to change anything. Pointers/suggestions welcome! :)

If the site's author uses images with transparent background, only light or dark would work, so it'd be nice if perse can hint that the other mode is broken by hard-coding the working mode.

Describe the solution you'd like

As suggested by @pavithraes on GH-24:

Something like a setting in conf.py for the preferred action?

html_theme_options = {
    "theme-color": light/dark/dual,
}

Describe alternatives you've considered

None.

Additional context

If plantuml plugin is used for Sphinx, the diagram would look somewhat like this in dark mode:

One could tweak the plantuml theme but it's not very easy to get something looking nice for both dark and light.

Is your feature request related to a problem? Please describe.
I've been trying to migrate the theme of our project's documentation to furo. This requires a customization of the theme's sidebar and adding a logo, title, oneliner/short-description and a version selection to the top of it, which means that the main menu moves down by a bit.

The issue I'm seeing with the theme's current main menu layout however is that on smaller screen heights, the sidebar's vertical scrollbar does only affect the main menu, not the entire sidebar. I don't think this is a good solution, because depending on the screen size and the height of the "sidebar header", the scrolling area of the main menu can become tiny and barely able to use (see first screenshot below).

I think that this should be changed/fixed in the theme, as it already optionally supports logos, which means that the available vertical space of the main menu is variable and not strict.

Describe the solution you'd like
The scrollbar should cover the entire sidebar.

However, the problem with a scrollbar on the sidebar is that when it appears (overflow: auto), it'll change the center alignment of the content, as the width shrinks. This needs to be taken into account.

Without changing any padding/margin properties of the sidebar layout, this worked for me while quickly testing the behavior in Chromium's dev tools, but it's just a hack and not a proper solution:

.sidebar-sticky {
  overflow-y: overlay;
}
.sidebar-scroll {
  overflow: unset;
  flex-shrink: unset;
}

I don't know how well overflow-y: overlay is supported by current and last-gen browsers. caniuse.com doesn't list the property's value, as the property's behavior has been moved to scrollbar-gutter in the CSS overflow module level 4 spec, but Chromium 86 doesn't seem to support it yet AFAICT.

• https://caniuse.com/css-overflow
• https://www.w3.org/TR/css-overflow-4/#scollbar-gutter-property

Describe alternatives you've considered
See how it's done here for example:
https://docs.codecov.io/docs

Additional context

Thank you!

Describe the bug

Glossary supports display multiple terms but furo renders it incorrectly.

Checked on 2020.11.19b18 version.

To Reproduce
Steps to reproduce the behavior:

1. Add glossary with multiple term:

.. glossary::

    RC
    release candidate
        The environment separated and isolated from
        production intended for developing as well as manual and
        automated testing.

2. Render html by furo theme.
3. Incorrect result:

Expected behavior

Something like this:

PS: furo is grate theme! Thank for work!

Proposal: currently the right sidebar is named "Contents". What do you think about changing the text to "On this page", like in https://stripe.com/docs/payments/payment-methods? I found "Contents" a bit ambiguous, as left sidebar also contains contents in a way, but for the whole docs.

Notably RTD uses Python 3.7:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/sphinx/cmd/build.py", line 303, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/sphinx/application.py", line 263, in __init__
    self._init_builder()
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/sphinx/application.py", line 324, in _init_builder
    self.builder.init()
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/sphinx/builders/html.py", line 329, in init
    self.init_templates()
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/sphinx/builders/html.py", line 375, in init_templates
    self.theme = theme_factory.create(themename)
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/sphinx/theming.py", line 277, in create
    self.load_extra_theme(name)
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/sphinx/theming.py", line 199, in load_extra_theme
    self.load_external_theme(name)
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/sphinx/theming.py", line 227, in load_external_theme
    self.app.registry.load_extension(self.app, entry_point.module_name)
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/sphinx/registry.py", line 472, in load_extension
    mod = __import__(extname, None, None, ['setup'])
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/furo/__init__.py", line 9, in <module>
    from .navigation import get_navigation_tree
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/site-packages/furo/navigation.py", line 19, in <module>
    @functools.lru_cache
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/functools.py", line 477, in lru_cache
    raise TypeError('Expected maxsize to be an integer or None')
TypeError: Expected maxsize to be an integer or None

Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/urllib3/envs/1950/lib/python3.7/functools.py", line 477, in lru_cache
    raise TypeError('Expected maxsize to be an integer or None')

I think @functools.lru_cache the way it's being used now was only added in Python 3.8. Might be best to use @functools.lru_cache(maxsize=None)?

This issue is meant to be a planning/dumping ground for tasks that have to be done prior to the first stable release of furo.

• Write the documentation for this theme
  • Finalize skeleton structure.
  • Write the content!
• Deploy the documentation w/ GitHub Pages
• Stylize API documentation
• Stylize captions
• Stylize field lists (low priority)
• Stylize the remaining permalinks
• Switch to em for typography, instead of using rem everywhere
• Tweak spacing for headings & paragraphs -- they might have a little too much margin?
• Fix page's height on mobile, where 100%-100vh is not 0. -.-
• Fix z-index levels for overlay (the toctree overlay needs to be above the sidebar and vice-versa).
• Skeleton + styling for index pages (#50)
• Add JS-based buttons to copy code blocks
• Create a good looking landing page for the documentation

Is your feature request related to a problem? Please describe.
A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]

Currently, I think by default furo adapts to OS (or browser) settings to display light/dark mode. I'll be nice if we can choose to render only light mode, or only dark mode, or both like the present default.

Describe the solution you'd like
A clear and concise description of what you want to happen.

Something like a setting in conf.py for the preferred action?

html_theme_options = {
    "theme-color": light/dark/dual,
}

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Stick with the current default. :)

Describe the bug

In this theme, and not in Alabaster (the demo site for sphinx-copybutton), the copy button image moves when the user scrolls the code cell horizontally.

To Reproduce

1. Enable sphinx-copybutton
2. Create a code cell with long lines
3. Scroll

You can try it out here: https://wn.readthedocs.io/en/latest/

Expected behavior

The copy button image should stay put, as it does here: https://sphinx-copybutton.readthedocs.io/en/latest/

Screenshots

Desktop (please complete the following information):

• OS: Pop!_OS 20.04 (Ubuntu derivative)
• Browser: Both Firefox 83.0 and Chrome 87.0 show the same thing
• Version: furo-2020.11.19b18

Smartphone (please complete the following information):

• Device: iPhone7
• OS: iOS14.1
• Browser Safari

Additional context

Looking at the CSS, I think this has to do with the copybutton's containing div.highlight element having overflow: auto while in the Alabaster theme it's the sibling pre element that has the property.

Describe the bug

html_show_sourcelink, html_show_copyright and html_show_sphinx are currently ignored by furo.

To Reproduce

In conf.py add the following

html_show_sourcelink = True
html_show_copyright = False
html_show_sphinx = False

Rebuild the docs and observe that copyright and sphinx are shown but source link is nowhere to be found.

Expected behavior

Sphinx configuration should be respected. Furthermore, it'd be really nice if the version of Sphinx as well as Furo is displayed (if html_show_sphinx is True) for debugging.

Platform

Irrelevant, I think.

This page https://github.com/python-attrs/attrs/blob/master/docs/examples.rst has a title of

``attrs`` by Example
====================

Which results in the following html title tag:

<title><code class="docutils literal notranslate"><span class="pre">attrs</span></code> by Example - attrs 20.3.0.dev0 documentation</title>

(you can check for yourself on https://www.attrs.org/en/latest/examples.html :))

There's a bunch of metadata like OpenGraph or Twitter that allow for rich previews. I've just run into hynek/structlog#197 and I guess it's time to pester you with it. :)

To give you a starting point, my hopepage puts this in the <header>:

    <meta property="og:site_name" content="Homepage and blog of Hynek Schlawack">
    <meta property="og:author" content="Hynek Schlawack">
    <meta property="og:type" content="article">
    <meta property="og:title" content="Waiting in asyncio">
    <meta property="og:description" content="One of the main appeals of using Python’s asyncio is being able to fire off many coroutines and run them concurrently. How many ways do you know for waiting for their results?">
    <meta property="og:url" content="https://hynek.me/articles/waiting-in-asyncio/">
    <meta property="article:published_time" content="2020-05-21T00:00:00Z">
    <meta name=twitter:card content="summary">
    <meta name=twitter:site content="@hynek">
    <meta name=twitter:creator content="@hynek">
    <meta name=twitter:image content="https://hynek.me/img/avatar.jpg">
    <meta name=twitter:title content="Waiting in asyncio">
    <meta name=twitter:description content="One of the main appeals of using Python’s asyncio is being able to fire off many coroutines and run them concurrently. How many ways do you know for waiting for their results?">

Requesting ability for an html document to be inserted at the top of each page.
Would be nice for both announcements and warnings/redirects if you're on an old / deprecated version of the software.

Is your feature request related to a problem? Please describe.
It'd be nice to have an option for adding a header to the docs.

It can be used to organize navigation in a different way - for example, for having links which are not related directly to the documentation content, important links to related projects, etc. Sometimes it is also a better place for branding (depends on design).

Describe the solution you'd like
Optional header block.

Describe alternatives you've considered

• Reusing announcement block (hack)
• overriding page.html template to add a header (good to have something standard, out-of-the-box).

Describe the bug
In addition to #36, I've noticed an issue with the max-width: $full-width media query:

This is without the width changes mentioned in #36, just default theme stylesheets.

Demonstration
https://youtu.be/mVmTa_k-UWk

It looks fine width-wise when using the browser's media query dev tools, but there's a gap of a couple of pixels which causes a horizontal scrollbar on the document body to appear.

Desktop (please complete the following information):

• Arch Linux
• Chromium
• 87

Smartphone (please complete the following information):

Not tested

Example:

When a code statement is also a hyperlink, that underline (double line) is bothering me a little. 🙈

First of all, kudos for this awesome theme. Finally, a modern UI for Sphinx docs has arrived! 🎆

Is your feature request related to a problem? Please describe.

I'm using the .. rubric:: directive quite extensively. A simple example:

Initialize optimal bias weights.

.. rubric:: Standalone usage

>>> x = 0

.. rubric:: Usage in optimal model

>>> x = 1

.. rubric:: Usage in trainable model

>>> x = 2

.. rubric:: Formulae

Lorem ipsum dolor sit amet.

Using e.g. alabaster or sphinx-rtd-theme, they are rendered in bold:

With furo, the rubrics are rendered as plain text:

Describe the solution you'd like

I'm not sure actually what the best styling would be for the rubrics 🤷 The default CSS for the rubric class seems to be

p.rubric {
    margin-top: 30px;
    font-weight: bold;
}

(relevant spot in basic.css_t), but maybe you can find a better one? I find e.g. the solution with centered captions very elegant, maybe something similar is suitable here also.

Describe alternatives you've considered

Right now I'm including the above snippet in a custom.css sheet.

The search page receives the RTD version selector:

• https://urllib3.readthedocs.io/en/latest/search.html?q=a&check_keywords=yes&area=default

However as far as I can tell all RST pages don't receive the selector:

• https://urllib3.readthedocs.io/en/latest/sponsors.html

Potentially something to do with jQuery? From the Inspect Element Console:

Uncaught ReferenceError: $ is not defined

Describe the bug
Search is endless looping with Sphinx 3.4.1.

To Reproduce

1. Create a minimal Sphinx 3.4.1 documentation with:

• as conf.py, the same as default, except of course html_theme = 'furo' instead of html_theme = 'alabaster':

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))


# -- Project information -----------------------------------------------------

project = 'Test 3.4.1'
copyright = '2020, Denis Bitouzé'
author = 'Denis Bitouzé'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
# html_theme = 'alabaster'
html_theme = 'furo'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

• as index.rst, almost the default one:

.. Test 3.4.1 documentation master file, created by
   sphinx-quickstart on Sat Dec 26 14:09:47 2020.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Test 3.4.1's documentation!
======================================

.. toctree::
   :maxdepth: 2
   :caption: Contents:

This a title
============

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

2. Run make html.
3. Open the index.html resulting file in any Web browser.
4. Search e.g. "title".

The searching will endless loop on: "Searching", "Searching.", "Searching..", "Searching...".

Expected behavior
Search works as expected.

Desktop (please complete the following information):

• OS: Linux Mageia 7
• Browsers: Firefox, Chromium, GNOME Web, Midori
• Version: furo 2020.11.27.beta19 or furo 2020.12.9b21

Additional context
Search is working as expected with:

• Sphinx 3.3.1 and Furo,
• Sphinx 3.4.1 and Alabaster.

Describe the bug

When I use search I receive an error stating: " Please activate JavaScript to enable the search functionality. "

To Reproduce
Steps to reproduce the behavior:

1. Do a search
2. See error

Expected behavior

See my search results instead :)

Screenshots

https://urllib3.readthedocs.io/en/latest/search.html?q=a&check_keywords=yes&area=default

Desktop (please complete the following information):

• OS: Ubuntu
• Browser: Firefox
• Version: 80.0.1