Table of Contents #

Anna configuration #

Define an anna.json file to configure the various sites and paths to be rendered and served by anna.

It contains the following fields:

Sample anna.json #

{
  "siteDataPaths": {
    "site": "site/",
    "site-test": "site-test/"
  }
}

Directory structure #

anna requires the following directory structure

site1
├── content
│   ├── docs.md
│   ├── index.md*
│   ├── sub0folder
│   │   ├── bench.md
│   │   ├── building-anna
│   │   │   ├── images
│   │   │   │   ├── bench.png
│   │   │   │   └── wizard.gif
│   │   │   ├── index.md
│   │   └── weekly-progress
│   │       ├── week-1.md
│   │       ├── week-2.md
│   │       └── week-3.md
├── layout
│   ├── collection-subpage.html*
│   ├── collections.html*
│   ├── config.json*
│   ├── page.html*
│   ├── partials
│   │   ├── head.html
│   ├── robots.txt*
│   ├── tag-subpage.html*
│   |── tags.html*
│   ├── collection-subpage.html*
│   └── collections.html*
├── public
└── static
    ├── fonts
    │   ├── VictorMono
    │   │   └── victormono_italics.ttf
    ├── scripts
    │   └── light.js
    ├── style.css
    ├── styles
       └── tokyo-dark.css

site2
├── content
...

Files marked * are required and cannot be omitted

Anna must be run from the parent of the site/ dir

Description of the directory structure #

Building layouts #

Each layout file can access any data from the entire ssg

The tags.html page can access the following data

The remaining pages can access the following data

PageURL #

The {{.PageURL}} is of the form index.html, collections/tech/go.html and so on.

Elements stored in DeepDataMerge #

Accessing specific page data #

The URL for the current page can be accessed using {{.PageURL}}

To access the data for a particular page, use Go templating syntax:

{{$PageData := index .DeepDataMerge.Templates .PageURL}}
{{$PageData.CompleteURL}}

To access the page data for collections.html, tags.html and their respective partials, set

{{$PageData := .TemplateData}}

All of the following page data fields can be accessed in the above manner:

Custom template functions #

Anna has the following pre-defined template function:

Frontmatter #

Metadata such as the title of the page can be added as frontmatter to the markdown files in the YAML format. This metadata can be accessed from the layout files with the appropriate syntax.

Currently, the following frontmatter tags are supported:

Important - The frontmatter field cannot be omitted #

anna will throw an error if a page does not contain frontmatter or if the title frontmatter field is missing

Body #

Anna uses Goldmark to render markdown files, which is CommonMark compliant

A few useful goldmark extensions have been included:

Static assets #

Images #

Images can be added to the content/ dir, public/ dir or the static/ dir. The contents of the static/ and public/ directories and the non-markdown files present in the content/ dir are copied to rendered/

The images can be referenced in the markdown files via their relative or absolute paths

CSS #

CSS can be added in the following ways:

Site configuration #

The config.json file stores additional information regarding the layout of the site It contains the following fields:

Sample config.json #

  {
    "navbar": [
      {
        "Index": "index.html"
      },
      {
        "Quick Start": "quick-start.html"
      },
      {
        "Docs": "docs.html"
      },
      {
        "Dev Guide": "developer-guide.html"
      },
      {
        "Tags": "tags.html"
      },
      {
        "Collections": "collections.html"
      },
      {
        "Posts": "collections/posts.html"
      },
      {
        "Anna Blog": "posts/building-anna/index.html"
      }
    ],
    "CustomFields": [
      {
        "Github": "https://github.com/anna-ssg/anna"
      }
    ],


    # make sure no trailing slash com/
    "baseURL": "https://example.com",

    # Replace this with the actual canonical-url of your site
    # baseURL tells search-engines (SEO), web-crawlers (robots.txt) so people can discover your site on the internet.
    # It's also embeded in your sitemap / atom feed and can be used to change metadata about your site.

    "siteTitle": "anna",
    "siteScripts": null,
    "author": "Anna",
    "themeURL": "/static/style.css",
    "copyright": "This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.",

    # Here, `all-posts` is the name of the layout template to be used to render the `collection/posts.html` subpage
    "collectionLayouts": {
        "collections/posts.html": "all-posts"
      }
  }