Display GitHub README screenshot stored in a different branch, both on GitHub and locally

Question

Update: This is the GitHub test repository for this question.

I'm storing a screenshot (screenshot.png) in a separate Git branch (assets), to be used in a README.md file (on the master branch).

To see the image on GitHub, I have to link to:

/../assets/screenshot.png

or

../assets/screenshot.png

However, this does not work when viewing the README file locally, the image is not displayed (such as when using the Markdown preview feature in VS Code or Atom).

I have even used the git worktree feature, to check out the assets branch in the assets subdirectory:

git worktree add -B assets assets origin/assets

so the directory structure is something like this:

.git
assets
assets/screenshot.png
README.md

This means that, in order to view the image locally in the README file, I have to link to

/assets/screenshot.png

or

assets/screenshot.png

How can I reconcile the two "worlds"?

Is there a way to link to the screenshot so it's always displayed, "whether I view the documentation on GitHub itself, or locally, using a different markup renderer"*?

Answer 1

No, this is not possible and you shouldn't expect it to.

You should make the assets folder a part of your main branch, or you should separate the two into different repositories, or something along those lines.

There is a good reason why GitHub serves this screenshot but that "good reason" is just a technical reason related to how GitHub serves content from your repository.

Let's look at the URL to your screenshot, as used in the served HTML from your main repository page:

https://raw.githubusercontent.com/devliber/ReadmeScreenshotBranch/assets/screenshot.png

As you can see, the name of the branch with the image is part of the URL. Let's try to hack the URL back to your README:

https://raw.githubusercontent.com/devliber/ReadmeScreenshotBranch/master/README.md

If you try this URL you will see that it shows your README file.

So the issue here is that your "hack" to get to the screenshot, from another branch, is that you get this URL:

https://raw.githubusercontent.com/devliber/ReadmeScreenshotBranch/master/../assets/screenshot.png

This resolves to the exact same URL as the first one i posted here and that is why you see the image.

However, if you check out branch X then you shouldn't expect any content from branch Y to be present in your working folder. It "works" on GitHub because of the way they serve content from your branches but it won't, and shouldn't work locally, except if you start checking out multiple branches using worktrees.