Tag: docs
Endpoints
The server router can be found here.
Endpoint Patterns
ID ¶
lowercase a-z, uppercase A-Z, numerals 0-9, between 2 characters and 64 characters
page numbers ¶
numeric 0-9, between 1 and 12 digits
Available Endpoints
home ¶
/
/page/(pageNum)/
tag ¶
/tag/(ID)/
/tag/(ID)/page/(pageNum)/
author ¶
/author/(ID)/
/author/(ID)/page/(pageNum)/
post ¶
/post/(ID)/
feed ¶
/index.xml
archive ¶
/archive/
robots ¶
/robots.txt
custom pages ¶
/s/(ID)/
assets ¶
/assets
images ¶
/images
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.
Page Data ¶
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
EndPoint string
MagnetURL string
Pagination
PageTitle string
Posts []Post
SiteName string
SiteRemoteAddress string
Tag string
Tags ItemsCount
TagsByName []NameCount
TagsByCount []NameCount
ThemeName string
Version string
Structure
Default Structure ¶
You can see the default installed structure by running the “new” command:
|_ magnet
|_ posts
|_ posts.yaml
|_ 20230501-my-post.md (post filenames...)
|_ static
|_ images
|_ indices
|_ themes
|_ propeller-1.0 (theme names...)
|_ 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
|_ markdown-files...
|_ my-blog
|_ posts.yaml
|_ markdown-files...
|_ my-topic
|_ posts.yaml
|_ markdown-files...
|_ joes-posts
|_ posts.yaml
|_ markdown-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
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.
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-fetch-exts ¶
List. Default is [“gif”, “png”, “jpg”, “jpeg”].
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.
robots-file ¶
String. The location of the robots.txt file. The default location is in the “templates-dir”, robots.txt.
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 of the external, remote site to which you’ll push the HTML. Used for templating. The default is empty, set this for your XML feed template, or adjust the XML template accordingly.
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. The full path of a directory where the templates for the server are kept. These need to be written in the Go templating format. See the templates included in the initial install for examples.
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"]