There's currently no styling for the scroll bar in darkmode which causes it to stand out more than it should:

light dark

I'm currently using some custom CSS to produce the following scroll bar looks:

light dark

The CSS itself is below. I've just used colors from the available CSS variables, so the look could be improved by adding new ones:

::-webkit-scrollbar {
  width: 16px;
  height: 16px;
}

::-webkit-scrollbar-corner,
::-webkit-scrollbar-track {
  background-color: var(--color-background-border);
}

::-webkit-scrollbar-thumb {
  background-color: var(--color-foreground-border);
  background-clip: padding-box;
  border: 2px solid transparent;
}

/* Buttons */
::-webkit-scrollbar-button:single-button {
  background-color: var(--color-background-border);
  display: block;
  background-size: 10px;
  background-repeat: no-repeat;
}

/* Up */
::-webkit-scrollbar-button:single-button:vertical:decrement {
  height: 12px;
  width: 16px;
  background-position: center 4px;
  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='100' height='100' fill='var(--color-background-border)'><polygon points='50,00 0,50 100,50'/></svg>");
}

/* Down */
::-webkit-scrollbar-button:single-button:vertical:increment {
  height: 12px;
  width: 16px;
  background-position: center 2px;
  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='100' height='100' fill='var(--color-background-border)'><polygon points='0,0 100,0 50,50'/></svg>");
}

/* Left */
::-webkit-scrollbar-button:single-button:horizontal:decrement {
  height: 12px;
  width: 12px;
  background-position: 3px 3px;
  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='100' height='100' fill='var(--color-background-border)'><polygon points='0,50 50,100 50,0'/></svg>");
}

/* Right */
::-webkit-scrollbar-button:single-button:horizontal:increment {
  height: 12px;
  width: 12px;
  background-position: 3px 3px;
  background-image: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' width='100' height='100' fill='var(--color-background-border)'><polygon points='0,0 0,100 50,50'/></svg>");
}

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. :)

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.

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

Is your feature request related to a problem? Please describe. The current variable that controls the highlighting of the inline code block and general code block coloring always looks out of place: (this screenshot is from the PhotonVision documentation)

Describe the solution you'd like CSS variable that the user can control in conf.py to change both of these.

Describe alternatives you've considered Have a set color that is used for light/dark mode that cannot be controlled by the user but still would fit in.

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.

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?

Describe the bug sphinx-panels dropdown directive does not respect dark mode if it is not within a panels directive

To Reproduce sorry I don't have a full repro, but here's the page I used to test this

Bug
===

.. panels::

    Content of the top-left panel

    ---

    Content of the top-right panel

    :badge:`example,badge-primary`

    ---

    .. dropdown:: :fa:`eye,mr-1` Bottom-left panel

        Hidden content

    ---

    .. link-button:: https://example.com
        :text: Clickable Panel
        :classes: stretched-link


.. dropdown:: Click on me to see my content!

    I'm the content which can be anything:

    .. link-button:: https://example.com
        :text: Like a Button
        :classes: btn-primary

Expected behaviour The dropdown at the bottom of the page should also have a dark background

Screenshots https://gyazo.com/b53f60444de0427d08b270a280f9784e https://gyazo.com/2ed3766faa9d43325e8b020311ad78a6

Desktop (please complete the following information):

• OS: macOS Big Sur 11.2.1
• Browser: safari
• Version: 14.0.3

Additional context Using the latest PyPi version for both Furo and sphinx-panels

Hi. Thanks for the lovely project!

The furo theme is not compatible currently with the json builder.

Steps to reproduce the behavior:

1. Create a project and enable the furo theme.
2. make html (Observe no problem)
3. make json (Error: see below)
4. Comment out furo theme
5. make json (Observe no problem)

At step three, the end of the traceback is:

  File "/env/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 360, in build
    self.write(docnames, list(updated_docnames), method)
  File "/env/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 534, in write
    self._write_serial(sorted(docnames))
  File "/env/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 544, in _write_serial
    self.write_doc(docname, doctree)
  File "/env/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 611, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/env/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/__init__.py", line 104, in handle_page
    self.dump_context(ctx, outfilename)
  File "/env/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/__init__.py", line 79, in dump_context
    self.implementation.dump(context, ft, *self.additional_dump_args)
  File "/env/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/jsonimpl.py", line 31, in dump
    json.dump(obj, fp, *args, **kwds)
  File "/Users/carlton/.pyenv/versions/3.8.3/lib/python3.8/json/__init__.py", line 179, in dump
    for chunk in iterable:
  File "/Users/carlton/.pyenv/versions/3.8.3/lib/python3.8/json/encoder.py", line 431, in _iterencode
    yield from _iterencode_dict(o, _current_indent_level)
  File "/Users/carlton/.pyenv/versions/3.8.3/lib/python3.8/json/encoder.py", line 405, in _iterencode_dict
    yield from chunks
  File "/Users/carlton/.pyenv/versions/3.8.3/lib/python3.8/json/encoder.py", line 438, in _iterencode
    o = _default(o)
  File "/env/lib/python3.8/site-packages/sphinxcontrib/serializinghtml/jsonimpl.py", line 25, in default
    return super().default(obj)
  File "/.pyenv/versions/3.8.3/lib/python3.8/json/encoder.py", line 179, in default
    raise TypeError(f'Object of type {o.__class__.__name__} '
TypeError: Object of type _lru_cache_wrapper is not JSON serializable

Expected behavior The JSON builder should succeed.

• Version: furo==2021.2.21b25

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!

This is copied from https://github.com/sphinx-doc/sphinx/blob/3.x/sphinx/themes/basic/domainindex.html and then edited to extend base.html rather than layout.html.

I thought I'd already tried something similar to this, but obviously not!

This seems to work, but maybe further work is needed in order fully to integrate it into the theme.

Is your feature request related to a problem? Please describe. I understand that it doesn't make much sense to have a full table of contents as furo already shows full ToC on the sidebar and I'm assuming this is why such an error message exists, but I don't think those reasons are as valid for the local table of contents. A local table of contents can be useful to, for example, list the options available to the user more clearly.

Describe the solution you'd like I think hiding the message only for the local table of contents would be a great solution to this problem.

Describe alternatives you've considered If you don't agree that having a local table of contents can be useful then a possible alternative would be to have a theme setting that you have to opt into to disable the error (fully or just for the local table of contents, whatever is easier or is of your preference).

Additional context Links to some examples of docs pages where we would like to use the local table of contents: https://red-discordbot--4675.org.readthedocs.build/en/4675/install_windows.html https://red-discordbot--4675.org.readthedocs.build/en/4675/install_linux_mac.html

If a document has more than one TOC tree directive and no other headings on the page, an empty "Contents" section is rendered in the sidebar. Adjusting the hide-toc logic to check if all entries in the TOC tree are all local TOC tree entries.

It would be nice to allow HTML in the copyright so that you can link to a website, like so:

copyright = "<a href=\"https://jareddillard.com\">Jared Dillard</a>"

I don't know if this creates a security risk by using safe, but if it does I think you'd have to try and shoot yourself in the foot. I'm also not sure if docs of some kind should be added to point out that use can use HTML (carefully).

Description

This PR increases the admonition title background opacity from 10% to 20%, resulting in a more vibrant mood and smoother contrast. If desired this value could even be raised to 25 or even 30 percent, although that may draw more attention than wanted.

Rationale

Currently, admonition title backgrounds are quite dark. When compared to the 100% opacity left border, there is a high contrast that looks out of place upon further inspection. The current opacity doesn't give enough overall contrast to the document as a whole, and therefore doesn't draw as much attention as you would expect from an admonition. Increasing the background opacity decreases the sharp contrast between the border and background, while increasing the overall contrast just enough to draw the eye to land on the admonition title, but doesn't draw the eye too much as to disrupt the flow of the document. Overall, it gives admonitions (particularly warnings and danger messages) the importance they deserve without seeming out of place.

Description

This PR increases the size of some icons in order to improve accessibility, particularly for mobile devices. The larger sizes only consume a slightly larger horizontal width, while the vertical width is mainly unchanged due to padding/margin - which is great, because it only takes up previously empty space. I've included some before/after comparison images below.

Rationale

I've found that on mobile the menu icons are harder to tap than they should be, and compared to honestly most other websites the proportions just look and feel unnatural. I've even had difficulty clicking the icons on desktop sometimes. These new sizes make the site feel more modern and easy to use.

What's happening?

Currently, I use the announcement banner to warn users that they are looking at an outdated version of the generated docs. However, the banner is not sticky / fixed, so it disappears when users scroll down the page. This can be problematic when users access the docs through a hyperlink referencing a paragraph, as they probably won't see the banner.

I tried using custom CSS to simply make the banner sticky, but it seems it seems more complex (see discussion #545). In particular, the rest of the page will scroll under the banner, eventually hiding the logo, which I think is not the expected behaviour.

Reproducer

Simply use announcement option and scroll down.

Expectation

In my opinion, banners should be sticky by default in order to prevent this, but I guess having an option to make them sticky or not could be nice! :slightly_smiling_face:

Code of Conduct

• [X] I agree to follow the Code of Conduct.