gossamer-ssg

v0.1.0

Published

2 months ago

Static site generator that's actually simple

0High
0Medium
0Low

katieblackabee

static-site-generator markdown simple blog

Gossamer

Static site generator that's actually simple. Zero JavaScript by default. Builds in milliseconds, not the heat death of the universe.

Live Example - See what it outputs

Why Another Static Site Generator?

Because Gatsby has 1,847 dependencies. Because Next.js wants to be everything to everyone. Because Hugo's templating language was designed by someone who hates joy.

Gossamer does one thing: turns markdown into HTML. It does this quickly, with sensible defaults, and without requiring a PhD in configuration file syntax.

Install

npm install -g gossamer-ssg

Or if you prefer the scenic route:

git clone https://github.com/katieblackabee/gossamer.git
cd gossamer
npm install
npm run build
npm link  # makes 'gossamer' command available globally

Quick Start

# Create a new site
gossamer new my-site
cd my-site

# Build it
gossamer build

# Or serve with live reload
gossamer serve

That's it. You now have a website. No 47-step configuration process. No YAML files that are longer than your actual content.

CLI Commands

`gossamer new <directory>`

Creates a new site with starter files. Includes an index page, about page, and a sample blog post so you're not staring at an empty folder wondering what to do next.

gossamer new my-blog

`gossamer build [directory]`

Builds your site to _site/ (or wherever you want with --output).

# Build current directory
gossamer build

# Build specific directory
gossamer build ./my-site

# Custom output
gossamer build --output ./public

`gossamer serve [directory]`

Starts a development server that actually watches for changes and rebuilds. Like magic, except it's just filesystem events.

# Serve current directory
gossamer serve

# Custom port for the commitment-phobic
gossamer serve --port 8080

How It Works

Markdown files (.md) become HTML
Static assets (CSS, JS, images) get copied as-is
Your layout wraps each page (or you use the beautiful default)
Posts in posts/ get a generated index

No build plugins. No middleware. No "ecosystem." Just files in, files out.

File Structure

my-site/
  index.md          -> _site/index.html
  about.md          -> _site/about.html
  style.css         -> _site/style.css (copied)
  images/
    logo.png        -> _site/images/logo.png (copied)
  posts/
    2024-01-15-hello.md -> _site/posts/hello.html
    2024-01-20-world.md -> _site/posts/world.html
                        -> _site/posts/index.html (generated)
  _layout.html      -> (template, not copied)

Ignored Files

Files starting with . or _ are ignored:

.gitignore, .DS_Store - dotfiles
_layout.html, _draft.md - underscore-prefixed
node_modules/, dist/, _site/ - common build directories

Front Matter

Add YAML at the top of your markdown files like a normal person:

---
title: My Page Title
date: 2024-01-15
author: Katie
draft: true
---

# Content starts here

Supported Fields

| Field | Description | |-------|-------------| | title | Page title (auto-extracted from first H1 if you're lazy) | | date | Publication date (YYYY-MM-DD) | | draft | If true, the page won't be built. Procrastination, codified. | | layout | Custom layout file (future feature) | | anything | Your custom fields work in templates too |

Custom Layouts

Create _layout.html in your site root:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>{{title}} | My Site</title>
  <link rel="stylesheet" href="/style.css">
</head>
<body>
  <nav>
    <a href="/">Home</a>
    <a href="/about.html">About</a>
  </nav>
  <main>
    {{content}}
  </main>
  <footer>Built with Gossamer, stubbornness, and caffeine</footer>
</body>
</html>

Template variables: {{content}}, {{title}}, {{date}}, {{slug}}, plus any custom front matter fields.

Per-Directory Layouts

Different sections can have different looks:

my-site/
  _layout.html          <- default
  posts/
    _layout.html        <- blog posts use this
  docs/
    _layout.html        <- docs use this

Gossamer walks up the directory tree to find the nearest _layout.html. It's smarter than it looks.

Posts

Files in posts/ are treated as blog posts:

Sorted by date (newest first, like God intended)
Auto-generated index at /posts/index.html
Dates can be in filename (2024-01-15-hello.md) or front matter

Default Theme

Without a custom layout, Gossamer uses a default theme that's actually good:

Clean typography optimized for reading
Automatic dark mode (follows system preference)
Responsive design
Styled code blocks, tables, blockquotes
No JavaScript

You can build an entire blog and never touch CSS. Though you'll probably want to eventually. That's fine.

Philosophy

Markdown in, HTML out. That's the whole job.
Beautiful defaults so you can ship something today.
No configuration required. Zero-config is possible when you're not trying to do everything.
No JavaScript in output unless you put it there.
Builds in milliseconds because life is short.

Troubleshooting

"Command not found: gossamer"

npm link  # In the gossamer directory

Changes not showing up

The dev server watches for changes, but if it's being stubborn:

Stop the server (Ctrl+C)
Delete _site/
gossamer build && gossamer serve

Posts not appearing

Must be in a posts/ directory
Must not have draft: true in front matter
Must exist (check your file path)

License

MIT