anna-docs

Anna Documentation

anna — Sun, 28 Apr 2024 00:00:00 +0000

Table of Contents #

Directory structure #

Anna requires the following directory structure

site
├── 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.css

Files marked * are required and cannot be omitted

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 along with images as the folder is recursively rendered.
- The contents of this dir is rendered to the root of rendered/
Static assets such as 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.json file stores the configuration of the site and includes details such as the baseURL
- The collections.html, collection-subpage.html, tags.html and other necessary layouts define the structure of the various pages of the site such as collections.html, collections/[[sub-page]].html and other SSG generated pages
- Additional layouts can be created and set for various pages of the site using the layout frontmatter field
- The layout files can be composed of smaller html files which are stored in the partials/ folder
Contents in public/ are rendered to the root of rendered/

Building layouts #

Each layout file can access any data from the entire ssg
The tags.html page can access the following data:
- {{.DeepDataMerge}}
- {{.PageURL}}
- {{.TemplateData}}
- {{.TagNames}}
The remaining pages can access the following data
- {{.DeepDataMerge}}
- {{.PageURL}}

PageURL #

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

Elements stored in `DeepDataMerge` #

{{.DeepDataMerge.Collections}} - A map that stores the template data of the collection sub-pages for a particular collection url
{{.DeepDataMerge.CollectionsMap}} - A map that stores a slice of templates of all pages for a particular collection url
{{.DeepDataMerge.JSONIndex}} - Stores the JSON index generated for a particular site (primarily used for search and graphing of tags)
{{.DeepDataMerge.LayoutConfig}} - Stores the layout parsed from config.json
{{.DeepDataMerge.Templates}} - A map that stores the template data of all the pages of the site for the particular url(the URL is the PageURL for the speicified page)
{{.DeepDataMerge.Tags}} - A map that stores the template data of the tag sub-pages for a particular tag url
{{.DeepDataMerge.TagsMap}} - A map that stores a slice of templates of all pages for a particular tag url

Layout Partials #

Anna supports layout partials, which are reusable HTML template fragments stored in the layout/partials/ directory. Partials allow you to break down complex layouts into smaller, manageable pieces that can be shared across multiple layout files.

How Partials Work #

Partials use Go's template system with the {{define}} and {{template}} directives:

Defining a Partial: Use {{define "partialName"}} to define a partial template
Including a Partial: Use {{template "partialName" .}} to include the partial in a layout

Partials have access to the same data context as the main layout templates, including:

{{.DeepDataMerge}} - All site data
{{.PageURL}} - Current page URL
{{.TemplateData}} - Page-specific template data

Example Partial Structure #

Here's how the built-in partials are organized:

layout/partials/
├── head.html      # HTML head section with meta tags, stylesheets, and scripts
├── header.html    # Site header with navigation and branding
├── footer.html    # Site footer with copyright and links
└── search.html    # Search modal/component

Creating and Using Partials #

Example: Defining a partial in head.html

{{define "head"}}
<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{index .DeepDataMerge.Templates .PageURL | .Frontmatter.Title}}</title>
    <!-- Additional head content -->
</head>
{{end}}

Example: Using partials in a layout file (page.html)

{{define "page"}}
{{template "head" .}}

<body>
    {{template "header" .}}
    
    <main>
        <!-- Page content -->
        {{index .DeepDataMerge.Templates .PageURL | .Body}}
    </main>
    
    {{template "footer" .}}
</body>
</html>
{{end}}

Best Practices for Partials #

Naming Convention: Use descriptive names that match the partial's purpose (e.g., "head", "header", "footer")

Data Access: Always check if page data exists before accessing it:

{{$PageData := index .DeepDataMerge.Templates .PageURL}}
{{if eq $PageData nil}}
{{$PageData = .TemplateData}}
{{end}}

Modularity: Keep partials focused on a single responsibility
Reusability: Design partials to work across different layout types
Conditional Logic: Use template conditionals to show/hide content based on page data

Common Partial Patterns #

Head Section: Meta tags, stylesheets, scripts, and SEO data
Navigation: Site-wide navigation menus and breadcrumbs
Footers: Copyright notices, social links, and site information
Components: Reusable UI components like search forms, modals, or sidebars

Partials make your layouts more maintainable by separating concerns and reducing code duplication across different page types.

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:

{{$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

Custom template functions #

Anna has the following pre-defined template function:

func strSliceContains(items []string, search string) bool This function returns true if a search string is present in a slice of strings (items), else returns false

Usage: {{if strSliceContains $PageData.Frontmatter.Collections "posts"}}

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

authors: Stores (multiple) author/s of a particular page
collections: Stores the collections the particular page belongs to
date: The date of the current page
description: Stores the description of the current post previewed in html layouts
draft: When set to 'true', the current page is not rendered unless the '-d' flag is used
layout: Stores the layout file (*.html) to be used to render the current page
previewimage: Stores the preview image of the current page
scripts: Stores the page-level scripts to be added
tags: Stores the tags of the particular page

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

authors: Stores (multiple) author/s of a particular page
collections: Stores the collections the particular page belongs to
date: The date of the current page
description: Stores the description of the current post previewed in html layouts
draft: When set to 'true', the current page is not rendered unless the '-d' flag is used
layout: Stores the layout file (*.html) to be used to render the current page
previewimage: Stores the preview image of the current page
scripts: Stores the page-level scripts to be added
tags: Stores the tags of the particular page
title : The title of the current page
toc: When set to 'true', a table of contents is rendered for the current page

Frontmatter Examples #

Basic Page Frontmatter #

---
title: "My Blog Post"
date: 2024-01-15
description: "A brief description of this post"
authors: ["John Doe"]
tags: ["golang", "ssg"]
collections: ["posts"]
toc: true
---

Draft Post #

---
title: "Work in Progress"
date: 2024-01-15
draft: true
---

Custom Layout #

---
title: "Special Page"
layout: "custom-layout.html"
scripts: ["special.js"]
---

Collection Page #

---
title: "Building Anna: A Static Site Generator"
date: 2024-01-01
collections: ["posts", "anna"]
tags: ["golang", "static-site", "development"]
previewimage: "/static/images/anna-preview.png"
---

Accessing Frontmatter in Templates #

Frontmatter values are accessible in layout templates through the Frontmatter field:

<!-- Access title -->
<h1>{{ $PageData.Frontmatter.Title }}</h1>

<!-- Access authors -->
{{range $PageData.Frontmatter.Authors}}
<p>Author: {{.}}</p>
{{end}}

<!-- Access tags -->
{{range $PageData.Frontmatter.Tags}}
<a href="/tags/{{.}}.html">{{.}}</a>
{{end}}

<!-- Conditional rendering -->
{{if $PageData.Frontmatter.Toc}}
<div class="toc">{{ $PageData.Body | toc }}</div>
{{end}}

Body #

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

A few useful goldmark extensions have been included:

anchor
- adds support for anchors next to all headers
figure
- parse markdown paragraphs that start with an image into HTML <figure> elements
toc
- adds support for rendering a table-of-contents

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:

In an external file in the static/ directory and linked to the layout files

Example: <link rel="stylesheet" href="/static/style.css">
Placed inside <style></style> tags in the <head></head> of the layout files
Inline with the html elements

Development Workflow #

Building the Site #

Anna provides several ways to build and serve your site:

Basic Build #

# Build the site once
anna

# Build with drafts included
anna -d

# Build and serve locally
anna -s

# Build and serve with drafts
anna -s -d

Using Make #

The included Makefile provides convenient build targets:

# Build the site
make build

# Clean build artifacts
make clean

# Run tests
make tests

# Serve the site with live reload
make serve

Live Reloading #

When running with the -s flag, Anna includes live reload functionality:

The server watches for file changes in content/, layout/, and static/
When changes are detected, the site is automatically rebuilt
Connected browsers automatically refresh to show changes
Live reload scripts are injected into pages during development

File Watching #

Anna monitors the following directories for changes:

content/ - Markdown files and assets
layout/ - HTML templates and partials
static/ - Static assets (CSS, JS, images)
site/config.json - Site configuration

Changes to any files in these directories trigger a rebuild.

Troubleshooting #

Common Issues #

Missing Frontmatter Error #

Error: frontmatter is required for all pages

Solution: Ensure every .md file starts with YAML frontmatter including at least a title field:

---
title: "Page Title"
---

Template Execution Errors #

template: layout/page.html:1: function "undefined" not defined

Solution: Check for typos in template function names. Available functions:

strSliceContains for checking if a string exists in a slice

Missing Layout Files #

Error: open site/layout/page.html: no such file or directory

Ensure required layout files exist in site/layout/:

page.html (required)
collections.html (required)
tags.html (required)
config.json (required)

Broken Links in Rendered Output #

Use absolute paths starting with / for internal links:

<a href="/collections/posts.html">Posts</a>

Images Not Loading #

Place images in:

site/static/ for global assets
site/content/ alongside markdown files
site/public/ for root-level files

Reference with absolute paths: /static/images/logo.png

Collection Pages Not Generating #

Ensure pages have collections frontmatter:

collections: ["posts", "articles"]

Tag Pages Not Working #

Ensure pages have tags frontmatter:

tags: ["golang", "tutorial"]

Site configuration #

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

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
copyright: Stores the copyright information of the site
themeURL: Stores the link to the common stylesheet
customFields: Stores a set of arbitrary key-value pairs as required by the user
collectionLayouts: Stores the names of the layouts to be used for a particular collection subpage

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"
      }
  }

Quick Start

anna — Sun, 28 Apr 2024 00:00:00 +0000

Installation

Download a prebuilt binary for your platform from the latest release:

MacOS

brew install anna-ssg/anna/anna

GNU/Linux (tar.gz):

Linux (x86_64): anna_Linux_x86_64.tar.gz

tar -xzf anna_Linux_x86_64.tar.gz

./anna

Windows 10/11 (x86_64):

Download anna_Windows_x86_64.zip

Unzip anna_Windows_*.zip

Run anna.exe from the extracted folder in a terminal

Bootstrap (create a `site/` directory)

If you don't already have a site/ directory, Anna can initialize one for you with a default layout.

# will ask to download the default site layout when config is missing
./anna

Usage

Basic render

Render the site found at site/ (default):

anna

Specify a path:

anna -p ./site

Serve with live reload

anna -s

Version and debug

Show the version (includes embedded commit when present):

anna -v

Show usage and all flags:

anna -h

Developer Guide

anna — Sun, 28 Apr 2024 00:00:00 +0000

This document explains the repository layout, development commands and how to contribute.

Repository layout (high level)

cmd/anna - CLI and server (main command)
pkg/engine - core rendering engine
pkg/parser - markdown parsing and helpers
site/ - example site used for docs and dogfooding
test/ - integration and expected output for tests

Build & run

Build locally:

go build ./...

Run the CLI directly during development:

go run github.com/anna-ssg/anna/v3 -p ./site -s

Run only unit tests:

go test ./pkg/...

Run all tests and race detector:

go test ./... -v -race

Benchmarks & profiling

Run benchmarks and generate pprof data using the Makefile:

make bench
# results and pprof files are in the profiles/ or test output directories

While serving you can view pprof endpoints at http://localhost:8000/debug/pprof (see cmd/anna).

Makefile targets

Targets:
  build  : Build anna and render the site
  serve  : Build anna, render and serve the site with live reload
  tests  : Run all tests
  bench  : Run the benchmark and generate pprof files
  clean  : Remove the rendered site directory and test output

Contribution workflow

Fork the repository and create a feature branch (eg. feature/foo).
Write code, run go fmt ./... and add/update tests.
Run go test ./... -v and verify all tests pass.
Push your branch and open a Pull Request with a clear description and changelog.

Development tips

Use go vet and go test -race while developing for correctness.
Keep changes small and isolated; add tests for new behavior.
Update site/ when adding features that affect rendering or layouts so the docs can dogfood changes.

Building anna

anna — Thu, 04 Apr 2024 00:00:00 +0000

This post is WIP(work-in-progress) and has been authored by Adhesh, Aditya, Nathan and Anirudh.

There are several amazing static site generators(SSG) out there, like Hugo and 11ty. Building your own SSG is an amazing learning experience. It also motivates one to maintain and improve their personal site.

Building personal blogs from the ground up can be a tedious process. Some of us have had our hands deep in vanilla HTML and CSS, which isn't fun to maintain. We all want to get to the point and share our thoughts on the web. But, there is a small hurdle that stops us from doing so.

Maintaining your personal site is like working with your own Neovim configuration. Every issue fixed would lead to an entirely unrelated bug. There is a lot of time spent fixing things rather than getting productive work done.

A static site generator is an immensely useful application

Lighthouse scores of the anna-docs page

It can simplify the whole process: allowing you to spend time and energy on quality content. Keep reading to find out how we designed anna.

Introduction

ACM-PESU ECC conducts the ACM Industrial Experience Program (AIEP), an annual program that spans six weeks.

It involves students working as a team to develop an industrial-level project. AIEP intends to give students hands-on experience with real-world projects. It is an excellent opportunity to interact with like-minded individuals.

Our AIEP team consisted of Adhesh, Aditya, Nathan, and Anirudh.

Our mentors (cool senior names!) gave us some great ideas for our team of four freshers. We were puzzled whether to build a distributed Postgres clone or a load balancer.

Deep discussions over a week got us to the topic of making blog sites and how tiring it is to work with, which only gets worse as you write more and more content for your internethome.

This and inspirations from Saaru and Sapling pushed us to tackle this problem with our own SSG.

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

A static site generator in Go

The small but big decision

Anna is written in Go. We considered writing it in Rust, but it came with a steep learning curve. Go is a powerful language and has excellent concurrency support, which suited our requirements to build a performant application.

What's in a name?

Probably the first thing that the four of us came across when joining ACM and HSP was the famous Saaru repository, one of the projects that inspired our ssg. Saaru is a thin lentil soup, usually served with rice and is a Kannada word.

In Kannada, rice is referred to as 'anna' (ಅನ್ನ) pronounced /ɐnːɐ/

This was just a playful stunt that we engaged in. We planned on beating Saaru at site render times, optimizing at runtime.

Genesis

We began the project in a unique manner, with each of us creating our own prototype of the SSG. This was done to familiarize everyone with the Go toolchain.

The first version of the SSG did just three things. It rendered markdown (stored in files in a content folder in the project directory) to HTML. This HTML was injected into a layout.html file and served over a local web server. Later, we implemented a front matter YAML parser to retrieve page metadata

What made us develop this to a great extent?

Beginner-friendly: An easy setup wizard, ready to use layouts, and themes. We wanted the process of typing out a blog and putting it up on your site to be short and simple.
Speed: Render sites in a flash (hugo – written in Go, is remarkably fast)
Maintainable: This ssg would be used by us, hence it should be easy to fix bugs and add new features
Learning curve: None of us had really shipped a production-ready application. Since AIEP is all about making industry-ready projects, we chose to use Go: so we could spend more writing code and not worrying about our toolchain or escaping dependency hell.
Owning a piece of the internet: Aditya and Anirudh registered their own domain names. Now their anna sites live on hegde.live and sudhir.live.

Benchmarks! Can anna lift??

In simple terms, to beat Saaru's render time (P.S. we did beat the initial version!). Something you probably never notice while deploying, but it is what pushed us to spend hours on this.

Adhesh was pretty excited to pick up Go and implement profiling, shaving milliseconds off build times, when he implemented parallel rendering using goroutines.

We cook! 🍳

Here are some images that demonstrate build times, profiling et-al when having thousands of markdown files or in this case just copy-pasting a single markdown file en-mass!

Hyperfine benchmarks comparing the render times of anna, Saaru and 11ty

2 weeks into the project, we had a PR bringing parallel rendering and profiling to the table

Profiling

For those who love to get technical, anna has a profiling flag and a debug endpoint(available during live reload). This flag prints the profile data of the rendering process to stdout. The debug endpoint displays the data for site render in the live reload mode, which can be visualised by navigating to the specified pprof endpoint

Live Reload

anna can be run in a serve mode which serves the rendered site over localhost. It also includes live reload, which performs a re-render of the site for every change made to the markdown content. It also injects a script which auto-refreshes the browser on a site re-render.

Initial version

The initial version consisted of a multi-goroutine system.

A new goroutine would be spawned to walk the required content directories. If the current path being walked was a file, the path would be passed to another function along with its current modification time.
The previous mod time of the file would then be retrieved from a map holding the mod times of all the files:

If the given file was freshly created, its modification time would be added to the map.
If there was no change in the mod time, no changes would be made.
If there was a change between the current and previous mod times, a re-render of the site would be performed.

The site re-render function checks if a child process is running:

For the first render, when a process has not been created, a new process is created that runs anna ("go run main.go --serve")
For successive renders, the existing process is killed and a new process is spawned once again that runs the application.

This prototype was not very efficient as it created and killed processes for every change. It had multiple goroutines attempting to walk the directories at the same time, which also required multiple mutual exclusion locks to prevent data races. This was designed as a standalone component and integrating this proved to be challenging.

Improvements

The updated version of live reload utilised two goroutines.

The main goroutine used the initial file walker, with one important change: it sequentially traversed the directory without spawning new goroutines. For any modification to a file in the current traversal, a vanilla render of the entire site would be performed. The goroutine would then sleep for a specified duration (currently 1 second) before attempting the next directory traversal.

The secondary goroutine ran a local web server that served the rendered/ directory.

This eliminated all locks and avoided the creation and destruction of child processes.

