Troubleshooting¶

Find fixes for common configuration and rendering problems. For supported versions and theme limitations, see Compatibility.

A component looks like plain text¶

Check the component guide for required extensions and indentation, and don't overwrite another markdown_extensions list. For tabs, set alternate_style: true. For Markdown inside an HTML wrapper, follow Scope selected instances.

A custom icon looks too small or like a filled box¶

Artwork with internal padding occupies less of the icon slot. Source and edit images are alpha masks: use transparent backgrounds. See Icons.

Source links point at the wrong branch¶

Set edit_uri explicitly for the branch and documentation directory. MkDocs' GitHub default uses master, not main. See Source and edit links.

Search has no results¶

Keep search in plugins, rebuild the site, and preview through mkdocs serve instead of opening built files directly with file://. Search requires JavaScript and its generated index. See Search for setup.

A bundled plugin is missing¶

Confirm that the environment running MkDocs has the expected Pixel Lab version installed. Use python -m mkdocs to select the active Python environment. See Bundled plugins for exact plugin names.