shodo-ssg

Shodo Static Site Generator 🪶✒️📜

Shodo is a framework for rapidly building a static site from markdown files, json, and Jinja templates. Simply make changes to your site in the src directory, run the build command, and access the build in the dist directory. Easily deploy to Netlify in just a few clicks.

Check out shodo.dev for the latest project updates and documentation!

Why Shodo?

There is no shortage of options out there for building websites and apps, but they can quickly feel overcomplicated when all you need is a simple website with a few reusable components, or a quick solution to setting up a blog with an RSS feed. The goal of Shodo is to make publishing content to the web as simple and elegant as possible for developers, whether it's a personal blog, a portfolio, documentation, or a professional marketing site.

Key Features:

• ✅ Write content in Markdown with front matter support
• ✅ Powerful Jinja2 templating with custom API functions
• ✅ Query JSON data with filtering, sorting, and pagination
• ✅ Automatic page generation from markdown articles
• ✅ Built-in pagination for article listings
• ✅ RSS/Atom feed generation support
• ✅ Nested layouts and partial templates
• ✅ Fast build times with automatic asset compilation

Getting Started

Installing the package

• Create a new project directory and start a virtual environment using your preferred method

• Install the shodo_ssg package by running one of the following commands:

Via pip:

pip install shodo-ssg

Via pipenv:

pipenv install shodo-ssg

Via Poetry:

poetry add shodo-ssg

Via uv:

uv add shodo-ssg

• Once the package is installed, you can scaffold a new project using the command

start-shodo-project <name of project directory>

To create the project in the current directory, run

start-shodo-project .

• Build the starter site and serve it to localhost by running the following command from the root directory of the project:

python serve.py

You should now be able to view the site on localhost and can start by making changes to home.jinja. When you simply want to build the static site, run the following command from the root directory:

python site_builder.py

and you can find your static site located in the dist/ directory

Docs

Visit shodo.dev/docs to learn more!

Project Conventions

Jinja templates

For all jinja templates, use the .jinja file extension. Other extensions such as .j2 or .jinja2 are not fully supported at this time.

Syntax Highlighting

If you're using VSCode, the Better Jinja extension is recommended for full syntax highlighting out of the box using the .jinja extension. Other extensions will work, although you might need to configure the settings to look for the .jinja extension.

For Contributors

This project uses the Black Formatter and follows the current style guide

Pulling down the repository and installing locally

• Start up a virtual environment and install the dev dependencies using your preferred method after pulling down the repository

• Once your virtual environment is activated, in the root of the project directory run pip install -e .

• Upon successful install, navigate to an entirely separate directory and run

start-shodo-project <name of new project directory>

Upon success, a new starter project template should have been set up in the specified directory