• Magnet Commands
• Markdown and Metadata
• Post Settings
• Site Settings
• Site Structure
• Themes, Templates, Page Data
• Endpoints

The basic process is to create an index of posts, serve those posts, and then build the static site.

go-magnet <COMMAND> -path=<MAGNET DIR PATH>

build ¶

Will run “index” then “serve”, then the “wget” program to capture the site in the “static” directory by default, but you can set it to write where you want. These will be the files you place on your server. Build will only create pages from what it can find exposed in the templating, if you have a custom page, for instance, but do not link to it anywhere, the page will not be generated.

index ¶

Creates the json necessary for lists of entries, for a homepage, archive, tags, author and so on. It will also pull down and index any remote images (by default) if they are found in posts.

new ¶

Creates a new blog structure with example posts and docs (this site) in the current location by creating the directory name you specify. If no path is supplied the directory “magnet” will be created. Follow the instructions after running this command. This command will not create or overwrite existing directories.

serve ¶

Will run “index” then “serve” up the site on an address, “http://127.0.0.1:8081” as the default. You can check your work, change CSS and so on.

You will need to stop the serve and re-run if there are changes that require re-indexing such as adding new posts and changes in metadata.

show ¶

Is a convenience command that runs “index” then “serve”.

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, there will be no Title, and the Publish date will be the file creation date.

You should include 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. Be consistent, use lower case “kebab”.

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)

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 ¶

authors ¶

List. The name of the author of the entry. A slug will automatically be generated from the author name with dashes instead of spaces.

authors: ["Susan Essay", "Marvin Markdown"]

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: "here's my keywords"

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, until you re-build the site.

pin ¶

Bool. Default is false. If you pin one or more posts, they will appear above the rest of the other posts. The pinned posts will be sorted themselves by whatever sort settings you have, Date ASC/DESC, Path ASC/DESC, for instance. The default is Date Desc. See settings.

origin-url ¶

String. Let’s suppose you’re pulling down and converting some other data, from another site, for instance. 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 possible.

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 ¶

List. A comma seprated list of strings that group posts. Slugs will be created from these names for URLs.

For instance:

tags: ["My Art", "Thing Stuff", "And So On"]

title ¶

String. Generally you should quote the string. Escape interior quotes with slashes. For instance “This \"is my special\" Title!”

Posts Settings Field Reference ¶

For every directory within the root of a magnet site (or specified by the “posts-root-dir” setting) that contains a “posts.yaml” file, the markdown found there will be added to the site index. The settings are not cumulative, so that children directories do not inherit their parent directories posts.yaml.

|_ magnet
    |_ site.yaml <-this is the site settings file
    |_ posts
        posts.yaml <- this is a posts settings file
        a-post.md  <- a markdown post entry
        |_ blog-one
            |_ my-post.md <- a markdown post entry
            |_ posts.yaml <-this is a posts settings file
        |_ blog-two
            |_ oh-just-one-more-thing.md <- a markdown post entry
            |_ posts.yaml <-this is a posts settings file

Example posts.yaml

---
name: "my super blog"
skip-archive: false
skip-blog-roll: false
tags: ["My Blog", "Rocks Are Nice"]

Setting “skip-archive” keeps posts from showing up on the archive page. Setting “skip-blog-roll” keeps posts from showing up on the main blog-roll. The default is false.

Post Settings Fields ¶

authors ¶

List. A list of author names for every post in the directory. These will be added to whatever authors are set in individual posts.

expires-days ¶

Int. If set to 1 or greater, the posts in this directory will expire in N days from their Publish date.

name ¶

String. REQUIRED. An identifier in the file that tells magnet this directory contains posts, the name can be arbitrary. This is the only required value.

skip-archive ¶

Bool. Default false. If set to true then posts in the directory don’t appear on the archive page.

skip-blog-roll ¶

Bool. Default false. If set to true then posts in the directory don’t appear on the blog roll.

style ¶

String. If set then the Style markdown meta data for all posts in this directory will have that style string available for templating, to alter with CSS for instance, as “Post.Style”.

tags ¶

String. Just like you would use in markdown in the metadata for a post, tags added here will be applied to all the posts in the directory on indexing in addition to whatever tags are set in the post itself.

tags: [foo, bar]

Site Settings Fields Reference ¶

|_ magnet
    |_ site.yaml <-this is the site settings file
    |_ posts
    |_ images
    |_ ...

See what the “go-magnet new” command generates for the site site.yaml. There is only one required value “sitename”, the rest have defaults which you can override.

Site Settings Fields ¶

assets-dir ¶

String. The full path where the assets like CSS and so on are placed. The default a directory called “assets” in the active theme directory.

assets-path-prefix ¶

String. The uri which will be used in serving the assets as linked from the templates. The default is “assets”.

For instance:

http://my-site/assets/css/site.css
---------------^^^^^^-------------

custom-pages ¶

List. A list of simple page names. The html for these are expected to be found in the “templates-dir” as the name you have added plus “.html”. The name can be alphanum upper and lower case, with a dash.

For instance:

custom-pages: [about, contact, foobar, stuff, Mything-More-Stuff]

There should be several html files in the templates directory in this case:

