Hello

This is version 1.1.7 (2025-04) ¶

See the changelog here.

What’s a static site generator? ¶

Instead of work being done in an application on a remote server, like a CMS (WordPress for instance), work is done locally by Magnet to create the final set of HTML that you then put on a server or S3 or similar setup. Where you put the HTML is up to you.

What are the advantages? ¶

Speed. Without an application or scripting language, the serving of flat HTML pages is faster than creating them on the server.

Security. There’s no application or database or admin endpoints needed on the server for the site, just plain HTML.

Why write in Markdown? ¶

It’s simple, clean, helps removes distraction. If you write creatively it’s not going to get in your way. Markdown is plain text so you can use whatever editor you want. Basic Markdown syntax here.

Take a minute to read more. For settings reference and structure look at the docs here.

Your Site Settings

You’ll see a “site.yaml” file at the root of the magnet directory. See more about the site structure here.

You’ll also see “posts.yaml” files inside directories where posts live.

Try this, stop the “go-magnet show” command, open the “site.yaml” file and change the “pagesize: 5” line to “pagesize: 20”.

Restart go-magnet. You need to restart because this is a change that effects metadata and indices.

You’ll see that the number of posts shown on a single page has changed.

New Posts

Try adding a file named “newest.md” to the “posts” directory that looks like this:

---
title: "This Is The Newest Entry"
tags: test
---

This is a new entry in _Markdown_.

Stop and restart the “go-magnet show” command, you should see the new post at the top since there was no “publish” set in the markdown. It uses the file creation date in that case. You can set “publish” to whatever date you want as long as it fits the “Y-m-d H:m:s” format.

Whenever you change something like a filename, or something in a post’s metadata, you’ll need to restart Magnet. If you’re changing the body of the post, you can simply refresh the page to see your changes.

Removing A Post

If you want to remove a post then delete the markdown file and rerun the “go-magnet show” command or add:

live: false

to the metadata in the markdown of the entry you want to unpublish.

Page Layout

The page layout is a template that lives in the currently used theme. Open up “themes/propeller-2.0/templates/layout.html”. You should see some fairly basic HTML as well as some variables rendered by magnet. Note however, the “block content” section. This block is filled in by the “index.html” file, where the HTML for these posts lives. Changing the “layout.html” and “index.html” files lets you render the site very differently. A single theme is included here…

theme-name: propeller-2.0

…however you can easily copy and rename this directory to whatever you want, changing the html and css to what you like, then put that directory name into the site.yaml file. See more about site structure here.

Be sure to restart the magnet when you change this value.