diff --git a/docs/link_formatting.adoc b/docs/link_formatting.adoc index a87732af87..b0fb985b81 100644 --- a/docs/link_formatting.adoc +++ b/docs/link_formatting.adoc @@ -10,7 +10,9 @@ We often want to provide links in the 'Resources' section of a rule that point t * Links to framework documentation - e.g. Microsoft Learn - Object.ToString Method * Links to blog posts / news articles: - e.g. Google Security Blog - Moving towards a more secure web * Links to Stack Overflow answers (similar comments in a blog)e.g. Stack Overflow - Answer by Stephen Cleary for Best way to handle null task inside async method? -* Link to another Sonar rule: <rulenumber> - <title> e.g. S2755 - XML parsers should not be vulnerable to XXE attacks (note, linking to rules.sonarsource.com) +* Links to another Sonar rule: <rulenumber> - <title> e.g. S2755 - XML parsers should not be vulnerable to XXE attacks. + Note that rule-ids (`<rulenumber>`) are automatically hyperlinked in our products to point to the rule description in that product. + _Do not add any hyperlink yourself._ The hyperlink to anything apart from other Sonar rules should be applied to just the document name, with the 'source' being left as plain text. The idea is that this makes it really easy for a user to understand the source before they click on anything. For Sonar rules, the whole entry (<rulenumber> - <title>) should be a hyperlink. @@ -21,7 +23,8 @@ Here is how the above links should look like: * Microsoft Learn - https://learn.microsoft.com/en-us/dotnet/api/system.object.tostring[`Object.ToString` Method] * Google Security Blog - https://security.googleblog.com/2016/09/moving-towards-more-secure-web.html[Moving towards a more secure web] * Stack Overflow - Answer by Stephen Cleary for https://stackoverflow.com/a/27551261[Best way to handle null task inside async method?] -* https://rules.sonarsource.com/java/RSPEC-2755[S2755 - XML parsers should not be vulnerable to XXE attacks] +* S2755 - XML parsers should not be vulnerable to XXE attacks + + _Note, no link here, this is the intended behavior. In the products the "S2755" part will be automatically hyperlinked._ === Additional things to consider when adding a link to a rule: