wlls.dev / verso
This repository has no description
Star
Fork 0
Watch
Gleam 92%
CSS 8%
6 1 0
content
docs
src
static
test
.gitignore
gleam.toml
manifest.toml
readme.md
readme.md

Verso #

Verso is a fullstack Gleam exploration. The first working slice is a reusable static-site core plus wlls_blog, a dogfood site that will become Devon Wells' real blog.

The immediate goal is to keep the core primitives agnostic of any specific blog while using them to build a real site with real content, routes, styles, and publishing needs.

Current Status #

Implemented:

  • Reusable verso/* modules for Markdown documents, frontmatter, Markdown rendering, and output helpers
  • Concrete wlls_blog/* site using those primitives
  • Markdown posts with YAML frontmatter in content/posts/
  • Frontmatter parsing with taffy
  • Markdown rendering with mork
  • HTML page rendering with nakai
  • Static site generation into dist/
  • Wisp/Mist development server on http://localhost:4000
  • RSS feed generation at /feed.xml
  • Sitemap generation at /sitemap.xml
  • Shared content/render pipeline for static build and dev server
  • Parsed post dates with newest-first ordering
  • Typed site metadata and route helpers
  • Seed content migrated from the prior blog into plain Markdown

Generated output directories are intentionally ignored:

  • build/
  • dist/

Usage #

Install dependencies and compile:

gleam build

Run the static site generator:

gleam run -m wlls_blog build

This writes:

  • dist/index.html
  • dist/blog/<slug>/index.html
  • dist/feed.xml
  • dist/sitemap.xml
  • dist/static/*

Run the development server:

gleam run -m wlls_blog serve

The server listens on http://localhost:4000 and reloads posts from content/posts/ on each request.

Run tests:

gleam test

Format, build, generate, and test:

gleam format && gleam build && gleam run -m wlls_blog build && gleam test

Content #

Posts live in content/posts/*.md and use YAML frontmatter:

---
title: "Example Post"
topic: "Engineering"
date: "Apr 13 2026"
description: "A short description for indexes and feeds."
archive: true
---

Post body in Markdown.

Required fields:

  • title
  • topic
  • date, formatted as Mon D YYYY
  • description

Optional fields:

  • archive, defaults to false

Architecture #

Reusable core modules:

  • src/verso/content.gleam: generic Markdown document loading
  • src/verso/frontmatter.gleam: YAML frontmatter parsing and typed field helpers
  • src/verso/markdown.gleam: Markdown/frontmatter splitting and Markdown-to-HTML rendering
  • src/verso/output.gleam: generic output directory, file writing, and static asset helpers

Dogfood site modules:

  • src/wlls_blog.gleam: command entrypoint for build and serve
  • src/wlls_blog/build.gleam: concrete static output plan
  • src/wlls_blog/server.gleam: concrete Wisp/Mist development server
  • src/wlls_blog/content.gleam: maps generic documents into typed blog posts
  • src/wlls_blog/render.gleam: page, post, feed, and sitemap templates
  • src/wlls_blog/site.gleam: wlls.dev site metadata
  • src/wlls_blog/routes.gleam: wlls.dev path and absolute URL helpers
  • src/wlls_blog/date.gleam: current blog date parsing and sort helpers

Static build and development server both use wlls_blog/content and wlls_blog/render, so generated output and served output stay aligned. The reusable verso/* layer has no dependency on wlls_blog.

Routes #

The development server supports:

  • /
  • /blog/:slug
  • /feed.xml
  • /sitemap.xml
  • /static/*

Dependencies #

Primary libraries:

  • taffy for YAML frontmatter
  • mork for Markdown parsing/rendering
  • nakai for HTML generation
  • wisp and mist for the development server
  • fio for filesystem access
  • str for HTML/XML escaping
  • gleeunit for tests

License #

AGPL-3.0-or-later