Open kylebshr opened 2 years ago
The current URL pattern for DocC links is that they do not contain trailing slashes.
The expectation that URLs have trailing slashes sounds like possibly a configuration of the specific frontend server being used to host the static files that DocC produces.
Can you provide any info on which server technology is being used to host the docs at the website where you're encountering issues? There may be a simple configuration fix to resolve this.
Hmm interesting - I don't know a lot about the infrastructure, but the DocC files are in an S3 bucket. It seems like the S3 API is looking for a file with that name rather than detecting that it should serve the directory.
I think you're right. I'm not super familiar with S3 myself, but the documentation makes it seem like the default behavior should work here by redirecting to the trailing slash style URL, but it's possible that I'm misreading it or overlooking some detail as to why that's not working in this case.
Different servers and hosting tools behave differently in this regard. For example, Google Cloud Storage buckets have a configuration option called MainPageSuffix
which can mimic this behavior. However, the MainPageSuffix only works when accessing the bucket through a custom domain (docs).
In our case, we make preview builds of a site for each PR, and host them in a GCS bucket. But because of this issue, the Swift docs don't work in the preview builds: https://storage.googleapis.com/foxglove-mcap-dev-preview/cfcd27a5da7b4985342566570186f3aeab7bbe8c/docs/swift/documentation/mcap/
Compare this to the final hosted site, where it works: https://mcap.dev/docs/swift/documentation/mcap/
In short, I think the option to automatically add trailing /
or even trailing /index.html
should be configurable, because it's impossible for this project to anticipate all the different hosting solutions that developers will be using.
Navigating to a page does not include a trailing slash, so copying the link and opening it directly doesn't work.
For example, our docs are hosted at https://example.com/marketui/documentation/marketui/
If you click on a type to see its details, the URL is directed to https://example.com/marketui/documentation/marketui/marketactionsheetcontroller
Copying that link and pasting it in to a browser gives the following error, unless a trailing slash is added:
Replace this paragraph with a short description of the incorrect behavior. If you think this issue has been recently introduced and did not occur in an earlier version, please note that. If possible, include the last version that the behavior was correct in addition to your current version.
Checklist
main
branch of this package.Expected behavior
Links in the documentation should work when copy-pasted.
Actual behavior
Links in the documentation do not work when copy-pasted.
Steps to Reproduce
See above.
Swift-DocC Version Information
Swift-DocC version: Xcode 13.3.1 Swift Compiler version:
swift-driver version: 1.45.2 Apple Swift version 5.6 (swiftlang-5.6.0.323.62 clang-1316.0.20.8)