zeta-sharp/swallow

★ 0PythonAudience · developerComplexity · 2/5ActiveLicenseSetup · moderate

Mindmap

mindmap
  root((Swallow))
    Inputs
      Markdown per language
      YAML frontmatter
      Site settings
    Outputs
      Static HTML site
      SPA transitions
      Lazy loaded extensions
    Use Cases
      Publish a multilingual blog
      Lazy load embeds
      Generate static pages
    Tech Stack
      Python
      Jinja2
      Alpine.js
      Poetry

mindmap root((Swallow)) Inputs Markdown per language YAML frontmatter Site settings Outputs Static HTML site SPA transitions Lazy loaded extensions Use Cases Publish a multilingual blog Lazy load embeds Generate static pages Tech Stack Python Jinja2 Alpine.js Poetry

Things people build with this

USE CASE 1

Publish a personal blog with every post written in two or more languages

USE CASE 2

Host a static site on any plain web server without a runtime

USE CASE 3

Lazy-load Twitter embeds or Prism.js code highlighting only on pages that declare them

USE CASE 4

Use SPA-style article navigation with prefetch to avoid white-flash transitions

Tech stack

PythonJinja2Alpine.jsPoetry

Getting it running

Difficulty · moderate Time to first run · 30min

Needs Python 3.14 and Poetry, and every article must have a translated version for each configured language or the build fails.

MIT license, so you can use, modify, and redistribute it freely as long as you keep the copyright notice.

In plain English

Swallow is a static site generator, sometimes shortened to SSG, written in Python with the Alpine.js library for the browser side. A static site generator takes Markdown files plus templates and produces plain HTML pages, which you can host on any web server. The author describes Swallow as minimal and fast, and the project's tagline is about conveying your words without walls of language. It is released under the MIT license and runs on Python 3.14 with Jinja2 templates. The distinguishing feature is multi-language blogging. If you want to publish the same article in several languages, you write one Markdown file per language with a suffix like _en.md or _ja.md. Every article must have a translated version for each configured language, otherwise the build will fail. The README notes that a default-message fallback for missing translations is being considered for a future update. Swallow also does on-demand loading of extensions on the client side. Instead of always shipping every helper script, the generator inspects each article's frontmatter for an extensions list, like Twitter or codeblock, and only loads the matching scripts (for example the Twitter embed widget or Prism.js for code highlighting) when an article actually needs them. The third main feature is an SPA-like transition between articles: when you follow an internal link, only the main content area swaps in, with prefetching to avoid blank white screens. Installation has four steps: clone the repo, run poetry install to fetch Python dependencies, run swallow init to enter settings such as the target output directory, then write articles in the markdown folder. Each article uses YAML frontmatter with required fields for per-language title and summary, a date that becomes the article's ID and file name, optional tags, optional extension declarations, and an optional draft flag that tells Swallow to skip generation. The author welcomes contributions for new extensions, new themes, and bug fixes, and plans to add a CONTRIBUTING.md later.

Copy-paste prompts

Prompt 1

Set up Swallow with Poetry, run swallow init, and generate a sample bilingual post in English and Japanese

Prompt 2

Add a new extension to Swallow that lazy-loads a math rendering script only on articles that declare math in frontmatter

Prompt 3

Implement the default-message fallback for missing translations that the README says is planned

Prompt 4

Write a new Jinja2 theme for Swallow with a dark mode toggle and a tag index page

Prompt 5

Add a draft preview server that watches the markdown folder and rebuilds on save

Open on GitHub → Explain another repo

Generated 2026-05-22 · Model: sonnet-4-6 · Verify against the repo before relying on details.