Open Hexagon opened 1 year ago
It's really hard to get the links right in documentation, in GitHub you can link to a relative file fine, but that isn't translated in any meaningful way into the docs site. For some reason they link to the cdn as stated above as a download.
It would be useful to default relative links to documentation pages in deno.land/x, with a option to link to source or even cdn - which could be specified by a URL param or hash (would need something that didn't affect GitHub though).
Here's an example, I've got a README.md here in GitHub, that has markdown like this...
[Module](./handle.ts) | [Example](./examples/handle.ts)
In GitHub those link directly to the respective source files, which is entirely appropriate for GitHub.
In deno.land/x they both link to raw files in cdn.deno.land, but I'd prefer them to link by default to the module doc (ie. ./handle.ts
-> https://deno.land/x/http_fns@v0.0.27/handle.ts?doc), with an option to also link to source, which would be more appropriate for the example (ie. ./examples/handle.ts
-> https://deno.land/x/http_fns@v0.0.27/examples/handle.ts?source)
Maybe we could add something like ?source
, ?doc
, ?raw
to those links (defaulting ?doc
) to have deno.land link to the preferred place...
[Module](./handle.ts?doc) | [Example](./examples/handle.ts?source)
Although we'd need to check this doesn't break in GitHub.
While checking out the READMEs of various libraries on deno.land/x, I've found a recurring problem with relative links.
For instance, the link to
/docs/examples
in pup@1.0.0-rc.0 incorrectly leads to https://cdn.deno.land/docs/examples instead of the expected location (directory listing).Moreover, in the case of the Danet README, a link that should point to
CONTRIBUTING.md
instead incorrectly points to https://cdn.deno.land/CONTRIBUTING.md when viewed from danet@1.8.0.Relative links in READMEs are quite common, as GitHub links lead to GitHub, n-links lead to n, deno.land links lead to deno.land, etc.
To clarify, my expectations for different relative path cases are as follows:
./CONTRIBUTING.md
->https://deno.land/x/package@version/CONTRIBUTING.md
(including dot, relative to the current directory)/CONTRIBUTING.md
->https://deno.land/x/package@version/CONTRIBUTING.md
(excluding dot, relative to the repository root)CONTRIBUTING.md
->https://deno.land/x/package@version/CONTRIBUTING.md
(excluding path, implicitly relative to current directory)./contributing.md
->https://deno.land/x/package@version/CONTRIBUTING.md
(case insensitivity)./docs/examples
->https://deno.land/x/package@version/docs/examples
(directory listing)