A simple static site generator for blog style websites.
- Python 3
- Install the required packages with
pip install -r requirements.txt
- Fork this repository
- Update the content in the
sample
directory to your liking - Optionally rename the
sample
directory to something else and update the 'source' entry inconfig.yaml
- Run
py build.py
to generate the site - The generated site will be in the _site directory
Optionally, you can run py watch.py
run a local server and automatically rebuild the site when changes are made. It will host at http://localhost:8000.
The configuration is stored in config.yaml
. The following options are available:
title
: The title of the site. This can be referenced in templates as{{ title }}
description
: A description of the site. This can be referenced in templates as{{ description }}
source
: The directory where the source files are stored. Defaults tosrc
destination
: The directory where the generated site will be stored. Defaults to_site
base_url
: The base URL of the site. This can be referenced in templates as{{ base_url }}
. All relative URLs will use the base URL as the root.
HTML files are copied to the destination directory, and any mustache tags are replaced with the corresponding values from the configuration file.
Markdown files are converted to HTML and then processed as HTML files.
Collections are groups of pages that can be accessed in templates. For example, a collection of blog posts could be accessed in a template as {{ collections.posts }}
.
To create a collection, just create a new folder in the source directory and add md files to it. The folder name will be the collection name and you can access the collection in templates as {{ collections.<collection_name> }}
.
You can create an index.html file in the collection directory to create an index page at the root of the collection folder.
You can create an _item.html file in the collection directory to create a template for each item in the collection, otherwise a simple dump of the content is used (or the _default template if provided).
The items are markdown files in the collection directory. Each item needs to have a title
property. Optionally, you can add a date
property to sort the items by date. The date should be in the format YYYY-MM-DD
. You can also add a category
property to categorize the items. See sample/things
for an example.
Any other properties you add to the item will be available in the template for the item.
The following properties are available on collections:
items
: A list of all the items in the collection that you can loop through. Items are sorted bydate
in descending order if the property exists on the item, otherwise, they will be sorted bytitle
in ascending order.categories
: If your items contain acategory
property, this will be a list of all the unique categories. Each category contains aname
and a list ofitems
that belong to that category. Seesample/things
for an example.
You can create reusable HTML snippets in the _includes
directory. These can be included in other files using the mustache syntax {{{ filename-without-extension }}}
.
You can create default layouts for items by creating an _item.html
file in the _defaults
directory. This will be used as the template for each item in the collection rather than a simple dump of the content. This can be overridden by creating an _item.html
file in the collection's directory.
You can find a live example at https://github.com/kylecorry31/kylecorry31.github.io