# Are symbol links case-sensitive or not?

**URL:** <https://forums.swift.org/t/are-symbol-links-case-sensitive-or-not/66693>\
**Category:** Swift-DocC\
**Tags:** swift-nio\
**Created:** [August 10, 2023, 3:02am UTC](https://forums.swift.org/t/are-symbol-links-case-sensitive-or-not/66693 "2023-08-10T03:02:51Z")\
**Posts on this page:** 3\
**Page:** 1

<div class="post-metadata">

**Author:** ![taylorswift](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/taylorswift/32/43413_2.png) [@taylorswift](https://forums.swift.org/u/taylorswift)\
**Post date:** [August 10, 2023, 3:02am UTC](https://forums.swift.org/t/are-symbol-links-case-sensitive-or-not/66693/1 "2023-08-10T03:02:51Z")

</div>

i am told that symbollinks/codelinks have become [case sensitive](https://forums.swift.org/t/how-to-reference-an-article-in-a-different-module/65581/9).

> For example, a type and a property like this

```swift
enum Something {}
var something: Something

```

> needed to be written as `Something-swift.enum` and `something-swift.property` to match those "topic references". If the enum link was lowercase—like `something-swift.enum`—it wouldn't resolve.

this is a good idea and i wholeheartedly support it.

on the other hand, i notice certain packages, such as SwiftNIO, have [articles](https://github.com/apple/swift-nio/blob/2.57.0/Sources/NIO/Docs.docc/index.md#a-note-on-blocking) that use case-insensitive autolinks:

```swift

<!-- links -->
[module-core]: ./niocore
[module-posix]: ./nioposix
[module-embedded]: ./nioembedded
[module-concurrency-helpers]: ./nioconcurrencyhelpers
[module-embedded]: ./nioembedded
[module-foundation-compatibility]: ./niofoundationcompat
[module-http1]: ./niohttp1
[module-tls]: ./niotls
[module-websocket]: ./niowebsocket
[module-test-utilities]: ./niotestutils

[ch]: ./niocore/channelhandler
[c]: ./niocore/channel
[chc]: ./niocore/channelhandlercontext
[ec]: ./nioembedded/embeddedchannel
[el]: ./niocore/eventloop
[eel]: ./nioembedded/embeddedeventloop
[elg]: ./niocore/eventloopgroup
[bb]: ./niocore/bytebuffer
[elf]: ./niocore/eventloopfuture
[elp]: ./niocore/eventlooppromise
[cp]: ./niocore/channelpipeline
[mtelg]: ./nioposix/multithreadedeventloopgroup
[sb]: ./nioposix/serverbootstrap
[cb]: ./nioposix/clientbootstrap
[db]: ./nioposix/datagrambootstrap
[pthreads]: https://en.wikipedia.org/wiki/POSIX_Threads
[kqueue]: https://en.wikipedia.org/wiki/Kqueue
[epoll]: https://en.wikipedia.org/wiki/Epoll

```

it appears that the DocC engine does not even bother trying to resolve them, they just become relative URLs that the browser resolves, which means they only work if the article is bound to a module. (e.g., not a standalone article.) moreover, these links [**return 404**](https://github.com/apple/swift-nio/blob/2.57.0/Sources/NIO/Docs.docc/niocore/eventloopfuture) when viewed on GitHub.

when i feed the package into my own documentation tooling, the links fail to resolve because their casing does not match. (correctly-cased cross-target links _do_ work.)

what is our policy towards all-lowercased symbol links?

---

<div class="post-metadata">

**Author:** ![taylorswift](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/taylorswift/32/43413_2.png) [@taylorswift](https://forums.swift.org/u/taylorswift)\
**Post date:** [August 10, 2023, 7:14pm UTC](https://forums.swift.org/t/are-symbol-links-case-sensitive-or-not/66693/2 "2023-08-10T19:14:02Z")

</div>

the easiest way to resolve this issue turned out to just be [updating the article source](https://github.com/apple/swift-nio/pull/2500) in NIO to use the correct casing. thanks to @lukasa for the speedy PR review!

---

<div class="post-metadata">

**Author:** ![ronnqvist](https://sea2.discourse-cdn.com/swift/user_avatar/forums.swift.org/ronnqvist/32/20110_2.png) [@ronnqvist](https://forums.swift.org/u/ronnqvist)\
**Post date:** [August 28, 2023, 10:23pm UTC](https://forums.swift.org/t/are-symbol-links-case-sensitive-or-not/66693/3 "2023-08-28T22:23:55Z")

</div>

> [@taylorswift](#):
>
> i am told that symbollinks/codelinks have become [case sensitive](https://forums.swift.org/t/how-to-reference-an-article-in-a-different-module/65581/9).

A small but important clarification; symbol links in DocC were always case sensitive.

What previously made the symbol links _appear_ to be case insensitive was that that `Something` and `something` used to have a name collision which meant that they needed to be written with both the correct capitalization and with disambiguation.

As of 5.9 symbols with different capitalization no longer need further disambiguation.

> [@taylorswift](#):
>
> on the other hand, i notice certain packages, such as SwiftNIO, have [articles](https://github.com/apple/swift-nio/blob/2.57.0/Sources/NIO/Docs.docc/index.md#a-note-on-blocking) that use case-insensitive autolinks:

This looks to me like it's relying on the URLs that DocC creates for these pages being all lowercase. DocC intentionally lowercases symbol names in the URLs and it would be a very big breaking change to stop doing so.

IIRC this was done to avoid differences in behavior across servers with case sensitive and case insensitive URL handling.

> [@taylorswift](#):
>
> what is our policy towards all-lowercased symbol links?

My personal opinion about this is that symbol links (using the ```SymbolName``` syntax) should be capitalized the same way as those symbol names are capitalized when in source code.

DocC doesn't attempt to resolve regular web links (neither absolute not relative links) so a link that references a DocC page using a regular web link is essentially invisible to DocC.
