Skip to main content

Adding Icons to Docusaurus

· 4 min read

Icons

Instead of the links in the navigation bar that have text such as LinkedIn, I want to display the icon. I will show how I added icons to Docusaurus for Email, Twitter, Github, and LinkedIn. The method I use is self-hosting with Font Awesome - Web Fonts + CSS.

Font Awesome

First, we need to download the files. I am using the free web version.

Once downloaded, I move the web fonts into the Docusaurus src folder. For the CSS files, I put the files I want to use in root/src/css. Which files you place here will depend on what icons you are going to use. You have to include the fontawesome.min.css since it is the core styling file. I am using brands for the social media icons and solid for the email icon so I include those files.

root/src/css
├src
├─css
├───custom.css
├───fontawesome.min.css
├───brands.min.css
├───solid.min.css

You will need to decide which files you are going to use for your setup. You can also remove web font files that you are not using.

If you are using the classic theme in the docusaurus config file there is a reference to the default custom CSS file.

docusaurus.config.js
theme: {
customCss: require.resolve('./src/css/custom.css'),
},

This by default should already be part of the project and not commented out.

In the custom.css file, I add the following towards the top of the file:

root/src/custom.css
@import "fontawesome.min.css"; 
@import "brands.min.css";
@import "solid.min.css";

Instead of referencing the local files you could reference the files stored on a content delivery network

root/src/custom.css
@import url(https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.2.1/css/fontawesome.min.css);
@import url(https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.2.1/css/brands.min.css);
@import url(https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.2.1/js/solid.min.js);

Now I can reference this CSS in my project. I could add a Github icon here using the following:

<i class="fa-brands fa-github"></i>

I could also use the icons in blog posts and other parts of the site.

I want to use these in the navigation bar on the home page. To do that you need to add them to the docusaurus.config.js file under the themeConfig. I chose to only put them in the navbar but you can also use them in the footer.

docusaurus.config.js
themeConfig:
({
image: 'img/logo.png',
navbar: {
title: 'The DAX Shepherd',
logo: {
...
},
items: [
...
{
href: 'https://github.com/thedaxshepherd',
position: 'right',
'aria-label': "Github Repository",
className: 'fa-brands fa-github fa-2xl',
}
...
],
}
...
}),

Href is where we specify the URL outside of the website. Position determines whether it is on the left or right side of the navigation bar. Since I am using icons and not visible text I specify the aria-label for assistive technology.

The className is where we get to specify what icon and any properties such as size. fa-brands selects the brand family of icons. fa-github picks the specific GitHub icon we want and lastly fa-2xl increases the size of the icon. There are lots of options for styling such as size, rotation, and animate.

I follow this same method for the icons for Twitter ('fa-brands fa-twitter fa-2xl'), LinkedIn ('fa-brands fa-linkedin fa-2xl'), and Email ('fa-solid fa-envelope fa-2xl').

More than one way

There are many ways to add icons to the navigation bar of Docusaurus. The method above also allows those icons to be used elsewhere such as in blog posts or documentation. In the future, it would be a good exercise to switch to using the Font Awesome React components. Or use one of the other many ways such as embedding it into the CSS. In the future, I may try another method if for no other reason than it is a good learning experience.