# Marmite
[**Mar**kdown **M**akes s**ite**s] is a **very!** simple static site generator.
## How it works
It does **"one"** simple thing only:
- Reads all `.md` files on the `content` folder
- Using `CommonMark` parse it to `HTML` content
- Renders each content using templates from the `templates` folder
- Outputs the rendered static site to the `site` folder.
[](http://www.gnu.org/licenses/agpl-3.0)
## Installation
Install with cargo
```bash
cargo install marmite
```
Or download the pre-built binary from the [releases](https://github.com/rochacbruno/marmite/releases) page.
## Write the content
1. Initialize the project
This command creates the initial folder structure
> **NOTE** this command is not implemented yet.
```bash
marmite init myblog
```
For now `copy and paste` the [example](example/) folder
Folder structure will be
```plain
myblog
├── marmite.yaml # Site configuration
├── content
│ ├── about.md # Page on the menu
│ └── first-post.md # Post on the timeline
├── static
│ └── style.css # Empty CSS
└── templates
├── base.html # Common HTML
├── content.html # Renders page and post
└── list.html # Renders index, tags, archive
```
2. Edit the configuration
> All keys are optional, but you probably want to set at least `name`,`tagline`, `url`
`marmite.yaml`
```yaml
name: My Blog
tagline: This blog is awesome
url: https://www.myblog.com
# pagination: 10
# footer: This is an example site generated with Marmite
# list_title: Blog Posts
# tags_title: Tags
# content_path: content
# templates_path: templates
# static_path: static
# media_path: content/media
# site_path: site
```
3. Write your content
Drop Markdown files with `.md` extension on the `content/` folder.
**Pages vs Posts**
- Post: If it has a `date` property it is considered a post to show in the index posts list.
- Page: If it does not have a `date` it is considered a page to show in the menu.
**Metadatada**
Front matter is used in yaml format.
```
---
date: "2024-01-01"
title: Title
slug: title
tags: comma,separated,tags
tags:
- yaml
- list
- also
- works
show_in_menu: true
---
```
- **date**: If informed, the content is considered a `Post` and shows in index list.
- **title**: If not defined, the first line of the markdown content is used.
- **slug**: If not defined, the filename is used to build the url.
- **tags**: Optional
- **show_in_menu**: if content is a page (has no date) then it is added in the menu (this field has no effect for posts).
All fields are optional, if nothing is declared then the content is considered a `Page` that does't show in the listing, neither rss or menu. (useful for drafts, or pages accessible with link only.)
**Example Post**
`content/first-post.md`
````markdown
---
date: "2024-01-01"
title: My First Blog Post
slug: my-first-blog-post
tags: poetry,life
---
# Hello this is my first post
This blog was generated by `Marmite` the simplest static site generator
I can have local images as along as those are located on the `static` folder.
## Images
I can also have remote images
## Code Snippets
```python
de foo():
return "bar"
```
````
### Build the site
```console
$ cd myblog
$ marmite .
Site generated at: site/
```
Now take the output of `site/` and deploy it.
> **NOTE** marmite does not serve the site **yet**, it will do for edevelopment purposes soon, use `python -m http.server` inside the site folder for now.
### editors and deployment
Marmite does not come with an editor but as the content is simply markdown files, **any** text editor will work!
Generated site is pure HTML + CSS so it can be served on **any** static webserver.
Workflow is generally:
- Create a new `content/your-content-title.md`.
- Edit in your preferred **editor** (There are some with good preview support).
- Add the `date` metadata when it is ready to publish.
- commit to your preferred **repository**.
- use your preferred **automation system** to publish it to your preferred **web server**.
Common examples:
- Edit in **Marktext** Editor, configure it to move pasted images to `static/img`, commit to Github, Add an action to build and Publish as a Github Page.
- Edit directly in the Github Web UI, commit, let CI Action to build and publish.
- Edit in **vim**, Generate the site locally, Publish via FTP.
- Edit in **VsCode**, Commit to Git Repository, Have the CI to build and Publish (GH pages, netlify etc)
> Marmite focus on generating the site from markdown only, the deployment and media management is a separate problem to solve.
## That's all!
**Marmite** is very simple, and limited in functionality, there is no intention to add more features or built-in themes.
If this simplicity does not suit your needs, there are other awesome static site generators.
Here are some that I recommend:
- Cobalt
- Zola