Browser reload (WIP)

When anna performs a re-render of the site, the browser is automatically refreshed to reflect the latest changes. This involved utilising server-sent events(SSE). A script was injected into all pages that polled a particular port. On receiving an event sent by anna during the re-render, the script would reload the page.

(The following content is WIP)

A big rewrite (when we went for a TDD approach)

Starting off this project, we kept adding functionality without optimization. We did not have a proper structure; PRs would keep breaking features and overwriting functions written by team-mates.

We dived into the codebase to rebuild the application following a TDD-approach.

A new proposed rendering system

main.go

Firstly, we refactored main.go to only handle flags. The rest of the program logic was moved to other packages. A benchmark for main.go was also written to time the entire application.

pkg/ modules

Modules previously part of cmd/anna/utils.go and cmd/anna/main.go were to be split between pkg/parsers/, pkg/engine/ and pkg/helper

pkg
├─── helpers
│   ├─── helpers.go
│   └─── helper_test.go
├─── engine
│   ├─── anna_engine.go
│   ├─── anna_engine_test.go
│   ├─── engine.go
│   ├─── engine_test.go
│   ├─── user_engine.go
│   ├─── user_engine_test.go
│   └─── engine_integration_test.go
└─── parsers
 ├── parser.go
 ├── parser_test.go
 └── parser_integration_test.go

Wrote unit and integration tests for the parser and engine package

Splitting the render pipeline

Currently, there are three kinds of files that have to be rendered. One set includes user-defined files such as index.md, docs.md and various posts. These are specific to a user.

The second set of files that are rendered include tags.html and posts.html, which are present on every site rendered by anna.

The third set of files included the tag-sub pages. For every tag, there would be a corresponding sub-page containing all of the posts with the same tag.

Split the rendering system to make parallelisation easier by switching to a three method system.

