aurora-ssg 0.0.4

A fast static site generator implemented in Python.

Aurora

Aurora is a static site generator implemented in Python.

Demo

https://github.com/capjamesg/aurora/assets/37276661/59e4f3e6-f470-46bd-8812-0b475be40e88

Get Started

Install Aurora

First, install Aurora:

pip3 install aurora-ssg

Create a Site

To create a new site, run the following command:

aurora new my-site

This will create a folder called my-site with everything you need to start your Aurora site.

To navigate to your site, run:

cd my-site

Aurora sites contain a few directories by default:

• _layouts: Store templates for your site.
• assets: Store static files like images, CSS, and JavaScript.
• posts: Store blog posts (optional).
• pages: Store static pages to generate.

A new Aurora site will come with a pages/index.html file that you can edit to get started.

Build Your Site (Static)

You can build your site into a static site by running the aurora build command.

Aurora works relative to the directory you are in.

To build your site, navigate run the following command:

aurora build

This will generate your site in a _site directory.

Build Your Site (Dynamic)

For development purposes, you can run Aurora with a watcher that will automatically rebuild your site when you make changes to any page in your website.

To run Aurora in watch mode, run the following command:

aurora serve

Your site will be built in the _site directory. Any time you make a change to your templates, the _site directory will be updated to reflect those changes.

Development Setup

If you are interested in contributing to Aurora, you will need a local development setup.

To set up your development environment, run the following commands:

git clone https://github.com/capjamesg/aurora
cd aurora
pip3 install -e .

This will install Aurora in editable mode. In editable mode, you can make changes to the code and see them reflected in your local installation.

Configuration

You need a config.py file in the directory in which you will build your Aurora site. This file is automatically generated when you run aurora new [site-name].

This configuration file defines a few values that Aurora will use when processing your website.

Here is the default config.py file, with accompanying comments:

import os

BASE_URLS = {
    "local": os.getcwd(),
}

SITE_ENV = os.environ.get("SITE_ENV", "local")
BASE_URL = BASE_URLS[SITE_ENV]
ROOT_DIR = "pages" # where your site pages are
LAYOUTS_BASE_DIR = "_layouts" # where your site layouts are stored
SITE_DIR = "_site" # the directory in which your site will be saved
REGISTERED_HOOKS = {} # used to register hooks (see `Build Hooks (Advanced)` documentation below for details)

The BASE_URLS dictionary is used to define the base URL for your site. This is useful if you want to maintain multiple environments for your site (e.g., local, staging, production).

Here is an example configuration of a site that has a local and staging environment:

BASE_URLS = {
    "production": "https://jamesg.blog",
    "staging": "https://staging.jamesg.blog",
    "local": os.getcwd(),
}

Build Hooks (Advanced)

You can define custom functions that are run before a file is processed by Aurora. You can use this feature to save metadata about a page that can then be consumed by a template.

These functions are called "hooks".

To define a hook, you need to:

1. Write a hook function with the right type signature, and;
2. Add the hook function to the HOOKS dictionary in your config.py file.

For example, you could define a function that saves the word count of a page:

def word_count_hook(file_name: str, page_state: dict, site_state: dict):
    if "posts/" not in file_name:
        return page_state

    page_state["word_count"] = len(page_state["content"].split())
    return page_state

Suppose this is saved in a file called hooks.py.

This function would make a page.word_count available in the page on which it is run.

Hooks must return the page_state dictionary, otherwise the page cannot be processed correctly.

To register a hook, create an entry in the REGISTERED_HOOKS dictionary in your config.py file:

REGISTERED_HOOKS = {
    "hooks": ["word_count_hook"],
}

Above, hooks corresponds to the name of the Python file with our hook, relative to the directory in which aurora build is run. (NB: aurora build should always be run in the root directory of your Aurora site.) word_count_hook is the name of the function we defined in hooks.py.

You can define as many hooks as you want.

To register multiple hooks in the same file, use the syntax:

REGISTERED_HOOKS = {
    "hook_file_name": ["hook1", "hook2", "hook3"],
}

Performance

In a test on a website with 1763 files, Aurora built the website in 0:00:04.23.

The files were a combination of blog posts, static pages, and programmatic archives for blog posts (date pages, category pages).

Users

The following sites are built with Aurora:

• James' Coffee Blog (1,500+ pages)

Have you made a website with Aurora? File a PR and add it to the list!

License

This project is licensed under an MIT license.