added tutorials page and blog tutorial

[alexvoss]

I have added the blog tutorial to a new branch as the old one got messy and I could not make sense of it.

The tutorials page is under docs/tutorials.md and can be found under Getting-started, then Tutorials.

As mentioned elsewhere, there are perhaps bits that don't need to be in here or perhaps not in all their glory (looking at you custom social layout) but I did not want to cut anything before discussion.

[squidfunk]

Thanks for this first draft! It's already quite good, but I think it does too many detours and is quite wordy at times. I tried to comment all section that I felt need massaging. For instance, custom social cards should not be part of this tutorial. Essentially, this tutorial should be a 5-10min starter that helps the user to get a blog of the ground, ideally with a starter template that can be cloned. Reading through it takes too long, IMHO. We should create multiple smaller tutorials out of this and keep the scope of a blog introductory tutorial as lean and small as we possibly can.

An idea for a multi-level tutorial spread across several pages:

Blog

• Quick start: Get a blog up and running in 5 minutes (blog plugin)
• Authors, categories and tags: How to organize and group blog articles, including recommended file system structure (+ meta plugin)
• Post URLs: Configuring and influencing post URLs (settings, overrides, etc.) (+ blog plugin advanced config)
• Improving sharing: Social cards and RSS plugin (+ social and RSS plugin)

Each of those can be a tutorial of its own, and zoom in on a specific aspect of the blog plugin in conjunction with other plugins. IMHO a 5min quick start is absolutely essential to show our great DX, and in-depth tutorials show how powerful the blog plugin and the combination with other plugins is.

[squidfunk]

Proof-reading required – I spotted several typos, including this one.

[alexvoss]

Right, I must have written that part before turning on Vale, which would have alerted me to this one. It does not catch problems where a word is correctly spelled but is the wrong word in the context. I guess Grammarly or LanguageTool would find those.

[squidfunk]

Noh prlblemo!

[squidfunk]

We should create a discussion asking for feedback on this tutorial, pin it, and link to that.

[squidfunk]

Please don't. This tutorial is already very, very long, IMHO.

[alexvoss]

Perhaps adding social cards to a blog would be a part in the social cards tutorial rather than the other way round?

[squidfunk]

Jup, good idea. A tutorial on how to get up and running, configure and customize social cards could be an excellent link target from the blog target. Something like: oh, you think you're done with what can be done with Material for MkDocs? Well, check those tutorials out! ...

[squidfunk]

Honestly, this is so much line noise and irrelevant at this point. I'm not even sure I understand it.

[alexvoss]

Thanks, that is very helpful and goes in the direction I though it would go. Mayn't get to refactor by Tuesday but it should not take too long.

[Andre601]

This line is reading a bit weird. Especially the "work work" which must be a typo.

[squidfunk]

Jup, as I mentioned in #7014 (comment), this is a draft and not proof-read.

[squidfunk]

This looks pretty good! Cutting the tutorial into multiple parts makes them way more digestible ☺️ Two things that caught my attention immediately:

1. The blog tutorials are not linked in the navigation, i.e., the sidebar is empty. I understand that this might not work when we have too many tutorials, but just start with putting them in the navigation, so they are more easily accessible
2. Maybe too many admonitions are used. Note that admonitions are not linkable, as they do not feature a distinctive id attribute. It might be a good idea to convert some admonitions to sections, especially at the end of the third part.