Question about external links

[exchange12rocks]

AFAIK, all external links currently are not in a form of Markdown syntax - they look like this:
Link Title "http://example.com"

Sometimes the quotes are replaced by brackets, sometimes by a semicolon.

The question is: should we format all links in a proper Markdown-way? Or maybe they will disappear from PS console help if we implement it?

[zjalexander]

Yes, format all links in Markdown. PlatyPS knows to strip those out for console help.

[zjalexander]

For the purposes of the style guide, I have to answer a few questions:

• What should get linked - every first mention of a specific cmdlet?
  • Just the see-also section?
• Caveat: don't do stuff like give link text to URLs that need to be usable from console help. For example, [don't do this](http://wwww.microsoft.com/PowerShell) in a context where the user needs to see the url. Instead, you can just do http://www.microsoft.com/PowerShell which should render as a link on the web without obfuscating the URL.

I don't know if that's worded well enough, so this should all be clarified by #15.

[vors]

@zjalexander why not use [don't do this](http://wwww.microsoft.com/PowerShell) ?

PlatyPS handles it just fine. As far as I remember it strips away relative paths (which are common on github) but keeps absolute uris. The reason is actually our help system that enforces target links to be valid URIs.

For example usage you can see https://github.com/PowerShell/platyPS/blob/master/docs/New-MarkdownHelp.md

Here is how it's rendered

RELATED LINKS
    Online Version: https://github.com/PowerShell/platyPS/blob/master/docs/New-MarkdownHelp.md
    Character Encoding in the .NET Framework https://msdn.microsoft.com/en-us/library/ms404377.aspx
    Using PowerShell to write a file in UTF-8 without the BOM 
    http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom

[sdwheeler]

For general guidance see https://docs.microsoft.com/en-us/style-guide/urls-web-addresses

[sdwheeler]

Updated style guide