Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

page.html: Position the flyout to bottom-left, on ReadTheDocs #865

Open
wants to merge 2 commits into
base: main
Choose a base branch
from

Conversation

ferdnyc
Copy link
Contributor

@ferdnyc ferdnyc commented Jan 21, 2025

As we know, ReadTheDocs has developed a new backend for their content integrations, including the floating menu of different versions and other links that's displayed when docs are built on the ReadTheDocs site. This new menu is built as an "addon" which can be configured in their system, but which can't be styled by theme CSS since it lives in a shadow DOM.

Recently (see readthedocs/addons#395), the ability to configure the position of that menu was added — the position can be set to any of bottom-right, bottom-left, top-right, or top-left. Positioning can be overridden in the project settings, but the new default setting for projects is "Default (from theme or Read the Docs)".

The Read the Docs default positioning is bottom-right, which in Furo docs tends to overlap content. The theme default can be changed, however, by adding a new tag to the content body:

<readthedocs-flyout position="{bottom,top}-{left,right}"></readthedocs-flyout>

This PR adds that tag to the page.html template, making the Furo default position for the flyout bottom-left instead of bottom-right. Again, individual projects can still override this in their settings; this merely sets the default for the theme.

I don't know if this is the best place to put such a tag, I only know that this worked for me in a test project. So consider this PR as more of a change suggestion than a change proposal. If there's a better implementation, I'm happy to make any changes necessary, or to close this entirely in favor of a better fix.

@ferdnyc
Copy link
Contributor Author

ferdnyc commented Jan 28, 2025

The ReadTheDocs team are also working on a position="inline" mode for the tag (readthedocs/addons#500), which would allow the flyout to be placed at a specific location in the theme DOM.

This might be an even better option for Furo docs, particularly ones that have sidebar TOCs long enough to exceed the browser height in length (where the flyout would normally overlap the bottom of the TOC even in position="bottom-left" mode). The flyout could be pinned to the very bottom of the sidebar, below all of the TOC entries, instead of floating above the ones at the bottom of the window area.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant