From 4a20c4f9dbfdf548cd67a22f8c2daeb92c260a45 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Wed, 11 Oct 2023 07:55:00 +0100 Subject: [PATCH 1/9] an initial idea about how we might manage a list of examples Thought adding metadata to each example would make this easier to maintain than if we had to separately add things to a list. Happy to have a go at writing something to compile the list of examples. Now that I write this, I seem to remember there is a plugin - mkdocs-gen-files? --- examples/blog-basic/meta.yml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) create mode 100644 examples/blog-basic/meta.yml diff --git a/examples/blog-basic/meta.yml b/examples/blog-basic/meta.yml new file mode 100644 index 0000000..1abae26 --- /dev/null +++ b/examples/blog-basic/meta.yml @@ -0,0 +1,14 @@ +# This file is used only to generate a browsable +# list of examples for our documentation. You do +# not need it in your own projects. +meta: + tags: + - public # works without Insiders + - blog # functionality demonstrated + - simple # requires no extra plugins or other magic + # - experimental # uses an experimental feature somewhere + author: + name: Alex Voss # author name + handle: alexvoss # a Github handle for giving credit and + # identifying who would fix any regressions + # other than @squidfunk From 569c57569d766b48bf8b37943e9a2c506a7516f2 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Wed, 11 Oct 2023 08:51:54 +0100 Subject: [PATCH 2/9] fixed stupid cut-n-paste error, using # for CSS comments... --- .../page-status/docs/stylesheets/extra.css | 44 +++++++++---------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/examples/page-status/docs/stylesheets/extra.css b/examples/page-status/docs/stylesheets/extra.css index 5addc81..7065444 100644 --- a/examples/page-status/docs/stylesheets/extra.css +++ b/examples/page-status/docs/stylesheets/extra.css @@ -1,25 +1,25 @@ -# Copyright (c) 2016-2023 the authors: -# -# Martin Donath -# Alex Voss - -# 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. +/* + * Copyright (c) 2016-2023 Martin Donath + * Alex Voss + * + * 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 + * urnished 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. + */ :root { --md-status--happy: url('data:image/svg+xml;charset=utf-8,') From fa123cad80d04824cd24659aabce82f13c298367 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Wed, 11 Oct 2023 12:05:50 +0100 Subject: [PATCH 3/9] first stab at a basic blog example --- examples/blog-basic/docs/README.md | 18 ++++++++ examples/blog-basic/docs/blog/.authors.yml | 9 ++++ examples/blog-basic/docs/blog/index.md | 2 + .../docs/blog/posts/2023-10-11-firstpost.md | 32 ++++++++++++++ .../docs/blog/posts/2023-10-12-welcome.md | 32 ++++++++++++++ examples/blog-basic/mkdocs.yml | 42 +++++++++++++++++++ 6 files changed, 135 insertions(+) create mode 100644 examples/blog-basic/docs/README.md create mode 100644 examples/blog-basic/docs/blog/.authors.yml create mode 100644 examples/blog-basic/docs/blog/index.md create mode 100644 examples/blog-basic/docs/blog/posts/2023-10-11-firstpost.md create mode 100644 examples/blog-basic/docs/blog/posts/2023-10-12-welcome.md create mode 100644 examples/blog-basic/mkdocs.yml diff --git a/examples/blog-basic/docs/README.md b/examples/blog-basic/docs/README.md new file mode 100644 index 0000000..18167eb --- /dev/null +++ b/examples/blog-basic/docs/README.md @@ -0,0 +1,18 @@ +# Adding a blog to your site + +This example shows how to add a [blog] to your site. + +It shows how to: + +- configure the `mkdocs.yml` to activate and configure the plugin +- set up a directory structure in your `docs/` folder +- add an `.authors.yml` file with author information + +The naming of the files containing the blog posts is just a +suggestion, you can name them any way you like. What matters is the +meta data at in the header. + + [blog]: https://squidfunk.github.io/mkdocs-material/plugins/blog/ + + + diff --git a/examples/blog-basic/docs/blog/.authors.yml b/examples/blog-basic/docs/blog/.authors.yml new file mode 100644 index 0000000..6119bc8 --- /dev/null +++ b/examples/blog-basic/docs/blog/.authors.yml @@ -0,0 +1,9 @@ +authors: + squidfunk: + name: Martin Donath + description: Creator + avatar: https://github.com/squidfunk.png + alexvoss: + name: Alex Voss + description: Weltenwanderer + avatar: https://github.com/alexvoss.png diff --git a/examples/blog-basic/docs/blog/index.md b/examples/blog-basic/docs/blog/index.md new file mode 100644 index 0000000..c58f16c --- /dev/null +++ b/examples/blog-basic/docs/blog/index.md @@ -0,0 +1,2 @@ +# Blog + diff --git a/examples/blog-basic/docs/blog/posts/2023-10-11-firstpost.md b/examples/blog-basic/docs/blog/posts/2023-10-11-firstpost.md new file mode 100644 index 0000000..5cdcd8c --- /dev/null +++ b/examples/blog-basic/docs/blog/posts/2023-10-11-firstpost.md @@ -0,0 +1,32 @@ +--- +authors: + - alexvoss +date: 2023-10-11 +categories: + - meta +--- + +# My first blog post + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec +maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula +erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst. +Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris +Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in +sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac +metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet. + + + +Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum +massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam +tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet +molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus. + +Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat. +In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc +pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis +arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue. +In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque +tellus id elit ultricies, vel finibus erat cursus. + diff --git a/examples/blog-basic/docs/blog/posts/2023-10-12-welcome.md b/examples/blog-basic/docs/blog/posts/2023-10-12-welcome.md new file mode 100644 index 0000000..c8cc7e6 --- /dev/null +++ b/examples/blog-basic/docs/blog/posts/2023-10-12-welcome.md @@ -0,0 +1,32 @@ +--- +authors: + - squidfunk +date: 2023-10-12 +categories: + - hello +--- + +# Welcome to Material for MkDocs + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec +maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula +erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst. +Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris +Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in +sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac +metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet. + + + +Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum +massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam +tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet +molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus. + +Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat. +In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc +pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis +arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue. +In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque +tellus id elit ultricies, vel finibus erat cursus. + diff --git a/examples/blog-basic/mkdocs.yml b/examples/blog-basic/mkdocs.yml new file mode 100644 index 0000000..0bb2e09 --- /dev/null +++ b/examples/blog-basic/mkdocs.yml @@ -0,0 +1,42 @@ +# Copyright (c) 2016-2023 the authors: +# +# Martin Donath +# Alex Voss + +# 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. + +# ----------------------------------------------------------------------------- +# Recommended: set up configuration validation, see https://t.ly/xpZXU +# ----------------------------------------------------------------------------- + +# Project information +site_name: Basic blog setup example + +# Theme +theme: + name: material + +# Plugins +# Note that you need to add the search plugin manually +# as soon as you use another plugin. +plugins: + - search + - blog: + pagination: true + pagination_per_page: 5 From 4ea467fc6df7bcf5ed68317f542c236727aede14 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Wed, 11 Oct 2023 12:12:45 +0100 Subject: [PATCH 4/9] more ideas about what the metadata could look like --- examples/blog-basic/meta.yml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/examples/blog-basic/meta.yml b/examples/blog-basic/meta.yml index 1abae26..be38935 100644 --- a/examples/blog-basic/meta.yml +++ b/examples/blog-basic/meta.yml @@ -4,11 +4,13 @@ meta: tags: - public # works without Insiders + #- insiders # requires Insiders edition - blog # functionality demonstrated - simple # requires no extra plugins or other magic - # - experimental # uses an experimental feature somewhere - author: - name: Alex Voss # author name - handle: alexvoss # a Github handle for giving credit and - # identifying who would fix any regressions - # other than @squidfunk + #- integration # demonstrates integration, use of other plugins + #- experimental # uses an experimental feature somewhere + authors: + alexvoss: + name: Alex Voss + description: Collaborator + avatar: https://github.com/alexvoss.png From bc6ad43171f6ab2f7e6e4f33bbcd99f9b747e278 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Wed, 11 Oct 2023 13:09:25 +0100 Subject: [PATCH 5/9] added missing requirements.txt --- examples/blog-basic/requirements.txt | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) create mode 100644 examples/blog-basic/requirements.txt diff --git a/examples/blog-basic/requirements.txt b/examples/blog-basic/requirements.txt new file mode 100644 index 0000000..df8b44f --- /dev/null +++ b/examples/blog-basic/requirements.txt @@ -0,0 +1,21 @@ +# Copyright (c) 2016-2023 Martin Donath + +# 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. + +mkdocs-material From 8d2377275113f07122a53c9e9668201761e11af3 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Wed, 11 Oct 2023 13:51:41 +0100 Subject: [PATCH 6/9] added an example for adding RSS to a blog --- examples/blog-rss/docs/README.md | 8 +++ examples/blog-rss/docs/blog/.authors.yml | 9 +++ examples/blog-rss/docs/blog/index.md | 4 ++ .../docs/blog/posts/2023-10-11-firstpost.md | 32 +++++++++++ .../docs/blog/posts/2023-10-12-welcome.md | 32 +++++++++++ examples/blog-rss/meta.yml | 16 ++++++ examples/blog-rss/mkdocs.yml | 56 +++++++++++++++++++ examples/blog-rss/requirements.txt | 24 ++++++++ 8 files changed, 181 insertions(+) create mode 100644 examples/blog-rss/docs/README.md create mode 100644 examples/blog-rss/docs/blog/.authors.yml create mode 100644 examples/blog-rss/docs/blog/index.md create mode 100644 examples/blog-rss/docs/blog/posts/2023-10-11-firstpost.md create mode 100644 examples/blog-rss/docs/blog/posts/2023-10-12-welcome.md create mode 100644 examples/blog-rss/meta.yml create mode 100644 examples/blog-rss/mkdocs.yml create mode 100644 examples/blog-rss/requirements.txt diff --git a/examples/blog-rss/docs/README.md b/examples/blog-rss/docs/README.md new file mode 100644 index 0000000..aa41ae6 --- /dev/null +++ b/examples/blog-rss/docs/README.md @@ -0,0 +1,8 @@ +# Adding an RSS feed to a blog + +This example shows how to [add an RSS feed to a blog]. Have a look at +[the feed for this example]. + + [add an RSS feed to a blog]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/?h=#rss + [the feed for this example]: /feed_rss_created.xml + diff --git a/examples/blog-rss/docs/blog/.authors.yml b/examples/blog-rss/docs/blog/.authors.yml new file mode 100644 index 0000000..6119bc8 --- /dev/null +++ b/examples/blog-rss/docs/blog/.authors.yml @@ -0,0 +1,9 @@ +authors: + squidfunk: + name: Martin Donath + description: Creator + avatar: https://github.com/squidfunk.png + alexvoss: + name: Alex Voss + description: Weltenwanderer + avatar: https://github.com/alexvoss.png diff --git a/examples/blog-rss/docs/blog/index.md b/examples/blog-rss/docs/blog/index.md new file mode 100644 index 0000000..ea91c08 --- /dev/null +++ b/examples/blog-rss/docs/blog/index.md @@ -0,0 +1,4 @@ +# Blog + + +[Subscribe to this feed](http://localhost:8000/feed_rss_created.xml) diff --git a/examples/blog-rss/docs/blog/posts/2023-10-11-firstpost.md b/examples/blog-rss/docs/blog/posts/2023-10-11-firstpost.md new file mode 100644 index 0000000..5cdcd8c --- /dev/null +++ b/examples/blog-rss/docs/blog/posts/2023-10-11-firstpost.md @@ -0,0 +1,32 @@ +--- +authors: + - alexvoss +date: 2023-10-11 +categories: + - meta +--- + +# My first blog post + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec +maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula +erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst. +Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris +Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in +sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac +metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet. + + + +Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum +massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam +tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet +molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus. + +Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat. +In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc +pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis +arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue. +In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque +tellus id elit ultricies, vel finibus erat cursus. + diff --git a/examples/blog-rss/docs/blog/posts/2023-10-12-welcome.md b/examples/blog-rss/docs/blog/posts/2023-10-12-welcome.md new file mode 100644 index 0000000..c8cc7e6 --- /dev/null +++ b/examples/blog-rss/docs/blog/posts/2023-10-12-welcome.md @@ -0,0 +1,32 @@ +--- +authors: + - squidfunk +date: 2023-10-12 +categories: + - hello +--- + +# Welcome to Material for MkDocs + +Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec +maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula +erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst. +Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris +Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in +sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac +metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet. + + + +Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum +massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam +tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet +molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus. + +Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat. +In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc +pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis +arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue. +In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque +tellus id elit ultricies, vel finibus erat cursus. + diff --git a/examples/blog-rss/meta.yml b/examples/blog-rss/meta.yml new file mode 100644 index 0000000..9fe7d81 --- /dev/null +++ b/examples/blog-rss/meta.yml @@ -0,0 +1,16 @@ +# This file is used only to generate a browsable +# list of examples for our documentation. You do +# not need it in your own projects. +meta: + tags: + - public # works without Insiders + #- insiders # requires Insiders edition + - blog # functionality demonstrated + #- simple # requires no extra plugins or other magic + - integration # demonstrates integration, use of other plugins + #- experimental # uses an experimental feature somewhere + authors: + alexvoss: + name: Alex Voss + description: Collaborator + avatar: https://github.com/alexvoss.png diff --git a/examples/blog-rss/mkdocs.yml b/examples/blog-rss/mkdocs.yml new file mode 100644 index 0000000..930ceb3 --- /dev/null +++ b/examples/blog-rss/mkdocs.yml @@ -0,0 +1,56 @@ +# Copyright (c) 2016-2023 the authors: +# +# Martin Donath +# Alex Voss + +# 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. + +# ----------------------------------------------------------------------------- +# Recommended: set up configuration validation, see https://t.ly/xpZXU +# ----------------------------------------------------------------------------- + +# Project information +site_name: Blog with RSS example # required by RSS plugin +site_description: one of many fine examples # required by RSS plugin +site_url: http://localhost:8080 # required by RSS plugin + +# Theme +theme: + name: material + +# Plugins +plugins: + # Note that you need to add the search plugin manually + # as soon as you use another plugin. + - search + # Blog plugin + - blog: + pagination: true + pagination_per_page: 5 + # RSS plugin - https://pypi.org/project/mkdocs-rss-plugin/ + - rss: + match_path: blog/posts/.* + date_from_meta: + as_creation: date + as_update: false + date_format: "%Y-%m-%d" # specify if the RSS plugin does + # not understand the format you use + categories: + - categories + - tags diff --git a/examples/blog-rss/requirements.txt b/examples/blog-rss/requirements.txt new file mode 100644 index 0000000..cb2a5e8 --- /dev/null +++ b/examples/blog-rss/requirements.txt @@ -0,0 +1,24 @@ +# Copyright (c) 2016-2023 the authors: +# Martin Donath +# Alex Voss + +# 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. + +mkdocs-material +mkdocs-rss-plugin From 9ba2f61b642df024e60217e26c89ce15f3d0a3f1 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Wed, 11 Oct 2023 16:32:34 +0100 Subject: [PATCH 7/9] incorporated PR feedback - renamed and tidied up example metadata - changed formatting of copyright - renamed blog post files - retitled 2nd blog post - removed unnecessary stuff from mkdocs.yml - for both examples --- examples/blog-basic/.example.yml | 10 ++++++++++ .../{2023-10-11-firstpost.md => firstpost.md} | 0 .../{2023-10-12-welcome.md => secondpost.md} | 2 +- examples/blog-basic/meta.yml | 16 ---------------- examples/blog-basic/mkdocs.yml | 14 ++++---------- examples/blog-rss/.example.yaml | 10 ++++++++++ .../{2023-10-11-firstpost.md => firstpost.md} | 0 .../{2023-10-12-welcome.md => secondpost.md} | 2 +- examples/blog-rss/meta.yml | 16 ---------------- examples/blog-rss/mkdocs.yml | 16 ++++------------ 10 files changed, 30 insertions(+), 56 deletions(-) create mode 100644 examples/blog-basic/.example.yml rename examples/blog-basic/docs/blog/posts/{2023-10-11-firstpost.md => firstpost.md} (100%) rename examples/blog-basic/docs/blog/posts/{2023-10-12-welcome.md => secondpost.md} (97%) delete mode 100644 examples/blog-basic/meta.yml create mode 100644 examples/blog-rss/.example.yaml rename examples/blog-rss/docs/blog/posts/{2023-10-11-firstpost.md => firstpost.md} (100%) rename examples/blog-rss/docs/blog/posts/{2023-10-12-welcome.md => secondpost.md} (97%) delete mode 100644 examples/blog-rss/meta.yml diff --git a/examples/blog-basic/.example.yml b/examples/blog-basic/.example.yml new file mode 100644 index 0000000..5186201 --- /dev/null +++ b/examples/blog-basic/.example.yml @@ -0,0 +1,10 @@ +example: + tags: + - public # works without Insiders + - blog # functionality demonstrated + - simple # requires no extra plugins or other magic + authors: + alexvoss: + name: Alex Voss + description: Collaborator + avatar: https://github.com/alexvoss.png diff --git a/examples/blog-basic/docs/blog/posts/2023-10-11-firstpost.md b/examples/blog-basic/docs/blog/posts/firstpost.md similarity index 100% rename from examples/blog-basic/docs/blog/posts/2023-10-11-firstpost.md rename to examples/blog-basic/docs/blog/posts/firstpost.md diff --git a/examples/blog-basic/docs/blog/posts/2023-10-12-welcome.md b/examples/blog-basic/docs/blog/posts/secondpost.md similarity index 97% rename from examples/blog-basic/docs/blog/posts/2023-10-12-welcome.md rename to examples/blog-basic/docs/blog/posts/secondpost.md index c8cc7e6..352d997 100644 --- a/examples/blog-basic/docs/blog/posts/2023-10-12-welcome.md +++ b/examples/blog-basic/docs/blog/posts/secondpost.md @@ -6,7 +6,7 @@ categories: - hello --- -# Welcome to Material for MkDocs +# A second post Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula diff --git a/examples/blog-basic/meta.yml b/examples/blog-basic/meta.yml deleted file mode 100644 index be38935..0000000 --- a/examples/blog-basic/meta.yml +++ /dev/null @@ -1,16 +0,0 @@ -# This file is used only to generate a browsable -# list of examples for our documentation. You do -# not need it in your own projects. -meta: - tags: - - public # works without Insiders - #- insiders # requires Insiders edition - - blog # functionality demonstrated - - simple # requires no extra plugins or other magic - #- integration # demonstrates integration, use of other plugins - #- experimental # uses an experimental feature somewhere - authors: - alexvoss: - name: Alex Voss - description: Collaborator - avatar: https://github.com/alexvoss.png diff --git a/examples/blog-basic/mkdocs.yml b/examples/blog-basic/mkdocs.yml index 0bb2e09..901f2cb 100644 --- a/examples/blog-basic/mkdocs.yml +++ b/examples/blog-basic/mkdocs.yml @@ -1,7 +1,5 @@ -# Copyright (c) 2016-2023 the authors: -# -# Martin Donath -# Alex Voss +# Copyright (c) 2016-2023 Martin Donath +# Alex Voss # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to @@ -32,11 +30,7 @@ site_name: Basic blog setup example theme: name: material -# Plugins -# Note that you need to add the search plugin manually -# as soon as you use another plugin. +# Plugins plugins: - search - - blog: - pagination: true - pagination_per_page: 5 + - blog diff --git a/examples/blog-rss/.example.yaml b/examples/blog-rss/.example.yaml new file mode 100644 index 0000000..1d5a3c5 --- /dev/null +++ b/examples/blog-rss/.example.yaml @@ -0,0 +1,10 @@ +example: + tags: + - public # works without Insiders + - blog # functionality demonstrated + - integration # demonstrates integration, use of other plugins + authors: + alexvoss: + name: Alex Voss + description: Collaborator + avatar: https://github.com/alexvoss.png diff --git a/examples/blog-rss/docs/blog/posts/2023-10-11-firstpost.md b/examples/blog-rss/docs/blog/posts/firstpost.md similarity index 100% rename from examples/blog-rss/docs/blog/posts/2023-10-11-firstpost.md rename to examples/blog-rss/docs/blog/posts/firstpost.md diff --git a/examples/blog-rss/docs/blog/posts/2023-10-12-welcome.md b/examples/blog-rss/docs/blog/posts/secondpost.md similarity index 97% rename from examples/blog-rss/docs/blog/posts/2023-10-12-welcome.md rename to examples/blog-rss/docs/blog/posts/secondpost.md index c8cc7e6..352d997 100644 --- a/examples/blog-rss/docs/blog/posts/2023-10-12-welcome.md +++ b/examples/blog-rss/docs/blog/posts/secondpost.md @@ -6,7 +6,7 @@ categories: - hello --- -# Welcome to Material for MkDocs +# A second post Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula diff --git a/examples/blog-rss/meta.yml b/examples/blog-rss/meta.yml deleted file mode 100644 index 9fe7d81..0000000 --- a/examples/blog-rss/meta.yml +++ /dev/null @@ -1,16 +0,0 @@ -# This file is used only to generate a browsable -# list of examples for our documentation. You do -# not need it in your own projects. -meta: - tags: - - public # works without Insiders - #- insiders # requires Insiders edition - - blog # functionality demonstrated - #- simple # requires no extra plugins or other magic - - integration # demonstrates integration, use of other plugins - #- experimental # uses an experimental feature somewhere - authors: - alexvoss: - name: Alex Voss - description: Collaborator - avatar: https://github.com/alexvoss.png diff --git a/examples/blog-rss/mkdocs.yml b/examples/blog-rss/mkdocs.yml index 930ceb3..6feef93 100644 --- a/examples/blog-rss/mkdocs.yml +++ b/examples/blog-rss/mkdocs.yml @@ -1,7 +1,5 @@ -# Copyright (c) 2016-2023 the authors: -# -# Martin Donath -# Alex Voss +# Copyright (c) 2016-2023 Martin Donath +# Alex Voss # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to @@ -36,15 +34,9 @@ theme: # Plugins plugins: - # Note that you need to add the search plugin manually - # as soon as you use another plugin. - search - # Blog plugin - - blog: - pagination: true - pagination_per_page: 5 - # RSS plugin - https://pypi.org/project/mkdocs-rss-plugin/ - - rss: + - blog # https://squidfunk.github.io/mkdocs-material/plugins/blog/ + - rss: # https://pypi.org/project/mkdocs-rss-plugin/ match_path: blog/posts/.* date_from_meta: as_creation: date From 5121044e6c807c1aa1ab354f575635f29b5225f9 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Wed, 11 Oct 2023 17:54:58 +0100 Subject: [PATCH 8/9] removed link to feed from README... and added a note about how to use it with an RSS reader. I would still love to have a UI element for accessing the feed --- examples/blog-rss/docs/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/examples/blog-rss/docs/README.md b/examples/blog-rss/docs/README.md index aa41ae6..629c575 100644 --- a/examples/blog-rss/docs/README.md +++ b/examples/blog-rss/docs/README.md @@ -1,8 +1,8 @@ # Adding an RSS feed to a blog -This example shows how to [add an RSS feed to a blog]. Have a look at -[the feed for this example]. +This example shows how to [add an RSS feed to a blog]. You should be +able to point any RSS reader at the site and it will pick up the RSS +feed from a declaration in the HTML header. [add an RSS feed to a blog]: https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/?h=#rss - [the feed for this example]: /feed_rss_created.xml From 8d9be97bd58b5d3961191a2b0ac09e2461dd43e0 Mon Sep 17 00:00:00 2001 From: Alex Voss Date: Wed, 11 Oct 2023 17:57:55 +0100 Subject: [PATCH 9/9] reformatted copyright notice --- examples/blog-rss/requirements.txt | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/examples/blog-rss/requirements.txt b/examples/blog-rss/requirements.txt index cb2a5e8..1a71d07 100644 --- a/examples/blog-rss/requirements.txt +++ b/examples/blog-rss/requirements.txt @@ -1,6 +1,5 @@ -# Copyright (c) 2016-2023 the authors: -# Martin Donath -# Alex Voss +# Copyright (c) 2016-2023 Martin Donath +# Alex Voss # Permission is hereby granted, free of charge, to any person obtaining a copy # of this software and associated documentation files (the "Software"), to