From e11b1db95dfe4f37a37dde7197afb2e6e666a69d Mon Sep 17 00:00:00 2001 From: Bruno Rocha Date: Tue, 22 Oct 2024 12:51:07 +0100 Subject: [PATCH] Just formatting of examples/content --- README.md | 6 +- ...9-what-is-marmite-static-site-generator.md | 111 +++++++++------ example/content/customizing-templates.md | 14 ++ example/content/hosting.md | 126 ++++++++++++++++++ example/content/markdown-format.md | 16 +-- example/templates/content.html | 2 +- example/templates/list.html | 2 +- 7 files changed, 227 insertions(+), 50 deletions(-) create mode 100644 example/content/hosting.md diff --git a/README.md b/README.md index dfb89cf..e92ef14 100644 --- a/README.md +++ b/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 diff --git a/example/content/2024-10-19-what-is-marmite-static-site-generator.md b/example/content/2024-10-19-what-is-marmite-static-site-generator.md index 857003c..0d5f5a3 100644 --- a/example/content/2024-10-19-what-is-marmite-static-site-generator.md +++ b/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.
CLICK HERE TO SEE SOME SCREENSHOTS @@ -59,48 +65,57 @@ Content:
+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 diff --git a/example/content/customizing-templates.md b/example/content/customizing-templates.md index ca94703..045e525 100644 --- a/example/content/customizing-templates.md +++ b/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 %} +
+ {%- for content in content_list %} +

{{ content.title | capitalize }}

+

{{ content.html | striptags | truncate(length=100, end="...") }}

+ {%- endfor %} +
+{% endblock %} +``` + ## Templates all templates are rendered with the global context. diff --git a/example/content/hosting.md b/example/content/hosting.md new file mode 100644 index 0000000..91761a9 --- /dev/null +++ b/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. diff --git a/example/content/markdown-format.md b/example/content/markdown-format.md index 40b6c64..03ed671 100644 --- a/example/content/markdown-format.md +++ b/example/content/markdown-format.md @@ -1,13 +1,13 @@ --- -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. @@ -15,7 +15,7 @@ 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! | ``` -### 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. - + ```html - + ``` ### Pico CSS components diff --git a/example/templates/content.html b/example/templates/content.html index b319081..5939a0d 100644 --- a/example/templates/content.html +++ b/example/templates/content.html @@ -24,7 +24,7 @@ {% if content.date %}