JSSG - Jtremesay's Static Site Generator

An ever evoluting thing that propulse jtremesay.org.

Specifications

It's not a generic static site generator. It's really tailored to my needs for jtremesay.org. For most of its life, the code of jssg was merged with the content of jtremesay.org. I moved it to a separate repo because some crazy people wanted to use it for profesisonal stuff‽‽‽.

My needs:

• I want to write my content on my computer with adapted tools, not in a shitty WSYIWYG editor in a web app
• I want the content in files in a git repository, not a in database
• I don't want to write HTML. The content should use markdown or whatever
• I need to be able to use a templating in the content. Sometime, I'm too lazy too write the content myself. It's really nice to have things like table automatically generated from a csv file or ect…
• Since everything is files and in git, use a CI/CD to build and deploy the site
• I don't need a backend or a database
• Fully static so easy to deploy / host on anything. FTP and RSYNC POWA!
• 2024-06-13: provide jssg as a django app instead of a django project so people can easily integrate it
• deployed on a docker swarm cluster on my kimsufi server, so I can be flex on what I use (just an containered nginx with a copy of the site)
• should be easy to use it locally (writting content / front stuff) and work on it

History

JSSG was successively:

• a flask app (dynamic)
• a thing that use python + jinja + a very cerative use of makefile
• a django project that can generate a fully static site + rss + processed static files
• the same, but with distill for the generation part

It's currently:

• a django app

In the future, it will become:

• TBD

Installation

1. Install JSSG from the repo (no pypi package provided at this time):

python3 -m pip install --user https://github.com/jtremesay/jssg.git

2. Update proj/settings.py to add the JSSG:

INSTALLED_APPS = [
    ...,
    "jssg",
]

3. Update proj/urls.py:

from jssg.utils import jssg_urls

urlpatterns = [
    # ...
]

# Automatically declare urls for pages, posts and rss feed
urlpatterns += jssg_urls()

Configuration

You need to set the following variables in your settings.py:

• JSSG_RSS_LINK: str: The base URL of your site, used in the rss feed
• JSSG_RSS_TITLE: str: The description of your site in the rss feed

Content

Just put your md files in yourapp/content/posts and yourapp/content/pages and JSSG will autodiscover them.

The content of the file is processed by the django template engine before being rendered as markdown. So you can use the full power of the template language.

Page

Ex:

---
title: Hello, world!
slug: index
---
## bla bla bla

bla bla bla

Post

Ex:

---
title: Hello, world
date: 2023-05-31T20:00+02:00
---
bla bla bla

A page with django templating!

---
title: Hello, world!
---
{% load static %}

An image:
![A cat]({% static 'yourapp/images/cat.jpg' %})

A js app:
<div id="myjsapp"></div>
<script src="{% static 'yourapp/js/myjsapp.js' %}">

A table generated from a csv:
{% csv_table 'yourapp/files/data.csv' %}

Templating

You need to provide the page.html and post.html template.

In the template, you will have access to the object variable that is the instance of the Page or Post model.

Ex:

{% extends "base.html" %}

{% block "content" %}
Published {{ object.timestamp|date:"Y-m-d" }}.

<h1>{{ object.title }}</h1>
{{ object.content_md|safe }}
{% endblock %}

Usage

Local

Just use the good old ./manage.py runserver and build your site like a regular django project

Generate site

When your are happy with your site, you can generate the static version with distill:

./manage.py distill-local --collectstatic --force dist

The dist folder contains the generated .html files and the collected statics. You can now rsync it to your webserver or whatever.