added blog template based on tutorial

.gitignore

@@ -0,0 +1,4 @@
+*~
+site
+.cache
+__pycache__

LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2016-2023 Martin Donath <[email protected]>
+                        Alex Voss <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.

README.md

@@ -0,0 +1,58 @@
+# A Material for Mkdocs Blog Template
+
+The purpose of the template in this repository is to give you a starting point
+for setting up a blog that makes use of features that Material for MkDocs
+provides and of selected integrations with other plugins that are of specific
+relevance to running a blog.
+
+It reflects the results you get by going through the [blog tutorials] in the
+documentation. 
+
+[blog tutorials]: https://squidfunk.github.io/mkdocs-material/tutorials#blogs
+
+## Requirements
+
+The to use the all the features this template uses, you need the [Insiders
+Edition] of Material for MkDocs but it should be easy enough to strip it down so
+that it works with the public version.
+
+[Insiders Edition]: https://squidfunk.github.io/mkdocs-material/insiders/
+
+You will also need to install the [mkdocs-rss-plugin].
+
+[mkdocs-rss-plugin]: https://github.com/guts/mkdocs-rss-plugin
+
+## Using it
+
+This the repository is a [template repository], so you can create as many forks 
+of it as you like and your repository will contain only a single commit to start 
+with, instead of the whole history of the template. Also, you can create a 
+private repository from this template (while forks inherit the visibility settings 
+from the original).
+
+[template repository]: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template
+
+Simply hit the `Use this template` button. You can set the specifics of your new 
+repository from there.
+
+[repository that contains this template]: https://github.com/mkdocs-material/create-blog
+
+
+## Project layout
+
+The following shows the layout of the files in this template. Note that you can
+configure Material for MkDocs to use a different layout, this is simply the
+default.
+
+```
+mkdocs.yml              # The configuration file.
+docs/
+    index.md            # The documentation homepage.
+    blog/               # The directory that all blog content goes into (first blog instance)
+        posts/          # the place to put your posts
+        author/         # Author profiles
+        .authors.yml    # Author information to be added to posts (shared betwe
+ext/                    # Directory that contains code for the custom slugs
+hooks/                  # Directory for a hook that adds social media share buttons
+```
+

docs/blog/.authors.yml

@@ -0,0 +1,9 @@
+authors:
+  team:
+    name: Team
+    description: Creator
+    avatar: https://simpleicons.org/icons/materialformkdocs.svg
+  squidfunk:
+    name: Martin Donath
+    description: Creator
+    avatar: https://github.com/squidfunk.png

docs/blog/author/team.md

@@ -0,0 +1,4 @@
+# The Material Team
+
+A small group of people dedicated to making writing documentation easy, if
+not outright fun! Here are some of the things we have blogged about:

docs/blog/index.md

@@ -0,0 +1,2 @@
+# Blog
+

docs/blog/posts/draft.md

@@ -0,0 +1,13 @@
+---
+date:
+  created: 2024-01-01
+draft: true
+---
+
+# Happy new year!
+
+Happy 2024 to everyone. Wishing you all the best!
+<!-- more -->
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua.

docs/blog/posts/drafts/.meta.yml

@@ -0,0 +1,2 @@
+draft: true
+

docs/blog/posts/drafts/may_4th.md

@@ -0,0 +1,13 @@
+---
+date:
+  created: 2024-05-04
+---
+
+# May the 4th be with you!
+
+Happy Star Wars Day to all!
+
+<!-- more -->
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua.

docs/blog/posts/drafts/may_day.md

@@ -0,0 +1,15 @@
+---
+date:
+  created: 2024-05-01
+categories:
+  - Holidays
+---
+
+# Happy May Day!
+
+Happy May Day 2024 to everyone. Wishing you all the best!
+
+<!-- more -->
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua.

docs/blog/posts/drafts/pirate_day.md

@@ -0,0 +1,13 @@
+---
+date:
+  created: 2024-09-19
+---
+
+# Happy speak like a pirate day to all!
+
+Arr!
+
+<!-- more -->
+
+Also, note how the slug for this post has been shortened to five words thanks
+to the custom slugify function.

docs/blog/posts/drafts/sysadmin_day.md

@@ -0,0 +1,13 @@
+---
+date:
+  created: 2024-07-26
+---
+
+# Happy sysadmin appreciation day!
+
+Bake them a cake.
+
+<!-- more -->
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua.

docs/blog/posts/drafts/ten_years.md

@@ -0,0 +1,13 @@
+---
+date:
+  created: 2026-02-09
+---
+
+# Happy 10th birthday, Material for MkDocs!
+
+It has been an amazing journey.
+
+<!-- more -->
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua.

docs/blog/posts/myfirst.md

