Icons

Heyo Docs uses semantic icon names instead of bundling a specific icon library. Each generated application imports the icons it wants, then supplies a local mapping to DocsApp. This keeps unused icon packs out of the browser bundle and lets a project adopt its preferred visual style.

The heyo-landing React Router example maps Remix Icons in app/heyo-docs-icons.tsx.

Use semantic names in configuration

Pass a semantic name to a group or section:

export default heyoDocs({
  content: "content",
  groups: [
    {
      group: "Documentation",
      icon: "globe",
      sections: [{ section: "Get started", icon: "book", pages: ["index"] }],
    },
  ],
});

Names are normalized, so gitRepository, git-repository, and Git Repository resolve to the same semantic icon. An unknown name or a name without a mapped component intentionally renders no icon.

Available names

These are the semantic names recognized by the current Heyo Docs runtime:

The runtime itself uses several of these names for controls such as search, navigation arrows, the color-mode toggle, and copy actions. Retain those mappings when replacing the icon family.

Replace the icon family

Open the application icon file, replace its imports, and preserve the semantic keys:

import { RiBookOpenLine, RiGlobalLine, RiLoginBoxLine } from "@remixicon/react";
import type { IconSet } from "@heyo-sh/heyo-docs";

export const iconSet = {
  book: RiBookOpenLine,
  globe: RiGlobalLine,
  signIn: RiLoginBoxLine,
  // Keep the remaining semantic mappings from the generated file.
} satisfies IconSet;

The generated file uses satisfies Required<IconSet> so TypeScript confirms that all built-in controls are covered. Keep that stricter form in a real application and replace every existing component with its equivalent from the new library.

The framework-specific mapping files are:

Add a new semantic capability

Configuration accepts strings, but the runtime only normalizes the semantic names listed above. A new semantic name requires a Heyo Docs source change: extend SemanticIcon and its alias map, then add the matching icon component to each application mapping. This is intentional; a random configuration string cannot cause an arbitrary icon package to be included in the client bundle.

For one-off visual decoration inside an MDX article, use an ordinary MDX or React component instead of expanding the global semantic icon contract.

Check icon-only controls

After changing a mapping, test the mobile menu, search, section chevrons, theme toggle, code-copy button, and footer links. Semantic mappings give those controls consistent icons, while their accessible labels are supplied by the UI itself.