Markdown
Posts are written in Markdown. They can contain YAML metadata. For instance:
---
title: "Some Title, Be Sure To Use Quotes"
publish: 2020-01-02 10:00:00
---
Here's some __markdown__ text
If no metadata is included, which is perfectly valid, the publish date defaults to file creation time. If there is no metadata title, and settings.GuessTitle is true, the first H1 (the first “#” in markdown) will be used as the title. It is better to set the metadata.
The format of the metadata should be lower case “kebab” to be consistent with the yaml settings files. However, camel case will also work if you prefer it. Mixed cases like “tiTLE” will not work.
Basic HTML is preserved, but complex HTML is not recommended. For this you may want a custom page, which does not parse Markdown (see “custom-page” in site settings)
Some markdown extensions are supported, see https://github.com/yuin/goldmark#built-in-extensions
Markdown Metadata Fields Reference ¶
Regarding the metadata YAML at the top of each markdown file.
While none of these fields are required, title and publish are recommended.
Example
---
title: "More About Weasels"
publish: 2022-01-15 10:00:00
tags: nature
summary: "You didn't know, did you?"
---
The content of my article about weasels here.
Markdown Meta Fields ¶
author ¶
String. The name of the author of the entry. A slug will automatically be generated from the author name with dashes instead of spaces.
author: Susan Essay
date ¶
String. See publish. An alias for compatibility.
expires-days ¶
Int. If set to 1 or greater, the post will expire in N days from the publish date.
id ¶
String. Must be between 2 and 64 alphanumeric characters. Overrides the default URI for the post which is the filename minus the “.md” extension.
For instance, if the markdown file is named “2025-03-01-Thinger.md”, then the post URI is:
/post/2025-03-01-Thinger/
But if you set the id to “my-special-post”, then the URI will be:
/post/my-special-post/
keywords ¶
String. A string of keywords, for instance, for a local search engine or for templating.
keywords: "this, that, the other"
link ¶
String. Unlike the origin-url the link could be used for articles, news or whatever you may want to link to from the post entry in the templating.
live ¶
Bool. Setting this to false will remove it from site generation. Be aware the individual post html may continue to exist in the static site folder even if unlinked to until you re-build the site.
origin-url ¶
String. Let’s suppose you’re pulling down and converting some other data, from Mastodon, or the like. You may want to keep track of where the URL was originally found.
publish ¶
String. The date format is specific here, if it isn’t follow magnet will break.
Publish must match this format:
2019-12-16 10:13:13
Year-Month-Day Hour:Minutes:Seconds
If the date is in the future, magnet will not include the post in site generation until that date is reached.
Posts are ordered by date desc for the archive and blogroll. If there are two posts with the exact same date, the first one seen will be the first one placed in the index. There should be no clobbering in that case.
style ¶
String. If declared you can use this in the post entry markup in the templating.
summary ¶
String. A sentence or two about the post. You can call it out anywhere in templates, particularly the archive endpoint.
tags ¶
String. A comma seprated list of strings that group posts. Tags will be normalized automatically (no spaces, truncated).
For instance:
tags: art, painting, stuff, things
title ¶
String. Generally you should quote the string. Escape interior quotes with slashes. For instance “This \"is my special\" Title!”