This page does not exist. Go back to the homepage.
================================================ FILE: docs/pages/templates/archives.md ================================================ --- title: Date, Category, and Tag Archives layout: default permalink: /archives/ --- Aurora has support built-in for generating date, category, and tag archives. These are useful for blogs. ## Date Archives Aurora automatically generates date archives for blog posts. You do not need to configure any setting to use this feature. Date archives are generated as follows: - `https://example.com/2024/`: All posts published in 2024. - `https://example.com/2024/01/`: All posts published in January 2024. - `https://example.com/2024/01/01/`: All posts published on January 1, 2024. ## Category and Tag Archives Aurora automatically generates category and tag archives. These archives are generated if you specify `category` and/or `tag` attributes in your blog post front matters. Category archives are generated as follows: - `https://example.com/category/SITE_STATE = {
"category_slug_root": "categories",
"tag_slug_root": "tags",
}Aurora has out-of-the-box features designed for use with blogs.
Write a Blog Post
To use Aurora as a blog, create a markdown file with the following name structure in your pages/posts directory:
YYYY-MM-DD-title.mdFor example, 2020-01-01-hello-world.md.
Within this file, you can specify front matter and, optionally, jinja2 templating.
Here is an example:
---
title: Hello, World!
layout: post
---
This is our first blog post.
This will be rendered as a blog post using the "pages/_layouts/post.html" file.
Aurora automatically turns your permalink into a URL. For example, the above file will be available at https://example.com/2020/01/01/hello-world/.
Categories and Tags
Aurora can automatically generate archive pages for categories and tags.
Categories and tags are treated as two separate collections.
To use this feature, you need to give at least one blog post a category or a tag, like so:
---
title: Hello, World!
layout: post
categories:
- Announcement
---
This is our first blog post.
Categories and tags are not case-sensitive.
You then need to specify either a category or tag layout file, depending on which you want to support.
To do so, create a file called category.html or tag.html in your pages/_layouts directory.
This file will have access to a page.posts variable that lists all posts in the category or tag.
Here is an example of a category layout file:
{% raw %}
---
layout: default
title: "Category Archive"
---
<ul>
{% for post in page.posts %}
<li>
<a href="{{ post.url }}">{{ post.title }}</a>
</li>
{% endfor %}
</ul>
In this example, a page at /category/announcement/index.html will be generated.
Date Archives
Aurora can automatically generate date pages for categories and tags.
Date archives show all posts published on a specific day.
There is not currently support for month-based or year-based archives.
To use this feature, you need to have at least one blog post.
You then need to specify a date archive layout.
To do so, create a file called date.html in your pages/_layouts directory.
This file will have access to a page.posts variable that lists all posts published on a specific day.
Here is an example of a category layout file:
{% raw %}
---
layout: default
title: "Date Archive"
---
<ul>
{% for post in page.posts %}
<li>
<a href="{{ post.url }}">{{ post.title }}</a>
</li>
{% endfor %}
</ul>
In this example, a page at /2024/01/01/index.html will be generated, which lists one entry: the hello world post we wrote earlier in this guide.
Now you have a blog set up with Aurora! 🎉
================================================ FILE: docs/pages/templates/build-methods.md ================================================ --- title: Build Methods permalink: /build-methods/ layout: default --- There are three ways you can build your Aurora site: 1. Full build 2. Incremental build 3. Interactive, incremental build ## Full Build A full build generates your entire website. Your site is saved in `_site`, ready for serving. To build your site, navigate to the root directory of your project (the folder with the `config.py` file in it), and run:aurora buildaurora build --incrementalTip: Incremental builds support CSV and JSON data files.
## Interactive, Incremental Build An interactive, incremental build generates your full site. It starts a web server through which you can preview pages. When you make a change to any file, the changed file -- and its dependencies -- are re-built and made available over the server. Any open browser tabs that are viewing the site will automatically refresh to show the changes. This mode is intended for development. With interactive, incremental building, you can see changes to your site as you make them, without having to wait for your full site to build, and without having to manually refresh your browser. To run an interactive, incremental build, navigate to the root directory of your project and run:aurora serveNote: The interactive server should not be used in production.
================================================ FILE: docs/pages/templates/collections-from-data.html ================================================ --- title: Create a Collection from Data permalink: /collections-from-data/ layout: default ---You can turn data from JSON and CSV files into web pages.
This is useful if you have a data set that you want to turn into a website.
For example, you could export a list of coffee shops you have visited from a spreadsheet and turn the list into a static website.
Create a Collection
JSON
To create a collection from a JSON file, add a new file to your site's
pages/_data directory. This file should have a
.json extension.
Within the file, create a list that contains JSON objects, like this:
[
{
"slug": "rosslyn-coffee",
"layout": "coffee",
"title": "Rosslyn Coffee in London is terrific."
}
]
This file is called
pages/_data/coffee.json.
Every entry must have a layout key. This corresponds
with the name of the template that will be used to render the page. For
example, the coffee layout will be rendered using the
pages/_layouts/coffee.html template.
Every entry must also have a slug key. This corresponds
with the name of the page that will be generated. In the case above, one
file will be created in the _site output directory:
_site/coffee/rosslyn-coffee/index.html.
CSV
To create a collection from a CSV file, add a new file to your site's
pages/_data directory. This file should have a
.json extension.
Here is an example CSV file:
slug,layout,title
rosslyn-coffee,coffee,Rosslyn Coffee in London is terrific.
Your CSV file must have a header row that contains the keys for each entry.
This file is called
pages/_data/coffee.csv.
Every entry must have a layout key. This corresponds
with the name of the template that will be used to render the page. For
example, the coffee layout will be rendered using the
pages/_layouts/coffee.html template.
Every entry must also have a slug key. This corresponds
with the name of the page that will be generated. In the case above, one
file will be created in the _site output directory:
_site/coffee/rosslyn-coffee/index.html.
Create a Collection
JSON
To create a collection from a JSON file, add a new file to your site's
pages/_data directory. This file should have a
.json extension.
Within the file, create a list that contains JSON objects, like this:
[
{
"slug": "rosslyn-coffee",
"layout": "coffee",
"title": "Rosslyn Coffee in London is terrific."
}
]
This file is called
pages/_data/coffee.json.
Every entry must have a layout key. This corresponds
with the name of the template that will be used to render the page. For
example, the coffee layout will be rendered using the
pages/_layouts/coffee.html template.
Every entry must also have a slug key. This corresponds
with the name of the page that will be generated. In the case above, one
file will be created in the _site output directory:
_site/coffee/rosslyn-coffee/index.html.
CSV
To create a collection from a CSV file, add a new file to your site's
pages/_data directory. This file should have a
.csv extension.
Here is an example CSV file:
slug,layout,title
rosslyn-coffee,coffee,Rosslyn Coffee in London is terrific.
Your CSV file must have a header row that contains the keys for each entry.
This file is called
pages/_data/coffee.csv.
Every entry must have a layout key. This corresponds
with the name of the template that will be used to render the page. For
example, the coffee layout will be rendered using the
pages/_layouts/coffee.html template.
Every entry must also have a slug key. This corresponds
with the name of the page that will be generated. In the case above, one
file will be created in the _site output directory:
_site/coffee/rosslyn-coffee/index.html.
---
title: My Page
collections: coffee
---{% raw %}{% for item in coffee %}{% endraw %}
{{ item.title }}
{% raw %}{% endfor %}{% endraw %}
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
HOOKS = {} # used to register hooks (see Hooks documentation for details)
SITE_STATE = {}Base URLs
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(),
}
See Also
================================================ FILE: docs/pages/templates/dates.html ================================================ --- layout: default title: Date Handling permalink: /dates/ ---Aurora has several default filters that you can use to handle dates.
- long_date - Converts a date to a long format, e.g. "January 01, 2020"
- date_to_xml_string - Converts a date to an XML string, e.g. "2020-01-01T00:00:00"
- archive_date - Converts a date to a format suitable for archivess, e.g. "2020/01"
- month_number_to_written_month - Converts a month number to a written month, e.g. "01" to "January"
These filters can be used like:
{% raw %}{{ date | long_date }}
{{ date | date_to_xml_string }}
{{ date | archive_date }}
{{ date | month_number_to_written_month }}{% endraw %}I have written several blog posts that explore the design, inspiration, and development of Aurora.
See a list of these posts below.
- Announcing Aurora
- Implementing Incremental Static Regeneration in Aurora
- Designing Aurora, a new static site generator
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".
There are three types of hooks, which run:
- As a jinja2 filter you can access on all pages (
template_filtershook) - Immediately before a page is generated (
pre_generationhook) - After your site has built (
post_buildhook)
To define a hook, you need to:
- Write a hook function with the right type signature, and;
-
Add the hook function to the
HOOKSdictionary in yourconfig.pyfile.
Below are instructions on how to define each type of hook.
Filter Hooks
Filter hooks are registered as a jinja2 filter.
These hooks are useful for manipulating specific values in a template (i.e. formatting dates, changing text).
The type signature of this hook is:
def hook_name(text: str) -> str:
return text.upper()
You can register this hook in the template_filter hook:
HOOKS = {
"template_filter": {
"example": ["hook_name"]
}
}
This hook can then be used in any template on your website:
<h1> "hello world" | hook_name </h1>
Pre-Generation Hooks
Pre-generation hooks run immediately before a page is generated.
These hooks are useful for adding state to a page for use in rendering (i.e. loading link prveiews from a cache, calculating reading times.)
The type signature of this hook is:
def hook_name(file_name: str, page_state: dict, site_state: dict) -> dict:
return page_state
You can register this hook in the template_filter hook:
HOOKS = {
"pre_generation": {
"example": ["hook_name"]
}
}
Post-Build Hooks
Post-build hooks run after your site has been built.
These hooks are useful for performing actions after your site has been built (i.e. saving a log of last generation time, invoking CSS/JS minification).
The type signature of this hook is:
def hook_name(site_state: str) -> None:
pass
You can register this hook in the template_filter hook:
HOOKS = {
"post_build": {
"example": ["hook_name"]
}
}
Aurora is a static site generator implemented in Python.
With Aurora, you can generate thousands of static web pages in seconds.
Aurora supports:
- Static generation, with support for jinja2 logic
- Incremental Static Regeneration (ISR) with hot reloading
- Markdown and HTML content
- Generating pages from CSV and JSON files
Aurora is open source, and licensed under an MIT license.
Build your first website with Aurora.
Demo
================================================ FILE: docs/pages/templates/pagination.md ================================================ --- title: Pagination layout: default permalink: /pagination/ --- You can generate pagination pages for collections. This is ideal if you have a collection with many items that you want to split into multiple pages for ease of navigation. ## Usage To set up pagination, first [create a collection](/collections/). Then, create a new layout in your `_layouts` directory. This layout will be used to generate the pagination pages. This page can access the `page.___` variable, where `___` is the name of the collection (i.e. `page.books` would reference the `page.books` collection). This variable is an array of all the items in a given page in the collection. To see the current page number, reference the `page.page_number` variable. Finally, add a `paginators` key to the `SITE_STATE` value in your `config.py` file:SITE_STATE = {
"paginators": {
"books": {
"per_page": 10,
"template": "books"
}
}
}In a test generating 292,884 files from a CSV file with a single layer of inheritance in each template, Aurora built the website in 140.59 seconds (2m:20s).
In a test on a website with 1,763 files and multiple layers of inheritance, Aurora built the website in 3.149s. The files in this test were a combination of blog posts, static pages, and programmatic archives for blog posts (date pages, category pages).
In a test rendering 4,000 markdown files with a single layer of inheritance in each template, Aurora built the website in between 0.9 and 1.2 seconds.
In a test comparing 11ty to Aurora in generating the Airport Pianos website (~45 pages), 11ty took 1.36 seconds to start and generate the site, whereas Aurora took 0.034 seconds.
================================================ FILE: docs/pages/templates/permalinks.html ================================================ --- title: Set a Permalink layout: default permalink: /permalinks/ ---You can define custom permalinks for a page in its front matter.
To do so, specify the permalink key:
---
title: Book List
permalink: /books/
layout: default
---The page above will be generated with the path /books/.
robots.txt files let you tell search engines which pages they can and can't index.
To define a robots.txt file, create a file called robots.txt in your pages/templates/ directory.
Here's an example of a robots.txt file that lets all bots crawl all pages, and points to your sitemap for reference:
User-agent: *
Allow: /
Sitemap: /sitemap.xml
See Also
================================================ FILE: docs/pages/templates/sitemap.html ================================================ --- title: Set a Sitemap layout: default ---To define a sitemap, create a file called sitemap.xml in your pages/templates/ directory and add the following code:
{% raw %}<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
{% for page in site.pages %}
{% if not page.noindex %}
<url>
<loc>
{{ page.url }}
</loc>
<lastmod>{{ site.build_time }}</lastmod>
</url>
{% endif %}
{% endfor %}
</urlset>{% endraw %}Learn how to create a website with Aurora.
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
cd my-site
This will create a folder called
my-site with everything you need to start your Aurora site.
There are two ways to run Aurora:
- aurora build: This command builds your site into a folder called
_site, which you can view on your file system. - aurora serve: This command builds your site and starts a local server at
http://localhost:8000on which your site will run. This is ideal for development.
To see your site locally, run:
aurora serve
This will start a local server at
http://localhost:8000 on which your site will run.
When you are ready to publish your site, you can run:
aurora buildThis will build your site into a folder called _site, which you can then upload to a web server.
You have started an Aurora website 🎉.
Next up: Add a page to your website.
================================================ FILE: docs/pages/templates/state.html ================================================ --- title: State permalink: /state/ layout: default ---There are three types of state in Aurora: page, post and site.
Page State
Page state stores values that are only available on that page.
For example, consider the following template:
---
title: Hello, World!
layout: default
---
Welcome to the website!
Any value in the front matter is stored in the page state. This state can be accessed using:
{% raw %}{{ page.title }}{% endraw %}Tip
You can access the name of the template from which a page was generated with:
{% raw %}{{ page.generated_from }}{% endraw %}This is useful if you want to make a public edit page to a GitHub repository, like the one in the footer of this documentation.
Post State
Post state stores information about a blog post.
You can access post state on any template that is used by a post.
For example, consider the following template called pages/_layouts/post.html for rendering a blog post:
---
layout: default
---
<h1>{% raw %}{{ post.title }}{% endraw %}</h1>
<p>{% raw %}{{ post.content }}{% endraw %}</p>
Here, we access the title and content of the post using the post state.
This template (pages/_layouts/post.html) inherits from the default layout, and could be used on any blog post with:
---
layout: post
title: Hello, World!
---
...
Site State
Page state stores values that are global to the website.
You can access site state on any page.
By default, site state contains:
- A list of your posts (
site.posts) - The root URL of your site (
site.root_url) - The build date of your site (
site.build_date) - A list of all pages in your site (
site.pages)
For example, consider the following template:
---
title: Blog Home
layout: default
---
{% raw %}
<ul>
{% for post in site.posts[:5] %}
<li>
<a href="{{ post.url }}">{{ post.title }}</a>
</li>
{% endfor %}
</ul>
{% endraw %}
Here, we iterate over the first five posts in the site state and display them on the page.
The above code could be used on a home page to display the most recent posts.
You can add custom values to your site state by adding to the SITE_STATE dictionary in your config.py file:
SITE_STATE = {
'site_version': os.getenv('SITE_VERSION', '1.0.0')
}
When you create a new Aurora site, some folders and files are created by default.
Below is a list of those files.
├── _site # where your generated site is stored
│ └── index.html
├── assets # where to store your CSS, JS, and images
├── config.py # your Aurora configuration
└── pages # any page in this directory is generated
├── _data # store JSON / CSV files to be used in generating pages
├── _layouts # page layouts
├── posts # blog posts
└── templates # store single pages to generate
└── index.html
See Also
================================================ FILE: docs/pages/templates/templates.md ================================================ --- title: Templates permalink: /templates/ layout: default --- Below are templates you can use to get started with Aurora.-
Blog
-
Documentation
================================================
FILE: docs/pages/templates/templating.md
================================================
---
title: Templating with Jinja2
layout: default
permalink: /templating/
---
Aurora supports using [jinja2](https://jinja.palletsprojects.com/en/3.1.x/) to create template logic.
jinja2 is a popular Python templating engine with support for variable interpolation, conditionals, loops, and more.
You can use jinja2 in any HTML or markdown document in your Aurora project.
Here is an example of a Jinja2 template that defines a blog home page:
```html
---
title: Blog
layout: default
permalink: /blog/
---
-
James' Coffee Blog (1,500+ pages)
-
Airport Pianos (~45 pages)
-
Train Station Pianos (~20 pages)
-
Aurora Documentation (~10 pages)
- Study Hall
- Quiet Corner
- {{ post.title }} {% endfor %}
- {{ post.title }} {% endfor %}
- {{ room.title }} {% endfor %}
- {{ post.title }} {% endfor %}
- {{ book.title }} - {{ book.author | capitalize }} {% endfor %}
Blog
{% for post in site.posts %}{{ post.title }}
{{ post.content }}
{% endfor %} ``` ================================================ FILE: docs/pages/templates/users.html ================================================ --- title: Users layout: default ---The following sites are built with Aurora:
If you would like your site to be featured here, please submit a pull request to the Aurora GitHub repository.
================================================ FILE: docs/state.json ================================================ {"last_build": "2024-06-22T19:51:46.751675", "data_file_integrity": {"pages/test/apple/index.html": "542b47f9fbb9dca05694183f48c8fe925e193b45", "pages/test/banana/index.html": "f49e2e069c37a6fc12809ba2db409db23cccfba9", "apple": "542b47f9fbb9dca05694183f48c8fe925e193b45", "banana": "f49e2e069c37a6fc12809ba2db409db23cccfba9"}} ================================================ FILE: requirements.txt ================================================ jinja2 livereload toposort pyromark~=0.9.3 python-frontmatter requests progress click orjson tqdm chardet bs4 ================================================ FILE: setup.py ================================================ import re import setuptools from setuptools import find_packages with open("./aurora/__init__.py", "r") as f: content = f.read() # from https://www.py4u.net/discuss/139845 version = re.search(r'__version__\s*=\s*[\'"]([^\'"]*)[\'"]', content).group(1) with open("README.md", "r", encoding="UTF-8") as fh: long_description = fh.read() setuptools.setup( name="aurora-ssg", version=version, author="capjamesg", author_email="readers@jamesg.blog", description="A fast static site generator implemented in Python.", long_description=long_description, long_description_content_type="text/markdown", url="https://github.com/capjamesg/aurora", install_requires=[ "jinja2", "livereload", "toposort", "pyromark>=0.6,<0.10", "python-frontmatter", "requests", "progress", "click", "orjson", "tqdm", "python-dateutil", "chardet", "bs4" ], include_package_data=True, package_data={"": ["templates/index.html"]}, packages=find_packages(exclude=("tests",)), entry_points={ "console_scripts": [ "aurora = aurora.cli:main", ], }, extras_require={ "dev": [ "flake8", "black==25.11.0", "isort", "twine", "pytest", "wheel", "mkdocs-material", "mkdocs", ], }, classifiers=[ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ], python_requires=">=3.7", ) ================================================ FILE: tests/fixtures/about.html ================================================We serve 100 readers every month.
================================================ FILE: tests/fixtures/about_ISO-8859-1.html ================================================A test of a file encoded with ISO-8859-1.
We serve 100 readers every month.
================================================ FILE: tests/fixtures/about_UTF-16-BE.html ================================================A test of a file encoded with UTF-16 BE.
We serve 100 readers every month.
================================================ FILE: tests/fixtures/about_Windows-1252.html ================================================A test of a file encoded with Windows-1252 .
We serve 100 readers every month.
================================================ FILE: tests/fixtures/book.html ================================================The Great Gatsby
F. Scott Fitzgerald
================================================ FILE: tests/fixtures/book_list.html ================================================Books
================================================ FILE: tests/fixtures/category_archive.html ================================================Posts from 2024
Below are the posts we wrote in 2024.
================================================ FILE: tests/fixtures/date_year_month.html ================================================Posts from 2024/01
Below are the posts we wrote in 2024/01.
================================================ FILE: tests/fixtures/date_year_month_day.html ================================================Posts from January 01, 2024
Below are the posts we wrote on January 01, 2024.
================================================ FILE: tests/fixtures/index.html ================================================Welcome to the library!
================================================ FILE: tests/fixtures/new_site_config.py ================================================ import os BASE_URLS = { "local": os.getcwd(), "production": "https://example.com", } SITE_ENV = os.environ.get("SITE_ENV", "local") BASE_URL = BASE_URLS[SITE_ENV] ROOT_DIR = "pages" LAYOUTS_BASE_DIR = "_layouts" SITE_DIR = "_site" HOOKS = {} SITE_STATE = {} ================================================ FILE: tests/fixtures/post.html ================================================This is our first blog post.
================================================ FILE: tests/fixtures/review.html ================================================James
An excellent book.
5/5 stars
================================================ FILE: tests/fixtures/robots.txt ================================================ User-Agent: * Allow: / ================================================ FILE: tests/fixtures/styles.css ================================================ * { font-family: San system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif; } ================================================ FILE: tests/fixtures/tag_archive.html ================================================{{ page.title }}
{{ page.author }}
================================================ FILE: tests/library/pages/_layouts/category.html ================================================ --- layout: default title: "Category Archive" ----
{% for post in page.posts %}
Posts from {{ page.date | year }}
Below are the posts we wrote in {{ page.date | year }}.
{% endif %} {% if page.date_type == "month" %}Posts from {{ page.date | archive_date }}
Below are the posts we wrote in {{ page.date | archive_date }}.
{% endif %} {% if page.date_type == "day" %}Posts from {{ page.date | long_date }}
Below are the posts we wrote on {{ page.date | long_date }}.
{% endif %}-
{% for post in page.posts %}
{{ page.name }}
{{ page.review }}
{{ page.star }}/5 stars
================================================ FILE: tests/library/pages/_layouts/rooms.html ================================================ --- layout: default title: Rooms ----
{% for room in page.current_page %}
-
{% for post in page.posts %}
Quiet Corner
================================================ FILE: tests/library/pages/rooms/study-hall.html ================================================ --- title: Study Hall layout: default collection: rooms ---Study Hall
================================================ FILE: tests/library/pages/templates/about.html ================================================ --- title: About layout: default ---We serve {{ page.visitors }} readers every month.
================================================ FILE: tests/library/pages/templates/about_ISO-8859-1.html ================================================ --- title: About ISO Test layout: default ---A test of a file encoded with ISO-8859-1.
We serve {{ page.visitors }} readers every month.
================================================ FILE: tests/library/pages/templates/about_Windows-1252.html ================================================ --- title: About Windows-1252 Test layout: default ---A test of a file encoded with Windows-1252 .
We serve {{ page.visitors }} readers every month.
================================================ FILE: tests/library/pages/templates/book_list.html ================================================ --- title: Book List permalink: /book-list/ layout: default ---Books
-
{% for book in site.books %}