I’m working on a GitHub wiki page and need to create links that jump to different sections within the same document. For example, I want to link from one heading to another heading on the same page.
# Main Topic
## Section A
This content should link to [Section B](#section-b) below.
## Section B
This section can link back to [Section A](#section-a) above.
I’ve also tried creating a table of contents approach:
# Main Topic
## Contents
- [Section A](#section-a)
- [Section B](#section-b)
## Section A
Content here
## Section B
More content here
Is this the correct way to handle same-page navigation in GitHub markdown? I know how to link between different files, but I’m specifically trying to navigate within a single markdown file.
yep, that’s right! pro tip: if your headings have weird characters or emojis, just hover over the heading on GitHub and copy the anchor link from your browser. saves you from debugging why #section-🚀-deploy doesn’t work (spoiler: emojis get stripped). works on gitlab and bitbucket too.
Your markdown syntax looks good, but here’s what’ll save you tons of time.
Creating and updating all those internal links manually is a pain when you’ve got multiple docs or make frequent changes. I spent hours fixing broken anchor links every time someone tweaked a heading.
Now I automate everything. I’ve got a workflow that scans markdown files, pulls out headings, and builds the table of contents automatically. It also checks that internal links actually work before they go live.
The automation handles those annoying edge cases too - stripping special characters, numbering duplicate headings, dealing with unicode issues. No more manually checking HTML or figuring out why links died after changing a heading.
I push changes to any of my docs and the links rebuild themselves. Saves me about 30 minutes weekly across projects.
Latenode makes this documentation automation really simple. Set it to trigger on repo changes and it handles the markdown processing without custom scripts.
Your approach is spot on for GitHub markdown linking. The #section-name format works great, but here’s what I’ve learned from using it:
GitHub converts headings to lowercase and swaps spaces for hyphens. Special characters get dropped, so “Section A (Important!)” becomes #section-a-important.
I’ve hit some inconsistencies with unicode characters and really long headings. When I’m not sure, I just inspect the HTML on GitHub to see the actual anchor IDs.
Watch out for duplicate headings - GitHub adds numbers like #section-a-1, #section-a-2.
For longer docs, I throw in “Back to top” links at the end of major sections using [↑ Back to top](#main-topic). Makes navigation way smoother. Your table of contents idea is solid - see it all the time in bigger documentation projects.
Internal linking in GitHub markdown works exactly like you showed. But here’s what trips people up - GitHub handles anchor IDs differently depending on where you are. Links that work fine in repository READMEs can break in wiki pages or GitHub Pages.
I found this out the hard way during a docs migration from repo files to wiki pages. The anchor generation was consistent, but my links broke because GitHub handles relative paths differently across environments. Always test your links where they’ll actually live.
Here’s a trick that’s saved me tons of headaches: manually add anchor tags for tricky headings. Just drop <a name="custom-anchor"></a> right before the heading when you need reliable anchor names. Gives you full control over the linking structure, especially when headings have numbers or special formatting that GitHub might mess up.
GitHub’s anchor linking works exactly like that. I use this method for work docs and it’s solid across all GitHub markdown renderers. Heads up though - GitHub strips out everything except letters, numbers, and spaces when making anchors. So “Section 2.1: Overview” turns into #section-21-overview. I throw a horizontal rule --- after my table of contents to separate it from the actual content. Keep your anchor text matching the heading text - saves headaches when you edit headings later. Scales great too. I’ve done 20+ section docs with zero browser performance problems.