How to add a "share link to this page", especially for private GitLab/GitHub pages sites?

[ryran]

When deploying a private project to GitLab Pages, the site_url redirects to a random URL in order to force you through authentication. In the end, instead of landing on a site like:

https://group.pages.example.com/project

... you end up at something like:

https://project-group-fd7c2d0a7d761b2fe7722c69fad518f193fd3bb5b95f1dc1afdc3.pages.example.com

I want to make it easier for folks to share the (shorter) canonical URLs to pages (i.e., https://group.pages.example.com/project/Some page/ does properly redirect and would be preferable to the much longer URL users will see in their browser bar) so I was wondering if anyone could point me in the right direction to add a share button that could put the correct URL (of the current page) into the clipboard. (Presumably with JS snippets? I know nothing.)

In a perfect world, I would imagine said button going right next to the two code actions view/edit buttons but I'm open to anything.

[kamilkrzyskow]

Hello @ryran,
I'm a bit confused, as site_url is a setting in the mkdocs.yml: https://www.mkdocs.org/user-guide/configuration/#site_url
and it is set as the canonical link of the site 🤔 but here you refer to site_url as the address the user uses to access the page, witch then redirects to a GitLab authentication login page, and from there the login page redirects to a secret link.

Once the user authenticates the login and gets redirected to the private link, can they go back to the "public" link and stay there without authentication?

From your example I surmise that

https://{group}.{pages}.example.com/{project}

is converted to the other one with the same parts + the commit hash:

https://{project}-{group}-<commit-hash>.{pages}.example.com

So if you don't have access to the <meta canonical> address based on the site_url setting, then you should be able to extract it via regex.

---

As for the button next to the code actions, in the Gothic Modding Community we've added a button for translations, you can see the code here (don't mind the comments, they're outdated...), the function is executed in the "DOMContentLoaded" event here, we don't use navigation.instant, you probably will have to adjust the logic if you do. The button's contents are set before the script runs in the main.html override in the scripts block here

As for the copy to clipboard logic, I believe this will suffice: https://developer.mozilla.org/en-US/docs/Web/API/Clipboard/writeText
Though the topic seems to be a bit convoluted after a quick search online, so I'm not sure, as I never done it myself.

---

I guess, another approach to this is to change the link in the URL address bar after the page was loaded. I believe there is a way to change the URL with JavaScript without reloading the page: https://developer.mozilla.org/en-US/docs/Web/API/History/replaceState
Maybe I even used it at some point somewhere, but can't recall 😅

---

Also like mentioned in:

• When using content.action.view in theme.features with GitLab, how can I make it go to blob/ instead of raw/? #6850

you can override the actions.html template partial to directly generate the HTML for the share button in the "back end", without any JavaScript.

[ryran]

DUDE! This is brilliant! I was really intimidated, but after half an hour of digesting what you shared and combining your two comments and playing with it, I got this:

const site_url = "<insert site_url from mkdocs.yml here>"
const canonicalLink = `${site_url}/` + location.href.split("/").slice(3).join("/");

var buttonContent = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M16.5 12c0-.68-.06-1.34-.14-2h3.38c.16.64.26 1.31.26 2 0 .37-.03.73-.08 1.08.69.1 1.33.32 1.92.64.1-.56.16-1.13.16-1.72 0-5.5-4.5-10-10-10C6.47 2 2 6.5 2 12s4.5 10 10 10c.59 0 1.16-.06 1.72-.16A5.9 5.9 0 0 1 13 19c0-.29.03-.57.07-.85-.32.63-.67 1.24-1.07 1.81-.83-1.2-1.5-2.53-1.91-3.96h3.72a5.95 5.95 0 0 1 2.59-2.4c.06-.53.1-1.06.1-1.6M12 4.03c.83 1.2 1.5 2.54 1.91 3.97h-3.82c.41-1.43 1.08-2.77 1.91-3.97M4.26 14C4.1 13.36 4 12.69 4 12s.1-1.36.26-2h3.38c-.08.66-.14 1.32-.14 2s.06 1.34.14 2H4.26m.82 2H8c.35 1.25.8 2.45 1.4 3.56A8.008 8.008 0 0 1 5.08 16M8 8H5.08A7.923 7.923 0 0 1 9.4 4.44C8.8 5.55 8.35 6.75 8 8m6.34 6H9.66c-.1-.66-.16-1.32-.16-2s.06-1.35.16-2h4.68c.09.65.16 1.32.16 2s-.07 1.34-.16 2m.25-9.56c1.84.63 3.37 1.9 4.33 3.56h-2.95a15.65 15.65 0 0 0-1.38-3.56M23 18v2h-3v3h-2v-3h-3v-2h3v-3h2v3h3Z"/></svg>';

var anchor = document.querySelectorAll("a.md-content__button")[0];

var newAnchor = document.createElement("a");
newAnchor.id = "special-share-button";
newAnchor.classList = anchor.classList;
newAnchor.innerHTML = buttonContent;
newAnchor.title = "Copy canonical page URL to clipboard";
newAnchor.dataset.clipboardText = canonicalLink;
anchor.parentElement.prepend(newAnchor);

I had no idea I could do things like that directly in the devtools console. So cool!

If you (or anyone else reading) would be so kind, I have a few questions:

1. When I add this code to my extra.js and rebuild my site, the button shows up on page load and it works; however, it behaves slightly differently than it does when I add the code live via dev console: upon clicking the button, the "Copied to clipboard" tooltip only shows for a split-second because the page actually reloads. Kind of annoying. Any tips?
2. The icon Kamil chose matches beautifully with the other two (view/edit) icons, but I'd like to try something that might be more obvious, like 🔗 ... I've never played with defining SVGs in this way before, but I found icon-sets.iconify.design/octicon/link-16/ and removed the width/height + modified the viewBox to match what Kamil provided ... so came up with:

   var buttonContent = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="m7.775 3.275l1.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 0a.751.751 0 0 1 .018-1.042a.751.751 0 0 1 1.042-.018a1.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-.018a.751.751 0 0 1-.018-1.042m-4.69 9.64a1.998 1.998 0 0 0 2.83 0l1.25-1.25a.751.751 0 0 1 1.042.018a.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 0a.751.751 0 0 1-.018 1.042a.751.751 0 0 1-1.042.018a1.998 1.998 0 0 0-2.83 0l-2.5 2.5a1.998 1.998 0 0 0 0 2.83"/></svg>';

... which looks like this:
How can I fix that to match? (I.e., to be bigger and centered instead of small and floating up high.)

3. Is there a more efficient way to load the icon from mkdocs-material's bundled icons or is this the best bet?
4. How could I make the new icon show up to the left of the existing ones, instead of the right?

[kamilkrzyskow]

Great progress! I'm happy you finally see the power of Dev Tools prototyping. It has its limits like you've observed, but it is very handy.

Great idea with the site_url to use it as canonical yourself, I don't remember if it's available in JS by default, but you could definitely add it in main.html yourself, so extra.js always stays is sync with mkdocs.yml.

Also looking at it now location.href seems too simplistic, there are other location properties:
https://developer.mozilla.org/en-US/docs/Web/API/Location#instance_properties
so perhaps there is no need to slice the link yourself.

Also use var only while prototyping, as it's less strict, final code should use let or const.

As for the points:

1. Change the document.createElement("a"); to "button", as anchor is used to link to other sources that would warrant a "reload".

2. The icon I've provided comes from the main.html override as I mentioned before:
   https://github.com/Gothic-Modding-Community/gmc/blob/1014dd00e7ae5c7de96408a12c1a71e54c8dd6b2/overrides/main.html#L79
   I add the <script> tag within the announce block, which is rendered at the top of the HTML source, so the global variable in that script tag is then visible in the extra.js at the bottom of the HTML source.
   If the announce block is overriden, it does add some more things to the HTML page, and adds more padding so maybe use another block, even the scripts block will do just add the {{ super() }} at the bottom after the added icon.

   Basically you serach for the emojis / icons here: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/
   Then the emoji you want :material-web-plus: becomes the ".icons/material/web-plus.svg" path.

   If you don't want to include the SVG dynamically in the main.html, but want to include it in the extra.js, then you can access the SVG's here: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
   Just edit them as text and copy.

3. As explained in 2.

4. I think you only have to change anchor.parentElement.prepend(newAnchor); to parentElement.append

[ryran]

• > Also looking at it now location.href seems too simplistic, there are other location properties
  Sweeeet! That's even better.

• > Also use var only while prototyping, as it's less strict, final code should use let or const

• > even the scripts block will do just add the {{ super() }} at the bottom after the added icon
  Thank you for that explanation. Doing the following allowed my js to set newAnchor.innerHTML to OCTICONS_LINK_16_SVG:

  <!-- main.html -->
  {% block scripts %}
      <script>
          const OCTICONS_LINK_16_SVG = '{% include ".icons/octicons/link-16.svg" %}';
      </script>
      {{ super() }}
  {% endblock %}

• > 4. I think you only have to change anchor.parentElement.prepend(newAnchor); to parentElement.append
  Good idea. I tried that but it did this:
  

  That said, it's the least of my worries. I can let that go. :-)

• > 1. Change the document.createElement("a"); to "button", as anchor is used to link to other sources that would warrant a "reload".
  Such a simple fix! Making that change prevents the reloading; however, it also disables the hover colorization that was being done, which nicely matched the other icons. I decided to see what chatgpt had to say and it started out OK:

  The page reloads when the user clicks the button because, by default, clicking an <a> (anchor) element may navigate to the href attribute's URL or, if href is not specified, may cause the page to reload. In the JavaScript code you've provided, there's no href attribute explicitly set on the new anchor (newAnchor) element, which leads to the default behavior of reloading the page when it's clicked.

  ... but then it when into a really convoluted solution that involved an event listener which I think is incorrect, based on what you already shared. Any ideas?

EDIT: Using newAnchor.href = "#"; in concert with document.createElement("a") gives the color onHover and avoids the full reload, so that's kinda cool. Of course, if you've already scrolled down a little when you click the button, it pushes you back to the top, but that's OK.

[ryran]

Here's the final solution which I'll mark as answer, but it must be made clear that this would never have happened without the help from @kamilkrzyskow so they should get all the credit for this thread. 🙏

overrides/main.html:

{% extends "base.html" %}
{% block scripts %}
    <!-- Save :octicons-link-16: to var for use by extra.js -->
    <script>
        const OCTICONS_LINK_16_SVG = '{% include ".icons/octicons/link-16.svg" %}';
    </script>
    {{ super() }}
{% endblock %}

docs/javascripts/extra.js:

// The following block adds a new button next to the buttons described at https://squidfunk.github.io/mkdocs-material/setup/adding-a-git-repository/#code-actions
// The new button copies the current page URL to clipboard
// Customization required:
//   - this depends on "OCTICONS_LINK_16_SVG", which is set in main.html
//   - this depends on "site_url" from mkdocs.yml

const site_url = "https://insert site_url here"
const anchor = document.querySelectorAll("a.md-content__button")[0];
const newAnchor = document.createElement("a");
newAnchor.id = "copy-canonical-url-button";
newAnchor.href = "#";
newAnchor.classList = anchor.classList;
newAnchor.innerHTML = OCTICONS_LINK_16_SVG;
newAnchor.title = "Copy canonical page URL to clipboard";
newAnchor.dataset.clipboardText = site_url + location.pathname;
anchor.parentElement.prepend(newAnchor);

// The following binds the lowercase "L" key to the above button
// So anywhere on the page, you can press "l" and it will copy the current URL, including the heading
// (Including the heading probably requires you have anchor tracking enabled -- see https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/#anchor-tracking)

keyboard$.subscribe(function(key) {
  if (key.mode === "global" && key.type === "l") {
    newAnchor.href = location.hash || "#";
    newAnchor.dataset.clipboardText = site_url + location.pathname + location.hash;
    newAnchor.click();
    key.claim()
  }
})

[ryran]

Caution

The above approach to adding a button is not compatible with mkdocs-material's navigation.instant feature. If you enable this feature, clicking the button works 1 time, but then makes the button disappear.

If anyone has tips for how to modify the code to make it work with instant navigation, please speak up! 😄

[alexvoss]

With instant navigation you would likely need to make sure that your code runs whenever the content is loaded. It seems like scripts that are part of the page are being evaluated but the code from extra JavaScript files is not? That might make sense in many cases but in this case it would be necessary to have some sort of callback when the new page is loaded so that the setup code could be run again.

Am I holding the wrong end of the stick here, @squidfunk?

[kamilkrzyskow]

Great work ryran! Your answer is rightfully marked as the answer, and I appreciate the attribution. Don't know about your team's policy, but would be great to see this discussion linked in a comment next to the solution or the commit message/description ✌️

4. I think you only have to change anchor.parentElement.prepend(newAnchor); to parentElement.append
   Good idea. I tried that but it did this:

Bummer, I should've checked the structure without guessing blindly, sorry. The parent element is the article itself so appending does add the element at the end of it.

So one way to do it would be to use:
https://developer.mozilla.org/en-US/docs/Web/API/Element/nextElementSibling
https://developer.mozilla.org/en-US/docs/Web/API/Element/insertAdjacentElement

Another guess 😃

let anchor = document.querySelectorAll("a.md-content__button")[0]; // Could also be just 1 for the second button, but perhaps you'll turn off 1 of the 2, so better be safe than error.
const sibling = anchor.nextElementSibling;
if (sibling.nextElementSibling.classList.contains("md-content__button")) {
    anchor = sibling;
}
// ... Logic for the button creation
anchor.insertAdjacentElement("afterend", newAnchor);

---

however, it also disables the hover colorization that was being done

Another bummer, so additional CSS is needed to add the coloring, also kind of embarrassing I forgot something so elementary as setting the # on the anchor tag. Fortunately AI came to the rescue.

---

const site_url = "https://insert site_url here" this could also be set in main.html to be dynamic, as said before. So set a global like the SVG with {{ config.site_url }}.

---

Your final solution also seems to be written directly in the extra.js file at the top root level, is that right?
You should put the reusable things in a function and then call it in an event "DOMContentLoaded" if not using navigation.instant.
I mentioned before that my solutions don't work for navigation.instant, as I don't optimize for it.
But you just need to use the document$ observable to know a document was loaded. Here is one answer that could be used as reference:

• Why the custom cookie banner sticks with the page when you click sub-headings? #6788 (reply in thread)

[squidfunk]

With instant navigation you would likely need to make sure that your code runs whenever the content is loaded. It seems like scripts that are part of the page are being evaluated but the code from extra JavaScript files is not? That might make sense in many cases but in this case it would be necessary to have some sort of callback when the new page is loaded so that the setup code could be run again.

Correct. Anything added to extra_javascript is evaluated only on the initial page load, as this is primarily meant for libraries. script tags inside Markdown are evaluated each time the page loads. As @kamilkrzyskow pointed out, just wrap the code with the document$ observable to integrate with instant navigation:

document$.subscribe(() => {
  // Executed on navigation event, also triggered on the initial load
})