Blog | Perplex

event Nov 1, 2022

Code Layout

The main text column offers space for 80 characters of code in one line. When we need 120 to fit in one line, we can choose to additionally use the marginal column.

Short snippets of code are usually placed in line with the normal text. Longer pieces of code or entire files should be embedded as code blocks.

Hugo can style and colorize code blocks according to their content with the built-in Chroma highlighter and offers some options to style these blocks.

Syntax

Inline Code

A code snippet is surrounded by single backticks like `code`.

Code Block

We have two ways to mark a block as code:

Fenced: When a block is surrounded by three back-ticks ``` in the line above and beyond it’s a fenced code block.
Indented: A block of text indented by 4 spaces or a tab is also treated as a code block.

The fenced version of the CommonMark syntax is preferable for two reasons:

The following styling options are only available for fenced blocks:
1. Code highlighting
2. Line numbers
3. Line markers
4. Line anchors
There is an overlap with the syntax for the extensions footnote and definition-list. When we have subsequent paragraphs there, we need to indent them also by 4 spaces or a tab. If we try to place an indented code block after a footnote reference or a definition detail, Hugo will treat it as this kind of continuation indent and not as a code block.

Highlighting

Chroma can highlight many languages, when we add their usual file suffixes. The Hugo docs include the full list of available languages.

Additional styling for fenced code blocks

In contrast to other block elements the attributes follow the first fence of the code block on the same line after a space, like ```md {linenos=true}.

The options suitable for Perplex are:

linenos: Enables or disables line numbers. They are disabled by default for this project — enable them with linenos=true.
hl_lines: Especially highlights some code lines. The lines must be given as a set of numbers or ranges enclosed in square brackets. Every range has to be surrounded additionally by quotes: hl_lines=[2,"5-7"].
linenostart: Lets the line numbers begin with a given number, like linenostart=23
lineanchors: Adds a prefix to the anchors on the line numbers. With lineanchors=prefix for example the anchors are named prefix-1, prefix-2, …

The HTML tag to mark the beginning of code is <code>. And to mark the end we use the corresponding closing tag </code>. Markdown text surrounded by backticks like `text` gets enclosed by these tags.

Block

The first backticks marking a code block may be followed by an abbreviation for the code language. Then Hugo is able to highlight and colorize the source code for better legibility. The abbreviations are usually the same as the common suffix for a code file.

Fenced

Without line numbers

The *HTML* tag at the **beginning** of code is `<code>`.
And to mark the **end** we use the corresponding closing tag `</code>`.

With line numbers (table layout)

1
2

The *HTML* tag at the **beginning** of code is `<code>`.
And to mark the **end** we use the corresponding closing tag `</code>`.

Indented

The _HTML_ tag at the **beginning** of code is `<code>`.
And to mark the **end** we use the corresponding closing tag `</code>`.

Long lines

// NodeRendererFunc is a function that renders a given node.
type NodeRendererFunc func(writer util.BufWriter, source []byte, n ast.Node, entering bool) (ast.WalkStatus, error)

// A NodeRenderer interface offers NodeRendererFuncs.
type NodeRenderer interface {
 // RendererFuncs registers NodeRendererFuncs to given NodeRendererFuncRegisterer.
 RegisterFuncs(NodeRendererFuncRegisterer)
}

Normal consecutive text is transformed by the markdown renderer to a paragraph
block.

Every blank line indicates the beginning of a new paragraph.
> A blockquote is marked by a `>` at the beginning of every line
> of the quote. It may contain *text formatting* itself.

An unformatted text segment like this one is transformed by the markdown renderer to a paragraph block.

Every blank line indicates the beginning of a new paragraph.

A blockquote is marked by a > at the beginning of every line of the quote. It may contain text formatting itself.

When all lines are no longer than 40 characters

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 35,
  "profession": "Last Man Standing"
}

├── assets
├── config
├── package.json
├── public
├── resources
└── themes

- Content
- Markdown · Block · Inline · Image
event Aug 17, 2022
Two basic layout types
Valery Sysoev/ Unsplash
Markdown only two basic layout modes: inline & block. Before we think about applying others with an attribute or a shortcode, we need to understand them.
The distinction between those two in Markdown seems simple. Every block is surrounded by at least one blank line. Everything written on the same or the directly following line is inline — except lists and their items. We usually don’t need to think about layout modes and use them intuitively correct. One problematic element is the main reason to recall the distinction:
Inline elements
behave like characters and may be embedded in text. They are placed on the same line as long as there is any horizontal space left — and then the line wraps and so on. They may contain other inline elements — like a piece of code in emphasis for example. Inline elements shouldn’t include block elements, but they always need to be embedded in block elements.
It’s common practice to place an anchor-tag <a> around block elements to generate a linked page elements in HTML. But then, its display mode is explicitly changed into one with vertical spacing. This is impossible in Markdown.
Block elements
always completely fill the available width and may include additional vertical space. Block elements may contain other block elements or inline elements. A common example for the latter is a paragraph block, which fills at least one line, but may include an arbitrary amount of inline elements and text.
The Markdown image element is creating some confusion, because its an inline element. Because many images appear visually as blocks, we falsely tend to infer they should be block elements. But a Markdown image is always inline and embedded in an enclosing block. When its placed stand-alone on a separated line, its not only an image but enclosed in a paragraph block of its own.
To generate a stand-alone image resulting in semantically correct HTML, we need the figure shortcode. And we can easily add CSS-styles to resize or move the resulting figure — even beside the main text column.
- Theme
- Accessible · Fluid · Responsive
event Jul 12, 2022
Accessible Fluid Design
SVG by Pablo Busatto
There are some doubts about the accessibility of fluid typography among web developers. But websites with a responsive fluid design can behave especially user-friendly and accessible. This site is an example.
Fluid fonts solely depend on the width of the browser window or the view-port width of the mobile device. When a user changes the zoom-factor of his browser or his device, they are not affected at all. That’s the problem with fluid sized fonts. The solution is obvious: We need to change their value accordingly, when we change the layout responsively.
They are not suitable for every possible width. For various reasons we shouldn’t deviate to much from the default browser font-size on mobile devices. Responsive fluid design is beneficial on larger screens — tablet sizes and up. Breakpoints depending on the ‘em’-unit allow to fit our fluid text precisely into the variants of our responsive layout. On large desktop screens we need to stop the fluid growth again, because their height is usually more restricted than their width.
A while ago the CSS function clamp has been introduced to use a single view-port dependent size within given constraints. The approach based on breakpoints is more complicated but also more flexible.
A responsive fluid layout changes to a larger or smaller version in our favor as soon as a breakpoint is reached — wether we change the width or change our zoom setting. And not only the fonts but the size of all elements will change accordingly, if they consequently rely on the same fluid base font-size. We may have to change the zoom setting by a larger step sometimes, to make a layout change happen — but that’s all there is to it.
Just give it a try with Ctrl + + and Ctrl + - or the zoom setting of your desktop browser. You will be surprised how well you can zoom in or out of this layout. Even the images get reloaded in a higher resolution, if necessary.
- Shortcode
- Note
event Jul 4, 2022
The Beauty of Marginal Notes
Reprint of Diophantus arithmetica including Fermat’s theoremPD
Marginal notes allow to add further information in an elegant and unobtrusive way. We can glance over them and stay with the main text or zone out for a while, when they pique our curiosity.
The famous mathematician Fermat wrote his last conjecture around 1637 in the marginal column besides an ancient Greek proof by Diophantus. The “marvelous proof” Fermat mentioned there has never been uncovered and his note kept mathematicians wondering for over 350 years.
Sir Andrew John Wiles© C. J. Mozzochi, Princeton N.J
A proof has been considered generally inaccessible until Sir Andrew John Wiles announced to have found one in 1993 after years of ground-breaking work. A few mathematicians were able to follow him and pointed some flaws out, that his first promising preliminary version did still contain. Wiley finally published a completely convincing version in 1995 — a break-through in number theory which won him a few prizes.
The proof is so advanced, that its still inaccessible to almost everyone. But the ancient proof by Diophantus’ and Fermat’s conjecture are relatively easy to follow:
To divide a given square into a sum of two squares.
To divide 16 into a sum of two squares.
Let the first summand be x², and thus the second 16 – x². The latter is to be a square. I form the square of the difference of an arbitrary multiple of x diminished by the root of 16, that is, diminished by 4. I form, for example, the square of 2x – 4. It is 4x² + 16 – 16x. I put this expression equal to 16 – x². I add to both sides x² + 16x and subtract 16. In this way I obtain 5x² = 16x, hence x = ¹⁶⁄₅
Thus one number is ²⁵⁶⁄₂₅ and the other ¹⁴⁴⁄₂₅. The sum of these numbers is 16 and each summand is a square.
It is impossible to separate a cube into two cubes, or a fourth power into two fourth powers, or in general, any power higher than the second, into two like powers. I have discovered a truly marvelous proof of this, which this margin is too narrow to contain. — Pierre de Fermat
Like to use marginal notes? Have a look at the shortcode mnote.

