What’s a static site generator? ¶
Instead of work being done in an application on a remote server, like a CMS (WordPress for instance), work is done locally by Magnet to create the final set of HTML that you then put on a server or S3 or similar setup. Where you put the HTML is up to you.
What are the advantages? ¶
Speed. Without an application or scripting language, the serving of flat HTML pages is faster than creating them on the server.
Security. There’s no application or database or admin endpoints needed on the server for the site, just plain HTML.
Why write in Markdown? ¶
It’s simple, clean, helps removes distraction. If you write creatively it’s not going to get in your way. Markdown is plain text so you can use whatever editor you want. Basic Markdown syntax here.
Take a minute to read more. For settings reference and structure look at the docs here.
If you’re looking at this in a browser then you already ran the “go-magnet show” command.
go-magnet <COMMAND> -path<PATH>
Try stopping it and re-running it. You’ll need to stop and restart when you add posts, when you change tags or other metadata. If you’re just adding or editing text in existing posts, you can leave it running and refresh the view in the browser.
Try it now, go to one of the Markdown files in the posts directory and change some text then refresh the page in the browser.
See more about commands.
You’ll see a “site.yaml” file at the root of the magnet directory. You’ll also see “posts.yaml” files inside directories where posts live.
Try this, stop the “go-magnet show” command, open the “site.yaml” file and change the “pagesize: 5” line to “pagesize: 20”.
Restart go-magnet. You need to restart because this is a change that effects metadata and indices.
You’ll see that the number of posts shown on a single page has changed.
The page layout is a template that lives in the currently used theme. Open up “themes/propeller-1.0/templates/layout.html”. You should see some fairly basic HTML as well as some variables rendered by magnet. Note however, the “block content” section. This block is filled in by the “index.html” file, where the HTML for these posts lives. Changing the “layout.html” and “index.html” files lets you render the site very differently. For instance, in the site settings (“site.yaml”) change the value
theme-name: propeller-1.0
to
theme-name: simple-1.0
and restart magnet, you’ll see different templating and css applied.
Including Local Images ¶
Including images in a post is done in Markdown.
Take a look at the file “posts/images.md”, you’ll see that there are local images and remote images in the markdown. This one for instance:
Including Remote Images ¶
You can include images from remote sources by using the remote url in the markdown. The image will be pulled down and placed into your images directory, and it should only do this once.
Since we can’t rely on the original name being well-formed or unique, the remote image gets renamed when it is saved. JPG, PNG or GIF can be included this way.
Images Index ¶
An image index is created in the “indices” directory so that remote images are only pulled down once. If you need to re-pull images either edit or remove the “images.json” file in the “indices” directory.