Why Parentheses are Legal in URLs

Oct 13, 2025 by pynkocean.com 53 views

Introduction

In the world of web development, URLs (Uniform Resource Locators) play a crucial role in navigating and accessing various web resources. However, when it comes to URLs containing parentheses (also known as brackets), they can get mangled, leading to broken links and unexpected behavior. In this article, we will delve into the issue of URLs containing parentheses getting mangled and explore the reasons behind it.

Describe the Bug

The bug in question occurs when a URL like https://en.wikipedia.org/wiki/Antenna_(radio) is typed in a ReST (ReStructuredText) document. The rendered URL becomes https://en.wikipedia.org/wiki/Antenna_(radio - i.e., the left parenthesis is intact, but the right parenthesis is missing, resulting in a broken URL. The expected behavior is for the URL to remain intact, as parentheses are perfectly legal in URLs and are commonly used at sites like Wikipedia and MSDN.

How to Reproduce

To reproduce the bug, follow these steps:

Create a Sphinx project by running the command sphinx-quickstart --no-sep --project "demo" --author "tester" --release 1 --language en .
Add a demo URL to the index.rst page by running the command echo "Wikipedia https://en.wikipedia.org/wiki/Antenna_(radio) example" >> index.rst
Add another URL with a percent-encoded version of the parentheses by running the command echo "Pct-encoded https://en.wikipedia.org/wiki/Antenna_%28radio%29 version" >> index.rst
Render the HTML by running the command make html
Test the linkcheck by running the command make linkcheck

Environment Information

The environment information for this bug is as follows:

Sphinx version: sphinx-build 8.2.1

Sphinx Extensions

No Sphinx extensions are used in this case.

Additional Context

No additional context is provided for this bug.

The Problem with URLs

The problem with URLs containing parentheses is that they can get mangled when rendered in certain contexts. This is because the parentheses are not properly encoded, leading to a broken URL. In the case of ReST documents, the parentheses are not escaped, resulting in the right parenthesis being missing.

Why Parentheses are Legal in URLs

Parentheses are perfectly legal in URLs because they are used to group and enclose other characters. In the case of URLs, parentheses are used to indicate that a particular character or sequence of characters should be treated as a single unit. This is especially important in URLs that contain special characters or reserved words.

Common Use Cases for URLs with Parentheses

URLs with parentheses are commonly used at sites like Wikipedia and MSDN. For example, the URL https://en.wikipedia.org/wiki/Antenna_(radio) is a valid URL that contains parentheses. Similarly, the URL https://docs.microsoft.com/en-us/dotnet/api/system.string.split%28%29 is a valid URL that contains parentheses.

Conclusion

In conclusion, URLs containing parentheses can get mangled when rendered in certain contexts. This is because the parentheses are not properly encoded, leading to a broken URL. However, parentheses are perfectly legal in URLs and are commonly used at sites like Wikipedia and MSDN. By understanding the problem with URLs containing parentheses, developers can take steps to ensure that their URLs are properly encoded and rendered correctly.

Workarounds

There are several workarounds that can be used to avoid the issue of URLs containing parentheses getting mangled:

Use percent encoding: One way to avoid the issue is to use percent encoding to encode the parentheses. For example, the URL https://en.wikipedia.org/wiki/Antenna_(radio) can be encoded as https://en.wikipedia.org/wiki/Antenna_%28radio%29.
Use a different character: Another way to avoid the issue is to use a different character that is not prone to getting mangled. For example, the URL https://en.wikipedia.org/wiki/Antenna_(radio) can be rewritten as https://en.wikipedia.org/wiki/Antenna%20%28radio%29.
Use a URL encoding library: Finally, developers can use a URL encoding library to encode the URLs properly. This can help to avoid the issue of URLs containing parentheses getting mangled.

Future Work

In the future, it would be beneficial to investigate ways to improve the handling of URLs containing parentheses in ReST documents. This could involve adding support for percent encoding or other encoding schemes to ensure that URLs are properly rendered.

