• 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:

    1. The following styling options are only available for fenced blocks:

      1. Code highlighting

      2. Line numbers

      3. Line markers

      4. Line anchors

    2. 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, …

    Layout

    Inline

    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

    1
    2
    3
    4
    5
    6
    7
    8
    
    // 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)
    }
    
    3
    4
    5
    6
    7
    8
    
    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
    

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


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


  • event

    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.

    Portrait of Sir Andrew John Wiles
    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 x2, and thus the second 16 – x2. 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 4x2 + 16 – 16x. I put this expression equal to 16 – x2. I add to both sides x2 + 16x and subtract 16. In this way I obtain 5x2 = 16x, hence x = 165

    Thus one number is 25625 and the other 14425. The sum of these numbers is 16 and each summand is a square.


    Like to use marginal notes? Have a look at the shortcode mnote.


  • event

    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.

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

    2. 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:

    ParameterKeyValues
    Alternative textaltPlain string
    AttributionattrInline Markdown string
    Attribution linkattrlinkURL
    CaptioncaptionInline Markdown string
    ClassclassCSS class names
    LinklinkURL
    Horiz. positionposhleft, right
    Vert. positionposvtop, middle
    RelatedrelSee MDN web docs
    Sizesizetiny, small, normal, full
    Targettarget_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

    Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Separated they live in Bookmarksgrove right at the coast of the Semantics, a large language ocean. A small river named Duden flows by their place and supplies it with the necessary regelialia.

    It is a paradisematic country, in which roasted parts of sentences fly into your mouth. Even the all-powerful Pointing has no control about the blind texts it is an almost unorthographic life. One day however a small line of blind text by the name of Lorem Ipsum decided to leave for the far World of Grammar.

    Small figure on the left (default horizontal position)gm

    Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Separated they live in Bookmarksgrove right at the coast of the Semantics, a large language ocean. A small river named Duden flows by their place and supplies it with the necessary regelialia.

    It is a paradisematic country, in which roasted parts of sentences fly into your mouth. Even the all-powerful Pointing has no control about the blind texts it is an almost unorthographic life. One day however a small line of blind text by the name of Lorem Ipsum decided to leave for the far World of Grammar.

    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

    Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Separated they live in Bookmarksgrove right at the coast of the Semantics, a large language ocean. A small river named Duden flows by their place and supplies it with the necessary regelialia.

    It is a paradisematic country, in which roasted parts of sentences fly into your mouth. Even the all-powerful Pointing has no control about the blind texts it is an almost unorthographic life. One day however a small line of blind text by the name of Lorem Ipsum decided to leave for the far World of Grammar.

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

    Far far away, behind the word mountains, far from the countries Vokalia and Consonantia, there live the blind texts. Separated they live in Bookmarksgrove right at the coast of the Semantics, a large language ocean. A small river named Duden flows by their place and supplies it with the necessary regelialia.

    It is a paradisematic country, in which roasted parts of sentences fly into your mouth. Even the all-powerful Pointing has no control about the blind texts it is an almost unorthographic life. One day however a small line of blind text by the name of Lorem Ipsum decided to leave for the far World of Grammar.

    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)