Just formatting of examples/content

README.md

@@ -19,7 +19,11 @@ It also handles generating or copying `static/` `media/` to the `output` dir.
 [![AGPL License](https://img.shields.io/badge/license-AGPL-blue.svg)](http://www.gnu.org/licenses/agpl-3.0)
 [![Crates.io Version](https://img.shields.io/crates/v/marmite)](https://crates.io/crates/marmite)
 
-[Demo](https://rochacbruno.github.io/marmite/)
+[Demo and Docs](https://rochacbruno.github.io/marmite/)  
+
+---
+
+[Create your blog in one click using github actions](https://github.com/rochacbruno/make-me-a-blog)  
 
 ## Installation
 

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

@@ -29,7 +29,13 @@ Generated /mysite/second-post.html
 Site generated at: /mysite
 ```
 
-That is all you need to have a blog like this generated:
+That is all you need to have a blog generated, now you just need to take the 
+`mysite` folder and publish it in a webserver, read more on [hosting](./hosting.html).
+
+## Layout
+
+By default the site is generated using marmite embedded theme (this one you are reading right now)
+it is based on picocss and supports ligh/dark themes.
 
 <details>
 <summary> <strong>CLICK HERE</strong> TO SEE SOME SCREENSHOTS </summary>
@@ -59,48 +65,57 @@ Content:
 
 </details>
 
+You can of course, customize your own look and feel by adding `templates` and `static` files to 
+your `mycontent` folder, read more on [customizing templates](./customizing-templates.html).
+
 ---
 
 ## Content Types
 
 Marmite separates content in two kinds, **posts** and **pages**.
 
-An **opinionated** decision of marmite is how it makes this distinction,
+An **opinionated** decision of marmite is how it makes the distinction.
 
-### Post
+### Posts
 
-If content has a **date** it is a **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`
+then marmite will consider it as a **post**.
 
 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
+### Pages
 
-If the markdown file does't define a date, then `marmite` can't list it on index or feeds, because
+If the markdown file doesn'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.
+as a page named `{slug}.html` and make it accessible only via the link directly, so it can optionally
+added to the main menu or linked in other content.
 
 ## 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.
-
-
+**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**,
+On each markdown file it is possible (and optional) to define metadata on the **FrontMatter**,
 the first lines of the file separated by `---`.
 
 ```markdown
@@ -115,15 +130,46 @@ 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)
+**title**
+
+  : str: Title of the post  
+  **default**: extracted from the first line of markdown.
+
+**slug** 
+
+  : str: this-is-the-post-slug`  
+  **default**: slugfied `title` or `filename`.
+
+**date**
+
+  : str: `YYYY-MM-DD`  
+  **formats** `YYYY-MM-DD`, `YYYY-MM-DD HH:MM`, `YYYY-MM-DD HH:MM:SS`  
+  **default**: extracted from filename or null.
+
+**tags** 
+
+  : Comma separated list of tags, or YAML list of tags  
+  **formats**  
+    ```yaml
+    tags: tag1, tag2, tag3
+    tags:
+      - tag1
+      - tag2
+    ```
+  **default** empty
+
+**extra**
+
+  : arbitrary extra `key:value` pair in YAML format (for template customization)  
+  **format**
+    ```yaml
+    extra:
+      math: true
+      comments: true
+      draft: true
+      top_banner_image: ./media/image.png
+    ```
+
 
 ## Media
 
@@ -175,20 +221,7 @@ 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
-
+[Customizing Templates](./customizing-templates.html)
 
 ## More features
 

example/content/customizing-templates.md

@@ -7,6 +7,20 @@ tags: templates, theme
 Marmite uses [Tera](https://keats.github.io/tera/docs/#templates) as its template
 parser, the language is very similar to **Jinja** or **Twig**.
 
+Example on `templates/list.html`
+
+```html
+{% extends "base.html" %}
+{% block main %}
+  <div class="content-list">
+  {%- for content in content_list %}
+    <h2 class="content-title"><a href="{{url_for(path=content.slug)}}.html">{{ content.title | capitalize }}</a></h2>
+    <p class="content-excerpt">{{ content.html | striptags | truncate(length=100, end="...") }}</p>
+  {%- endfor %}
+  </div>
+{% endblock %}
+```
+
 ## Templates
 
 all templates are rendered with the global context.

example/content/hosting.md

@@ -0,0 +1,126 @@
+---
+date: 2024-10-16
+---
+## Hosting
+
+Marmite genetates a static site, so you can host it in any web server.
+
+Examples:
+
+- Github pages
+- Gitlab pages
+- Netlify
+- Vercel
+- Nginx
+- Apache
+
+### Github Pages
+
+This is the easiest and cheapest option to publish your static blog,
+you need a **Github Repository** containing a `content` directory and a `marmite.yaml`
+
+
+Fork this template repository https://github.com/rochacbruno/make-me-a-blog and give a meaninful name like `blog` to
+the forked repo.
+
+Or start from scratch! it is very simple!
+
+---
+
+Create a new repository and the following files.
+
+```bash
+.
+|_ marmite.yaml
+|_ content
+  |_ 2024-10-22-my-first-post.md
+  |_ about.md
+```
+
+Edit `marmite.yaml` to add your preferences.
+
+```yaml
+name: My Blog
+tagline: Poems, Essays and Articles
+url: https://YOURUSER.github.io/REPONAME
+menu:
+  - ["About", "about.html"]
+  - ["Pages", "pages.html"]
+  - ["Tags", "tags.html"]
+  - ["Follow me", "https://mastodon.social/@YOURUSER"]
+  - ["Github", "https://github.com/rochacbruno"]
+```
+
+Now you need to tell github actions to go inside your repo root and run
+
+```
+marmite . site
+```
+
+And then publish the `site/` directory as the github page for your repo.
+
+You can automate that:
+
+First access https://github.com/YOURUSER/REPONAME/settings/pages and set the
+pages source to **Github Actions**
+
+Then add a workflow to your repository.
+
+`.github/workflows/main.yaml`
+```yaml
+name: GH Pages Deploy
+
+on:
+  push:
+    branches: [main]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout 🛎
+        uses: actions/checkout@v4
+
+      - name: Install marmite 🫙
+        run: cargo install marmite
+
+      - name: Build site 🏗️
+        run: marmite . site --debug
+
+      - name: Setup Pages
+        if: github.event_name == 'push'
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        if: github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: 'site'
+
+      - name: Deploy to GitHub Pages
+        if: github.event_name == 'push'
+        id: deployment
+        uses: actions/deploy-pages@v4
+```
+
+Now commit and push to the main branch and wait for your blog to be published at
+
+https://YOURUSER.github.io/REPONAME
+
+
+Read [Customizing Templates](./customizing-templates.html) to learn how 
+to customize the look and feel of your blog.

example/content/markdown-format.md

@@ -1,21 +1,21 @@
 ---
-date: 2024-01-01 12:00:01
+date: 2024-10-17 12:00:01
 slug: markdown-format
 title: Markdown Formatting Options
-tags: markdown, python, rust, Common Mark
+tags: markdown, Common Mark, GFM
 extra:
   math: true
 ---
 
-# This is the post content
+# Writing content in Markdown
 
 The content here accepts any valid `CommonMark` or **Github** _Flavoured_ markdown
 and some `GFM` extensions.
 
 Simple paragraph and usual formatting like **bold**, __underline__, *italic*
 and also all sorts of formatting elements.
 
-### Strikethrough
+### Strike-through
 
 The following is ~~no more~~.
 ```markdown
@@ -36,7 +36,7 @@ The following is ~~no more~~.
 | List        | Here's a list! <ul><li>Item one.</li><li>Item two.</li></ul> |
 ```
 
-### Autolink
+### Auto-link
 
 https://github.com/rochacbruno/marmite  
 [A link with a tooltip](https://pudim.com.br "A picture of a pudim")  
@@ -168,7 +168,7 @@ Rich quotes
 >  *Everything* is going according to **plan**.
 ```
 
-## Emojis
+## Emoji
 
 :smile: - :crab: - :snake:
 
@@ -311,10 +311,10 @@ Same but containing a tooltip if you hover the mouse on
 
 Just use raw HTML for now, in future we may have a shorcode.
 
-<iframe width="360" height="215" src="https://www.youtube.com/embed/MjrBTcnnK6c?si=PmQWsGiTh5XguSpb" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
+<iframe width="260" height="160" src="https://www.youtube.com/embed/MjrBTcnnK6c?si=PmQWsGiTh5XguSpb" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
 
 ```html
-<iframe width="360" height="215" src="https://www.youtube.com/embed/MjrBTcnnK6c?si=PmQWsGiTh5XguSpb" title="YouTube video player"></iframe>
+<iframe width="260" height="160" src="https://www.youtube.com/embed/MjrBTcnnK6c?si=PmQWsGiTh5XguSpb" title="YouTube video player"></iframe>
 ```
 
 ### Pico CSS components

example/templates/content.html

@@ -24,7 +24,7 @@
     {% if content.date %}
     <footer>
         <span class="content-date"> {{ content.date | date(format="%v") }}</span>
-        <ul class="content-tags">
+        <ul class="content-tags overflow-auto">
         {% for tag in content.tags  %}
             <li><a href="{{url_for(path='/tag/')}}{{ tag | trim | slugify }}.html">{{ tag }}</a></li>
         {% endfor %}