jupyter / nbconvert

Jupyter Notebook Conversion
https://nbconvert.readthedocs.io/
BSD 3-Clause "New" or "Revised" License
1.72k stars 564 forks source link

Improve HTML accessibility by including h1 tag #1992

Open rgaiacs opened 1 year ago

rgaiacs commented 1 year ago

Related with [WCAG 2.1 G130:Providing descriptive headings], might be beneficial to add <h1> if user doesn't provide one.

Consider the Minimal Working Example Jupyter Notebook.

Convert the notebook to HTML using

$ jupyter nbconvert --to html --template basic no-title.ipynb
[NbConvertApp] Converting notebook no-title.ipynb to html
[NbConvertApp] Writing 282 bytes to no-title.html

gives

$ cat no-title.html 
<div id="cell-id=2e2edc0e-f180-4da0-84bd-6317bb3276cd" class="cell border-box-sizing text_cell rendered"><div class="prompt input_prompt">
</div><div class="inner_cell">
<div class="text_cell_render border-box-sizing rendered_html">
<p>Sample paragraph.</p>

</div>
</div>
</div>

that has no <h1>.

cc @Jenneh @isabela-pf

tonyfast commented 1 year ago

yes i think this make would sense, but i don't know if nbconvert is the right scope. there are some immediate ambiguities i imagine in this inference problem. do we operate in notebook or html space? WCAG is defined in HTML, but we are talking notebooks. if we operate in notebook space then we have markdown headers mixed with HTML headers potentially. It is a sticky problem.

i feel like enforcing headings would be something that a static site generator like sphinx or mkdocs would enforce for the notebook author.

nbconvert turns notebooks into other document formats. i could imagine a library that extends the nbconvert machinery to add some accessibility into the exporting pipeline. it would make the most sense to operate in HTML space because that is where the WCAG standards are defined. further, we could add more guard rails that let folks know there are ways to improve the accessibility of their content.