4. Features documentation

Post structure

athena supports two types of Markdown-to-HTML content: posts and pages. posts are normal blog posts and pages are auxiliary to the blog pages such as About or Contact. Both are read from the pages/ directory and are subsequently built to static HTML files. The difference between a post and a page is one YAML key.

Posts

Posts must start with the following YAML structure:

---
title: Title of the post
date: 2016-03-12
description: A short description of the post.
...

Posts are accessible in the following endpoint: /posts/<name-of-post>

Pages

Pages must start with the following YAML structure:

---
title: Title of the page
date: 2017-11-14
description: A sample about page.
ispage: yes
...

Pages are accessible in the following endpoint: /<name-of-page>

For both posts and pages: title and date values are extracted for the index loop and the post's permalink; the ispage value is filtered in the backend in order to produce a list of posts and a list of pages for the nav and side bars, as well as the Atom feed. Both author and description values are used in the post's HTML meta tags and are optional. The name of the Markdown file for either a post or a page can by anything and is its URL path.

For instance:

• about.md with ispage: yes will be available at /about
• random.md without ispage at all will be available at /posts/random

Tufte CSS-specific elements

athena uses the beautiful Tufte CSS layout. Markdown is automatically rendered to proper HTML and corresponding Tufte rules.

I highlight all relevant syntax in the elements file. However, a brief summary of the most frequent elements is provided below.

Header anchor links

As of commit 6121f12 athena supports header anchor links for # Foo and ## Bar headers (H1, H2.) Anchor links are created automatically, i.e., you do not need to append a {#tag} at the end of a heading. Anchor links are visible on hover when browsing from desktop; anchor links are appended at the end of the headers and are always visible when browsing from mobile.

Image

![Hackers and painters; by Pieter Bruegel.]( {{
url_for('static', filename='img/bruegel.jpg') }}){#fig:bruegel}

A relevant directory to host and serve from all your image assets is static/img. The image caption is used as the image's margin note.

Side note (Numbered footnote in the right margin)

Etiam ut arcu nec massa bibendum lobortis ac eu justo. Proin sit amet
sagittis est. [^note]

[^note]: A note.

Margin note (Unnumbered footnote in the right margin)

They're not doing research per se, though if in the course of
trying to make good things they discover some new technique, so much the
better. [^mn]

[^mn]:
  {-} This is a margin note. Notice there isn't a number preceding
  the note.

Code

You can write inline code by enclosing text in single backticks. Alternatively, for blocks use three backticks. athena supports code highlighting via Pygmentize.

``` {.python}
# a code block with syntax highlighting
def hello():
    print "world"
```

Table

When including a table element align the first column to the left for maximum Tufte enjoyment.

| Tables   |      Are      |  Cool |
|:---------|---------------|-------|
| col 1 is |  left-aligned |  Foo  |
: A demo table. {#tbl:demo}

Bib citations

Simply create a .bib file in the /pages directory for each post that cites one or more references and populate it accordingly. At build time, athena creates a new all.bib index out of all .bib files. Then, simply reference your citation as you normally would:

At one end you have people who are really mathematicians, but call
what they're doing computer science so they can get
DARPA grants. [@clark1988design]

For posts with citations, athena automatically appends the relevant bibliography at the end of the post under a References header element. The header element is automatically extended a header anchor link under /posts/<name-of-post>#bibliography. (See Header anchor links.)

Math

You can write inline math by enclosing text in single dollar signs. Alternatively, for blocks use double dollar signs and a space. Math is rendered via MathML.

See [@eq:euler].

$$ e^{i\pi} - 1 = 0 $$ {#eq:euler}

Cross-references

You might have observed that for image, table, and math references athena also relies on {#fig:xxx} and [@fig:xxx] (tbl and eq respectively) elements. These are optional and are used by pandoc-crossref to automatically generate numbered captions and references in the generated text. For the complete cross-reference documentation please visit the pandoc-crossref repository.

Atom feed

athena generates an Atom feed at the /feed.atom endpoint.