Typography style guide

The purpose of this guide is to help you, dear editor, see at a glance the full range of type styling options you have available in Markdown.

Headings

Headings help users to scan and read a page of text. They are numbered 1 up to 6, and nest logically, much like an outline.

First-level heading, optionally linked

First level headings are often the page title itself. Most content on the page should fall under the first header. Consider starting the page with a second-level heading.

Second-level heading, optionally linked

The header above is an ## element. More than one may be used per page. Consider using an ## unless you need a header level of less importance, or as a sub-header to an existing ## element.

Third-level heading, optionally linked

The header above is an ### element, which may be used for any form of page-level header which falls below the ## header in a document’s hierarchy.

Fourth-level heading, optionally linked

The header above is an #### element, which may be used for any form of page-level header which falls below the ### header in a document hierarchy.

Sometimes, headers fall immediately after each other. This section exercises the spacing between headers when there are no paragraphs of copy between them. It also tests for word wrap.

First-level heading, optionally linked, that might be long enough to wrap one or many times on a page depending on the page width

Second-level heading, optionally linked, that might be long enough to wrap one or many times on a page depending on the page width

Third-level heading, optionally linked, that might be long enough to wrap one or many times on a page depending on the page width

Fourth-level heading, optionally linked, that might be long enough to wrap one or many times on a page depending on the page width

Grouping content

Steps

Horizontal rule

The *** element represents a paragraph-level break, e.g. a scene change in a story, or a transition to another topic within a section of a reference book.

The above line is an example of a horizontal rule.

Blockquotes, with attribution

A > represents a section that is being quoted from another source.

Don’t communicate by sharing memory, share memory by communicating.
— Rob Pike¹

Note that blockquotes may contain more than one paragraph. For example, this one. Note: blockquotes may contain a link, or use Markdown syntax.

Footnotes

This is a simple footnote¹. This is another footnote². And this is a named³ footnote.

Alerts

Alerts are supported by Hextra and Hugo v0.134.0 or later.

Ordered list

Ordered lists are lists that display numbers for each item.

1. This is an ordered list, which may contain a link
2. This is the second item, which contains a sub list
   1. This is the sub list, which is also ordered, and which may contain a link
   2. It has two items.
   3. This third item is intentionally very long, so that we can see how word wrap will work. This third item is intentionally very long, so that we can see how word wrap will work.
3. This is the word wrapped primary list item. This is the word wrapped primary list item. This is the word wrapped primary list item. This is the word wrapped primary list item.
4. This is the final item on this list.

Unordered list

Unordered lists are lists that don’t require numbering. They may be presented as bulleted lists, or with other line item makers. Here is an example list showing the constituent parts of the British Isles:

• United Kingdom of Great Britain and Northern Ireland:
  • England
  • Scotland, which may contain a link
  • Wales
  • Northern Ireland
• Republic of Ireland
• Isle of Man, which may contain a link
• Channel Islands:
  • Bailiwick of Guernsey
  • Bailiwick of Jersey

Tables

Text-level Semantics

There are a number of inline elements you may use anywhere within other elements.

Links and anchors

Links link text, be that to another page, a named fragment on the current page or any other location on the web. Example:

Go to the home page or return to the top of this page.

Bold, or strong importance

The ** element is used to denote text with strong importance.

Italics, or stressed emphasis

The _ element is used to denote text with stressed emphasis, or an academic reference to a text.

You simply must try the negitoro maki!

Code Style Guide

Mermaid

sequenceDiagram
    Alice->>+John: Hello John, how are you?
    Alice->>+John: John, can you hear me?
    John-->>-Alice: Hi Alice, I can hear you!
    John-->>-Alice: I feel great!

Inline backticks:

Here’s an example of inline backtick code and what that looks like. Often for variables or commands.

Code block with three backticks, yaml specified:

title: Style Guide
description: 
tags: 
date: 2025-02-11
draft: false
image: 
layout: 
excludeSearch: true
unlisted: true

Code block with three backticks, html specified

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Code block indented with four spaces

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Shortcode Highlight

<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
    {{ range .Pages }}
        {{ .Render "summary"}}
    {{ end }}
  </div>
</section>

Shortcode Highlight: table option

1
2
3
4
5
6
7
8

<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
    {{ range .Pages }}
        {{ .Render "summary"}}
    {{ end }}
  </div>
</section>

Go HTML template: Linenos True

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<nav id="primary-nav" class="row" role="navigation">
  {{ if .Site.Menus.main }}
    <ul class="menu">
      {{ range .Site.Menus.main }}
        <li class=""><a class="" href="{{ .URL }}" title="{{ .Name }} page">{{ .Name }}</a></li>
      {{ end }}
    </ul>
    <hr />
  {{- end -}}
</nav>

Go HTML template: Linenos False

<nav id="primary-nav" class="row" role="navigation">
  {{ if .Site.Menus.main }}
    <ul class="menu">
      {{ range .Site.Menus.main }}
        <li class=""><a class="" href="{{ .URL }}" title="{{ .Name }} page">{{ .Name }}</a></li>
      {{ end }}
    </ul>
    <hr />
  {{- end -}}
</nav>

Go HTML template: Linenos Inline

 1<nav id="primary-nav" class="row" role="navigation">
 2  {{ if .Site.Menus.main }}
 3    <ul class="menu">
 4      {{ range .Site.Menus.main }}
 5        <li class=""><a class="" href="{{ .URL }}" title="{{ .Name }} page">{{ .Name }}</a></li>
 6      {{ end }}
 7    </ul>
 8    <hr />
 9  {{- end -}}
10</nav>