Table of Contents #

Directory structure #

The ssg currently requires the following directory structure

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

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 posts.html layout can access the following data

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, posts/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 posts.html, tags.html and their respective partials, set

{{$PageData := .TemplateData}}

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

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 #

anna will not render a page unless it contains the type field in the frontmatter

Important #

anna automatically renders a table of contents for every file of type: post

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.yml file stores additional information regarding the layout of the site It contains the following fields:

Sample config.yml #

navbar:
  - about
  - posts
  - tags

# 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:
author: Anna

Notes #

Anna provides users with functionality of maintaining notes and sharing them. Notes opens another set of functionality for anna. Users can create under the site/notes directory. Besides similar use cases as a post, notes can be short snippets of information, code or even some kind of list that the users want. It supports some important aspects of zettelkasten where users can link notes to each other, and organise similar posts in a zettel.

We aren't trying to re-invent the process of making an editor that helps users maintain these zettels as there are already some fantastic applications, namely Obsidian, Ginko Writer and Evergreen Notes. Our application as a rather needs to provide a generator to stitch these notes together to make it accessible on the site.

Notes directory structure #

/notes
├── /zettel A
└── /zettel B
    ├── note A
    ├── note B
    └── note C

Linking Notes #

Notes can be linked by using callouts in markdown files such as [[]]. The parser will validate these links during the runtime. It checks whether there are existing valid notes with a title matching the content of the callout. If not an error is thrown and you wont be able to compile the site.

For example. If you have a note with the title Note A and you would like to reference it else where in another note (could even be part of another zettel). Then [[Note A]] would be the appropriate callout to use it.