event Sep 11, 2021

figure

Because no Markdown element corresponds to the complex HTML <figure> tag, we need this shortcode for self-contained stand-alone images.

Hugo already provides a figure shortcode and Perplex overrides this shortcode.

Syntax

The original syntax remains valid with two exceptions.

The Perplex shortcode allows to write the caption between the starting and closing shortcode tag. When there is no shortcode closing tag, we need to add a slash to the last angled bracket, to mark the shortcode as self-closing like {{< figure src="image" />}}.
Should we miss the self-closing slash, Hugo can’t recognize the mistake and expects a closing tag. It will treat all the following Markdown as the caption and produce a probably very garbled page.
The title parameter has a different meaning in Perplex. The Hugo shortcode treats it as a title for the caption and generates a <h4> tag. The Perplex figure instead uses the title parameter as title attribute and adds it to the resulting figure tag, because captions should contain only inline Markdown in the Perplex layout.

The Perplex version offers the same set of named parameters as Hugo’s built-in shortcode and a few more to specify size and position of a figure.

Named parameters

We can specify the following parameters with the given key names and types of values:

Parameter	Key	Values
Alternative text	alt	Plain string
Attribution	attr	Inline Markdown string
Attribution link	attrlink	URL
Caption	caption	Inline Markdown string
Class	class	CSS class names
Link	link	URL
Horiz. position	posh	left, right
Vert. position	posv	top, middle
Related	rel	See MDN web docs
Size	size	tiny, small, normal, full
Target	target	_blank, _parent, _self, _top

When we need many of these parameters, the figure tag gets very long and therefore prone to typing errors. Perplex also offers the alternative to specify these parameters in the resources section of the front-matter.

Overriding of front-matter meta-data

When we have set parameters in the front-matter and also specify them in named parameters for the shortcode, the latter will override the former. Same goes for the optional caption between the shortcode tags.

Layout

The numbers in the following placeholder images are roughly a multiple of the main text width.

Small

Small portrait figure on the rightgm

Small figure on the left (default horizontal position)gm

Medium

This size is a good choice for images with a landscape ratio. On smaller screens with only two columns its displayed like a small image.gm

On pages without a sidebar on the left, we can place a medium sized image also on the left.gm

Normal

To use the full width of the main text column is the usual default for stand-alone images.

The default normal size is using the full text width. If the margin is available, the caption is placed there.gm

Large

Large images exceed the full text width. The caption is placed in line with the main text at the bottom. Other possible places for the caption would be possible, but aren’t implemented for now.

In the documentation layout the large size fills the text width and the right margin. The text of the caption is constrained to the text width. The attribution is placed in the right margin an on the right as usual.gm

Extra Large

This size takes up 2 times of the main text width and is oversized on this documentation page. If there is a long table of contents included on a page and a figure with this size and a big height, the TOC may overlap the image in every possible scrolling position.

The size of an extra large image will only show on large desktop screens. Extra-large is an oversize in documentation pages, because it extends beyond the right margin. Therefore, it should be used sparingly and with great care.gm

Layout on documentation pages

The layout some figures is different documentation pages, because we can’t use the left margin there. It’s taken by the sidebar navigation. (See figure documentation page)