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

add support for alt tags for jpeg and png images #1112

Merged
merged 1 commit into from
Oct 9, 2019

Conversation

hx2A
Copy link
Contributor

@hx2A hx2A commented Oct 9, 2019

Accessible web content needs to have proper 'alt' text for images. Currently, nbconvert will create html pages without any way for the user to add alt text if they wanted to. With this pull request, I added support for alt text for jpeg and png images.

The first way to use it is by adding to the output metadata, like so:

    from IPython.display import Image

    Image('images/some_image.jpg', metadata={'alt': 'description of image'})

This approach doesn't really work for matplotlib plots, however. Instead, the user must first create the plot:

    %matplotlib inline
    import matplotlib.pyplot as plt

    plt.plot([0, 2, 1])

And then set the cell's metadata to this:

    {
        "alt": "description of plot"
    }

Note: use View => Cell Toolbar => Edit Metadata to bring up a button to edit a cell's metadata.

Although writing proper alt text for complicated charts is challenging, there are resources explaining how it can and should be done:

http://diagramcenter.org/specific-guidelines-e.html

@@ -155,6 +155,10 @@ height={{ height }}
{%- if output | get_metadata('unconfined', 'image/png') %}
class="unconfined"
{%- endif %}
{%- set alttext=(output | get_metadata('alt', 'image/png')) or (cell | get_metadata('alt')) -%}
Copy link
Contributor

Choose a reason for hiding this comment

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

What if the cell has multiple images? Are we ok with all images getting the cell | get_metadata('alt')?

Copy link
Contributor Author

Choose a reason for hiding this comment

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

If a cell has multiple image outputs, the alt-text should be added to the output's metadata, not the cell's metadata. But there's no way to edit an output's metadata using Jupyter notebook or Jupyter lab. We can only edit the cell's metadata. We can use IPython.display.Image to programmatically set the output metadata, but that doesn't help people creating figures with matplotlib because you can't set the output metadata through matplotlib, and even if you could, not everyone would want to type out the alt-text in their code like that.

People who want or need to add alt-text to their notebooks for accessibility reasons can limit their cell outputs to one figure per cell, which isn't much of a limitation since that's what a lot of people do anyway. And without this change, all notebooks have zero alt-text added to figures and images, making Jupyter notebook blog posts less accessible to the blind or low vision community.

Copy link
Contributor

Choose a reason for hiding this comment

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

Yeah I think that's a fair compromise. Just wanted to make sure it was thought out.

Thanks for the improvement!

Copy link
Contributor Author

Choose a reason for hiding this comment

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

You are welcome!

I'd also like to update the documentation somewhere so people know about this feature. Can you advise how I should go about that? Which github project should I update and where should the documentation go?

Copy link
Contributor

Choose a reason for hiding this comment

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

It's this repo -- you can find to root of the docs here: https://github.com/jupyter/nbconvert/tree/master/docs

@MSeal MSeal merged commit fda8ba5 into jupyter:master Oct 9, 2019
@MSeal MSeal added this to the 5.6.1 milestone Oct 21, 2019
THargreaves added a commit to warwickdatasciencesociety/wdss-research-website that referenced this pull request Jun 3, 2020
Solves #6
Based on jupyter/nbconvert#1112 but applied
to markdown rather than HTML
@MSeal MSeal added this to the 5.6.1 milestone Sep 8, 2020
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.

2 participants