search

w3c / wai-std-gl-overview

4 stars 30 forks source link

double brackets in links in MD #21

Closed code-elegant closed 5 years ago

code-elegant commented 5 years ago

There are sometimes double square brackets in MD links: [[ … ]](…) What is the purpose? (I can't find a satisfactory explanation) The rendering on GitHub and by Jekyll are different: GitHub render the inside brackets while Jekyll filter them out without a noticeable effect, at least for me. Jekyll rendering example: https://www.w3.org/WAI/standards-guidelines/#guidelines

code-elegant commented 5 years ago

GitHub rendering example: https://github.com/w3c/wai-std-gl-overview/blob/master/index.md#accessibility-guidelines-guidelines

yatil commented 5 years ago

The double brackets are replaced by the title of the resource you link to. For example if you translate the title of a page to French (which has not been translated itself yet), but another translator or you would end up translating the title slightly differently, the correct title of the page would be used.

The GitHub previews don’t know what to do with it as it is a custom extension for us, make sure to always look at the Netlify preview that we provide. (Or Interpret the visible brackets as a marker that the title will be replaced.)

Obviously this is only applicable for links that have 100% of a resource name in them.

Documentation (starter) for this feature is here: https://www.w3.org/wiki/WAI/Website/Anatomy_of_a_Document#Title_Markdown_Links:_.5B.5BTitle_of_the_Page.5D.5D.28.2Fpath.2Fto.2Fpage.2F.29

code-elegant commented 5 years ago

Thank you Eric for this explanation. Something like a wiki link.

It means that we can't translate the title to [whatever other language, i. e. French] when linking to a page /and/ using double brackets.

As I understand that the text between the double brackets is only a placeholder, the "issue/bug" I encountered isn't that important (=you can't use HTML tag inside it, i. e. a to split text in 2 different languages).

Best,

~Erwan

yatil commented 5 years ago

It means that we can't translate the title to [whatever other language, i. e. French] when linking to a page /and/ using double brackets.

I don’t understand what you mean by this. Let me put it another way in the hope it clarifies it: If the source document has double brackets, you keep them and translate the text inside the brackets (or take the title of the already translated page, if that exists).

As I understand that the text between the double brackets is only a placeholder, the "issue/bug" I encountered isn't that important (=you can't use HTML tag inside it, i. e. a to split text in 2 different languages).

Only when the target page is translated, it is a placeholder, otherwise, the text is displayed. Using HTML should work (but as it is my programming, it might as well not :-D). If you find an instance where you would like to do something and it comes out weird, feel free to ping me to look at it.