Skip to content

Change default logo alt text #1472

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.

Sign up for GitHub

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

Merged
merged 13 commits into from
Sep 27, 2023
Merged

Change default logo alt text #1472

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
a4a6979
Default logo alt text only if no extra text
gabalafou Sep 21, 2023
e1b9f7b
change default logo
gabalafou Sep 21, 2023
881847a
use docstitle as default logo alt text
gabalafou Sep 21, 2023
71c57b1
update docs to reflect change
gabalafou Sep 21, 2023
36f1fe5
Apply suggestions from code review
gabalafou Sep 21, 2023
c54c0ac
use string formatting operator
gabalafou Sep 21, 2023
3430634
Update docs/user_guide/branding.rst
gabalafou Sep 26, 2023
4c4c0f0
Merge branch 'main' into no-logo-image-default
gabalafou Sep 26, 2023
442e776
docs fixes
gabalafou Sep 26, 2023
3850784
Update docs/user_guide/branding.rst
drammock Sep 26, 2023
7cbcc32
add test
drammock Sep 26, 2023
b75cf0f
Update pyproject.toml
12rambau Sep 27, 2023
a83bca2
revert to original
12rambau Sep 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 19 additions & 17 deletions docs/user_guide/branding.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,41 +77,43 @@ To reference an external website, make sure your link starts with ``http``:
}
}

Customize logo alternative text
-------------------------------

You may set a custom ``alt text`` for your logo to replace the default ``"logo image"`` generic description.
Adding a descriptive ``alt text`` can help make your documentation more accessible to readers using screen readers or another assistive tech.
Add a logo title
----------------

To do so, customize the ``html_theme_options["logo"]["alt_text"]`` configuration option as in the following example:
To add a title in the brand section of your documentation, define a value for ``html_theme_options.logo["text"]``.
This title will appear next to the logo image if set.

.. code-block:: python
:caption: conf.py

html_theme_options = {
"logo": {
# Because the logo is also a homepage link, including "home" in the alt text is good practice
"alt_text": "My Project Name - Home",
"text": "My awesome documentation",
}
}

Add a logo title
----------------
.. note:: The ``html_title`` field will work as well if no logo images are specified.

To add a title in the brand section of your documentation, define a value for ``html_theme_options.logo["text"]``.
This title will appear next to the logo image if set.
Customize logo alternative text
-------------------------------

Adding a descriptive ``alt text`` can help make your documentation more accessible to readers using screen readers or other assistive tech.

By default, the theme will set ``alt text`` to ``<Your Project Name> - Home`` unless you provide a logo title, in which case the theme sets the ``alt text`` to the empty string. The assumption is that if you provide a logo title, the title is probably doing the work of the alt text.

However, if you don't like the default values, you may set a custom ``alt text`` for your logo.

To do so, customize the ``html_theme_options["logo"]["alt_text"]`` configuration option as in the following example:

.. code-block:: python
:caption: conf.py

html_theme_options = {
"logo": {
"text": "My awesome documentation",
# Because the logo is also a homepage link, including "home" in the alt text is good practice
"alt_text": "My Project Name - Home",
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

seems odd to demo customization by specifying what would happen by default anyway? Here's a realistic made-up example.

Suggested change
# Because the logo is also a homepage link, including "home" in the alt text is good practice
"alt_text": "My Project Name - Home",
"logo": "path/to/pggpy/logo.jpg",
"text": "A pretty good geometry package", # something other than package name
# Because the logo is also a homepage link, including "home" in the alt text is good practice
"alt_text": "PggPy - Home",

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good point. Hmm. This would result in assistive tech representing the link as "PggPy - Home A pretty good geometry package."

I think that this section of the docs needs to be rewritten to provide a handful of examples (maybe a couple ones marked good and a couple marked bad).

That was something I was planning to do in a follow-up PR.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

does it help if default is "Home - pkgname" instead of "pkgname - Home"?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After examining logo alt text on a few sites, such as pac.bz, tink.uk, sarasoueidan.com, and w3.org, I do not think there's a clear consensus on how to do this.

So I think, ultimately, what we have is fine.

}
}

.. note:: The ``html_title`` field will work as well if no logo images are specified.


Add favicons
============

Expand Down
2 changes: 1 addition & 1 deletion src/pydata_sphinx_theme/theme/pydata_sphinx_theme/components/navbar-logo.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
<a class="navbar-brand logo" href="{{ href }}">
{# get all the brand information from html_theme_option #}
{% set is_logo = "light" in theme_logo["image_relative"] %}
{% set alt = theme_logo.get("alt_text", "Logo image") %}
{% set alt = theme_logo.get("alt_text", docstitle + " - Home" if not theme_logo.get("text") else "") %}
{% if is_logo %}
{# Theme switching is only available when JavaScript is enabled.
# Thus we should add the extra image using JavaScript, defaulting
Expand Down