Internal links no longer working in README.md file

[HexadigmSystems]

Select Topic Area

Question

Body

Hi there.

Not sure if this is the correct category for my issue but recently the internal links in my README.md file stopped working for some reason, but only at GitHub's site. External links work correctly. When you click any internal link however nothing happens. Would anyone mind taking a quick at the README.md code here:

https://github.com/HexadigmAdmin/FunctionTraits

Almost all links in the file are internal and they do in fact work in a test repository I created under another GitHub account, as well as in several online markdown editors I've tried (that support links).

I'm relying on the <a name="Whatever"></a> tag to create the links, and the [Description](#Whatever) syntax to access them. I've even force pushed my repository more than once to see if I could somehow fix whatever might be causing the problem but I have no idea what's wrong.

Any help would be appreciated.

[OshekharO]

In markdown, you can create anchor links by using the following syntax:

Link Text

And then later in the document:

Note: Anchor name is case sensitive, and it should be unique within the document

Code: https://pastebin.com/AmH0NDiR

Hopefully this answer satisfy you.

[HexadigmSystems]

Thanks for the reply. That's what I am doing but as you can see if you try clicking any of the (internal) links here:

https://github.com/HexadigmAdmin/FunctionTraits

None of them work (go figure). Can you confirm that on your end (thanks!)

[OshekharO]

The issue here seems to be the use of /tree/main in the URL

When I visit: https://github.com/OshekharO/FunctionTraits/blob/main/README.md#Technique1Of2 it's working but not here: https://github.com/OshekharO/FunctionTraits/tree/main#Technique1Of2

Solution

• Technique 1 of 2
• Technique 2 of 2

@HexadigmSystems

[HexadigmSystems]

I really appreciate your assistance (thanks). Still at a loss to explain what's going on though or how to fix it (and it used to work so don't know what happened to break it). Not sure how you even created your 1st link with the "blob/main" subdirectory vs "tree/main" (and both links have since gone dead) but in any case, these are internal links (bookmarks) that should just resolve to the current page in theory (AFAIK), regardless of the underlying directory structure. At the actual site here https://github.com/HexadigmSystems/FunctionTraits there are no subdirectories so what should I be doing doing exactly to fix the problem?

Note that your "Technique 1 of 2" link for instance is (if you hover the mouse over the link):

https://github.com/HexadigmSystems/FunctionTraits/blob/main/README.md#Technique1Of2

And mine is:

https://github.com/HexadigmSystems/FunctionTraits#Technique1Of2

I'm not sure why they differ. Yours contains "blob/main" and README.md in the link, mine doesn't. I'm lost.

[OshekharO]

Maybe mone is different because it's a fork where your is original. But yeah now the solution remains same as what I have recommended temporarily.

Here is how I used internal linking: https://github.com/OshekharO/NewsFeedSwitcher

[HexadigmSystems]

Ok, thanks. I've since discovered that if I explicitly click the README.md file from the main page at:

https://github.com/HexadigmSystems/FunctionTraits

Then it takes me to:

https://github.com/HexadigmSystems/FunctionTraits/blob/main/README.md

So it matches yours and the links now work. The "Technique 1 of 2" link for instance is:

https://github.com/HexadigmSystems/FunctionTraits/blob/main/README.md#Technique1Of2

On the main page itself though that users actually visit at https://github.com/HexadigmAdmin/FunctionTraits, it's the same README.md file but when accessed from that page (instead of explicitly clicking README.md) the link now becomes:

https://github.com/HexadigmSystems/FunctionTraits/#Technique1Of2

That's an invalid internal HTML link normally AFAIK (it should resolve to blob/main/README.md#Technique1Of2 in this case) which is presumably why it doesn't work. So why is GitHub creating the link this way? Why doesn't it create the correct link. I have no idea how to fix this or why things used to work (I did a normal push a few days ago and the problem suddenly surfaced)

[HexadigmSystems]

As a brief follow-up, at your own site it's the same situation but yours works. For instance, explicitly click README.md and your "Usage" link resolves to:

https://github.com/OshekharO/NewsFeedSwitcher/blob/main/README.md#usage

The same link at https://github.com/OshekharO/NewsFeedSwitcher however is:

https://github.com/OshekharO/NewsFeedSwitcher#usage

Link still works. Mine (the equivalent) doesn't.

[OshekharO]

Maybe because I am using complete markdown layout, where you using html inbetween.

[HexadigmSystems]

Yes, I realized that after I posted. I've since submitted a ticket to GitHub support but since it's a free account I don't know if they'll respond, even though I flagged it as a possible GitHub bug. If it's not a bug then I don't know what the issue is. It definitely shouldn't be this complicated to correct though (have tried numerous things).

Unless you can think of anything else or someone else responds (I may repost at some point), I may eventually be forced to delete the repository and start again (and no idea if the problem will even go away).

Thanks for all your assistance though. Greatly appreciated!

[nophead]

The internal links on my GitHub ftont page readme.md have also stopped working recently. The only one that works starts with a number. The others seem to get rendered into the html with the wrong case. The same readme.md works if I click on it in the repository, it is just the rendering of it on the front page that is broken and this only happened in the last few weeks.

