Magnet Docs v1.1.7 archive docs
tag → docs (8)

Themes and Templates

Themes

Themes are simply sets of assets like css and templates. These are grouped into named folders. Using a theme means declaring the name of the theme directory in the settings file. See “theme-name” in site settings.

Templates

Using the Go templating format.

Debugging problems in Go templates can be frustrating. Forget the final “{{end}}” in your conditions? Yeah, Go is gonna explode without much help. Use what I’ve put in demo generated by “go-magnet new” as a starting point.

In the source code, see structs.go particularly PageData and Pagination structs for specifics, as well as the Post struct.

PageData

When a page is built using a template, magnet populates some PageData for you to use in the templates.

https://codeberg.org/83h3m07h/go-magnet/src/branch/master/structs.go#L84

Author

String. Author name.

Endpoint

String. Possible values:
+ “tag”
+ “rss-tag”
+ “author”
+ “rss-author”
+ “post”
+ “custom”
+ “home”
+ “rss-home”
+ “archive”

MagnetURL

String. URL to the git repo.

PageName

String. A title if there is one.

PageTags

[]Strings. A list of unique tags contained in the entries of this page.

PageTitle

String. The SiteName and relevant string.

Pagination

Struct Pagination. See Pagination in structs.

Posts

[]Post. A list of Posts. See Post in structs.

SiteName

String. Set by settings.SiteName

SiteRemoteAddress

String. Set by settings.SiteRemoteAddress

Tag

String. The currently set Tag if any.

TagsByName

[]Name,Count. A list of tag names and the number of items with it ordered by its Name.

TagsByCount

[]Name,Count. A list of tag names and the number of items with it ordered by Count.

ThemeName

String. The name of the theme.

Version

String. The go-magnet version.

Site Structure

Default Site Structure

You can create a default site with the “new” command, which will have the following basic structure:

|_ magnet
    |_ images
    |_ indices
    |_ posts
        |_ posts.yaml
        |_ hello.md
        |_ (...more posts and post directories)
    |_ static
    |_ temp
    |_ themes
        |_ propeller-2.0
            |_ templates
            |_ assets
    |_ site.yaml

These are the default locations but can be overridden in the site.yaml.

Of particular note are the “images” and “static” directories, you may want to have these somewhere else entirely, for instance, if you have nginx serving from a www-data directory you’ve already setup.

But you should be able to begin right away by using the existing defaults.

Posts Structure

The “posts” directory contains the markdown for posts.

The name of the directory “posts” here is arbitrary — it can be called anything as long as it is:

1.) a subdirectory of "magnet"
2.) has its own posts.yaml file inside of it.

There can be multiple “posts” directories. These are searched for recursively.

This allows for some organization of posts on your part and maybe some portability if you are using or collecting the markdown from other sources. For instance, a script that reads Instagram’s API and writes markdown files into a directory called “instaposts” or something. For instance:

|_ magnet
    |_ images
    |_ insta-posts
        |_ posts.yaml
        |_ (...various md files)
    |_ my-blog
        |_ posts.yaml
        |_ (...various md files)
        |_ my-topic
            |_ posts.yaml
            |_ (...various md files)
    |_ joes-posts
        |_ posts.yaml
        |_ (...various md files)
    |_ static
    |_ themes
    |_ indices
    |_ site.yaml

Settings Structure

Settings are kebab-case yaml. There are two type of settings files, “site.yaml” and “posts.yaml”.

See the Post Settings Field Reference for those yaml files.

See the Site Settings Field Reference for the primary site settings yaml.

Site Settings

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.

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

String. A list of simple page names, e.g. “about, contact”. 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/
---------------^--------

guess-title

Bool. The default is false.

If true, and there is no title in the markdown metadata, a title will be taken from the first H1 if that exists.

# Test Post

Here's some content.

The title field for templating in this case, if guess-title is set, would be “Test Post”.

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

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-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 it since RSS needs wants to use full addresses.

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.

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"

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

Commands

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 if they are found in posts.

new

Will create a new blog structure with example posts and docs 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 (new posts, changes in metadata and so on).

show

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