GitHub style permalinks

[AshleighAdams]

So, I much prefer GitHub-style permalinks, where a chain icon floats to the left of the header, instead of the right.

I've looked for an easy solution over the months, hoping for a low hanging fruit, but unfortunately it looked too complex to invest time in, until, I discovered this site: https://facelessuser.github.io/pymdown-extensions/

They have some scss to append the chain from an SVG file, taking that as a base, and with a renewed resolve, I came up with this:

extra_css:
  - css/github-permalink-style.css
markdown_extensions:
  - toc:
      permalink: ''

.headerlink {
	--permalink-size: 16px; /* for font-relative sizes, 0.6em is a good choice */
	--permalink-spacing: 4px;

	width: calc(var(--permalink-size) + var(--permalink-spacing));
	height: var(--permalink-size);
	vertical-align: middle;
	background-color: var(--md-default-fg-color--lighter);
	background-size: var(--permalink-size);
	mask-size: var(--permalink-size);
	-webkit-mask-size: var(--permalink-size);
	mask-repeat: no-repeat;
	-webkit-mask-repeat: no-repeat;
	visibility: visible;
	mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg>');
	-webkit-mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg>');
}

[id]:target .headerlink {
	background-color: var(--md-typeset-a-color);
}

.headerlink:hover {
	background-color: var(--md-accent-fg-color) !important;
}

@media screen and (min-width: 76.25em) {
	h1, h2, h3, h4, h5, h6 {
		display: flex;
		align-items: center;
		flex-direction: row;
		column-gap: 0.2em; /* fixes spaces in titles */
	}

	.headerlink {
		order: -1;
		margin-left: calc(var(--permalink-size) * -1 - var(--permalink-spacing)) !important;
	}
}

Here's how it looks:

Full disclosure, I'm not experienced with HTML5/CSS, so I'm probably doing something wrong, so I can only provide the works-on-my-machine guarantee, sorry!

[squidfunk]

Thanks for sharing!

[AshleighAdams]

Just wondering in terms of that snippet, trying to make it less theme-specific, are you aware of a way to eliminate the magic number in the media query min-width: 76.25em?

[squidfunk]

Unfortunately, not possible, @custom-media is not (widely?) supported.

[AshleighAdams]

Updated it so it's mobile friendly, and reposition with flex instead of float on wider screens.

[MaximilianKohler]

For me, it changes the icon, but it's still on the right side. I'm not sure what to try/mess with?

Oh, I see it's a screen-width issue. It'll only do it on wide enough browsers.

[TRaSH-]

thank you so much for this, i was trying to figure out how to replace the weird icon to something better looking, need to get used to the option that the link is now before the title, but it's so much better looking then the default weird character

[santaimpersonator]

I found a simple workaround to use the built-in 🔗 icon (not sure if this is proper, but it works for me):

1. Add an admonition type
   mkdocs.yml (truncated)

   # Configuration for webpage theme
   theme:
     # Configures icons of admonition types
     icon:
       repo: fontawesome/brands/github
       admonition:
         # Add custom icon
         link: octicons/link-16

2. Referencing the icon similar to how it is done for custom admonition
   <filename>.css

    -webkit-mask-image: var(--md-admonition-icon--link);
            mask-image: var(--md-admonition-icon--link);
   /* mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg>');
   -webkit-mask-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="16" height="16" aria-hidden="true"><path fill-rule="evenodd" d="M7.775 3.275a.75.75 0 001.06 1.06l1.25-1.25a2 2 0 112.83 2.83l-2.5 2.5a2 2 0 01-2.83 0 .75.75 0 00-1.06 1.06 3.5 3.5 0 004.95 0l2.5-2.5a3.5 3.5 0 00-4.95-4.95l-1.25 1.25zm-4.69 9.64a2 2 0 010-2.83l2.5-2.5a2 2 0 012.83 0 .75.75 0 001.06-1.06 3.5 3.5 0 00-4.95 0l-2.5 2.5a3.5 3.5 0 004.95 4.95l1.25-1.25a.75.75 0 00-1.06-1.06l-1.25 1.25a2 2 0 01-2.83 0z"></path></svg>'); */

