Skip to main content

FontAwesome

Font Awesome is the Internet's icon library and toolkit, used by millions of designers, developers, and content creators.

Using icons in your documentation is a great way to add visual interest and help users understand the content. Font Awesome is a great icon library you can use in your documentation. This article shows you how to use Font Awesome icons in your Docusaurus documentation site.

Docusaurus Documentation: MDX Component Scope

To complete these steps you will need to have a custom MDXComponents file. If you don't have one, just create the file MDXComponents.js or MDXComponents.tsx in the src/theme directory of your project.

Installing Font Awesome​

Font Awesome is available for React as a series of Node Package Manager (NPM) packages. To install Font Awesome, run the following command, this installs the Font Awesome core, and the free solid icons:

npm install --save @fortawesome/fontawesome-svg-core @fortawesome/free-solid-svg-icons @fortawesome/react-fontawesome

You can add the regular and brand icons by adding the following NPM packages:

npm install --save @fortawesome/free-regular-svg-icons @fortawesome/free-brands-svg-icons

You can add the Pro versions of any Font Awesome packages by configuring access to the Font Awesome NPM repository and installing the appropriate packages (for example @fortawesome/pro-solid-svg-icons).

Protect your NPM token

If you are using a private NPM repository, you should protect your NPM tokens.

If you're using npm you should use environment variables along with a .npmrc file to store your NPM token. For more information, see alternate per project setup using environment variable (for NPM).

If you're using yarn you should use environment variables along with a .yarnrc.yml file to store your NPM token. For more information, see per-project setup for modern Yarn.

Using Font Awesome with Markdown or MDX​

You can use Font Awesome icons in your Markdown or MDX files by exposing the FontAwesomeIcon component in MDXComponents. An example of this is below with added comments to aid understanding:

src/theme/MDXComponents.js
import React from 'react';
// Import the original mapper
import MDXComponents from '@theme-original/MDXComponents';
import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'; // Import the FontAwesomeIcon component.
import { library } from '@fortawesome/fontawesome-svg-core'; // Import the library component.
import { fab } from '@fortawesome/free-brands-svg-icons'; // Import all brands icons.
import { fas } from '@fortawesome/free-solid-svg-icons'; // Import all solid icons.

library.add(fab, fas); // Add all icons to the library so you can use them without importing them individually.

export default {
  // Re-use the default mapping
  ...MDXComponents,
  FAIcon: FontAwesomeIcon, // Make the FontAwesomeIcon component available in MDX as <icon />.
};

We can then use the icon component in MDX files:

docs/my-doc.mdx
---
title: My Doc
---

<FAIcon icon="fa-brands fa-github" size="4x" /> This is a GitHub icon.

Using Font Awesome with React​

You can use Font Awesome icons in your React components by using the FontAwesomeIcon component. Font Awesome have fantastic React documentation that you can use to learn more about using Font Awesome with React components.

If this is working you'll see a Font Awesome GitHub icon below: