Avoiding rest_code_... on code-blocks

[DietmarSchwertberger]

Hi!

The listings that Nikola generates are full of id, name and href tags with "rest_code_....".
Every single line of code like

import wx

is converted into something like:

<a id="rest_code_a9db4fab05f54d7fa2fde251e00b63c2-6" name="rest_code_a9db4fab05f54d7fa2fde251e00b63c2-6" href="index.html#rest_code_a9db4fab05f54d7fa2fde251e00b63c2-6"></a>
<span class="kn">import</span> <span class="nn">wx</span>

This causes problems for people using screen readers like NVDA.
Is there a way to get rid of the except by post-processing them?

The relevant Nikola code seems to be this, but I could not see any configuration option:

nikola/plugins/compile/rest/listing.py

# A sanitized version of docutils.parsers.rst.directives.body.CodeBlock.
class CodeBlock(Directive):
    ...
    def run(self):
        """Run code block directive."""
        ....
        if self.site.invariant:  # for testing purposes
            anchor_ref = 'rest_code_' + 'fixedvaluethatisnotauuid'
        else:
            anchor_ref = 'rest_code_' + uuid.uuid4().hex
        ...
        formatter = utils.NikolaPygmentsHTML(
            anchor_ref=anchor_ref,
            classes=classes,
            linenos=linenos,
            linenostart=linenostart,
            **extra_kwargs
        )
        out = pygments.highlight(code, lexer, formatter)
        ....

[DietmarSchwertberger]

P.S.: I would suggest to avoid these tags by default and enable them only on request.

[felixfontein]

It sounds to me that adding aria-hidden="true" to the <a> tag should solve the problem (even if the link text is not empty, like if it's the line number if these are enabled). I'm not sure whether it is possible to get Pygments to do that, though.

[DietmarSchwertberger]

Non-empty links would probably be even worse.

[DietmarSchwertberger]

The aria-hidden="true" seem to solve the issue.

[DietmarSchwertberger]

For wxWidgets we will continue with a local copy of the listing.py plugin at wxPyWeb\plugins\compile\rest.
You should think about better accessibility support, though.

[DietmarSchwertberger]

If I find the time, I think I will submit a PR for Pygments to add aria-hidden="true" in case of empty links. That should not do any harm.

[DietmarSchwertberger]

PR pygments/pygments#2848 created.

[Kwpolska]

This enables linking to specific lines of a listing. This is a useful feature. I don't think we're going to disable it or make it configurable.

It might be worth checking if the screen reader issues occur with plain pygments (there are some customisations of ours in use), and if it does, maybe upstream could find a better implementation. That said, good looking code blocks tend to involve HTML and CSS hacks.

[felixfontein]

Pygments doesn't seem to use that feature, for example the listings in https://pygments.org/styles/ and https://pygments.org/docs/styles/ do not have these <a> tags. Also I'm not sure how useful the feature is if line numbers are not shown, like in https://getnikola.com/conf.html#rest_code_9889d49a6a5d427a9411a447e9c564cb-19, where you have to look at the HTML source to figure out the link's name.

[felixfontein]

According to the documentation (https://pygments-doc.readthedocs.io/en/latest/formatters/formatters.html#pygments.formatters.HtmlFormatter) I think lineanchors and anchorlinenos are mainly meant to be used with line numbers. We force its use also without line numbers.