Override more relative links in markdown / documentation

[Abhilash-Chandran]

• In the Readme.md of my package I linked the example tab of my package. Earlier this used to work by placing the following in the md file.

[example](/example)

• For reference: https://pub.dev/packages/number_inc_dec

• However this link fails now and goes to https://github.com/example

What is the correct approach to do this? How to link the install tab and example tabs correctly. Should I just use full URL instead?

[isoos]

Earlier this used to work by placing the following in the md file.

At the moment relative links to files are resolved (if github/gitlab URL is present), but not directories or paths that reference the site root.
https://github.com/dart-lang/pub-dev/blob/master/app/test/shared/markdown_test.dart#L110-L166

What is the correct approach to do this? How to link the install tab and example tabs correctly. Should I just use full URL instead?

Given that your README is also included in the documentation page generated by dartdoc, the scope of fixing this is a bit more than fixing the URL on the package page. I'd suggest using full URLs for now.

[Abhilash-Chandran]

Given that your README is also included in the documentation page generated by dartdoc, the scope of fixing this is a bit more than fixing the URL on the package page. I'd suggest using full URLs for now.

Ok. This makes sense. I didn't quite think about the api documentation page. Thank you @isoos for the quick feedback. Given that you updated the title I presume, I should leave this issue open. Is it ok..?

[isoos]

Yes, let's keep it open.

[isoos]

I think we should use the same relative URL rewrite logic we have for READMEs, and not implement a second (possibly different) version of it for package:dartdoc.

[magouyaware]

@isoos I just recently published my first flutter plugin, and noticed that links in the ReadMe that link to API docs are not working. However, these links do work when looking at the api reference.

For example, the CardDetailsSingleLineTextWidget link works here: https://pub.dev/documentation/olo_pay_sdk/latest/#available-widgets

But it does not work here:
https://pub.dev/packages/olo_pay_sdk#available-widgets

Unless I'm mistaken, it seems that this behavior is related to this issue, right? When I publish the next version of our package, I was going to set explicit urls for these types of links, but want to make sure that is the best approach until this issue is addressed.

Rather than just having [CardDetailsSingleLineTextWidget] in my ReadMe, I would replace it with the following:

[CardDetailsSingleLineTextWidget](https://pub.dev/documentation/olo_pay_sdk/latest/olo_pay_sdk/CardDetailsSingleLineTextField-class.html)

Is there a better alternative or is this the only option for now?

[isoos]

@magouyaware I'm not sure when did dartdoc start to rewrite such URLs in the README.md, but we don't have immediate plans to mirror that behavior. The main reason for that is GitHub/GitLab: they won't know about the link location, so to be consistent between multiple places, it is better to link with absolute URLs anyway.

[magouyaware]

@isoos Ok, so it seems like my issue is unrelated to this ticket then. Thanks for the advice, we'll use absolute URLs in the readme from now on.