References

The Problem with URLs
Very Common
Q&A: URLs Containing Parentheses (AKA Brackets) Get Mangled =====================================================

Q: What is the problem with URLs containing parentheses?

A: The problem with URLs containing parentheses is that they can get mangled when rendered in certain contexts. This is because the parentheses are not properly encoded, leading to a broken URL.

Q: Why are parentheses legal in URLs?

A: Parentheses are perfectly legal in URLs because they are used to group and enclose other characters. In the case of URLs, parentheses are used to indicate that a particular character or sequence of characters should be treated as a single unit.

Q: What are some common use cases for URLs with parentheses?

A: URLs with parentheses are commonly used at sites like Wikipedia and MSDN. For example, the URL https://en.wikipedia.org/wiki/Antenna_(radio) is a valid URL that contains parentheses. Similarly, the URL https://docs.microsoft.com/en-us/dotnet/api/system.string.split%28%29 is a valid URL that contains parentheses.

Q: How can I avoid the issue of URLs containing parentheses getting mangled?

A: There are several workarounds that can be used to avoid the issue of URLs containing parentheses getting mangled:

Use percent encoding: One way to avoid the issue is to use percent encoding to encode the parentheses. For example, the URL https://en.wikipedia.org/wiki/Antenna_(radio) can be encoded as https://en.wikipedia.org/wiki/Antenna_%28radio%29.
Use a different character: Another way to avoid the issue is to use a different character that is not prone to getting mangled. For example, the URL https://en.wikipedia.org/wiki/Antenna_(radio) can be rewritten as https://en.wikipedia.org/wiki/Antenna%20%28radio%29.
Use a URL encoding library: Finally, developers can use a URL encoding library to encode the URLs properly. This can help to avoid the issue of URLs containing parentheses getting mangled.

Q: What is the expected behavior for URLs containing parentheses?

A: The expected behavior for URLs containing parentheses is for the URL to remain intact, as parentheses are perfectly legal in URLs and are commonly used at sites like Wikipedia and MSDN.

Q: How can I reproduce the bug?

A: To reproduce the bug, follow these steps:

Create a Sphinx project by running the command sphinx-quickstart --no-sep --project "demo" --author "tester" --release 1 --language en .
Add a demo URL to the index.rst page by running the command echo "Wikipedia https://en.wikipedia.org/wiki/Antenna_(radio) example" >> index.rst
Add another URL with a percent-encoded version of the parentheses by running the command echo "Pct-encoded https://en.wikipedia.org/wiki/Antenna_%28radio%29 version" >> index.rst
Render the HTML by running the command make html
Test the linkcheck by running the command make linkcheck

Q: What is the environment information for this bug?

A: The environment information for this bug is as follows:

Sphinx version: sphinx-build 8.2.1

Q: Are there any Sphinx extensions used in this case?

A: No Sphinx extensions are used in this case.

Q: Is there any additional context for this bug?

A: No additional context is provided for this bug.

Q: What are some possible solutions to this bug?

A: Some possible solutions to this bug include:

Adding support for percent encoding: Sphinx could be modified to add support for percent encoding, which would allow URLs containing parentheses to be properly encoded.
Using a different character: Sphinx could be modified to use a different character that is not prone to getting mangled, such as a space or a hyphen.
Using a URL encoding library: Sphinx could be modified to use a URL encoding library to encode the URLs properly.

Q: What are some best practices for handling URLs containing parentheses?

A: Some best practices for handling URLs containing parentheses include:

Using percent encoding: When encoding URLs containing parentheses, use percent encoding to ensure that the parentheses are properly encoded.
Using a different character: When encoding URLs containing parentheses, consider using a different character that is not prone to getting mangled.
Using a URL encoding library: When encoding URLs containing parentheses, consider using a URL encoding library to ensure that the URLs are properly encoded.