The theme layout adapts responsively and fluid to modern screens. It’s designed for optimal legibility down to a view-port of 360px width.

Perplex is build on the basis of the IBM Plex font family* and best suited for technical content with mixed sections of text and code. The layout is vertically aligned to a baseline grid1 to introduce a comfortable reading rhythm. Horizontally it’s divided into evenly spaced columns — their number grows with the screen width.

On larger screens (view-port ≥ 600px) the responsive design is combined with view-port-sized design — a.k.a. fluid typography2. Hence, the layout is consistent between breakpoints. The layout gets fixed again and is centered on wide screens, before the font-size gets inconveniently large. The whole layout and its font-size respond to the zoom-setting of the browser.

Perplex styles the HTML generated by Hugo from Markdown content with YAML front-matter data through templates. This documentation also is a continuous test for the style sheet and the templates.

The modern stylesheet (CSS grid, flex, variables and calculations) works on browsers used by around 95% of the users in the world (as accounted by Can I Use).

Based on Standardized Markdown

Markdown is simple and simply great. It allows authors to structure their content with a few intuitive markup characters in plain text files. These structured files can be rendered into reliable and clean code.

Hugo’s default renderer Goldmark translates CommonMark Markdown and some extensions adopted from PHP Markdown Extra and GitHub flavored Markdown (GFM).

Because Markdown is simple, the resulting HTML also is. Sometimes we may like to change a style or use more complex elements. As of now, Perplex offers many attributes and a few shortcodes.

Alternative Styling and additional Elements

Attributes
are HTML attributes in single curly braces placed after Markdown elements. They are introduced on the pages of the specific element, whose appearance they alter, or in the chapter Attributes if they are of general use.
Replacements
are shorthands in single curly braces. They refer to the few less important inline HTML elements, which have no counterpart in Hugo’s Markdown.
Shortcodes
are enclosed in two curly braces and angle brackets — like {{< shortcode >}}. They can take input parameters and allow to extend Markdown with arbitrary HTML structures. They are powerful but tend to get complicated quickly. Perplex includes some shortcodes, but only in those cases, where a replacement or an attribute is insufficient. If Hugo already provides a built-in shortcode, its established syntax is preserved as good as possible.

Structured by YAML

The complete navigation and all other page layout elements besides the content are controlled by meta-data parameters. This documentation relies on YAML Ain’t Markup Language to format the data, because it’s well-known and has the widest support.

Site parameters
for every Hugo project are contained in the site-wide configuration.
Page parameters
are set directly in the front-matter of the Markdown files. Every file starts with a YAML block, which is enclosed by three dashes ---.

Despite its successful efforts to make data-formatting as simple as possible, YAML needs to adhere to strict rules which sometimes rely on the correct indentation. This may be frustrating for beginners. Perplex provides skeleton templates via Hugo’s new command. It generates files with a working front-matter block for every type of content. These YAML-blocks are filled with some reasonable auto-generated parameters or placeholders. The front-matter blocks for this documentation usually around 15-20 entries, and you probably have to change or add only a few of them in the beginning.

In Case of Problems

There are two repositories. One for the theme itself and one for the documentation. This documentation project ships with a recent copy of the theme to simplify the initial setup, but all work on the theme only happens in its own repository.

Trouble with the Theme?

When you find a bug in the layout or miss some functionality, please visit the theme repository. Have a look first at the already existing issues. Please create a new one, if your problem is not already listed. I’m happy to discuss issues there and maybe you like to help to optimize and extend Perplex.

Trouble with the Documentation?

When you miss some explanation or find a misleading one, please go to the documentation repository. Again, have a look at already existing issues, please. Only create a new issue, if you can’t find your problem. I’ll improve the documentation as soon as possible.

Should you stumble upon bad English, typos or wrong phrases, please excuse me. I’m not a native speaker, corrections are very welcome. You may submit a pull request immediately.


  1. The concept for a baseline grid has been inspired by Plumber. The vertical alignment is sometimes a few pixels off — despite precise calculations. This may be noticeable on screens with a low pixel density — usually desktop screens. All browser engines seem to face an inevitable trade-off between quality of font rendering and precision of line height. ↩︎

  2. The term fluid typography is falling a bit short here. Perplex is using a responsive fluid design, the whole layout can adapt to the width of the browser-window (Also see this posting). ↩︎