markdown-it-footnote
markdown-it-footnote copied to clipboard
markdown-it
Generate an aria-label attribute
It improves readability for audio readers like macOS VoiceOver.
Inspired by this article: https://bribesdereel.net/post/2018/12/02/markdown-footnotes-accessibility (in French)
via @llune
On a side note, it adds support for a constructor options object so as wrappers like https://github.com/hexojs/hexo-renderer-markdown-it can remotely configure the behaviour of the plugin, to personalise/localise the aria-label value.
Another commit restores the build status by making the dependencies to work with [email protected]. [email protected] drops this compatibility.
Existing templates are for examples only. I don't like to change those, because any change will be opinion-based. See previous rejected PRs https://github.com/markdown-it/markdown-it-footnote/pulls?q=is%3Apr+sort%3Aupdated-desc+is%3Aclosed
What do you mean by "Existing templates are for examples only."? I'm not sure what you refer to as "template" (the HTML output?).
I mean renderer functions. Those can not be empty (to show demo, for example), but there is no way to provide universal solution. So, users are expected to customize those.
Ah! I did not realise templates could be swapped. Thanks for the tip, it might be useful in the future 🙂
However in this case this is not a layout thing, it's an accessibility thing. It is a content which is read by screen readers and has no visual influence. The purpose is to make the back reference understandable with a VoiceOver-type application.
Without this pull request, the back reference link is read out loud as LEFTWARDS ARROW WITH HOOK.
With this pull request, the back reference link is read out loud as back to text.
It's not a customisation but a way to universally make it usable.
I don't like to promote api options for things, which are expected to be changed.
I understand handling the label option can be done by changing the template.
Is the arial label proposal acceptable if I remove the code related to the options? Or is there another path which would make it reach a mergeable state?
At first glance, i have no ideas how to add aria labels without options or hardcoding english phrases. Both are not perfect.
So, right now i see no ways how to get something acceptable.
Well, LEFTWARDS ARROW WITH HOOK is certainly not perfect.
I'd be keen on making at least making it sounds like back to text (or a better label) as the smallest step change, while looking for a nicer solution.
I don't like to hardcode english texts. My position is to change nothing if good solution is not available.
Sorry if it sounds rude but I don't think this change is about what you prefer but about the benefit for people who currently hear garbage on a hardcoded unicode arrow symbol.
Well, I second @oncletom. It's not a technical debate at first sight. It's a user oriented debate to or not to handle aria-label, literally making (or not) footnote more user-friendly, including those using a screenreader no matter why. Answering this user-oriented question by the positive is then making the subject into a technical debate. And perfect solution doesn't exist, only solution to a need matters. That said, since you're commenting the technical quality of @oncletom's contibution, it gives me some hope it's not an accessibility debate, thus allowing anyone to propose something technically better, in your standard, maybe later ? :)
As i explained, common mistake is to consider default renderer as out-of-box solution. But it is not. As soon as you accept this fact, you will fine to tune it local.
When no good solution available, i prefer to use the most simple one, as now. If someone wish to propose improvements - this can be discussed in issue. Not here.
Hi!
The current backref is clearly an accessibility issue. I think I understand @puzrin's concerns and that a solution can be found.
A solution could be to use the number of the footnote instead which would be better than the current arrow and would not need to hardcode English text. It is not ideal but it will be far more usable for the disabled persons concerned.
Create a variable for the content of the aria-label and set it to be the number of the footnote by default. Users could then change the variable and add the text they like.
Edit: Hi @puzrin! Did not see your message as I was typing mine at the same time. Should I open an issue?
Should I open an issue?
If you wish to discuss ideas - yes. Issue is much better place for such things.
Sorry if it sounds rude but I don't think this change is about what you prefer but about the benefit for people who currently hear garbage on a hardcoded unicode arrow symbol.
FWIW it would generally be nice if, when possible, examples (even if simplified) don't have major problems. yes, there's not always a universal solution, and yes authors will need to modify examples to suit their particular needs, but it's best to provide at least something that - even when just copy/pasted / cargo-culted - isn't completely broken for certain user groups/situations.
it would generally be nice if, when possible, examples (even if simplified) don't have major problems
What do you refer to as examples @patrickhlauke?
I'm happy to close this PR if the topic can still be discussed as part of an issue to design more accessible footnotes.
Example with aria-label override can be added here https://github.com/markdown-it/markdown-it-footnote#use. I this case, hardcoded english phrase will be ok.
If code change wished - anyone can inspect declined PRs/issues and suggest better solutions. I'm not against changes. I'm against replace kludges with another kludges.