Skip to content

Commit 07f434f

Browse files
rochacbrunorochacbruno
authoredOct 20, 2024··
More content on example/demo site (#57)
·
0.2.50.1.5
1 parent 262c5cb commit 07f434f

6 files changed

+320
-12
lines changed
 

‎example/content/2024-10-19-new-post.md

-11
This file was deleted.

‎example/content/2024-10-19-what-is-marmite-static-site-generator.md

+206
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
tags: markdown
3+
---
4+
# What is marmite
5+
6+
**Marmite** is a simple, easy and opinionated static site generator,
7+
probably the easiest and simple to use.
8+
9+
**Marmite** is written in **Rust** so it is very fast and everything is included
10+
in a single binary.
11+
12+
You can use it to generate a static blog, starting with the built-in **theme**
13+
and then fully customize if you want a more personalized website.
14+
15+
To generate your static site the only thing you need is a folder with some
16+
markdown files and `marmite`
17+
18+
assuming you have a folder called `mycontent` containing files with `.md` extension
19+
such as `about.md,first-post.md,second-post.md`
20+
21+
```console
22+
$ marmite mycontent mysite
23+
24+
Generated /mysite/about.html
25+
Generated /mysite/first-post.html
26+
Generated /mysite/second-post.html
27+
...
28+
29+
Site generated at: /mysite
30+
```
31+
32+
That is all you need to have a blog like this generated:
33+
34+
<details>
35+
<summary> <strong>CLICK HERE</strong> TO SEE SOME SCREENSHOTS </summary>
36+
37+
The following screenshots are using the default embedded
38+
templates (from [/example](https://github.com/rochacbruno/marmite/blob/main/example) folder)
39+
40+
**Light Mode**
41+
42+
Index:
43+
44+
![Index Light](https://github.com/rochacbruno/marmite/raw/main/assets/screenshots/index-light.png)
45+
46+
Content:
47+
48+
![Post Light](https://github.com/rochacbruno/marmite/raw/main/assets/screenshots/post-light.png)
49+
50+
**Dark mode**
51+
52+
Index:
53+
54+
![Index Dark](https://github.com/rochacbruno/marmite/raw/main/assets/screenshots/index-dark.png)
55+
56+
Content:
57+
58+
![Post Dark](https://github.com/rochacbruno/marmite/raw/main/assets/screenshots/post-dark.png)
59+
60+
</details>
61+
62+
---
63+
64+
## Content Types
65+
66+
Marmite separates content in two kinds, **posts** and **pages**.
67+
68+
An **opinionated** decision of marmite is how it makes this distinction,
69+
70+
### Post
71+
72+
If content has a **date** it is a **Post**
73+
74+
If the `file.md` has a **FrontMatter** (metadata on its first lines) defining a
75+
`date: YYYY-MM-DD` field, or the date field is extracted from the file name `YYYY-MM-DD-file.md`
76+
77+
Posts are shown on `index.html` page sorted by date, and also shown on `tag/{tag}.html` page,
78+
and included on the `RSS` and `JSON` **feeds**.
79+
80+
### Page
81+
82+
If the markdown file does't define a date, then `marmite` can't list it on index or feeds, because
83+
it doesn't know where to include it in the chronological order, so it makes sense to render this content
84+
as a `{slug}.html` and make it accessible only via the link directly.
85+
86+
## Menu
87+
88+
By default marmite includes 3 items in the main menu:
89+
90+
- Pages -> pages.html
91+
- List of posts in chronological order.
92+
- Tags -> tags.html
93+
- List of tags and a link to each tag group page.
94+
- Archive -> archive.html
95+
- List of YEAR and link to each year group page.
96+
97+
98+
Menu can be optionally customized in the configuration file, it is possible
99+
to add any **post**, **page** or external **link** to the menu.
100+
101+
## Metadata
102+
103+
On each markdown file it is possible to define metadata on the **FrontMatter**,
104+
the first lines of the file separated by `---`.
105+
106+
```markdown
107+
---
108+
field: value
109+
---
110+
111+
# title
112+
113+
Content
114+
```
115+
116+
`marmite` supports 5 fields:
117+
118+
- `title: This is the post title`
119+
- default: extracted from the first line of markdown.
120+
- `slug: this-is-the-post-slug`
121+
- default: title or filename slugified.
122+
- `date: YYYY-MM-DD`
123+
- default: extracted from filename or null.
124+
- `tags: tag1, tag2, tag3`
125+
- `extra: {}`
126+
- arbitrary extra key:value pair in YAML format (for template customization)
127+
128+
## Media
129+
130+
Images can be added using the normal markdown tag, marmite doesn't have shortcodes yet.
131+
132+
For local images you have to put the files in a folder named `media` in the content folder.
133+
134+
```markdown
135+
# content with media
136+
137+
![Image here](./media/subfolder/image.png)
138+
```
139+
140+
Marmite will copy your `media` folder to the output site, it is recommended to use `./media` as
141+
the URL for relative media.
142+
143+
## Site Config
144+
145+
Optionally, a file named `marmite.yaml` inside your content folder (together with your .md files)
146+
can be used to customize configuration.
147+
148+
> `--config file.yaml` can also be passed directly to the CLI.
149+
150+
example:
151+
152+
```yaml
153+
name: My Blog
154+
tagline: Poems, Essays and Articles
155+
url: https://mysite.com/blog
156+
menu:
157+
- ["About", "about.html"]
158+
- ["Projects", "projects.html"]
159+
- ["Contact", "contact.html"]
160+
- ["Github", "https://github.com/rochacbruno"]
161+
```
162+
163+
Other options are available and can be viewed on [repository](https://github.com/rochacbruno/marmite/blob/main/example/marmite.yaml)
164+
165+
## Theme customization
166+
167+
The embedded templates are created with [picocss.com](https://picocss.com/) and
168+
it is easy to customize, just put a `style.css` in the same folder where the markdown
169+
files are located and use anything that pico supports or just be creative with css.
170+
171+
## Creating a new Theme
172+
173+
To create a new theme is very simple, you just need to add to your content folder
174+
the `templates` and `static` directories and then customize in the way you like.
175+
176+
To learn more about how to create a new theme check this post:
177+
178+
[Customizing Templates](https://rochacbruno.github.io/marmite/customizing-templates.html)
179+
180+
181+
## Hosting
182+
183+
The result is a static site, so you can host it in any web server, examples:
184+
185+
- Github pages
186+
- Gitlab pages
187+
- Netlify
188+
- Vercel
189+
- Nginx
190+
- Apache
191+
192+
193+
## More features
194+
195+
There are more to come, marmite will include soon support for the most simple and
196+
popular comment systems.
197+
198+
Also, on of the goals is to integrate with **ActivityPub** via the JSON feed and
199+
**Hatsu**.
200+
201+
If you have ideas please open issues on the repository.
202+
203+
That's all!
204+
205+
206+

‎example/content/customizing-templates.md

+111
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,116 @@
1+
---
2+
date: 2024-10-18
3+
tags: templates, theme
4+
---
15
# Customizing Templates
26

7+
Marmite uses [Tera](https://keats.github.io/tera/docs/#templates) as its template
8+
parser, the language is very similar to **Jinja** or **Twig**.
9+
10+
## Templates
11+
12+
all templates are rendered with the global context.
13+
14+
```yaml
15+
site_data:
16+
posts: [Content]
17+
pages: [Content]
18+
site:
19+
name: str
20+
url: str
21+
tagline: str
22+
pagination: int
23+
...the keys on site configuration.
24+
menu: [[name, link]]
25+
```
26+
27+
The `Content` object can be a **page** or a **post** and contains
28+
29+
```yaml
30+
title: str
31+
slug: str
32+
html: str
33+
tags: [str] or []
34+
date: DateTimeObject or None
35+
```
36+
37+
There are 4 templates inside the `templates` folder, each adds more data to context.
38+
39+
- base.html
40+
- All other templates inherits blocks from this one.
41+
- list.html
42+
- Renders `index.html`, `pages.html`, `tags.html`
43+
- adds `title:str`, `content_list: [Content]`, `current_page: str`
44+
- content.html
45+
- Renders individual content page `my-post.html`
46+
- adds `title:str`, `content: [Content]`, `current_page: str`
47+
- group.html
48+
- Renders grouped information such as `tag/sometag.html` and `archive/2024.html`
49+
- adds `title:str`, `group_content: [[group, [Content]]]`, `current_page: str`
50+
51+
When customizing the templates you can create new templates to use as `include` or `macro`
52+
but the 4 listed above are required.
53+
54+
If you just want to customize some individual template you can add only it in the
55+
templates/ folder and the rest will be added by marmite.
56+
57+
See the templates on: [https://github.com/rochacbruno/marmite/tree/main/example/templates](https://github.com/rochacbruno/marmite/tree/main/example/templates)
58+
59+
## Static files
60+
61+
Just create a `static` folder side by side with your `templates` folder and add
62+
all `css`, `js`, `fonts` etc on this folder.
63+
64+
Marmite will copy this folder to the output site, if this folder is not found
65+
marmite will then copy the embedded static files to the static folder.
66+
67+
## URL
68+
69+
On templates use the `url_for` function to refer to urls.
70+
71+
```html
72+
{{ url_for(path='static/mystyle.css') }}
73+
{{ url_for(path='static/mystyle.css', abs=true) }}
74+
```
75+
76+
## Extra data
77+
78+
On site config `marmite.yaml` there is an arbitrary field `data` that can be accessed
79+
on any template.
80+
81+
```yaml
82+
data:
83+
myname: Bruno
84+
```
85+
Then on an template.
86+
87+
```html
88+
{{site.data.myname}}
89+
```
90+
91+
On each individual post there is a `extra` arbitrary field, so on `list.html` and
92+
`content.html` this field can also be accessed.
93+
94+
```markdown
95+
---
96+
extra:
97+
banner_image: media/banner.jpg
98+
---
99+
```
100+
then on template
101+
```html
102+
<img src="{{url_for(content.extra.banner_image)}}">
103+
```
104+
105+
## Raw HTML on markdown
106+
107+
Tera is configured to allow raw html on markdown, so any html tag will be
108+
allowed, a markdown file can include for example embeds, scripts, etc..
109+
110+
## Tera Object
111+
112+
Here the Tera object for reference,
113+
to see each individual filter or tester documentation read [https://keats.github.io/tera/docs/#templates](https://keats.github.io/tera/docs/#templates)
3114

4115
```rust
5116
Tera {

‎example/content/first-blog-post.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
date: 2024-01-01 12:00:01
33
slug: blog-post
44
title: Markdown Powered Blog Post (with code blocks)
5-
tags: markdown, python, rust, outra tag, batata
5+
tags: markdown, python, rust, another tag
66
---
77

88
# This is the post content

‎example/static/style.css

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/* customize me */

‎example/templates/base.html

+1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
}
1717
</style>
1818
<link rel="stylesheet" type="text/css" href="{{url_for(path='/static/marmite.css')}}">
19+
<link rel="stylesheet" type="text/css" href="{{url_for(path='/static/style.css')}}">
1920
{% endblock -%}
2021
</head>
2122

0 commit comments

Comments
 (0)
Please sign in to comment.