Why are headings automatically creating links in GitHub readme.md markdown pages?

Question

Hello: I have created readme.md files for my repositories and GitHub pages. But when I create headings that are formatted h2/## or h3/###, etc. in-page anchor links are automatically created. I have tried different ways to format the headings -- such as ##, , --- -- but I get the same result. It occurs with each heading. This occurs in readme.md files that are in the repository and those that are converted to GitHub pages. I've tested it in chrome browser and edge browser and it's the same behavior.

# sample will create the heading and an unwanted in-page link

## sample will create the heading and an unwanted in-page link

Here's a page with the behavior: https://burrittresearch.com/

My goal is to be able to format headings in markdown without having these links automatically created.

Thank you!

Answer 1

Those are part of the anchorjs default CSS rules from GitHub pages

<h2 id="skills">Skills
  <a class="anchorjs-link" 
     href="#skills" 
     aria-label="Anchor" 
     data-anchorjs-icon="" 
     style="font: 1em / 1 anchorjs-icons; padding-left: 0.375em;">
  </a>
</h2>

If you static page (like this one ) include its own set of CSS file/rules (like those ones ), you could add, to make sure they are not visible:

.anchorjs-link {
  display: none !Important;
}

Answer 2

GitHub documents their markup processing in github/Markup . Note that Markdown is converted to HTML in step one, which does not add any anchors to headers. However, in step 4, which is separate from the Markdown parsing, all headers in the document have anchors added. This is done to all content, regardless of whether is comes from Markdown, ReStructured Text, textile, asscidoc, etc., and is not specific to Markdown.

Note that the above only applies to content supplied by users which is displayed on github.com. It is their site, which they control, so we don't get to change/override that behavior.

However, it is different with GitHub pages. By default, GitHub Pages uses Jekyll to convert Markdown files into HTML. Jekyll includes a number of options to control how Markdown is processed, including the auto_ids option. Turn that option off (set it to false), and Jekyll will no longer add IDs to every header. However, that is a Kramdown option, but, as I understand if, GitHub Pages uses the GitHub Flavored Markdown variant of Commonmark , which doesn't have any such options. For that matter, the GFM spec doesn't indicate that headers would be assigned IDs either (so I'm not sure where those IDs are coming from). You might try configuring Jekyll to use Kramdown with the auto_ids option turned off. Configuration options "can either be specified in a _config.yml or _config.toml file placed in your site's root directory."

As an alternative, you could install Jekyll (or any other static site generator ) locally and build the site before uploading to GitHub Pages. Simply include an empty file named .nojekyll in the site root and GitHub will not run your files through Jekyll. In this way, you get complete control over the content and formatting of the pages.