Pkldoc generates broken page anchors #131

New Issue

adam · 2025-12-30T01:21:20+01:00

adam commented

2025-12-30 01:21:20 +01:00

Originally created by @odenix on GitHub (Apr 4, 2024).

Searching the standard library docs, I noticed that I always land at the top of the page, not at the function I search for. For example, searching for sort takes me to https://pkl-lang.org/package-docs/pkl/current/base/Collection.html#sort(). But #sort() doesn't exist, so I land at the top of the page. Inspecting the page source, I found that id attributes are erroneously percent-encoded:

<div id="sort%28%29" class="anchor">

Originally created by @odenix on GitHub (Apr 4, 2024). Searching the standard library docs, I noticed that I always land at the top of the page, not at the function I search for. For example, searching for `sort` takes me to `https://pkl-lang.org/package-docs/pkl/current/base/Collection.html#sort()`. But `#sort()` doesn't exist, so I land at the top of the page. Inspecting the page source, I found that `id` attributes are erroneously percent-encoded: ``` <div id="sort%28%29" class="anchor"> ```

adam commented

2025-12-30 01:21:21 +01:00

@bioball commented on GitHub (Apr 4, 2024):

Thanks for the error report.

Although, it's not strictly necessary, the percent-encoding there is intentional (we are using java.net.URLEncoder underneath the hood to encode links and anchors).

We should similarly run links from the generated search index through URLEncoder.

@bioball commented on GitHub (Apr 4, 2024): Thanks for the error report. Although, it's not strictly necessary, the percent-encoding there is intentional (we are using `java.net.URLEncoder` underneath the hood to encode links and anchors). We should similarly run links from the generated search index through URLEncoder.

adam commented

2025-12-30 01:21:21 +01:00

@odenix commented on GitHub (Apr 4, 2024):

Although, it's not strictly necessary, the percent-encoding there is intentional (we are using java.net.URLEncoder underneath the hood to encode links and anchors).
We should similarly run links from the generated search index through URLEncoder.

Unnecessarily obfuscating Pkldoc URLs will result in a worse user experience.
Swift and Scala API docs are fine with parentheses in URL paths/fragments, as is the URL spec.

https://developer.apple.com/documentation/swift/array/sorted(by:)
https://www.scala-lang.org/api/2.13.5/scala/collection/SeqOps.html#sortWith(lt:(A,A)=>Boolean):C
https://url.spec.whatwg.org/#path-percent-encode-set
https://url.spec.whatwg.org/#fragment-percent-encode-set

From https://docs.rs/crate/percent-encoding/2.3.1 (emphasis mine):

When encoding, the set of characters that can (and should, for readability) be left alone depends on the context.

@odenix commented on GitHub (Apr 4, 2024): > Although, it's not strictly necessary, the percent-encoding there is intentional (we are using java.net.URLEncoder underneath the hood to encode links and anchors). We should similarly run links from the generated search index through URLEncoder. Unnecessarily obfuscating Pkldoc URLs will result in a worse user experience. Swift and Scala API docs are fine with parentheses in URL paths/fragments, as is the URL spec. https://developer.apple.com/documentation/swift/array/sorted(by:) https://www.scala-lang.org/api/2.13.5/scala/collection/SeqOps.html#sortWith(lt:(A,A)=>Boolean):C https://url.spec.whatwg.org/#path-percent-encode-set https://url.spec.whatwg.org/#fragment-percent-encode-set From https://docs.rs/crate/percent-encoding/2.3.1 (emphasis mine): >When encoding, the set of characters that can (**and should, for readability**) be left alone depends on the context.

adam commented

2025-12-30 01:21:21 +01:00

@bioball commented on GitHub (Apr 5, 2024):

Yup, it definitely doesn't need to encode parentheses. It'd certainly be an improvement to not encode them here.

@bioball commented on GitHub (Apr 5, 2024): Yup, it definitely doesn't need to encode parentheses. It'd certainly be an improvement to not encode them here.

adam referenced this issue

2025-12-30 01:24:23 +01:00

[PR #131] [MERGED] Don't run JUnit tests for non-existing native executables #420

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/pkl#131