More content on example/demo site (#57)

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

@@ -0,0 +1,206 @@
+---
+tags: markdown
+---
+# 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`
+
+```console
+$ 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:
+
+<details>
+<summary> <strong>CLICK HERE</strong> TO SEE SOME SCREENSHOTS </summary>
+
+The following screenshots are using the default embedded
+templates (from [/example](/~https://github.com/rochacbruno/marmite/blob/main/example) folder)
+
+**Light Mode**
+
+Index:
+
+![Index Light](/~https://github.com/rochacbruno/marmite/raw/main/assets/screenshots/index-light.png)
+
+Content:
+
+![Post Light](/~https://github.com/rochacbruno/marmite/raw/main/assets/screenshots/post-light.png)
+
+**Dark mode**
+
+Index:
+
+![Index Dark](/~https://github.com/rochacbruno/marmite/raw/main/assets/screenshots/index-dark.png)
+
+Content:
+
+![Post Dark](/~https://github.com/rochacbruno/marmite/raw/main/assets/screenshots/post-dark.png)
+
+</details>
+
+---
+
+## 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 posts in chronological 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 `---`.
+
+```markdown
+---
+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.
+
+```markdown
+# 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:
+
+```yaml
+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](/~https://github.com/rochacbruno/marmite/blob/main/example/marmite.yaml)
+
+## Theme customization
+
+The embedded templates are created with [picocss.com](https://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](https://rochacbruno.github.io/marmite/customizing-templates.html)
+
+
+## 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!
+
+
+

example/content/customizing-templates.md

@@ -1,5 +1,116 @@
+---
+date: 2024-10-18
+tags: templates, theme
+---
 # Customizing Templates
 
+Marmite uses [Tera](https://keats.github.io/tera/docs/#templates) as its template
+parser, the language is very similar to **Jinja** or **Twig**.
+
+## Templates
+
+all templates are rendered with the global context.
+
+```yaml
+site_data:
+  posts: [Content]
+  pages: [Content]
+site:
+  name: str
+  url: str
+  tagline: str
+  pagination: int
+  ...the keys on site configuration.
+menu: [[name, link]]
+```
+
+The `Content` object can be a **page** or a **post** and contains
+
+```yaml
+title: str
+slug: str
+html: str
+tags: [str] or []
+date: DateTimeObject or None
+```
+
+There are 4 templates inside the `templates` folder, each adds more data to context.
+
+- base.html
+  - All other templates inherits blocks from this one.
+- list.html
+  - Renders `index.html`, `pages.html`, `tags.html`
+  - adds `title:str`, `content_list: [Content]`, `current_page: str`
+- content.html
+  - Renders individual content page `my-post.html`
+  - adds `title:str`, `content: [Content]`, `current_page: str`
+- group.html
+  - Renders grouped information such as `tag/sometag.html` and `archive/2024.html`
+  - adds `title:str`, `group_content: [[group, [Content]]]`, `current_page: str`
+
+When customizing the templates you can create new templates to use as `include` or `macro`
+but the 4 listed above are required.
+
+If you just want to customize some individual template you can add only it in the
+templates/ folder and the rest will be added by marmite.
+
+See the templates on: [/~https://github.com/rochacbruno/marmite/tree/main/example/templates](/~https://github.com/rochacbruno/marmite/tree/main/example/templates)
+
+## Static files
+
+Just create a `static` folder side by side with your `templates` folder and add
+all `css`, `js`, `fonts` etc on this folder.
+
+Marmite will copy this folder to the output site, if this folder is not found
+marmite will then copy the embedded static files to the static folder.
+
+## URL 
+
+On templates use the `url_for` function to refer to urls.
+
+```html
+{{ url_for(path='static/mystyle.css') }}
+{{ url_for(path='static/mystyle.css', abs=true) }}
+```
+
+## Extra data
+
+On site config `marmite.yaml` there is an arbitrary field `data` that can be accessed
+on any template.
+
+```yaml
+data:
+  myname: Bruno
+```
+Then on an template.
+
+```html
+{{site.data.myname}}
+```
+
+On each individual post there is a `extra` arbitrary field, so on `list.html` and
+`content.html` this field can also be accessed.
+
+```markdown
+---
+extra:
+  banner_image: media/banner.jpg
+---
+```
+then on template
+```html
+<img src="{{url_for(content.extra.banner_image)}}">
+```
+
+## Raw HTML on markdown
+
+Tera is configured to allow raw html on markdown, so any html tag will be 
+allowed, a markdown file can include for example embeds, scripts, etc..
+
+## Tera Object
+
+Here the Tera object for reference, 
+to see each individual filter or tester documentation read [https://keats.github.io/tera/docs/#templates](https://keats.github.io/tera/docs/#templates)
 
 ```rust 
 Tera {

example/content/first-blog-post.md

@@ -2,7 +2,7 @@
 date: 2024-01-01 12:00:01
 slug: blog-post
 title: Markdown Powered Blog Post (with code blocks)
-tags: markdown, python, rust, outra tag, batata
+tags: markdown, python, rust, another tag
 ---
 
 # This is the post content

example/static/style.css

@@ -0,0 +1 @@
+/* customize me */

example/templates/base.html

@@ -16,6 +16,7 @@
     }
     </style>
     <link rel="stylesheet" type="text/css" href="{{url_for(path='/static/marmite.css')}}">
+    <link rel="stylesheet" type="text/css" href="{{url_for(path='/static/style.css')}}">
     {% endblock -%}
 </head>