Perplex

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

The layout proportions of the theme are based on the IBM Plex font family^*^. The design is best suited for technical content with mixed sections of text, code, and media.

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 available view-port 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. When the maximum font size is reached on wide screens, the layout becomes static and centered.

Raster images are transformed by default into a set of WEBP formatted size variants and only the near-optimal version for a given view-port and screen resolution is actually delivered.³

In case vector images (SVG) are small they are embedded inline to save a separate request. Icons are always embedded.

The whole layout responds to the zoom-setting of browsers or mobile devices when one of its four major breakpoints is reached.

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

Perplex styles the HTML generated by Hugo from Markdown files and frontmatter data with HTML/GoLang templates. This documentation is also a continuous visual test for the style sheet and the templates.

Based on Standardized Markdown

Markdown is simple and simply great. It allows authors to format their content with a few intuitive markup characters in plain text files. And this content can be rendered into reliable and clean code for different purposes.

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 with injected CSS-classes and a few Hugo shortcodes to generate more complex HTML structures.

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.

Resource parameters

contain meta-data information associated with page resources. They can trigger preprocessing steps for images, change the layout, and provide a caption for example.

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 writing 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.

Configured by data files

The complete navigation and all other page layout elements besides the content are controlled by meta-data parameters:

Site configuration

Parameters for the usual site administration are contained in Hugo’s site-wide configuration files. Parameters for the fine-grained configuration of modules reside in their own configuration files, which may be overridden by project files with the same name.

Page parameters

are set directly in the frontmatter of the Markdown files. Every content file starts with a data block, which is enclosed by three dashes ---.

---
YAML: YAML Ain't Markup Language™

What It Is:
  YAML is a human-friendly data 
  serialization language for 
  all programming languages.
---

The theme relies on YAML to format the data, because it has the widest support. The included skeleton templates for new content files – the archetypes in the project folder with the same name – are written in YAML.

But Hugo also processes meta-data formatted by TOML and JSON and can convert frontmatter data between these three formats.

Despite its successful efforts to make data formatting as simple as possible, YAML still needs to adhere to strict grammar. It’s sensitive to the correct indentation of the keys.

Perplex provides templates for Hugo’s new command for a successful start. Every new content file includes a working frontmatter block. All essential keys are present and many of their values are filled with reasonable auto-generated values or placeholders.

frontmatter for a documentation page for example contains usually around 15–20 entries, and we have to change or add only a few of them in the beginning.

In case of problems

There are two main repositories — one for the theme itself and one for the documentation.

Having trouble with the theme?

When you encounter a bug in the templates or miss some functionality, the repository for the theme is the place to report the problem. Have a look at the already existing issues, please. If your problem or proposal is not already listed, I’m grateful for a new issue report.

If you are not sure about the cause of your problem, you can also discuss it there.

Should you like to improve the functionality of Perplex yourself, you are very welcome!

Having trouble with the documentation?

When you miss some explanation or find a misleading one, you may visit the repository for the documentation. Again, have a look at already existing issues, please.

Should you stumble upon bad English, typos, or wrong phrases, please excuse me. I’m not a native writer of the English language, corrections are very welcome.