@@ -0,0 +1,29 @@
+---
+date:
+  created: 2023-12-31
+  updated: 2024-01-02
+readtime: 15
+pin: true
+links:
+  - Homepage: index.md#project-layout
+  - Blog index: blog/index.md
+  - External links:
+    - Material documentation: https://squidfunk.github.io/mkdocs-material
+categories:
+  - Holidays
+tags:
+  - new year
+  - hogmanay
+  - festive season
+authors:
+  - team
+slug: ny-eve
+---
+
+# Happy new years eve!
+
+We hope you are all having fun and wish you all the best for the new year!
+<!-- more -->
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod
+tempor incididunt ut labore et dolore magna aliqua.

docs/blog/tags.md

@@ -0,0 +1,2 @@
+# Tag index  for the blog
+<!-- material/tags { scope: true } -->

docs/index.md

@@ -0,0 +1,17 @@
+# Welcome to MkDocs
+
+For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+
+## Commands
+
+* `mkdocs new [dir-name]` - Create a new project.
+* `mkdocs serve` - Start the live-reloading docs server.
+* `mkdocs build` - Build the documentation site.
+* `mkdocs -h` - Print help message and exit.
+
+## Project layout
+
+    mkdocs.yml    # The configuration file.
+    docs/
+        index.md  # The documentation homepage.
+        ...       # Other markdown pages, images and other files.

docs/tags.md

@@ -0,0 +1,2 @@
+# Tag index
+<!-- material/tags -->

ext/slugs.py

@@ -0,0 +1,23 @@
+
+import re, functools, unicodedata
+
+RE_HTML_TAGS = re.compile(r'</?[^>]*>', re.UNICODE)
+RE_INVALID_SLUG_CHAR = re.compile(r'[^\w\- ]', re.UNICODE)
+RE_WHITESPACE = re.compile(r'\s', re.UNICODE)
+
+def _make_slug(text, sep, **kwargs):
+    slug = unicodedata.normalize('NFC', text)
+    slug = RE_HTML_TAGS.sub('', slug)
+    slug = RE_INVALID_SLUG_CHAR.sub('', slug)
+    slug = slug.strip().lower()
+    slug = RE_WHITESPACE.sub(sep, slug)
+    return slug
+
+def _make_slug_short(text, sep, **kwargs):
+    words = _make_slug(text, sep, **kwargs).split(sep)
+    return sep.join(words[:5])
+
+def slugify(**kwargs):
+    if 'short' in kwargs and kwargs['short']:
+        return functools.partial(_make_slug_short, **kwargs)
+    return functools.partial(_make_slug, **kwargs)

hooks/socialmedia.py

@@ -0,0 +1,21 @@
+from textwrap import dedent
+import urllib.parse
+import re
+
+x_intent = "https://twitter.com/intent/tweet"
+fb_sharer = "https://www.facebook.com/sharer/sharer.php"
+include = re.compile(r"blog/[1-9].*")
+
+def on_page_markdown(markdown, **kwargs):
+    page = kwargs['page']
+    config = kwargs['config']
+    if not include.match(page.url):
+        return markdown
+
+    page_url = config.site_url+page.url
+    page_title = urllib.parse.quote(page.title+'\n')
+
+    return markdown + dedent(f"""
+    [Share on :simple-x:]({x_intent}?text={page_title}&url={page_url}){{ .md-button }}
+    [Share on :simple-facebook:]({fb_sharer}?u={page_url}){{ .md-button }}
+    """)

mkdocs.yml

@@ -0,0 +1,53 @@
+site_name: Blog Tutorial
+site_description: an example blog set up following the blog tutorials
+site_url: http://www.example.com
+
+theme:
+  name: material
+  features:
+    - navigation.indexes
+
+plugins:
+  - search
+  - blog:
+      blog_toc: true
+      archive_date_format: MMMM yyyy
+      categories_allowed:
+        - Holidays
+        - News
+      authors_profiles: true
+      pagination_per_page: 5
+      archive_pagination_per_page: 10
+      categories_pagination_per_page: 10
+      post_slugify: !!python/object/apply:ext.slugs.slugify
+        kwds:
+          short: true
+  - meta
+  - tags
+  - rss:
+      match_path: "blog/posts/.*"
+      date_from_meta:
+        as_creation: date.created
+        as_update: date.updated
+
+extra:
+  social:
+    - icon: fontawesome/brands/mastodon
+      name: squidfunk on Mastodon
+      link: https://fosstodon.org/@squidfunk
+
+hooks:
+  - hooks/socialmedia.py
+
+markdown_extensions:
+  - attr_list
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
+
+nav:
+  - Home: index.md
+  - Tags: tags.md
+  - Blog:
+     - blog/index.md
+     - blog/tags.md