Add Pandoc epub filter to Jupyter exports and add a tool to add W3C/ accessibility tags

Enabling in Jupyter export menu the pandoc filter to produce e-pub files might be a little step but a step forward to enhance accessibility. Since version 3.2 + accessibility 1.0 e-pubs provide facilities to introduce tags on accessibility. Those tags defined in the W3C standard with referenced vocabularies listed in, are lighter than aria roles and easy to implement through <meta> tags.
The availability of the “raw e-pub” filter in the export menu may open new perspectives for accessibility to at least enable authors to add by hand the requested tags.

  • Some work is needed to develop an add-on that will enable to add the <meta> tags in the same way that simple tags can be added to a cell
  • Some work is needed to add enhanced filters on Jupyter-Pandoc to export the meta information on accessibility from notebooks to e-pubs.

There are at least two advantages to promote this strategy :

  1. We produce accessible documents that can be used in conjunction with other facilitating tools for a better experience than pdf text only document (e_pubs can provide audio video and interactive javascripts)
  2. The is a validation tool ACE by Daisy that enables anybody to check the conformance to accessibility standards (WCAG)

A short example with global tags on the e-pub and local tags on video inside the e-pub can be found here and the original unmodified notebook here

I am not able to provide pull-requests but I am ready to help e-pubs can be read with thorium or browsers extensions, maybe enhancements like this can be included in e-pubs.


Excellent stuff.

It would be worth bringing this up at the Jupyter Accessibility Meeting (in a couple hours), which can be found on the community calendar, where other people/groups are working on related accessible static outputs, as well as the interactive experience.

:bellhop_bell: @tonyfast

OK I’ll join the meeting Thanks.

this is really interesting and timely information. moreover, standards calm me.

we are working on the accessibility of rendered notebooks in the notebooks for all project. our goal bring better proper html standards that improve the screen reader, zoom, navigation support when reading rendered works.

these standards seem to apply directly our efforts. thanks for sharing @g-vidal .

we’ve implemented a few testing approaches for html because they all provide some different information. it would makes sense to expand that toolchain to support epub auditing.

Thanks for your support !
I am not a dev :sob: but I can help to test or eventually propose amended blocks of code I can understand. I do not know where to read or contribute with efficiency.
I fully agree with your statement on notebooks for all :+1:, I am involved in a project at university of Lyon in France that promotes inclusion Jupyter is one of the tools in the core of the project and I have tackled the accessibility question. Years ago I worked with ISO and CEN and of course :innocent: I started from the standards point of view.

epub3.2+accessibility 1.0 is a W3C pool of standards that provide a path to enhance accessibility. I like the following properties :

  • e-pub is a format that enables to “hang” on an xml structure “pieces of html” with all their environment including fonts, CSS and even JS scripts which guarantees flexibility and portability
  • e-pub being developped by W3C is sticked to web standards like WCAG 2.0 and a large community of users/contrinbutors
  • e-pub having strong contributions from Daisy consortium it benefits from their thoughts and knowledge
  • all the information on disability being in meta tags or attributes it enables anybody with or without diability to use e-pubs which facilitates the teacher’s work : one document is enough
  • ACE by Daisy makes it easy to check accessibility properties with scores and explanations of errors
  • The syntax and vocabularies are much simpler and less risky that aria roles for beginners and they can be accessed from

To go back to my proposal I think that we have three subjects :

  1. Request to add in Save and Export Notebook As ... menu the pandoc command to transform an ipynb into an epub. I have tested commands like :
    pandoc -f ipynb -t epub3 --metadata title="MyTitle" --metadata=author:"first author" --metadata=author:"second author" --metadata=lang:"fr-FR" --metadata=cover-image:"mycover" --epub-cover-image="mycover" --top-level-division=chapter --toc --css=./book.css --highlight-style pygments.theme -o mynotebook.epub mynotebook.ipynb .
    Advanced jupyter skills are needed to pick up the parameters from the notebook and push them in the command. External parameters like CSS and PYGMENTS theme have to be shared through the community.
  2. Introduce a pandoc filter that will be able to pick up accessibility information stored in the .ipynb JSON. That is necessary if we want an automatic transformation. It is always possible to add meta information by hand but it would be a pity not to take advantage of jupyter lab user interface which leads to the third point that links with your work I think
  3. We have to find a strategy on howto write and store accessibility meta information in .ipynb without perturbating the ordinary functions of Jupyter and with an easy interface. I do not know enough to make a proposal but from what I have seen it is possible to add tags on cells; maybe that could be an easy way to add tag with property and contents the way they are proposed in Daisy examples, or in any other way.

Thanks for the context.

Having .epub as an output for a single notebook is a fine goal.

There’s lots of places to stuff metadata in notebooks, though some of them are easier to do from a user perspective. I guess the ideal would be to have a couple notebooks (e.g. a minimal one, and a more full one, ideally exercising a bunch of features) with some manual markup (or inline notes) about what more data would need to be hoisted.

As to the build chain:

While pandoc is an attractive option, and already used for a number of nbconvert outputs, there are still some blockers to folks getting it installed correctly locally… so we may want to consider a more direct generation technique: for example, sphinx and mkdocs supports building .epub, so there may be some techniques could be cribbed from them… and, indeed, because of this, and support for multiple documents, using one of those might be more robust and broadly applicable, with notebooks being just one possible (but potentially augmented) source of data.

1 Like

Having an example of a “known-good” output, exercising all the features would also help a lot.