What is marmite

Marmite is a simple, easy and opinionated static site generator, probably the easiest and simple to use.

Marmite is written in Rust so it is very fast and everything is included in a single binary.

You can use it to generate a static blog, starting with the built-in theme and then fully customize if you want a more personalized website.

To generate your static site the only thing you need is a folder with some markdown files and marmite

assuming you have a folder called mycontent containing files with .md extension such as about.md,first-post.md,second-post.md

$ marmite mycontent mysite

Generated /mysite/about.html
Generated /mysite/first-post.html
Generated /mysite/second-post.html
...

Site generated at: /mysite

That is all you need to have a blog like this generated:

CLICK HERE TO SEE SOME SCREENSHOTS

The following screenshots are using the default embedded templates (from /example folder)

Light Mode

Index:

Index Light

Content:

Post Light

Dark mode

Index:

Index Dark

Content:

Post Dark

Content Types

Marmite separates content in two kinds, posts and pages.

An opinionated decision of marmite is how it makes this distinction,

Post

If content has a date it is a Post

If the file.md has a FrontMatter (metadata on its first lines) defining a date: YYYY-MM-DD field, or the date field is extracted from the file name YYYY-MM-DD-file.md

Posts are shown on index.html page sorted by date, and also shown on tag/{tag}.html page, and included on the RSS and JSON feeds.

Page

If the markdown file does't define a date, then marmite can't list it on index or feeds, because it doesn't know where to include it in the chronological order, so it makes sense to render this content as a {slug}.html and make it accessible only via the link directly.

Menu

By default marmite includes 3 items in the main menu:

  • Pages -> pages.html
    • List of pages in alphabetical order.
  • Tags -> tags.html
    • List of tags and a link to each tag group page.
  • Archive -> archive.html
    • List of YEAR and link to each year group page.

Menu can be optionally customized in the configuration file, it is possible to add any post, page or external link to the menu.

Metadata

On each markdown file it is possible to define metadata on the FrontMatter, the first lines of the file separated by ---.

---
field: value
---

# title

Content

marmite supports 5 fields:

  • title: This is the post title
    • default: extracted from the first line of markdown.
  • slug: this-is-the-post-slug
    • default: title or filename slugified.
  • date: YYYY-MM-DD
    • default: extracted from filename or null.
  • tags: tag1, tag2, tag3
  • extra: {}
    • arbitrary extra key:value pair in YAML format (for template customization)

Media

Images can be added using the normal markdown tag, marmite doesn't have shortcodes yet.

For local images you have to put the files in a folder named media in the content folder.

# content with media

![Image here](./media/subfolder/image.png)

Marmite will copy your media folder to the output site, it is recommended to use ./media as the URL for relative media.

Site Config

Optionally, a file named marmite.yaml inside your content folder (together with your .md files) can be used to customize configuration.

--config file.yaml can also be passed directly to the CLI.

example:

name: My Blog
tagline: Poems, Essays and Articles
url: https://mysite.com/blog
menu:
  - ["About", "about.html"]
  - ["Projects", "projects.html"]
  - ["Contact", "contact.html"]
  - ["Github", "https://github.com/rochacbruno"]

Other options are available and can be viewed on repository

Theme customization

The embedded templates are created with picocss.com and it is easy to customize, just put a style.css in the same folder where the markdown files are located and use anything that pico supports or just be creative with css.

Creating a new Theme

To create a new theme is very simple, you just need to add to your content folder the templates and static directories and then customize in the way you like.

To learn more about how to create a new theme check this post:

Customizing Templates

Hosting

The result is a static site, so you can host it in any web server, examples:

  • Github pages
  • Gitlab pages
  • Netlify
  • Vercel
  • Nginx
  • Apache

More features

There are more to come, marmite will include soon support for the most simple and popular comment systems.

Also, on of the goals is to integrate with ActivityPub via the JSON feed and Hatsu.

If you have ideas please open issues on the repository.

That's all!