Perplex

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

Perplex is built based on the IBM Plex font family^* and is best suited for technical content with mixed sections of text, figures, and code. The layout is vertically aligned to a baseline grid¹ 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 typography². Hence, the layout remains consistent between breakpoints. At the maximum font size, the layout becomes static and centered on wide screens. The whole layout responds to the zoom-setting of browsers or mobile devices when one of its four major breakpoints is reached. Images are processed for an optimal resolution on every screen size.

Perplex styles the HTML generated by Hugo from Markdown content with YAML front-matter data through templates. This documentation is also a continuous visual 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. Perplex offers many style attributes to enhance the layout and a few Hugo shortcodes to utilize more complex elements.

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 lesser important inline HTML elements, which have no counterpart in Hugo’s Markdown renderer Goldmark. They are a simple workaround to avoid raw HTML in 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 ships with some shortcodes, but only for those cases, where a replacement or an attribute can’t do the job. 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 consisting of key-value pairs. This documentation relies on YAML Ain’t Markup Language (YAML) 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 still needs to adhere to strict grammar. It sometimes depends on the indentation of the keys and this can be a source of frustrating errors. Perplex provides templates for Hugo’s new command to help with that. For every type of content, we can easily begin with working front-matter blocks. All keys essential for Perplex are present and many of their values are filled with some reasonable auto-generated parameters or placeholders. Front-matter for a documentation page for example contains 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.

Having trouble with the Theme?

When you encounter a bug in the layout or miss some functionality, please visit the theme repository. Have a look at the already existing issues, please. If your problem or proposal is not already listed, I’m grateful for your new issue and happy to discuss it there. Should you like to improve the functionality of Perplex, you are very welcome.

Having 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. If you can’t find your problem, I’m thankful for your new issue and will 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 English speaker, corrections are very welcome. You may submit a pull request immediately.