Render "user defined" pages which include all markdown files and posts (This method has been parallelised, Render tags and tag-sub pages separately, which could be parallelised in the future

Useful features

To search or not to search? 🤔

That is the question > Is our static site becoming dynamic and at what cost?

We were wondering if we’d need a search function on our site since Google and any other web-crawler index our site anyway. If we needed to implement it, we had a constraint: do not use an API. It had to be static and local to be user-friendly to work with. We implemented a JSON index generator that uses "Deep Data Merge" to index posts on our site.

This index is generated during the site render and functions without any lag or noticeable delay when searching across posts. We mean to re-write it using WASM if necessary.

Here's a gif demonstrating search

JS integration as plugins

We added a field to the frontmatter which lets you pick and add certain JS based snippets to your site. This way, you get to add highlight.js support, analytics scripts and donation page widgets; that you can source from the static/scripts folder and toggle as needed per-markdown page.

Wizard

An important ease-of-use feature was a GUI; a web-based wizard that let's a new user setup anna along with a couple of easter eggs along the way 🍚

The wizard lets a user pick a theme, enter your name, pick navbar elements, and validates fields using regex checks so you don’t need to worry about relative paths in baseURLs, canonical links, and sitemaps. After successfully completing the setup, the wizard launches a live preview of your site in a new tab.

Raw HTML

What if you'd want to add a contact form to your site? or embed YouTube videos or iframes of your choosing?

Anna let's us do that! Although, the point of a static site generator is to quickly get to writing and focusing on the content. You can still embed js elements and iframe as needed to showcase any interesting YouTube videos or to just rickroll people!

changelog: showcasing important additions, which are yet to be added to this blog

Deep Data Merge
Style feed.xml
Site bootstrapping

Next steps

Wizard theme repo
Performance: Explore memory-mapping, etc

Feedback? / Learnings

We have a lot of things in store and bugs to squash!

Feel free to ask any questions / send feature requests you'd like to see?

This blog post misses out of many not-so well documented features and learnings that we got during midnight calls and the patches we kept sending each other fixing trivial but interesting issues. Have a look at our GitHub, for more

Today, we use anna on our personal sites: hegde.live // sudhir.live // polarhive.net

01100001 01101110 01101110 01100001

Week-3 Progress

anna — Mon, 01 Apr 2024 00:00:00 +0000

Week-3

Anirudh and Hegde's Progress

Split methods previously part of anna package among parser, engine and helpers packages
Refactored main.go to only handle flags
Wrote unit and integration tests for the parser and engine package
Split the rendering system to make parallelisation easier by switching to a three method system.
- Render "anna specific" pages such as sitemap and feed
- Render "user defined" pages which include all markdown files and posts (This method has been parallelised)
- Render tags and tag-subpages separately, which could be parallelised in the future
Wrote a benchmark for main.go that times the entire application

Whats Next (Anirudh and Hegde):

Improve test coverage for the engine package
Write unit and integration tests for the cmd and helper packages
Write unit and integration tests for main.go

Adhesh’s Progress

Re-implemented cobra CLI for the restructed codebase.
Re-implemented Parallel rendering pipelines for redering tags and content files separately.
Improved profiling.
Refactored code to improve performance.
Worked on content indexing.

What's next?

Implement content indexing and site wide content search.
Improve existing GUI:
- Add project directory browser.
- Add Theme browser.
Implement new flags to provide refined control on resource management.
- -c / --concurrency to set limit on number of goroutines.
Implement integration with hosting services to auto host project.

Nathan’s Progress

Implemented an interactive web based wizard to help a user bootstrap their anna site
- The intial build wrote the json blob to disk; now it passes it as a POST request to the webserver itself over port 8080 (may conflict)
- So far it lets you pick a fill metadata, pick a theme and preview your site
- It auto validates fields using regex as you proceed
- Also: an animated progressbar and other easter-eggs (confetti??)

What's next?

Improve UX by dogfooding and collecting feedback from new users
Theme triaging and cataloging (basic hugo compatability)
Bootstrap site dir, if the user didn't already have one, using go-git and add basic git-submodule support for themes
Implement go best practices: (auto generate docs, tag releases and known bugs)

Week-2 Progress

anna — Mon, 25 Mar 2024 00:00:00 +0000

Week-2

Anirudh’s Progress

Restructured the project
Improved and integrated the live reload functionality into the ssg
- Switched to a two goroutine system
  - The main goroutine runs the application and renders pages
  - The second goroutine runs the local web server
- Eliminated locks and restarting of application on file modification
Implemented the tagging system
- Added functionality to tag posts into collections
- Reverse search for posts of a particular category

Hegde’s Progress

Implemented chronological feed for posts
Added ssg flag and frontmatter field to allow working with draft posts. Changed page rendering process to prevent rendering of unnecessary posts.
Added options in frontmatter and config.yml to integrate javascript based plugins (eg: light mode, code highliting, etc). Users can have seprate plugin options per post.
Fixed iframe, video and image rendering (CSS)

Whats Next (Anirudh and Hegde):

Rebuild the project from ground up and split up the rendering process and Generator struct
Follow a TDD-based approach during the rebuild

Adhesh’s Progress

Implemented parallel rendering pipelines.
Improved parallel rendering and calculation of concurrency factor.
Cleaned and refactored code to improvise performance.

What's next?

Split Parallel rendering pipelines for tags and content files.
Implement work-stealing.

Nathan’s Progress

chore/build: Build and deploy anna using Netlify #11, #48
chore/build: switch to Makefile #49

What's next?

Implement a gui/wizard to configure the config.yml

Week-1 Progress

anna — Mon, 18 Mar 2024 00:00:00 +0000

Week-1

Anirudh’s Progress

Built the markdown to HTML renderer using the Goldmark library
Set up a web server to preview the rendered content locally
Implemented a front matter YAML parser to retrieve page metadata
Designed a reusable system of partials to build page layouts
Implemented a recursive renderer for the content/ and static/ directories

What's next?

Restructure the project
Refactor and improve the live reload functionality
Implement the post tagging system

Adhesh’s Progress

Migrated to Cobra for better CLI integration.
Implemented important flags for serving a local HTTP server (---serve), and to explicitly mention the port to use (---addr).
Implemented Real-Time Directory/File change watcher using fsnotify, and Hot-Reload system for reserving updated files instantaneously.
Cleaned and sanitised some parts of the codebase.
Included early optimizations to some functions of the codebase using goroutines and sync operations.

What's next?

Making main.go the entry point for the code.
Fix issues with the watcher, and clean up the goroutine issues.
Try studying about parallelizing code functions, and implementing it.
Add a developer mode/flag for profiling the performance of the application (---dev)
Look into Huge theme compatibility.
Try integrating JavaScript in templates.

Hegde’s Progress

Switched to automatic filename parsing
Implementing Draft Posts
Complete CSS styling
Cleaned up unnecessary post rendering

Whats Next:

JS injection as plugins into pages and individual posts
Draft post rendering
Chronological Feed for posts

Nathan’s Progress

Setup CI using GitHub actions which builds and deploys the SSG to gh-pages
Setup robots.txt to (currently set to prevent indexing until we reach a v1.0 release)
Implemented sitemap.xml to tell search engines how our site is structured
Fixed baseURL it now, uses absolute paths from root / when loading stylesheets

What's next?

SEO optimization (verify semantic HTML generation)
OGP tags in page headers

Henlo!

anna — Sat, 24 Feb 2024 00:00:00 +0000

Anna is a lightning fast static site generator written in Go, designed for simplicity and ease of use. With a focus on performance and minimal configuration, Anna allows you to create beautiful static websites with ease.

Crafted with Anna

Quick Start Guide

Download Anna and deploy your site in seconds with our quick start guide.

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

A static site generator in go

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

Language Codeblock Test

anna — Fri, 23 Feb 2024 00:00:00 +0000

struct in rust

struct Vector2D {
    x: f64,
    y: f64,
}

Brainfuck interpreter yanked from reddit

s[999],*r=s,*d,c;main(a,b){char*v=1[d=b];for(;c=*v++%93;)for(b=c%7?a&&(c&17?c&1?
(*r-=c-44):(r+=c-61):c&2?putchar(*r):(*r=getchar()),0):v;b&&c|a**r;v=d)main(!c,&
b-1);d=v;}

Entire `yake` sourcecode!

#include <stdio.h>

int opr(char *v);
void ex(int *p, char *syn);

int main(int ac, char *av[]) {
    int p = 0;
    return (ac < 2) ? (printf("synerr\n"),1) : (ex(&p, av[1]), 0);
}

void ex(int *v, char *syn){
    int *p;
    int st = 0; // 0 for value control, 1 for pointer control
    while ((int)*syn!='\0'){
        switch ((int)*syn) {
            case 46: printf("&v : %d | %p -> %d | m = %d\n", *v, p, *p, st); break;
            case 43: if(st!=1){++*v;}else{++p;} break;
            case 45: if(st!=1){--*v;}else{--p;} break;
            case 60: if(st!=1){*v = *v<<1;}else{printf("synerr");return;} break;
            case 62: if(st!=1){*v = *v>>1;}else{printf("synerr");return;} break;
            case 64: if(st == 1){st = 0;*p=*v;}else{st=1;} break;
            case 38: if(st == 1){st = 0;*v=*p;}else{st=1;}break;// & is used to get value

            // operations, st == 1, for subsequent value for operation type
            case 37: if(st==1){
                syn++;
                switch((int)*syn) {
                    case 45: *v-=*p; break;
                    case 43: *v+=*p; break;
                }
                st = 0; // auto switch back to st=0
            } break;

            case 58: // ascii to string
                     // length of string to be printed is
                     // to be stored in v
                     for (int i=0;i<*v;++i){printf("%c",*p);++p;}

                     printf("\n");
                     break;

            default: printf("synerr\n"); return;
        }
        syn++;
    }
    return;
}

Sample Post

anna — Fri, 23 Feb 2024 00:00:00 +0000

h1 Heading 8-)