|_ templates
    |_ about.html
    |_ contact.html
    |_ foobar.html
    |_ stuff.html
    |_ Mything-More-Stuff.html
    |_ ...layout, index, other html files

custom-pages-dir ¶

String. The location of the custom pages html. The default location is the templates-dir.

You might want to set this to a different location per site if you have multiple sites using the same theme.

custom-page-prefix ¶

String. The uri that will be served for custom pages. The default is “/s”. So, for instance:

http://my-site/s/about/
---------------^--------

domain ¶

String. The domain name of your site, if you choose to set it, for templating.

ignore-future-publish ¶

Bool. The default is false. If true, then any future dated post which doesn’t have a meta “live: false” value, will be displayed. Useful for previewing future dated posts.

image-auto-subdir ¶

Bool. Default is false. In cases where you are fetching a lot of images from remote urls, you may not want them all together in one directory, for instance, S3 type buckets — this will create subdirectories from the first two characters (by default) and place the appropriate images there. Be aware that if you toggle this setting back and forth you may be placing images where they later may not be found by the server.

image-auto-subdir-len ¶

Integer. Default is two. Only used if image-auto-subdir is true.

image-dir ¶

String. The full path to where go-magnet will find and store images.

If, on indicing, magnet sees a remote image in markdown, it will pull it down to this directory and serve it from there (unless “image-skip-fetch” is set to true).

image-domain ¶

String. The name of the domain which will be inserted in the final markup for the capured image. If your images are being uploaded to S3 through some mechanism, it would be set here.

image-err-expires ¶

Int. The number of seconds waiting before trying to re-fetch an image given that the image fetch returned an error or 404. The default is 1800.

image-fetch-exts ¶

List. Default is [“gif”, “png”, “jpg”, “jpeg”, “png”, “webp”, “pnj”].

Be aware, this list is currently case sensitive.

image-fetch-timeout ¶

Int. The number of seconds before an image fetch request times out. The default is 3 seconds.

image-full-url ¶

Bool. Default false. Use a full url for the img tag in rendered html. This is always “true” for the RSS endpoint. Requires site-remote-address to be set because otherwise what would the url be? image-domain takes precedent and will be used if set.

image-path-prefix ¶

String. The uri element which go-magnet will use. The default is “images”.

http://my-site/images/da836af924596a4c9154f56dd9be82f5.jpg
---------------^^^^^^-------------------------------------

image-skip-fetch ¶

Bool. Default is false. Skip fetching remote images.

index-dir ¶

String. The path where the json indices are kept. The default is to keep this directory in the root of the magnet directory.

markdown-anchors ¶

Bool. Default is false. When parsing the markdown, magnet automatically creates ids and anchors for each heading element.

page-size ¶

Integer. The number of items in each set of pagination. Default is 10. If you have a lot of posts and want to decrease the size of the static site increase this number.

posts-sort-asc ¶

Bool. If set to true the sort order will be ASC instead of the default DESC.

posts-sort-path ¶

Bool. If set to true the sort will use the relative path name instead of date. The default sort is Date DESC.

posts-root-dir ¶

String. The location which should be crawled to find markdown as entries for the site index. The default is the current magnet directory.

render-xhtml ¶

Bool. When converting markdown into HTML, use XHTML instead. Since the included theme templates are doctype HTML this is set to false by default.

robots-file ¶

String. The location of the robots.txt file. The default location is in the “templates-dir”, robots.txt. When the site is built it wants to also include this robots file.

site-local-address ¶

String. The web address of the local magnet site. The default is “http://127.0.0.1:8081”.

site-remote-address ¶

String. The web address used in URLs for templating. The default is empty.

You should set this since valid RSS needs a full address for URLs.

site-name ¶

String. REQUIRED The name of the site.

site-port ¶

Integer. Defaults to 8081.

static-dir ¶

String. The full path where the “build” of the site using wget will be placed — the static site itself.

Wget is used to crawl against the Go server, using a mirror command, but the root of it will be this “static-dir”.

temp-dir ¶

String. The full path of a directory where temporary work is done on json and images. The default is a “temp” directory inside your magnet directory.

templates-dir ¶

String. Full path of a directory with templates. The default for this is the “template” directory in the theme-name. Included as another way to share a theme across sites.

theme-name ¶

String. The name of the theme in the magnet directory structure. A valid value here must have an appropriately matching directory in the themes folder.

themes-dir ¶

String. The location of the themes directory. The default is “themes” inside your magnet directory.

wget-cmd ¶

Array. A list of strings. This will be the wget command used on the “site-local-address” to write files to the “static-dir”.

Default is: ["-e robots=off", “-nH”, “-m”, “–base=/”, “-P”]. The robots file is pulled in a seprate operation.

For instance, if you wanted to add wget logging, use this in the yaml:

wget-cmd: ["--output-file=wget.log", "-e robots=off", "-nH", "-m", "--base=/", "-P"]

Or, if you want the final links of the static site to be relative (supposing you want to serve it from https://mydomain.com/some-directory/) you could:

wget-cmd: ["--output-file=wget.log", "-e robots=off", "-k", "-nH", "-m", "--base=/", "-P"]

See the Wget documentation here.