[HexadigmSystems]

@nophead

Thanks for the info. Exact same problem here. I've already been in touch with GitHub support and will forward your response as well. They were able to recreate the problem but it's not occurring in all environment they tried but it's occurring frequently enough. On my end it consistently happens on Windows 10 Pro every time, in all major browsers I tried, on Android, but surprisingly not Edge running on an Apple phone (go figure).

No promises from GitHub they said or or any timeline but they assured me it's now being investigated.

Thanks for the feedback.

[nophead]

I worked around the problem by converting all the anchors and hrefs to lowercase. Easy for me because my readme.md file is created by my own Python script. It is definitely a GitHub bug that they render the anchors in lowercase when they are in uppercase in the md file.

[HexadigmSystems]

@nophead Nice catch! Not sure what your reason was for checking that but it works. Will report it back to GitHub support.

For anyone else coming across this issue, until GitHub corrects the problem the issue is that in internal links like the following:

[My link text](#Whatever)

<a name="Whatever"></a>

#Whatever needs to be changed to lower case #whatever or the link won't (usually doesn't) work in the README.md file (depending on the user's environment), but only in the surfaced version of that file which GitHub shows on your repository's main landing page (as described here). When explicitly clicking the README.md file directly in the repository itself however and viewing it that way the issue doesn't exist. Until GitHub corrects the problem the above link should therefore be changed to the following:

[My link text](#whatever)

<a name="Whatever"></a>

Note that my (limited) testing shows that only #Whatever needs to be converted to lower case #whatever. In the anchor line itself "<a name="Whatever"></a>" the case of "Whatever" can optionally remain unchanged (its own case apparently has no impact on the issue).

[nophead]

The reason I spotted it is because I looked at the page source GitHub makes and notitced that my anchors had been totally re-written. In My source they where <a name= "Name"></a> but on the Github page they become

<a id="user-content-axials" class="anchor" aria-hidden="true" href="#name">
    <svg class="octicon octicon-link" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true">
       <path d="m7.775 3.275 1.25-1.25a3.5 3.5 0 1 1 4.95 4.95l-2.5 2.5a3.5 3.5 0 0 1-4.95 0 .751.751 0 0 1 .018-1.042.751.751 0 0 1 1.042-.018 1.998 1.998 0 0 0 2.83 0l2.5-2.5a2.002 2.002 0 0 0-2.83-2.83l-1.25 1.25a.751.751 0 0 1-1.042-.018.751.751 0 0 1-.018-1.042Zm-4.69 9.64a1.998 1.998 0 0 0 2.83 0l1.25-1.25a.751.751 0 0 1 1.042.018.751.751 0 0 1 .018 1.042l-1.25 1.25a3.5 3.5 0 1 1-4.95-4.95l2.5-2.5a3.5 3.5 0 0 1 4.95 0 .751.751 0 0 1-.018 1.042.751.751 0 0 1-1.042.018 1.998 1.998 0 0 0-2.83 0l-2.5 2.5a1.998 1.998 0 0 0 0 2.83Z">
       </path>
   </svg>
</a>

I made both the anchor and the link lowercase so that the readme works standalone. I.e. without GitHub forcing the ancor to be lowercase.

[HexadigmSystems]

Like I said "nice catch". I doubt I would have made the connection myself. I'm not an HTML specialist per se but do have my share of experience (I'm actually a C++ specialist) but would have thought it wouldn't make a difference. I think (AFAIK) HTML is normally case-INsensitive even though lowercase is the convention. Not sure why any modern day browser would have an issue over the case-sensitivity of links. GitHub is free to dynamically create the HTML pages anyway they choose and it's still not entirely clear to me why it's failing (just because of the case).

It's theirs to investigate and fix though. Just glad I can temporarily fix it thanks to your help.

[LexProfi]

They still don't work. Even on regular files inside the project. :(

[HexadigmSystems]

@LexProfi Haven't tested it since originally reporting it here, and I also reported it to GitHub support (I don't think it went anywhere), but using lowercase as discussed in this thread works. I'd prefer for GitHub to fix (or at least address) the issue but likely very low priority for them (if it hasn't been fixed as you say - probably won't be at this stage).

[Hritik-Kumar-dev]

when use anchor tag it also adds a blue underline of which there is no any method to bypassing in gitHub

[Ma-XX-oN]

What is GitHub's reasoning for mandating that all links MUST BE LOWERCASE? It is excessive and unnecessary.

[Talha-Dogan]

You are spot on about the case-sensitivity issue.

Just to add clarity on why this happens: GitHub's Markdown rendering pipeline (GitHub Flavored Markdown) actively sanitizes HTML input. During this process, it often normalizes name and id attributes to lowercase to ensure consistency and prevent conflicting anchor links.

So, when you write:

GitHub renders it to the browser as:

However, your link Link tries to find the ID #Whatever (case-sensitive), but only #whatever exists in the final DOM.

Best Practice: Always use lowercase and kebab-case (hyphens instead of spaces) for manual anchors in GitHub READMEs to avoid these rendering discrepancies.

Markdown

Go to Anchor