h2 Heading

h3 Heading

h4 Heading

h5 Heading

h6 Heading

Horizontal Rules

Typographic replacements

Enable typographer option to see result.

test.. test... test..... test?..... test!....

!!!!!! ???? ,, -- ---

"Smartypants, double quotes" and 'single quotes'

Emphasis

This is bold text

This is italic text

~~Strikethrough~~

Blockquotes

Blockquotes can also be nested...

...by using additional greater-than signs right next to each other...

...or with spaces between arrows.

Lists

Unordered

Create a list by starting a line with +, -, or *
Sub-lists are made by indenting 2 spaces:
- Marker character change forces new list start:
  - Ac tristique libero volutpat at
  - Facilisis in pretium nisl aliquet
  - Nulla volutpat aliquam velit
Very easy!

Ordered

Lorem ipsum dolor sit amet
Consectetur adipiscing elit
Integer molestie lorem at massa
You can use sequential numbers...
...or keep all the numbers as 1.

Start numbering with offset:

Code

Inline code

Indented code

// Some comments
line 1 of code
line 2 of code
line 3 of code

Block code "fences"

Sample text here...

Syntax highlighting

var foo = function (bar) {
  return bar++;
};

console.log(foo(5));

Tables

| Option | Description | | ------ | ------------------------------------------------------------------------- | | data | path to data files to supply the data that will be passed into templates. | | engine | engine to be used for processing templates. Handlebars is the default. | | ext | extension to be used for dest files. |

Right aligned columns

