├── .gitignore ├── LICENSE ├── README.md ├── docs ├── blog │ ├── .authors.yml │ ├── author │ │ └── team.md │ ├── index.md │ ├── posts │ │ ├── draft.md │ │ ├── drafts │ │ │ ├── .meta.yml │ │ │ ├── may_4th.md │ │ │ ├── may_day.md │ │ │ ├── pirate_day.md │ │ │ ├── sysadmin_day.md │ │ │ └── ten_years.md │ │ └── myfirst.md │ └── tags.md ├── index.md └── tags.md ├── ext ├── __init__.py └── slugs.py ├── hooks └── socialmedia.py └── mkdocs.yml /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | site 3 | .cache 4 | __pycache__ 5 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Copyright (c) 2016-2023 Martin Donath 2 | Alex Voss 3 | 4 | Permission is hereby granted, free of charge, to any person obtaining a copy 5 | of this software and associated documentation files (the "Software"), to 6 | deal in the Software without restriction, including without limitation the 7 | rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 8 | sell copies of the Software, and to permit persons to whom the Software is 9 | furnished to do so, subject to the following conditions: 10 | 11 | The above copyright notice and this permission notice shall be included in 12 | all copies or substantial portions of the Software. 13 | 14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 15 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 16 | FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE 17 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 18 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 19 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS 20 | IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # A Material for Mkdocs Blog Template 2 | 3 | The purpose of the template in this repository is to give you a starting point 4 | for setting up a blog that makes use of features that Material for MkDocs 5 | provides and of selected integrations with other plugins that are of specific 6 | relevance to running a blog. 7 | 8 | It reflects the results you get by going through the [blog tutorials] in the 9 | documentation. 10 | 11 | [blog tutorials]: https://squidfunk.github.io/mkdocs-material/tutorials#blogs 12 | 13 | ## Requirements 14 | 15 | The to use the all the features this template uses, you need the [Insiders 16 | Edition] of Material for MkDocs but it should be easy enough to strip it down so 17 | that it works with the public version. 18 | 19 | [Insiders Edition]: https://squidfunk.github.io/mkdocs-material/insiders/ 20 | 21 | You will also need to install the [mkdocs-rss-plugin]. 22 | 23 | [mkdocs-rss-plugin]: https://github.com/guts/mkdocs-rss-plugin 24 | 25 | ## Using it 26 | 27 | This the repository is a [template repository], so you can create as many forks 28 | of it as you like and your repository will contain only a single commit to start 29 | with, instead of the whole history of the template. Also, you can create a 30 | private repository from this template (while forks inherit the visibility settings 31 | from the original). 32 | 33 | [template repository]: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template 34 | 35 | Simply hit the `Use this template` button. You can set the specifics of your new 36 | repository from there. 37 | 38 | [repository that contains this template]: https://github.com/mkdocs-material/create-blog 39 | 40 | 41 | ## Project layout 42 | 43 | The following shows the layout of the files in this template. Note that you can 44 | configure Material for MkDocs to use a different layout, this is simply the 45 | default. 46 | 47 | ``` 48 | mkdocs.yml # The configuration file. 49 | docs/ 50 | index.md # The documentation homepage. 51 | blog/ # The directory that all blog content goes into (first blog instance) 52 | posts/ # the place to put your posts 53 | author/ # Author profiles 54 | .authors.yml # Author information to be added to posts (shared betwe 55 | ext/ # Directory that contains code for the custom slugs 56 | hooks/ # Directory for a hook that adds social media share buttons 57 | ``` 58 | 59 | -------------------------------------------------------------------------------- /docs/blog/.authors.yml: -------------------------------------------------------------------------------- 1 | authors: 2 | team: 3 | name: Team 4 | description: Creator 5 | avatar: https://simpleicons.org/icons/materialformkdocs.svg 6 | squidfunk: 7 | name: Martin Donath 8 | description: Creator 9 | avatar: https://github.com/squidfunk.png -------------------------------------------------------------------------------- /docs/blog/author/team.md: -------------------------------------------------------------------------------- 1 | # The Material Team 2 | 3 | A small group of people dedicated to making writing documentation easy, if 4 | not outright fun! Here are some of the things we have blogged about: -------------------------------------------------------------------------------- /docs/blog/index.md: -------------------------------------------------------------------------------- 1 | # Blog 2 | 3 | -------------------------------------------------------------------------------- /docs/blog/posts/draft.md: -------------------------------------------------------------------------------- 1 | --- 2 | date: 3 | created: 2024-01-01 4 | draft: true 5 | --- 6 | 7 | # Happy new year! 8 | 9 | Happy 2024 to everyone. Wishing you all the best! 10 | 11 | 12 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod 13 | tempor incididunt ut labore et dolore magna aliqua. -------------------------------------------------------------------------------- /docs/blog/posts/drafts/.meta.yml: -------------------------------------------------------------------------------- 1 | draft: true 2 | 3 | -------------------------------------------------------------------------------- /docs/blog/posts/drafts/may_4th.md: -------------------------------------------------------------------------------- 1 | --- 2 | date: 3 | created: 2024-05-04 4 | --- 5 | 6 | # May the 4th be with you! 7 | 8 | Happy Star Wars Day to all! 9 | 10 | 11 | 12 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod 13 | tempor incididunt ut labore et dolore magna aliqua. -------------------------------------------------------------------------------- /docs/blog/posts/drafts/may_day.md: -------------------------------------------------------------------------------- 1 | --- 2 | date: 3 | created: 2024-05-01 4 | categories: 5 | - Holidays 6 | --- 7 | 8 | # Happy May Day! 9 | 10 | Happy May Day 2024 to everyone. Wishing you all the best! 11 | 12 | 13 | 14 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod 15 | tempor incididunt ut labore et dolore magna aliqua. -------------------------------------------------------------------------------- /docs/blog/posts/drafts/pirate_day.md: -------------------------------------------------------------------------------- 1 | --- 2 | date: 3 | created: 2024-09-19 4 | --- 5 | 6 | # Happy speak like a pirate day to all! 7 | 8 | Arr! 9 | 10 | 11 | 12 | Also, note how the slug for this post has been shortened to five words thanks 13 | to the custom slugify function. -------------------------------------------------------------------------------- /docs/blog/posts/drafts/sysadmin_day.md: -------------------------------------------------------------------------------- 1 | --- 2 | date: 3 | created: 2024-07-26 4 | --- 5 | 6 | # Happy sysadmin appreciation day! 7 | 8 | Bake them a cake. 9 | 10 | 11 | 12 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod 13 | tempor incididunt ut labore et dolore magna aliqua. -------------------------------------------------------------------------------- /docs/blog/posts/drafts/ten_years.md: -------------------------------------------------------------------------------- 1 | --- 2 | date: 3 | created: 2026-02-09 4 | --- 5 | 6 | # Happy 10th birthday, Material for MkDocs! 7 | 8 | It has been an amazing journey. 9 | 10 | 11 | 12 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod 13 | tempor incididunt ut labore et dolore magna aliqua. -------------------------------------------------------------------------------- /docs/blog/posts/myfirst.md: -------------------------------------------------------------------------------- 1 | --- 2 | date: 3 | created: 2023-12-31 4 | updated: 2024-01-02 5 | readtime: 15 6 | pin: true 7 | links: 8 | - Homepage: index.md#project-layout 9 | - Blog index: blog/index.md 10 | - External links: 11 | - Material documentation: https://squidfunk.github.io/mkdocs-material 12 | categories: 13 | - Holidays 14 | tags: 15 | - new year 16 | - hogmanay 17 | - festive season 18 | authors: 19 | - team 20 | slug: ny-eve 21 | --- 22 | 23 | # Happy new years eve! 24 | 25 | We hope you are all having fun and wish you all the best for the new year! 26 | 27 | 28 | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod 29 | tempor incididunt ut labore et dolore magna aliqua. 30 | -------------------------------------------------------------------------------- /docs/blog/tags.md: -------------------------------------------------------------------------------- 1 | # Tag index for the blog 2 | 3 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # Welcome to MkDocs 2 | 3 | For full documentation visit [mkdocs.org](https://www.mkdocs.org). 4 | 5 | ## Commands 6 | 7 | * `mkdocs new [dir-name]` - Create a new project. 8 | * `mkdocs serve` - Start the live-reloading docs server. 9 | * `mkdocs build` - Build the documentation site. 10 | * `mkdocs -h` - Print help message and exit. 11 | 12 | ## Project layout 13 | 14 | mkdocs.yml # The configuration file. 15 | docs/ 16 | index.md # The documentation homepage. 17 | ... # Other markdown pages, images and other files. 18 | -------------------------------------------------------------------------------- /docs/tags.md: -------------------------------------------------------------------------------- 1 | # Tag index 2 | 3 | -------------------------------------------------------------------------------- /ext/__init__.py: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/mkdocs-material/create-blog/97f0557eace51df502ea8ed19f31cc7dccc27671/ext/__init__.py -------------------------------------------------------------------------------- /ext/slugs.py: -------------------------------------------------------------------------------- 1 | 2 | import re, functools, unicodedata 3 | 4 | RE_HTML_TAGS = re.compile(r']*>', re.UNICODE) 5 | RE_INVALID_SLUG_CHAR = re.compile(r'[^\w\- ]', re.UNICODE) 6 | RE_WHITESPACE = re.compile(r'\s', re.UNICODE) 7 | 8 | def _make_slug(text, sep, **kwargs): 9 | slug = unicodedata.normalize('NFC', text) 10 | slug = RE_HTML_TAGS.sub('', slug) 11 | slug = RE_INVALID_SLUG_CHAR.sub('', slug) 12 | slug = slug.strip().lower() 13 | slug = RE_WHITESPACE.sub(sep, slug) 14 | return slug 15 | 16 | def _make_slug_short(text, sep, **kwargs): 17 | words = _make_slug(text, sep, **kwargs).split(sep) 18 | return sep.join(words[:5]) 19 | 20 | def slugify(**kwargs): 21 | if 'short' in kwargs and kwargs['short']: 22 | return functools.partial(_make_slug_short, **kwargs) 23 | return functools.partial(_make_slug, **kwargs) 24 | -------------------------------------------------------------------------------- /hooks/socialmedia.py: -------------------------------------------------------------------------------- 1 | from textwrap import dedent 2 | import urllib.parse 3 | import re 4 | 5 | x_intent = "https://twitter.com/intent/tweet" 6 | fb_sharer = "https://www.facebook.com/sharer/sharer.php" 7 | include = re.compile(r"blog/[1-9].*") 8 | 9 | def on_page_markdown(markdown, **kwargs): 10 | page = kwargs['page'] 11 | config = kwargs['config'] 12 | if not include.match(page.url): 13 | return markdown 14 | 15 | page_url = config.site_url+page.url 16 | page_title = urllib.parse.quote(page.title+'\n') 17 | 18 | return markdown + dedent(f""" 19 | [Share on :simple-x:]({x_intent}?text={page_title}&url={page_url}){{ .md-button }} 20 | [Share on :simple-facebook:]({fb_sharer}?u={page_url}){{ .md-button }} 21 | """) -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Blog Tutorial 2 | site_description: an example blog set up following the blog tutorials 3 | site_url: http://www.example.com 4 | 5 | theme: 6 | name: material 7 | features: 8 | - navigation.indexes 9 | 10 | plugins: 11 | - search 12 | - blog: 13 | blog_toc: true 14 | archive_date_format: MMMM yyyy 15 | categories_allowed: 16 | - Holidays 17 | - News 18 | authors_profiles: true 19 | pagination_per_page: 5 20 | archive_pagination_per_page: 10 21 | categories_pagination_per_page: 10 22 | post_slugify: !!python/object/apply:ext.slugs.slugify 23 | kwds: 24 | short: true 25 | - meta 26 | - tags 27 | - rss: 28 | match_path: "blog/posts/.*" 29 | date_from_meta: 30 | as_creation: date.created 31 | as_update: date.updated 32 | 33 | extra: 34 | social: 35 | - icon: fontawesome/brands/mastodon 36 | name: squidfunk on Mastodon 37 | link: https://fosstodon.org/@squidfunk 38 | 39 | hooks: 40 | - hooks/socialmedia.py 41 | 42 | markdown_extensions: 43 | - attr_list 44 | - pymdownx.emoji: 45 | emoji_index: !!python/name:material.extensions.emoji.twemoji 46 | emoji_generator: !!python/name:material.extensions.emoji.to_svg 47 | 48 | nav: 49 | - Home: index.md 50 | - Tags: tags.md 51 | - Blog: 52 | - blog/index.md 53 | - blog/tags.md --------------------------------------------------------------------------------