pysocha

Pysocha is a static site generator of as simple a variety as we can make for our needs.

It reads Markdown content and Jinja templates. It writes a directory of files. No code runs on the server.

It still has features like search for large sites, rss and atom feeds, and extra files for things like favicons.

Installation

Pysocha needs Python 3.8 or newer.

python -m pip install pysocha

With uv:

uv tool install pysocha

Direct from this repository:

python -m pip install git+https://github.com/catalystcommunity/pysocha.git

For work on Pysocha itself, use uv from the repository root:

uv sync
uv run pysocha --help

Quickstart

Make a site with this shape:

site/
  config.yaml
  content/
    pages/
      index.md
    blog_posts/
      first-post.md
    extra_files/
      main.css
  templates/
    page.jinja2
    blog.jinja2
    listing.jinja2
    tags.jinja2
    tag.jinja2
    authors.jinja2
    author.jinja2

Write a page in content/pages/index.md:

---
Title: "Welcome"
---

# Welcome

This is the first page.

Write a post in content/blog_posts/first-post.md:

---
Title: "The first post"
PostedDate: "2026-07-14T10:00:00-06:00"
Author: "Your Name"
AuthorEmail: "you@example.com"
hook: "A short summary for feeds and listings."
---

Hello.

Write config.yaml. Every key has a default, so a short file is enough:

siteTitle: "My site"
siteAddress: "https://example.com/"
blogConfig:
  title: "My blog"
  blogBaseDir: "blog"

Build the site:

pysocha build --config-file config.yaml

Look at the site:

pysocha preview --config-file config.yaml

Pysocha writes the files into outputDir. The default is generated.

What Pysocha does

• Markdown pages, with one body or with named regions.
• Blog posts, listing pages, tag pages, and author pages.
• Atom feeds and RSS feeds.
• Syntax highlighting at build time, with no style sheet.
• Search in the browser, with more than one search for each site.
• Staged output. A failed build never replaces a good site.

Documentation

The docs directory holds the details:

• Configuration — every key and its default.
• Content — pages, blog posts, front matter, and regions.
• Markdown — syntax highlighting and themes.
• Feeds — Atom and RSS.
• Search — search configuration and the two providers.
• Search providers — how to write your own.
• Build behavior — commands, staged output, and preview.

Example sites

• example/ in this repository. It shows every feature, and it includes a search page for each provider.
• todpunk/tnl-site — the content of todandlorna.com.

Licence

Apache-2.0.