| Option | Description | | -----: | ------------------------------------------------------------------------: | | data | path to data files to supply the data that will be passed into templates. | | engine | engine to be used for processing templates. Handlebars is the default. | | ext | extension to be used for dest files. |

Links

link text

link with title

Autoconverted link https://github.com/nodeca/pica (enable linkify to see)

Images

Like links, Images also have a footnote style syntax

With a reference later in the document defining the URL location:

Plugins

The killer feature of markdown-it is very effective support of syntax plugins.

Emojies

Classic markup: :wink: :cry: :laughing: :yum:

Shortcuts (emoticons): :-) :-( 8-) ;)

see how to change output with twemoji.

Subscript / Superscript

19^th^
H~2~O

<ins>

++Inserted text++

<mark>

==Marked text==

Footnotes

Footnote 1 link[^first].

Footnote 2 link[^second].

Inline footnote^[Text of inline footnote] definition.

Duplicated footnote reference[^second].

[^first]: Footnote can have markup

and multiple paragraphs.

[^second]: Footnote text.

Definition lists

Term 1

: Definition 1 with lazy continuation.

Term 2 with inline markup

: Definition 2

    { some code, part of Definition 2 }

Third paragraph of definition 2.

Compact style:

Term 1 ~ Definition 1

Term 2 ~ Definition 2a ~ Definition 2b

Abbreviations

This is HTML abbreviation example.

It converts "HTML", but keep intact partial entries like "xxxHTMLyyy" and so on.

*[HTML]: Hyper Text Markup Language

Custom containers

::: warning here be dragons :::

benchmark

anna — Mon, 01 Jan 2024 00:00:00 +0000

heading L1

Lorem ipsum dolor sit amet, officia excepteur ex fugiat reprehenderit enim labore culpa sint ad nisi Lorem pariatur mollit ex esse exercitation amet. Nisi anim cupidatat excepteur officia. Reprehenderit nostrud nostrud ipsum Lorem est aliquip amet voluptate voluptate dolor minim nulla est proident. Nostrud officia pariatur ut officia. Sit irure elit esse ea nulla sunt ex occaecat

heading L2

bold and italics

quote text

Testing File for Extensions

anna — Thu, 01 Jan 1970 00:00:00 +0000

arrow right 200% "Markdown" "Source"
box rad 10px "Markdown" "Formatter" "(markdown.c)" fit
arrow right 200% "HTML+SVG" "Output"
arrow <-> down 70% from last box.s
box same "Pikchr" "Formatter" "(pikchr.c)" fit

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

---
title: Order example
---
erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

anna-docs

Anna Documentation

Table of Contents #

Directory structure #

Description of the directory structure #

Building layouts #

PageURL #

Elements stored in DeepDataMerge #

Layout Partials #

How Partials Work #

Example Partial Structure #

Creating and Using Partials #

Best Practices for Partials #

Common Partial Patterns #

Accessing specific page data #

Custom template functions #

Frontmatter #

Important - The frontmatter field cannot be omitted #

Frontmatter #

Important - The frontmatter field cannot be omitted #

Frontmatter Examples #

Basic Page Frontmatter #

Draft Post #

Custom Layout #

Collection Page #

Accessing Frontmatter in Templates #

Body #

Static assets #

Images #

CSS #

Development Workflow #

Building the Site #

Basic Build #

Using Make #

Live Reloading #

File Watching #

Troubleshooting #

Common Issues #

Missing Frontmatter Error #

Template Execution Errors #

Missing Layout Files #

Broken Links in Rendered Output #

Images Not Loading #

Collection Pages Not Generating #

Tag Pages Not Working #

Site configuration #

Sample config.json #

Quick Start

Installation

MacOS

GNU/Linux (tar.gz):

Windows 10/11 (x86_64):

Bootstrap (create a site/ directory)

Usage

Basic render

Serve with live reload

Version and debug

Developer Guide

Repository layout (high level)

Build & run

Benchmarks & profiling

Makefile targets

Contribution workflow

Development tips

Building anna

Introduction

The small but big decision

What's in a name?

Genesis

What made us develop this to a great extent?

Benchmarks! Can anna lift??

We cook! 🍳

Profiling

Live Reload

Initial version

Improvements

Browser reload (WIP)

A big rewrite (when we went for a TDD approach)

A new proposed rendering system

main.go

Elements stored in `DeepDataMerge` #

Sample `config.json` #

Bootstrap (create a `site/` directory)

Entire `yake` sourcecode!