6 releases
new 0.1.5 | Oct 22, 2024 |
---|---|
0.1.4 | Oct 20, 2024 |
#13 in Template engine
572 downloads per month
1.5MB
2K
SLoC
Contains (WOFF font, 23KB) Atkinson-Hyperlegible-Regular-102.woff
Marmite
[Markdown Makes sites] is a very! simple static site generator.
How it works
It does "one" simple thing only:
- Reads all
.md
files on theinput
directory. - Using
CommonMark
parse it toHTML
content. - Extract optional metadata from
frontmatter
orfilename
. - Generated
html
file for each page (templates are customizable). - Outputs the rendered static site to the
output
folder.
It also handles generating or copying static/
media/
to the output
dir.
Installation
Install with cargo
cargo install marmite
Or download the pre-built binary from the releases
Usage
~It's simple, really!
$ marmite folder_with_markdown_files path_to_generated_site
Site generated at path_to_generated_site/
CLI
❯ marmite --help
MARkdown Makes sITEs is a very simple static site generator, mainly for simple blogs.
Usage: marmite [OPTIONS] <INPUT_FOLDER> <OUTPUT_FOLDER>
Arguments:
<INPUT_FOLDER> Input folder containing markdown files
<OUTPUT_FOLDER> Output folder to generate the site
Options:
--serve Serve the site with a built-in HTTP server
--bind <BIND> [default: localhost:8000]
--config <CONFIG> Path to custom configuration file (defaults to marmite.yaml) [default: marmite.yaml]
--debug Print debug messages
-h, --help Print help
-V, --version Print version
Build a site from markdown content
Put some markdown in a folder.
myblog
|__ about.md
|__ 2024-01-31-my-first-post.md
|__ another-post.md
Or use your favorite markdown editor to edit.
Then, build:
$ marmite myblog site
building index.html
building pages.html
building tags.html
building archive.html
building feed.rss
building feed.json
building 404.html
building my-page.html
building my-first-post.html
building another-post.html
Site generated at: site/
Result
Site is generated from embedded templates that are purposely very simple!
- Front page lists all blog posts (markdown containing
date
attribute) - Menu is shown with links to
pages
,tags
,archive
(menu is customizable) - Feeds are generated as RSS and JSON formats
- Content pages are generated from every
.md
file
Deploy site/
folder to your favorite webserver.
Open index.html
on your web-browser or run marmite myblog site --serve
to run
the embedded webserver.
Screenshots
CLICK HERE TO SEE SOME SCREENSHOTS
The following screenshots are using the default embedded templates (from /example folder)
Light Mode
Index:
Content:
Dark mode
Index:
Content:
Customization
Marmite allows customization of the website using custom templates
that
are written using Tera
template language (similar to Jinja and Twig).
Site metadata can be customized on marmite.yaml
.
Folder structure
myblog
├── marmite.yaml # Site configuration
├── content
│ └── *.md # Site content
├── static
│ └── *.css|js|ttf # Static files (CSS, JS, Fonts)
└── templates
├── base.html # Common HTML
├── content.html # Renders page and post
├── group.html # Archive and tags list
└── list.html # Renders index, tags, archive
Optional configuration
the marmite.yaml
is optional, you simply omit and use defaults.
All keys are optional, but you probably want to set at least
name
,tagline
,url
marmite.yaml
name: My Blog
tagline: This blog is awesome
url: https://www.myblog.com
# footer: This is an example site generated with Marmite
# pagination: 10
# list_title: Blog Posts
# tags_title: Tags
# archive_title: Archive
# templates_path: templates
# static_path: static
# media_path: media
# menu:
# - ["Title", "link.html"]
# data: Custom key:pair values to be exposed to template context.
Content types
- Post: If
.md
has adate
property on filename prefix orfrontmatter
it is considered a post to show in the index.html posts list. - Page: If it does not have a
date
it is considered a page, listed on pages.html and acessible via direct link.
Metadata
FrontMatter can optionally be specified in yaml
format.
---
date: "2024-01-01"
title: Title
slug: title
tags: comma,separated,tags
tags:
- yaml
- list
- also
- works
---
# Title of my content
Content Text ...
- date: If informed, the content is considered a
Post
and shows in index list.- Date formats supported are
%Y-%m-%d
and%Y-%m-%d %H:%M
- Date can be defined as
date
on frontmatter or in the filename%Y-%m-%d-name.md
- Date formats supported are
- title: If not defined, the first line of the markdown content is used.
- slug: If not defined, the title or filename is used to build the url.
- tags: Optional list or comma separated string of tags.
All fields are optional, if nothing is declared then the content is considered an unlisted Page
.
Example content
content/first-post.md
---
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
## Images
![local image](/media/simple.png)
I can also have remote images
![remote image](https://github.com/rochacbruno/marmite/logo.png)
## Code Snippets
```python
de foo():
return "bar"
```
Everything CommonMark and Github flavoured markdown supports.
</strong>Raw HTML also allowed</strong>
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
media
, 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:
Dependencies
~21–33MB
~515K SLoC