Add a custom icon to a link in the page content

[patricklafrance]

I would like to add a custom icon to a link in my page content. Is it possible?

It's possible for the navigation menu with the following page metadata:

---
icon: ./static/browserslist.svg
---

Also seems possible for a file link:

[!file icon="../static/retype-icon.svg"](/static/sample.txt)

Or a reference link:

[!ref icon="../static/retype-icon.svg"](/guides/getting-started.md)

But I can't find how to do it with a regular link in my page content.

I tried a few silly things:

[icon="./static/browserslist.svg" text="Browserslist"](https://browsersl.ist/)
[Browserslist](https://browsersl.ist/) { icon="./static/browserslist.svg" }
:./static/browserslist.svg: [Browserslist](https://browsersl.ist/)

But none is working.

Almost got it with an image component, but I am not sure how to set the required CSS class to center the icon and set the width and height:

![](./static/browserslist.svg) [Browserslist](https://browsersl.ist/)

Thank you!

[geoffreymcgill]

Give the following a try:

![](./static/browserslist.svg){style="width:24px; height:24px"}

[patricklafrance]

It's working thank you :)

Would you consider supporting content links with an icon in a future release? Similar to how it works for the File or Ref component.

[geoffreymcgill]

Would you consider supporting content links with an icon in a future release? Similar to how it works for the File or Ref component.

Yes, it's a good idea and adding functionality to the standard hyperlink Markdown element is not something we had thought about. As you proposed, the same syntax used with the file and ref components could work well:

[icon="./static/sample.svg" text="Sample"](../sample.md)

I'm logging as a feature request.

---

Just to extend on the suggestion above, the following syntax is currently possible:

![](./static/sample.svg){style="width:18px; height:18px; padding-bottom:2px;"}

Another option would be assigning a custom css class to the image:

![](./static/sample.svg){.icon-sample}

Then you can define that icon-sample class in the page or in a common css include:

<style>
.icon-sample {
    width: 18px;
    height: 18px;
    padding-bottom:2px;
}
</style>

Another option is adding the <style> block into the _includes/head.html file to make the css available on all pages of the project:

<!-- Add content to _includes/head.html to include here -->
<style>
.icon-sample {
    width: 18px;
    height: 18px;
    padding-bottom:2px;
}
</style>

Or, you can go even further by linking to a custom .css file from your _includes/head.html:

<!-- Add content to _includes/head.html to include here -->
<link href="/static/styles.css?v={{ nonce }}" rel="stylesheet">

styles.css

.icon-sample {
    width: 18px;
    height: 18px;
    padding-bottom:2px;
}

Hope this helps.

[geoffreymcgill]

After thinking about this a little more, I would rather not mess around with the standard Markdown hyperlink syntax, such as the above proposed syntax:

# Let's not do this...
[icon="./static/sample.svg" text="Sample"](sample.md)

Extending the existing :icon: syntax or adding a new [!icon <path>] component would be better.

Here are a few syntax ideas:

:<path>:
:icon <path>:
[!icon <path>]

with values...

:/static/sample.svg:
:icon /static/sample.svg:
[!icon /static/sample.svg]

This custom icon syntax would only render an inline icon, and no other capabilities, such as linking.

To create a link from the icon, wrap the icon in a standard Markdown link:

[[!icon /static/sample.svg]](sample.md)

[patricklafrance]

Indeed might be a better option!

Does wrapping the icon in a standard markdown link would handle the expected spacing between the icon and the link?

[geoffreymcgill]

Does wrapping the icon in a standard markdown link would handle the expected spacing between the icon and the link?

The goal would be to maintain the same sizing and spacing as using the current Octicon or Emoji icons. For example:

[:icon-rocket:](sample.md)