169

How do I add a link to a URL containing parentheses () (or "round brackets" by heathens)?

For example:

http://msdn.microsoft.com/en-us/library/aa752574(VS.85).aspx

The parentheses around "VS.85" causes it to look like this:

Markdown:

[IHtmlDocument2 reference](http://msdn.microsoft.com/en-us/library/aa752574(VS.85).aspx)

Output renders as

IHtmlDocument2 reference

4
  • 1
    Can I further note that the preview is not consistent with the result at times. I detailed this in my "duplicate" meta.stackexchange.com/questions/18323
    – dlamblin
    Aug 28, 2009 at 17:35
  • 5
    The team eventually decided that this was a bug, and has fixed it.
    – Pops
    Jan 20, 2011 at 15:36
  • 1
    It is poor form to have parentheses in a URL, many RegExes will presume text with either parenthesis is not a URL.
    – Ryan Ward
    May 21, 2011 at 18:48
  • 2
    @RVWard - Can you provide any real world examples? RFC3986 states parenthesis are valid in general URI's and RFC1738 explicitly indicates parenthesis are valid in URL's. And the link above is from Microsoft.com so I'm very doubtful that Microsoft would publish MSDN documentation links with invalid/unescaped URL's (regardless of what some might say about M$ & standards compliance ;) I'm not sure what standard you're using to classify it as "poor form." Jan 10, 2012 at 2:05

6 Answers 6

136

There are many ways to format URLs in Markdown. Parentheses work better with some methods than others.

1. Bare             - http://example.com/test(1).html
2. Bare, encoded    - http://example.com/test%281%29.html
3. Delimited        - <http://example.com/test(1).html>
4. Hyperlink        - with <a href="http://example.com/test(1).html">parens</a>
5. Markdown Link #1 - with [parens][1]
6. Markdown Link #1 - with [parens at end][2]
7. Markdown Link #2 - with [parens](http://example.com/test(1).html)
8. Markdown Link #2 - with [parens at end](http://example.com/test(1))  

  1. Bare - http://example.com/test(1).html
  2. Bare, encoded - http://example.com/test%281%29.html
  3. Delimited - http://example.com/test(1).html
  4. Hyperlink - with parens
  5. Markdown Link #1 - with parens
  6. Markdown Link #1 - with parens at end
  7. Markdown Link #2 - with parens
  8. Markdown Link #2 - with parens at end

Note also that parenthetical sections in MSDN links are optional, so:

http://msdn.microsoft.com/en-us/library/5471dc8s\(VS.80\).aspx

could be linked to, instead, as:

http://msdn.microsoft.com/en-us/library/5471dc8s.aspx

See also The Problem With URLs for Jeff Atwood's blog post about coming up with a solution for Stack Overflow.

Other issues with URLs

Sometimes URLs can fail to link correctly because they contain disallowed characters. In these cases encode the characters using the % notation. Previously characters such as () [] ' and * were not allowed but the server-side Markdown renderer has been modified to accept them now. Currently the only (known) characters that aren't accepted are ones with accents, graves, diaeresis, etc. For example: é or ö, although if it's a Wikipedia link you can just use the unadorned character. (A suggestion to have these characters supported has been made on UserVoice.)

9
  • 4
    TIL parenthetical sections in MSDN links are optional. Mind = blown. Dec 11, 2011 at 6:59
  • 3
    Of course, the parentheticals are needed if you want to link to a page about an earlier release...
    – SamB
    Jan 31, 2012 at 7:04
  • Would approach #4 be the preferred way to do this in comments? It doesn't seem to work for me. Here's <a href="hadoop.apache.org/docs/r2.3.0/api/org/apache/hadoop/mapreduce/…, org.apache.hadoop.fs.Path...)">an example</a>. Jun 4, 2014 at 15:01
  • @NickChammas when you're commenting, click the help link to the right of the text box, that will show how to do links in comments.
    – Sam Hasler
    Jun 4, 2014 at 15:05
  • @Sam - It's not clear from the help how to link to a URL with parentheses in a comment. Approaches 4, 7, and 8 above look like what I want (in-line linking of text to URL with parentheses), but none of them appear to work in comments. Jun 4, 2014 at 15:14
  • OK let me try again with this link: http://hadoop.apache.org/docs/r2.3.0/api/org/apache/hadoop/mapreduce/lib/input/FileInputFormat.html#setInputPaths(org.apache.hadoop.mapreduce.Job, org.apache.hadoop.fs.Path...) OK... [here we go!](hadoop.apache.org/docs/r2.3.0/api/org/apache/hadoop/mapreduce/…, org.apache.hadoop.fs.Path...)) Jun 4, 2014 at 15:24
  • 3
    @NickChammas There's a "space" character in that URL. You need to encode it as "%20" thus: an example
    – Sam Hasler
    Jun 4, 2014 at 15:26
  • Ahhhhhh, OK! Thank you for helping me track that down. Jun 4, 2014 at 15:28
  • I'll try one as well, by escaping parentheses: [Android link](https://developer.android.com/reference/android/content/res/Resources.html#getColor%28int%29) converts to Android link Oct 4, 2017 at 12:14
35

I ran into the same thing working on an IPython notebook. You can simply use URL encoding for:

  • ( which is %28, and for
  • ) which is %29.

Reference: HTML URL Encoding Reference (W3Schools)

3
  • 1
    In the Atom Editor for a correct Markdown preview from all Answers, this was the only method that worked.
    – ovhaag
    Oct 16, 2016 at 22:56
  • This also works for TFS-Web interface where <> does not.
    – kuga
    Aug 21, 2018 at 9:49
  • 1
    This works for Roam (e.g. in links to Wikipedia)
    – Avi
    Dec 15, 2020 at 14:26
22

Use the <a> notation instead of the [ ] notation.

e.g. <a href="http://msdn.microsoft.com/en-us/library/aa752574(VS.85).aspx">IHtmlDocument2 reference</a>

0
17

You can do it like this:

link to [IHtmlDocument2 reference][1]

   [1]: http://msdn.microsoft.com/en-us/library/aa752574(VS.85).aspx

For what it's worth, () are parentheses. Braces are {}.

3
  • 1
    As long as we're discussing semantics, I've also heard parentheses called "round braces", which I think is a kind-of neat and more generic/accurate term for them. Jun 4, 2014 at 14:28
  • Worth mentioning (for future readers) that when this was a problem back in 2008 until 2014, this method wouldn't work in comments.
    – Cole Tobin
    May 9, 2020 at 16:04
  • 1
    Let’s call the whole thing off. "...the word bracket is commonly used to refer to a specific form of bracket, which varies from region to region. In most English-speaking countries, an unqualified 'bracket' refers to the round bracket; in the United States, the square bracket". Also, "round brackets or parentheses. Square brackets or brackets. Curly brackets or braces. Angle brackets or chevrons". Mar 6 at 15:12
15

FYI, if you're trying to do this in Octopress or Jeckyll, you'll see that some of these methods don't work.

You can use the delimiters inside the parens like this:

[My Link](<http://example.com/test(1)>)

Which looks like this:

My Link

2
  • Excellent answer. Works for images too.
    – its_me
    Aug 30, 2016 at 18:56
  • 1
    Except when there are more parentheses inside like: [HMS Ark Royal, 1941](<https://en.wikipedia.org/wiki/HMS_Ark_Royal_(91)#Final_voyage_and_sinking>) which gives:- [HMS Ark Royal, 1941](<en.wikipedia.org/wiki/…) & which can someplaces (reddit) be corrected with an internal backslash for the inner ) but alas not here:- [HMS Ark Royal, 1941](<en.wikipedia.org/wiki/…
    – steveOw
    Nov 25, 2020 at 15:32
-3

One workaround is to use a service like TinyURL or Bitly to shorten the URL.

2
  • 1
    URL shorteners are strongly discouraged because there's no indication of where they point. For example, is tinyurl.com/Example a link to example.com, or to goatse?
    – Mark
    Oct 22, 2019 at 20:31
  • They can also break. If the url shortener goes away then so does the URL. May 30 at 8:53

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .