Styleguide for Atticus (monospace)

This styleguide provides an overview of the different elements available in the article server Atticus and shows how they are styled. The styling is heavily inspired by Tufte CSS.

Typeface

The article copy use EB Garamond. Headings, the menu, and metadata elements use IBM Plex Sans. Code and monospace text use Fira Mono.

Section (H2) heading with emphasis and monospace

Two section levels are supported. Sections are indicated using the level 2 headings in Markdown which is denoted by by prefixing it with two hashes, as in:

## Section with *emphasis* and `monospace`

Subsections with emphasis and monospace

H3 headings also use the sans serif typeface and are similar in size to the body text.

Links (also in headings)

Links are identified by underlines. This is a well-established convention and is less distracting than the alternative convention of colouring links blue.

Lists

Both bullet and number lists are possible:

• First item
• Second item
• Third item is a much longer item that will wrap because all the text in it will not fit on a single line.

1. First item
2. Second item
3. Third item

Blockquotes and epigraphs

Blockquotes are used for longer excerpts or quotes. These are distinguished from the main text by indentation. For example:

The civilized man is distinguished from the savage by prudence, or, to use a slightly wider term, forethought. He is willing to endure present pains for the sake of future pleasures, even if the future pleasures are rather distant.

{{< blockquote "Bertrand Russell, *A History of Western Philosophy*" >}}
The civilized man is distinguished from the savage by
prudence, or, to use a slightly wider term, forethought.
He is willing to endure present pains for the sake of
future pleasures, even if the future pleasures are
rather distant.
{{< /blockquote >}}

Epigraphs are quotations at the beginning of a post and look like this:

{{< epigraph "Bertrand Russell, *A History of Western Philosophy*" >}}
The civilized man is distinguished from the savage by
prudence, or, to use a slightly wider term, forethought.
He is willing to endure present pains for the sake of
future pleasures, even if the future pleasures are
{{< /epigraph >}}

Source code and plain text

Preformatted text can be either a syntax-highlighted source code block or plain text in a block or inline:

{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes       #-}

module Atticus.View.NotFound
    ( notFoundView
    ) where

import           Prelude                     hiding (head)

import qualified Data.Text                   as T hiding (head)
import           Text.Blaze.Html5            (Html, (!))
import qualified Text.Blaze.Html5            as H
import qualified Text.Blaze.Html5.Attributes as A

import           Atticus.View.Head           (head)
import           Atticus.View.Page           (page)

notFoundView :: T.Text -> Html
notFoundView blogTitle = page (head blogTitle "404") $ do
    H.div ! A.class_ "frame-A-notfound notfound-C" $ do
        H.h1 ! A.class_ "notfound-A-title notfound-C-title" $ do
            _ <- "404 NOT FOUND!"
            H.a "" ! A.class_ "link-C icon-level-up" ! A.href "/"
        H.i "" ! A.class_ "notfound-C-icon icon-flash "

{{< highlight haskell >}}
{-# LANGUAGE OverloadedStrings #-}
{-# LANGUAGE QuasiQuotes       #-}
...
{{< /highlight >}}

Inline pre-formatted text is entered between backticks: `<footer>` results in <footer>.

A pre-formatted block starts and ends with three backticks:

```
Latency Comparison Numbers (~2012)
----------------------------------
L1 cache reference                           0.5 ns
Branch mispredict                            5   ns
...

```

Latency Comparison Numbers (~2012)
----------------------------------
L1 cache reference                           0.5 ns
Branch mispredict                            5   ns
L2 cache reference                           7   ns                      14x L1 cache
Mutex lock/unlock                           25   ns
Main memory reference                      100   ns                      20x L2 cache, 200x L1 cache
Compress 1K bytes with Zippy             3,000   ns        3 us
Send 1K bytes over 1 Gbps network       10,000   ns       10 us
Read 4K randomly from SSD*             150,000   ns      150 us          ~1GB/sec SSD
Read 1 MB sequentially from memory     250,000   ns      250 us
Round trip within same datacenter      500,000   ns      500 us
Read 1 MB sequentially from SSD*     1,000,000   ns    1,000 us    1 ms  ~1GB/sec SSD, 4X memory
Disk seek                           10,000,000   ns   10,000 us   10 ms  20x datacenter roundtrip
Read 1 MB sequentially from disk    20,000,000   ns   20,000 us   20 ms  80x memory, 20X SSD
Send packet CA->Netherlands->CA    150,000,000   ns  150,000 us  150 ms

Notes
-----
1 ns = 10^-9 seconds
1 us = 10^-6 seconds = 1,000 ns
1 ms = 10^-3 seconds = 1,000 us = 1,000,000 ns

Mathematics

Mathematical typesetting in both blocks and inline is supported using $\TeX$ expressions and MathJax.

Block maths is written within double dollar signs within <p> tags:

<p>
$$f(x) = \int{h(x)\, dx}$$
</p>

<p>
$$
\begin{align*}
 f(x)  &= a x^2+b x +c \\
 f'(x) &= 2 a x +b
\end{align*}
$$
</p>

Inline maths like $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ is written within single dollar signs:

... we can state the quadratic formula,
$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$, inline.

You need to double-escape actual dollar signs in inline text: A coffee costs \\\\$5.

Figures

Images are added using the figure shortcode:

{{< figure src="./minard.png" caption="Napoleon's *March*" >}}

Images can be made full width by adding the fullwidth class:

Notes

Two kinds of notes are supported: footnotes and sidenotes.

Footnotes¹ are displayed at the bottom of the page and written using the built-in markdown support.

Sidenotes ^… This is an example of a sidenote. It will appear either on the side or inline (hidden by default) depending on the width of the viewport.

appear on the side in wide viewports or inline in narrow viewports. When displayed inline, they are hidden by default. The note is indicated in the text and in the margin by a number. The note’s visibility can be toggled by clicking the margin indicator. Sidenotes only support a limited number of elements. They are added using the sidenote shortcode which takes the name of the user-defined parameters holding the content for the sidenote. For example:

---
...
sidenote-example: "This is an example of a *sidenote*. It will appear either on the side or inline (hidden by default) depending on the width of the viewport."
---

...
This text has a sidenote.{{< sidenote sidenote-example >}}

Footnotes and sidenotes are independently numbered, which can be confusing since both the first footnote and the first sidenote will be numbered “1”. Therefore, you should only use one style of notes per article.

Icons

Inline icons can be included using the fontawesome shortcode:

{{< fontawesome font-awesome >}} {{< fontawesome github >}}

References

Reference entries can be added using the ref shortcode, which looks up the reference details in data/bibliography.yaml. There is no shortcode or standard way to write inline references.

K. Anders Ericsson and Robert Pool, Peak: How all of us can achieve extraordinary things (London: Vintage, 2017)

Ericsson, Krampe, Tesch-Römer, "The role of deliberate practice in the acquisition of expert performance" Psychological review (American Psychological Association, 1993)

Paul Graham, Maker’s Schedule, Manager’s Schedule, http://paulgraham.com/makersschedule.html (2009)

{{< ref "peak" >}}
{{< ref "deliberate-practice" >}}
{{< ref "makers-managers" >}}

Using the following data/bibliography.yaml:

deliberate-practice:
  type: article-journal
  author: Ericsson, Krampe, Tesch-Römer
  title: The role of deliberate practice in the acquisition of expert performance
  publication: Psychological review
  year: 1993
  publisher: American Psychological Association
  url: https://graphics8.nytimes.com/images/blogs/freakonomics/pdf/DeliberatePractice(PsychologicalReview).pdf

peak:
  type: book
  author: K. Anders Ericsson and Robert Pool
  title: Peak
  subtitle: How all of us can achieve extraordinary things
  year: 2017
  publisher: Vintage
  location: London
  url: https://www.goodreads.com/book/show/31180435-peak

makers-managers:
  type: article-web
  author: Paul Graham
  title: Maker's Schedule, Manager's Schedule
  year: 2009
  url: http://paulgraham.com/makersschedule.html