Anna

    ___
   /   |  ____  ____  ____ _
  / /| | / __ \/ __ \/ __ `/
 / ___ |/ / / / / / / /_/ /
/_/  |_/_/ /_/_/ /_/\__,_/

A static site generator in go

Inspired by Hugo and Saaru, this static site generator aims to take performance to the next level with parallel rendering, live reload and so much more, all in Go.

Pronounced: /ɐnːɐ/ which means rice in Kannada 🍚

This Project is a part of the ACM PESU-ECC's yearly AIEP program, and is maintained by Adhesh Athrey, Nathan Paul, Anirudh Sudhir, and Aditya Hegde

Directory structure

The ssg currently requires the following directory structure

/anna
├── /cmd
├── /pkg
│   ├── /engine
│   ├── /helpers
│   └── /parser
├── /site
│    ├── /content
│    │   │   └── /posts
│    │   │           └── sample.md
│    │   └── index.md
│    ├── /layout
│    │   ├── config.yml (This file is necessary and cannot be omitted)
│    │   ├── page.html (This file is necessary and cannot be omitted)
│    │   ├── posts.html (This file is necessary to create a 'Posts' section)
│    │   └─── /partials
│    │       └── partials for page
│    ├── /static
│    │   ├── /fonts
│    │   ├── /images
│    │   ├── plane.jpg
│    │   ├── /scripts
│    │   └── style.css
│    └ /rendered (This directory is created by the ssg)
└── /test (Stores mock data required to test the SSG)
    ├── /engine
    │   ├── /merged_data_test
    │   ├── /render_engine_generated
    │   ├── /render_page
    │   ├── /render_tags
    │   └── /render_user_defined
    └── /parser
        ├── /input
        ├── /layout
        └── /parse_md

Description of the directory structure

All of the site data, including the content, configuration and static files, are stores in site/. The rendered/ directory generated by ssg is also stored in site/.
The markdown content for the site is stored in content/ it can contain subdirectories as the folder is recursively rendered.
Static assets such as images and fonts are stored in static/
Scripts are stored in the scripts/ dir in static/
The layout of the site is configured using html files in layout/
- The config.yml file stores the configuration of the site and includes details such as the baseURL
- The page.html file defines the layout of a basic page of the site
- The posts.html file defines the layout of a page displaying all the posts of the site
- The layout files can be composed of smaller html files which are stored in the partials/ folder

Building layouts

Each layout file(except posts.html and tags.html) can access any data from the entire ssg

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 partials, set {{$PageData := .TemplateData}}

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

{{$PageData.CompleteURL}} : Returns the complete url of the given page
{{$PageData.Date}} : Returns the last modified date of the current file
{{$PageData.Frontmatter.[Tagname]}} : Returns the value of the frontmatter tag
- Example: {{$PageData.Frontmatter.Title}} : Returns the value of the title tag
{{$PageData.Body}} : Returns the markdown body rendered to HTML
{{$PageData.Layout.[Tagname]}}: Returns the particular configuration detail of the page
- Example: {{$PageData.Layout.Navbar}} : Returns a string slice with the names of all the navbar elements

In addition to page data, the following fields can be accessed:

{{.DeepDataMerge.Tags}} - A map that stores the template of the tag sub-pages for a particular tag url
{{.DeepDataMerge.TagsMap}} - A map that stores a slice of templates of all posts for a particular tag url
{{.DeepDataMerge.LayoutConfig}} - Stores the layout parsed from config.yml
{{.DeepDataMerge.Posts}} - Stores a slice of templates of all posts
{{.DeepDataMerge.JSONIndex}} - Stores the JSON index generated for a particular site (primarily used for search and graphing of tags)

Notes

Images: To add images, add it to the 'static/' folder or a subdirectory under it. Use /static/[imagename.format] as the image link format in the markdown files.
CSS: CSS can be added in the following ways:

In an external file in the static/ directory and linked to the layout files
- To link the stylesheet, use the baseURL along with the relative path
  
  Example: <link rel="stylesheet" href="{{.Layout.BaseURL}}static/style.css">
Placed inside <style></style> tags in the <head></head> of the layout files
Inline with the html elements

Frontmatter: Metadata such as the title of the page can be added as frontmatter to the markdown files in the YAML format. Currently, the following tags are supported:

title : The title of the current page
date: The date of the current page
draft: When set to 'true', the current page is not rendered unless the '-d' flag is used
scripts: Stores the page-level scripts to be added
type: Sets the type of the page. Use type 'post' for posts
description: Stores the description of the current post previewed in posts.html
previewimage: Stores the preview image of the current page
tags: Stores the tags of the particular page
authors: Stores (multiple) author/s of a particular page

(The above tags are Frontmatter tags)

config.yml: This file stores additional information regarding the layout of the site

navbar: Stores the links to be added to the navbar (same name as the markdown files)
baseURL: Stores the base URL of the site
siteTitle: Stores the name of the site
siteScripts: Stores the javascript files to be included with every page
author: Stores the author of the site

(The above tags are Layout tags)

Sample `config.yml`

navbar:
  - about
  - posts

baseURL: http://localhost:8000/
# 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

Run locally

go run github.com/acmpesuecc/anna@v1.0.0-alpha

If you don't have a site dir with the pre-requisite layout template; anna proceeds to fetch the default site dir from our GitHub repository

Contributing to Anna

Detailed documentation for our SSG can be found: here

If you have git installed, clone our repository and build against the latest commit

git clone github.com/acmpesuecc/anna; cd anna
go build

Usage:
  anna [flags]

Flags:
  -a, --addr string   ip address to serve rendered content to (default "8000")
  -d, --draft         renders draft posts
  -h, --help          help for anna
  -l, --layout        validates html layouts
  -p, --prof          enable profiling
  -s, --serve         serve the rendered content
  -v, --version       prints current version number
  -w, --webconsole    wizard to setup anna