Relative links in readme can be broken

[pastelsky]

From HN:

Consider showing files other than the README. Relative links to things like CONTRIBUTING.md currently break. Alternatively interpret all relative links as pointing to github.com or npmjs.com. It'd be great to have a way to link from the README into API docs to guide readers. The community doesn't have a great convention for this unfortunately.

[DaniGuardiola]

It would be AMAZING if one could define some docs files structure that tsdocs can interpret and display. It would remove the need for a custom docusaurus-type site, as one could just put some markdown files in a docs/ directory and the link to tsdocs.

I see two options:

1. Convention - just define a specific filesystem structure, like relying on a docs/ dir and/or naming conventions. Pro: simpler, con: not very flexible.
2. Configuration file - something like a .tsdocs.config.json file that allows users to define options. Pro: more flexible, cons: a bit more complex, adds to the config file crazyness.

A third option would be to support both, where the convention would be a "default config" that can be customized by adding a config file.

[DaniGuardiola]

PD: I'd be happy to take a stab at this.

[pastelsky]

I believe the @group / @category / @packageDocumentation annotations should already allow for a lot of that, but need to be documented better.

@DaniGuardiola let's open a new issue to discuss structure. Keeping this one for broken readme links.

[hRupanjan]

are we talking about these links?

[WorldMaker]

If it helps, what npm's site seems to do is rewrite relative links to repository (GitHub) links. I don't know the details of their algorithm, but a relative link in the README of a GitHub hosted project points to GitHub's user/repo/blob/HEAD/

[hRupanjan]

Added a pull request addressing this issue

[difosfor]

I'd argue that relative links should link to files within the NPM package, not to GitHub. Our case for this is that we publish one of our packages to NPM from a private GitHub repo so that would make the links broken. Also, by linking within the same package you could also link to files generated at publish build time. And I think it just fits the general idea of relative links better, i.e: they point to the files next to the current one.

[hRupanjan]

I do agree with your use case. It won't function the same in the case of a private repo and relative links should actually refer to the root directory of the NPM package.
But, some of the relative files are generally not present when published to a NPM package (Eg: contribution.md), which are often times mentioned in the readme using relative links; will always be broken.
The workflow can be changed for private repos I think. But, surely will have to reengineer the whole process.

[difosfor]

I'd argue that packages should include all files linked to from other files. It should only be a small effort for them to include such files during publishing, no? So I'd just forget about supporting linking to GitHub to keep things simple.

In other words: If you decide to include the README.md file in your package, then you should also include any files linked to from there. The responsibility lies with the publisher.

[hRupanjan]

In an ideal world that should happen. But, unfortunately it doesn't happen that way. Already bumped into these issues.
Here is one package that has this issue. And there are multiple others.
NPM currently directly refers to GitHub links. That's why thought of implementing it this way.
For the sake of argument, this can go a long way. But, yes I agree with your private repo argument. A workflow needs to be implemented for that use case.

[difosfor]

How about we support both at the same time by first trying to resolve a relative link locally within the package that's being processed and falling back to GitHub deep links? I suppose that could be implemented in a followup PR so we can already merge your PR in the mean time to start using GitHub links.

[hRupanjan]

I think that is a good suggestion. But before we merge, we need to complete the discussion on post-load script for already generated docs.
So that we can change the links for those docs or we delete the whole cache for regenerating everything again which I think is not the better solution.