Github Markdown Heading Anchors

gistfile1.md

Anchors in Markdown

To create an anchor to a heading in github flavored markdown. Add - characters between each word in the heading and wrap the value in parens (#some-markdown-heading) so your link should look like so:

[create an anchor](#anchors-in-markdown)

Consider HTML <tr id="XXX">…. Then a link to #XXX is a link to that whole row. Clicking on a <a href="#XXX">to XXX</a> causes the whole row to be on the screen, if possible the top pixel of the row at the top of the screen (not always possible if row near end of page). This is good.

In Markdown, putting | <a name="XXX"></a> … |, and clicking on [to XXX](#XXX) jumps to the middle of the row, at least if there is an image in the row. The top half of the row isn’t visible: above top of viewport. This is not good.

Please, is there a known solution?

Jacks and Numbers
One
Two
Three
Four
Five
Six
Seven
Eight
Nine
Ten
Eleven
Twelve
Thirteen
Fourteen
Fifteen
Sixteen
Seventeen
Eighteen
Nineteen
Twenty
TwentyOne
TwentyTwo
TwentyThree
TwentyFour
TwentyFive
TwentySix
TwentySeven
TwentyEight
TwentyNine
Thirty
ThirtyOne
ThirtyTwo
ThirtyThree
ThirtyFour
ThirtyFive
ThirtySix

Solution found.
• The large image cannot be a link (which is what confounded me).
• Then wrap the <a names="…">…</a> around the image.

Just wanted to leave a note that this approach does have accessibility/semantic issues (ref: https://developers.google.com/style/headings-targets).

Unfortunately, Github does currently not support the extended markdown syntax heading-ids (e.g. ### My Heading {#my-heading-id}), so the most accessible approach would be to use the HTML equivalent <h3 id="my-heading-id">My Heading</h3> instead.

I needed a quick Markdown TOC generator that would be compatible with GitHub, so I made my own: gh-toc.

It’s basically a web page with some JavaScript: You paste in your Markdown and it generates a GitHub-compatible Table of Contents. Your browser does the work and nothing gets sent to the Internet.

Features:

• Full Unicode support, all international characters.
• Better handling of (hopefully) all underscore cases.
• Correct handling of code with backticks ` inside.
• Much better code block support (backticks, tildes, differing number of them).
• YAML front matter support.
• Optional output of the full Markdown file, ToC inserted between <!-- ToC begin --> and <!-- ToC end --> HTML comments, instead of just the ToC.
• Optional named anchor generation for each ToC element (not needed for GitHub use).
• Optional use of id instead name attribute in generated anchors.

Markdown test file included.

thank you