search

dart-lang / pub-dev

The pub.dev website
https://pub.dev
BSD 3-Clause "New" or "Revised" License
780 stars 147 forks source link

Override more relative links in markdown / documentation #3975

Open Abhilash-Chandran opened 4 years ago

Abhilash-Chandran commented 4 years ago 
[example](/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 commented 4 years ago

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 commented 4 years ago

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 commented 4 years ago

Yes, let's keep it open.

isoos commented 1 year ago

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 commented 6 months ago

@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 commented 6 months ago

@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 commented 6 months ago

@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.