Perplex is a Hugo theme for documentation and multi-purpose websites that combines a fluid-responsive layout with self-hosted resources for fast, legible publishing. It takes Markdown content and renders it into static HTML with a typographic design based on classic principles, running on the extended edition of Hugo for WEBP support. The theme is open source, maintained by bowman2001 in the GitHub repository bowman2001/perplex, and ships with an exampleSite folder to get started quickly.
What is Perplex?
Perplex is a Hugo theme designed to publish technical content such as documentation, news, blog posts, and articles with a strong emphasis on legibility and performance. It takes Markdown content as input and produces a static site with a fluid-responsive layout grid, automated navigation, and optimized images. The theme requires a recent extended Hugo version and generates all page types (docs, blog, news, author pages, card previews) consistently.
Key Features
- Fluid-responsive layout grid — All page types share one coherent grid that adapts to screens, and the typographic design follows classic legibility principles.
- Three-level documentation — The theme generates large documentation sites with up to three menu levels in the sidebar, plus breadcrumbs for orientation.
- Automated navigation — Site menu, sidebar menu, taxonomies, page-to-page links, and breadcrumbs are all generated from frontmatter data, eliminating manual menu setup.
- WCGA-compliant color schemes — Light and dark modes follow the operating system setting, with color contrast complying with WCGA standards; the default scheme is a separate CSS file you can replace.
- Optimized image pipeline — Images are preprocessed, variants are generated, and delivery uses Lazysizes with no layout shifts; the theme also handles WEBP support via extended Hugo.
- Icon sets — Google Material Symbols and Simple Icons can be included by identifier, with Material Symbols automatically appearing in all documentation navigation elements; both sets work in Markdown via shortcodes.
- Optional self-hosted search — Full-text search indices are prepared with Pagefind, but the open-source node package must be installed to generate them.
Who is it for?
Technical writers who build extensive documentation with multiple menu levels and want automatic navigation and breadcrumbs. Bloggers and news editors who need a legible reading experience, author pages, and a news stream. Teams that prioritize speed and cost-effectiveness by self-hosting all assets (fonts split into small packages, icons embedded inline) to minimize bandwidth and hosting fees. Developers new to Hugo can copy the exampleSite folder to start a project without additional software.
What can you do with Perplex?
- Documentation maintainers: structure technical docs up to three levels deep with sidebar navigation, breadcrumbs, and page-to-page links.
- Blog authors: publish blog postings and build a news stream, with author pages automatically generated from frontmatter.
- Project teams: deploy a fast static site on Netlify (the Netlify status badge references a live deployment) without needing extra software beyond Hugo.
Pricing
Free — Perplex is open source and available on GitHub under the repository's license file.
FAQ
Does Perplex require a specific Hugo version?
Yes, the extended edition of Hugo is required, specifically for WEBP image support.
Can I use Perplex for a blog?
Yes, the theme generates blog postings, author pages, and a news stream in addition to documentation.
Does Perplex support dark mode?
It does, and the light/dark mode follows the operating system setting. Both color schemes comply with WCGA contrast standards.
Can I customize the color scheme?
Yes, the default color scheme is in a separate CSS file and can be replaced with your own.
Does Perplex include full-text search built-in?
The theme is prepared for Pagefind-based search, but you must install the Pagefind node package to generate the indices.
