Add style guide item on autolinks#1081
Conversation
34d3ecf to
3722adc
Compare
| If you forget the angle brackets the URL it is still render as a link on Github | ||
| (per [GFM autolink] syntax), but other tools (e.g. link checking tools) are | ||
| likely to not recognize it as a link. |
There was a problem hiding this comment.
This kind of argument can be left out. It should be what, not why.
There was a problem hiding this comment.
When you apply the rule what is important, but when you change the rule why is important. I found the why to be non-obvious so I thought better to spell it out.
There was a problem hiding this comment.
OK, but could the "why" be shorter? E.g.
If the angle brackets are not included, the URL it is render as a link on Github ([GFM autolink] syntax), but other tools may not recognize it as a link.
ghost
left a comment
There was a problem hiding this comment.
I like the purpose of this suggestion.
| "Domain Part"). If a word is an abbreviation, it is usually written with all | ||
| capitals, e.g. "DNS". | ||
| * When linking to other documents and you want to include the URL in the | ||
| rendered text, make sure to put angle brackets around the URL, i.e. use the |
There was a problem hiding this comment.
Make it a rule, not a suggestion, i.e. remove "make sure to".
Also, I suggest that the text does not speak to the reader, i.e. replace "you" with passive wording.
tgreenx
left a comment
There was a problem hiding this comment.
LGTM, can approve when Mats comments are addressed.
9c94bfa to
ce50efe
Compare
|
|
||
| If the angle brackets are not included the URL is still rendered as a link on | ||
| Github (per [GFM autolink] syntax), but other tools (e.g. link checking tools) | ||
| are may not recognize it as a link. |
There was a problem hiding this comment.
"are may" --> "may"
To make it shorter I suggest that "(e.g. link checking tools)" is excluded.
Purpose
Document how to keep our Markdown documentation compatible with tools other than Github.
Context
Fixes #585.
Changes
Adds an item to the style guide.
How to test this PR
N/A