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”.

---
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!”

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]

|_ 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.