[AshleighAdams]

Just to note, I've updated the main post with a fix for title spacing with font changes, such as keywords being highlighted when searching

[gpdowney]

If you don't mind it being on the right-side, it also seems you can just add something similar to this to mkdocs.yml:

  - toc:
      permalink: '#'

Might be worth updating the docs on permalinks?

[alexvoss]

I may be holding the wrong end of the stick here but the documentation already mentions the possibility of adding a custom symbol? Switch to the tab with the anchor symbol. What does not work at the moment (I think) is to add an icon (rather than a unicode character) directly in the mkdocs.yml. At the moment, some extra.css would be needed as suggested above.

[gpdowney]

oh yikes, it sure is there and it's also in the mkdocs docs.

perhaps dummies like me would benefit from a slightly clarified description?

Proposed:

The permalink option adds an anchor link after each heading that appears on hover. If set to 'true' then it will default to ¶. Alternatively, it can be set to be another unicode string like '⚓︎' or '#' or even 'permalink'.

Existing:

This option adds an anchor link containing the paragraph symbol ¶ or another custom symbol at the end of each headline, exactly like on the page you're currently viewing, which Material for MkDocs will make appear on hover:

[PlasmaHH]

I used that to put the links on the left side and it works great, however I noticed that when usinig abbreviations (the *[XXX]: thing) ]the display:flex seems to cause some issues removing any spacing between the text and the <abbr> tag content... anyone ever saw that and maybe knows a fix? this goes over my css fu....

[alexvoss]

Can you perhaps post a screenshot, so we can see what you are seeing? You could also help us investigate the problem by creating a minimal reproduction.

[santaimpersonator]

Your issue is from copying the code above:

	h1, h2, h3, h4, h5, h6 {
		display: flex;
		align-items: center;
		flex-direction: row;
		column-gap: 0.2em; /* fixes spaces in titles */
	}

The combination of the display: flex;, flex-direction: row;, and align-items: center; attributes allow the permalink icon to be vertically centered with the header text despite the difference in font sizing. However, this also affects any formatting in the header text as well (i.e. the underlining from hyperlinks/abbreviations, superscript, subscript, etc.). Refer to this article for more information.

If you aren't familiar with CSS styling, I would suggest utilizing the default permalink extension for the MkDocs-Material theme instead.

[PlasmaHH]

Can you perhaps post a screenshot, so we can see what you are seeing? You could also help us investigate the problem by creating a minimal reproduction.

Creating a minimal example turns out to be harder than I thought (also because I am time limited) as this is multiple things working together, and I have quite a complex setup and failed to just create something and will have to work backwards from my existing one, once I have time. Thought I might give it a try here, since probably someone used the provided code already somehwere and might have hit the same.

The abbreviation functionality seems to transform the text the toc via javascript into the <abbr title="...">toc</abbr>...

So far I do partially workaround that by abbr { display: contents; } inside the h# css, but that kills the abbreviation functionalilty (not much of deal for me personally but not perfect either).

[PlasmaHH]

If you aren't familiar with CSS styling, I would suggest utilizing the default permalink extension for the MkDocs-Material theme instead.

For one I think that nobody knows 100% of css but they still should be allowed to use suggestions from other people and see if they work for them.

Also the point of this post and the mentioned css is to have the permalink show on the left of the heading. A prerequisite for this is to enable mkdocs permalinks in the first place, this just moves and styles them differently.

[do-me]

Thanks so much @AshleighAdams! I was looking for a solution as I still needed to keep the permanent links for convenience but we needed to remove the additional character as it was bad for SEO. Google would show Heading¶ in the search results. I think yours should be the default in mkdocs material.

[squidfunk]

Yes, I agree, it should be the default, but it must be the default in Python Markdown, which generates the HTML. We only render it and can't influence what Python Markdown generates – thus, I recommend taking this upstream to the maintainers of Python Markdown. If the permalink character would be supplied via a data-* attribute, we can easily use CSS to apply the styling.

[AshleighAdams]

I agree @squidfunk, my way is too much of a hack to be the default way. It works most of the time, and ironed out all of the issues I encountered, but it wouldn't surprise me if there is more hiding in there somewhere