relative URL rewrites don't work when the default branch is not master but eg. main

[ben-xD]

Problem

Local paths referenced in a GitHub readme are broken once shown on pub.dev. For example:

Current workarounds

Currently, packages work around this by using https://github.com/ or https://raw.githubusercontent.com/ to reference local images in the repo. However, this means:

• local previews require internet
• local previews might be broken since developers might be working on a branch but would still want to use main/ master in the URL, so that it works once merged. This is a slightly poor developer experience.

For example, flutter_local_notifications uses <img height="480" src="https://github.com/MaikuB/flutter_local_notifications/raw/master/images/android_notification.png">. Getx uses ![](https://raw.githubusercontent.com/jonataslaw/getx-community/master/getx.png).

Suggestion

If we changed the local paths automatically to https://raw.githubusercontent.com/$user/$repo/branch/$relative_path, this problem would be avoided, and it work seamlessly for users. Alternatively, we could use https://github.com/$user/$repo/branch/$relative_path. There doesn't seem to be a difference for images, but there is for normal files, so github.com would probably be better?

Concerns:

• how would you know which branch, use the default branch? Or keep track of this during publish (maybe its done already)?

[isoos]

We do have a limited support for relative URL rewrites if the homepage/repository url is on GitHub or GitLab. What's the package where you have the non-working example?

[ben-xD]

Hey @isoos, thanks for your reply. The package where it's not working is ably_flutter's 1.2.2-preview.1. You can find the spot by searching for run-configuration-1.

[isoos]

The issue here is the default branch: pub.dev at the moment doesn't query the git repository of its settings, we just assume that the default branch is called master. When somebody uses a different name e.g. main, we don't know about it, and use master in the URL. (you can see in the sources that the URL was rewritten into https://github.com/ably/ably-flutter/raw/master/images/run-configuration-1.png).

I'll update the title of the issue, as we definitely want to fix this eventually.

[sigurdm]

I'm not able to find a way to directly query the name of the main branch - but we can query the existence of master/main.

I think we can do it like this:

curl \
                                     -H "Accept: application/vnd.github.v3+json" \
                                     https://api.github.com/repos/dart-lang/pub/git/ref/heads/main

If main doesn't exist we get a 404, and we can assume master (or the other way around whatever seems most politically correct.)

See api doc here: https://docs.github.com/en/rest/reference/git#get-a-reference

[ben-xD]

@sigurdm would this be helpful?: How do I find the default branch for a repository using the Github v3 API

Edit: Actually if you list organization repositories: GET /orgs/{org}/repos, you will get a field in the response json:

 "default_branch": "master",

[sigurdm]

A cheap workaround would be to link to HEAD: https://github.com/dart-lang/pub/tree/HEAD/lib/src - it shows up a bit funny however (shows the sha-id instead of a branch name).

[definitelyokay]

I just discovered this issue while publishing a package: https://pub.dev/packages/recipe_flavored_markdown. The coverage badge (which is a relative link inside the readme markdown) is broken on pub.dev, but working on GitHub. I noticed that pub.dev is rewriting the url to point to master instead of main, as mentioned previously.

I would think this might be fixed by now since main is practically the default these days 😉.

[chykon]

It's not entirely clear how the link for the "Example" tab is generated.

Some packages (eg https://pub.dev/packages/flutter_markdown) use the "main" branch, others (eg https://pub.dev/packages/path) use the "master" branch. Both in the first and in the second case, the correct branches are selected.

However, for my package (https://pub.dev/packages/utf8decoder_hw) "master" is used when it should be "main", which causes the "Branch not found, redirected to default branch" box to appear.

[isoos]

@chykon: We have an experimental analysis of git repositories enabled for select packages, and their analysis result are already showing the correct branch on pub.dev (e.g. flutter_markdown is one of them). We plan to enable it for the rest of the packages in the near future, but a few other steps are also needed for it first. Stay tuned :)

[tamas-p]

We do have a limited support for relative URL rewrites if the homepage/repository url is on GitHub or GitLab.

Is it documented somewhere? The official docs on Writing package pages still points out using absolute URLs (what we do not want - this whole issue is opened for that).

After experimenting with publishing some packages this wich (partly) works for me:

• Use master as your main branch (as pointed out by @isoos)
• If you use a monorepo each package has to have repository URL defined in pubspec.yaml in the following form: https://github.com/USER/PROJECT/tree/master/packages/PACKAGE_NAME (if you store your packages under the packages directory in the monorepo, change it to your path to the package otherwise)

These seem allowing pub.dev to rewrite the relative links in README.md files correctly even for packages hosted in a monorepo.

I wrote that it works partly because it only fixes the README.md files published to pub.dev, see images and links now rendered correctly:
https://pub.dev/packages/hisma
(when reported it was https://pub.dev/packages/hisma/versions/0.1.1+2)

BUT it does not fix the generated API reference docs: Those links does not seem to have any URL rewrites, they are left relative URLs as they were in the source README.md files:
https://pub.dev/documentation/hisma/latest/
(when reported it was https://pub.dev/documentation/hisma/0.1.1+2)

So, I am happy that all my README.md files with relative URLs in my monorepo are rendered correctly now on pub.dev, but it would be even better if someone could help how to have even the API references rendered correctly.

[isoos]

Is it documented somewhere?

Not yet. The repository verification has been implemented, and we are waiting for a rollout of sandboxed analysis (also implemented, but rollout is blocked by minor infrastructure questions). Once these issues are resolved, we will have the following:

• The repository verification will detect the default branch name, and the relative path of the package inside the repository.
• pub.dev will rewrite pubspec URLs and relative URLs (e.g. inside README.md) to use the verified repository location.

In short, it will work as you would expect without any extra effort on the developer's side, with any default branch name, or any location inside the repository. However, we ask for a bit more patience as the rollout of this happens slower than we have anticipated earlier.

[tamas-p]

@isoos In short, it will work as you would expect without any extra effort on the developer's side, with any default branch name, or any location inside the repository.

Will it also handle the generated API reference? Today it seems no rewrite happens there.

However, we ask for a bit more patience as the rollout of this happens slower than we have anticipated earlier.

Your work is appreciated. Better to make it right than make it fast.

[isoos]

Will it also handle the generated API reference?

Eventually it will. We have plans for it, and it should happen, but not in the immediate future.

[tenhobi]

I also have issues with relative images and found out that it forces the master branch instead of main (GH default).

I will just link this issue to #6382, as it might be part of it.

[isoos]

This is now obsolete, as we rely on the repository verification (if available) which also reports the default branch.