Broken link in the docs
Closed this issue · 0 comments
Issue
docs/usage/using-transformers.md has a link at the very bottom that should lead to docs/transformers/getting-started.md, however it's broken and redirects to docs/introduction.md.
typescript-transformer/docs/usage/using-transformers.md
Lines 62 to 64 in 00d21fa
My inspection
The link in the .md source file seems to be structured correctly:
Upon further inspection in the browser, it appears that the link is not resolved to an absolute url, but to the relative url just like in the document itself.
<!-- Link expected to resolve to this -->
<a href="https://spatie.be/docs/typescript-transformer/v2/transformers/getting-started">writing transformers</a>
<!-- Instead we get this -->
<a href="docs/typescript-transformer/v2/transformers/getting-started">writing transformers</a>
The issue manifests because the source file and the target file are located in different namespaces (directories), clicking on the link appends it to the current namespace, eventually resolving to https://spatie.be/docs/typescript-transformer/v2/usage/docs/typescript-transformer/v2/transformers/getting-started
, a link that doesn't exist, hence redirection to the introduction page.
Mitigation
This issue can be fixed in one of two ways.
- Using absolute url instead of relative
We've added a whole section in the docs about [writing transformers](https://spatie.be/docs/typescript-transformer/v2/transformers/getting-started).
- Using directory traversal to navigate to target namespace/file
We've added a whole section in the docs about [writing transformers](../transformers/getting-started).
The second mitigation is cleaner in my opinion, a PR with such a mitigation will be submitted momentarily.
Suggestions
This might be the only instance of this issue in spatie/typescript-transformer
docs, but as far as I know, all spatie packages generate their docs the same way, therefore similar issues might be present in docs of other packages.
I suggest to use a script to scan the docs directory in every spatie package to catch any instance of a file having a link to another file in a different namespace.
Also, having a Github Actions job that warns/fixes this issue will insure future proofing against introducing such links accidentally.