spatie/typescript-transformer

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.

## Writing your own transformers
We've added a whole section in the docs about [writing transformers](docs/typescript-transformer/v2/transformers/getting-started).

My inspection

The link in the .md source file seems to be structured correctly:

We've added a whole section in the docs about [writing transformers](docs/typescript-transformer/v2/transformers/getting-started).

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.

  1. 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).
  1. 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.