Getting Started

Let me show you how to use this static site generator to create your own site!

Prerequisites

You'll need:

  • Python 3.10 or higher
  • uv package manager installed
  • A Neocities account (for deployment)

Installation

  1. Clone or download the project
  2. Install dependencies with uv:
uv sync
  1. Create a .env file with your Neocities credentials:
NEOCITIES_USERNAME=your_username
NEOCITIES_PASSWORD=your_password

Creating Content

Just create markdown files in the content/posts directory with frontmatter:

---
title: My Post Title
date: 2025-10-26
tags: [tag1, tag2]
---

Your content here...

Building the Site

Generate your static site:

uv run build

This will create all HTML files in the output directory.

Customizing

  • Edit templates in templates/
  • Modify styles in static/css/style.css
  • Add images or other assets to static/

Deploying

When you're ready to publish:

uv run deploy

Your site will be live on Neocities!

Tips

  • Use meaningful filenames - they become URLs
  • Add excerpts to frontmatter for better previews
  • Keep your markdown clean and simple
  • Test locally before deploying

Happy hacking!