docs(shortcodes): Add demo repository badge

[niclasheinz]

Hi @squidfunk

There are some example repositories at https://github.com/mkdocs-material, but these are not listed in the documents. With the new badge, the example repositories can be linked in the documentation.

[squidfunk]

Thanks for the PR. Just to knit pick, I'm not really happy with "examplerepo". Also, where would we use it? Could you add suggestions in this PR, so we can learn whether we really want/need this?

[niclasheinz]

I've updated the PR. I thought it would be useful if the existing template repositories from github.com/mkdocs-material were linked in the documentation.

[kamilkrzyskow]

I think it's a good addition to the example, which links to downloadable zip archives.

Likewise to squidfunk I think that the name examplerepo together with Example repository could be improved 🤔.
How about demo and Demonstration, as the repositories could have their own rendered pages?

[niclasheinz]

How about demo and Demonstration, as the repositories could have their own rendered pages?

Good point. That's definitely a better formulation than the one I made.

[squidfunk]

+1 for Kamil's proposal!

[squidfunk]

@niclasheinz are you still wanting to progress on this PR? If so, it would be great if you could find the time to include the proposed changes by Kamil ☺️ Specifically:

Likewise to squidfunk I think that the name examplerepo together with Example repository could be improved 🤔.
How about demo and Demonstration, as the repositories could have their own rendered pages?

Thanks in advance!

[niclasheinz]

Hi @squidfunk

Thanks for reminding me, I forgot about it because I'm busy at the moment. I'll catch up in a few days.

[squidfunk]

No hurry! Just wanted to know whether there are any impediments. Take your time ☺️

[niclasheinz]

@squidfunk It's ready for review 😄

[kamilkrzyskow]

I feel like the idea branched off into another direction.

The example code could've stayed and keep the Example naming as it refers to the https://github.com/mkdocs-material/examples repository, which hosts many different sub-example projects, and their .zip archive.

The demo would refer to standalone Demonstration repositories like the mike versioning repository, as it changes the "logic" of the repository, so it can't really be packaged into one the /examples repository sub-projects.

Either I'm making sense, or the separate demonstration and demo short codes bother me and I'm just blabbering 😅

[niclasheinz]

Thanks for your feedback!

I thought demonstration is better for a ‘live-demonstration’ where I can see what the result might look like. And the associated repository is the ‘demo’. That's why I originally chose ‘examplerepo’ as the name.

But yes, your view also makes sense.

What do you think @squidfunk?

[squidfunk]

Thanks for making the changes. However, I'm with Kamil here, so please keep the example as-is. An example is a show case of a specific feature. We can add the demo code for the blog, social card and versioning demo, which is more involved, as it includes several features, but we should really keep it simple. Just follow the style of the example code in the hook.

[niclasheinz]

Okay, I have adjusted it

[squidfunk]

Thanks again! We're almost there.

I just realized that you made all your changes in the material directory. This directory is actually generated and gets overwritten on each build, so you changes will be gone when you type npm run build:all. Please make the changes in the src folder and build the theme. For this, you need to go through the theme development process. If you're having trouble with the latter, you can just leave it as such and I will complete it for you in this case, no worries ☺️

[squidfunk]

Also please see Alex' excellent guide on how to create a PR on this repository.

[niclasheinz]

Thanks for the tip - reading will get me much further in life 😅

I'll keep my fingers crossed that it's right now.

[squidfunk]

No worries! I know it can be challenging at first. As you know from our last call, we're also working on making things much simpler in the near future ☺️ One last thing is missing: the search icon index is deleted, which is because pymdownx is not installed when you built it. Either remove the delete, or install pymdownx and do another rebuild.

[niclasheinz]

I have solved the problem

[squidfunk]

Perfect, LGTM! Merging through.