Index Icons

You can give any element in your documentation index an icon, and your readers see it next to that entry in the navigation sidebar. Icons work well as landmarks for the few entries readers look for most, such as a quick start, a changelog, or a link out to your status page.

Adding an Icon

• In the documentation index, hover the entry and click on the menu icon next to it.

• Select Add Icon . If the entry already has one, the item reads Change Icon.

• Choose an icon, then click Save.

Pages, categories, labels, and external links can all carry an icon. Separators cannot.

Choosing an Icon

The dialog offers two sources, and an entry uses one or the other. Picking from the icon set replaces an uploaded image, and uploading an image replaces a picked icon.

Font Awesome

Search the built-in set under Choose an icon, or browse the results grid. The tabs across the top switch between the Solid, Regular, and Brands styles.

DeveloperHub loads Font Awesome 7 Free, which is 2,157 icons across those three styles. The Pro styles (Light, Thin, Duotone, and Sharp) are not included. To browse the same set visually before you search, use Font Awesome's own search with the Free filter on.

Searching understands the older Font Awesome 5 names too, so typing times, cog, or search still finds xmark, gear, and magnifying-glass.

Uploading an Image

Click Upload an image to use your own artwork instead, which is the way to put a product or partner logo in the index. Use a square SVG or PNG of at least 32×32, since the icon renders at 15×15 next to the entry title. Uploaded images keep their own colours and are never tinted.

Removing an Icon

Open the menu icon next to the entry, select Change Icon, click Remove, then Save.

How Icons Affect the Index

Icons are designed to be used sparingly, so the index stays readable when only a few entries carry one.

As soon as one entry has an icon, a narrow slot is reserved for it on every entry in that documentation, and titles line up along a single edge. Entries with no icon leave the slot empty rather than showing a placeholder, which is what lets the icons you did set stand out. Categories reserve their slot separately, so giving your pages icons does not shift your category headings.

If you remove the last icon in a documentation, the slot disappears and the index returns to its previous layout.

Icons in a Synced Repository

In a GitHub-synced project, icons live in the documentation's _nav.yaml, not in page frontmatter. The icon key sits beside the entry's own key:

Write the value in one of these forms:

• Solid: the icon name on its own, such as rocket. There is no fas: prefix; solid is the default style.

• Regular: prefix with far:, such as far:bell.

• Brands: prefix with fab:, such as fab:github.

• An image: the full https:// URL of the image. Relative paths and protocol-relative URLs are not accepted.

A page normally appears in _nav.yaml as a bare path such as - introduction. It expands to the page: form only when it carries an icon, so adding this feature does not rewrite the navigation of repositories that use no icons.

For a link entry, note that icon is a sibling of link, not one of the fields inside it.

Your repository is the source of truth for icons, as it is for the rest of your navigation. Deleting an icon line removes the icon from that entry on the next sync.

Icons set on a page are carried over when you duplicate the page or clone the version.