Tags And Authors

Metadata at the top of each Markdown post can include Tags and/or an Author.

---
title: "More About Rocks"
publish: 2025-03-01 10:00:00
tags: rocks
author: "Susan Essay"
summary: "More than you ever wanted to know about rocks..."
---

Also, Tags and/or an Author can be included in the Post Settings file:

---
name: "Susan's Posts"
archive: true
blogroll: true
author: "Susan Essay"
tags: geology

Tags for each post are amended — so if the post meta has tags “things, stuff” and the post settings has “geology” then the published post will have the tags “things, stuff, geology”.

Author in only a single value, so it is not amended but is set — so all posts in a directory with this posts.yaml file will have the Author “Susan Essay” without having to put it into every posts’ metadata.

Images

Including Local Images ¶

Including images in a post is done in Markdown.

Take a look at the file “posts/images.md”, you’ll see that there are local images and remote images in the markdown. This one for instance:

Including Remote Images ¶

You can include images from remote sources by using the remote url in the markdown. The image will be pulled down and placed into your images directory, and it should only do this once.

Since we can’t rely on the original name being well-formed or unique, the remote image gets renamed when it is saved. See which image extensions are the default here.

Images Index ¶

An image index is created in the “indices” directory so that remote images are only pulled down once. If you need to re-pull images either edit or remove the “images.json” file in the “indices” directory.

Images Error Index ¶

If there’s an error pulling down a remote image, information is left in the “images-err.json” file in indices. There’s a waiting period before the image can be retried, to be polite to remote servers, which is set here.

Post IDs & Custom IDs

You might want to use a custom URI for a posts:

---
title: "Using A Custom Post ID"
publish: 2025-03-16 12:13:13
id: thingstuff
tags: about-ids
summary: "Showing a custom ID..."
---

This will be served under:

http://127.0.0.1:8081/post/thingstuff/

where “thingstuff” is used instead of the filename of the post markdown. The filename of this post is “custom-id.md” (you can name posts whatever you want), so without the ID set in metadata the local url would look like:

http://127.0.0.1:8081/post/custom-id/

If there are more than one files named the same (across different post directories for instance) the ID will have a small random suffix added to prevent collision.

A good practice is to name files with two pieces of information, say, date and title. For instance:

20230330-custom-ids.md

Naming like this, consistently, means you’ll be able to easily glance over the file tree to see your posts and also likely avoid naming two files the same thing. One of the purposes of Magnet is to keep everything within a human scope — instead of building and querying a database about your posts, simply use a file tree of plaintext.

Basic HTML

Basic HTML should render properly.

Here’s a table:

cell one

cell two

An H3, p tag:

Test

And this paragraph has a p tag with a css class.

Complex HTML alongside markdown may not render properly, so stick with markdown as much as you can.

Custom Pages

However markdown may be too restrictive — sometimes you may need a custom page instead of a post. See the “about” page. The file for “about” lives in the “templates” directory instead of one of the markdown directories. In Site Settings you’ll see “custompages: about”, which tells Magnet to look for an “about.html” file in templates. If you want to add a new custom page, add a name there and a “name.html” in “templates”. The content for the about page looks like:

{{define "content"}}

<h1>Some Custom page</h1>

<h2>Thing</h2>

This is a custom page. Some more text.

{{end}}

Custom pages are written in HTML, not markdown.

See the “define” part? That puts the content inside the layout template.

Create a new custom page — copy the “about.html” page and name it “contact.html”. Change the Site Settings “site.yaml” line from

custom-pages: about

to

custompages: about, contact

These pages are not posts, they don’t end up in the blogroll or the archive, they are indepedent and you’ll have to call them out in your templates.