added tutorials page and blog tutorial #7014
Conversation
There was a problem hiding this comment.
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.
docs/tutorials.md
Outdated
|
|
||
| ...and warnings like this! | ||
|
|
||
| ## Feeback wanted |
There was a problem hiding this comment.
Proof-reading required – I spotted several typos, including this one.
There was a problem hiding this comment.
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.
docs/tutorials.md
Outdated
|
|
||
| The tutorials are a recent addition to our documentation and we are still | ||
| working out what shape they should have in the end. Please contact us if you | ||
| want to provide feedback. <!--- TODOD: how? --> |
There was a problem hiding this comment.
We should create a discussion asking for feedback on this tutorial, pin it, and link to that.
docs/tutorials/blogs.md
Outdated
| To add social cards to your blog you need to install some dependencies. | ||
| These differ depending on what operating system you use. | ||
|
|
||
| TODO: paste in installation instructions here - use snippets since this is |
There was a problem hiding this comment.
Please don't. This tutorial is already very, very long, IMHO.
There was a problem hiding this comment.
Perhaps adding social cards to a blog would be a part in the social cards tutorial rather than the other way round?
There was a problem hiding this comment.
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! ...
docs/tutorials/blogs.md
Outdated
| itself and what configuration options you can use modify the defaults. Required | ||
| RSS element are marked with an asterisk. | ||
|
|
||
| | RSS element | default | configure | |
There was a problem hiding this comment.
Honestly, this is so much line noise and irrelevant at this point. I'm not even sure I understand it.
|
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. |
docs/tutorials.md
Outdated
| apply material just covered as well as reflect on how you would it in your | ||
| work work. |
There was a problem hiding this comment.
This line is reading a bit weird. Especially the "work work" which must be a typo.
There was a problem hiding this comment.
Jup, as I mentioned in #7014 (comment), this is a draft and not proof-read.
and reworked on the basis of comments, improved language, added missing things
|
This looks pretty good! Cutting the tutorial into multiple parts makes them way more digestible
|
|
We still need to finish the template repositories. Once they are online, we can merge this PR. |
|
@suidfunk, do you have a killer use case for the |
|
No, just leave them out. It's a general feature that allows to use different layouts via multiple instances, but it's definitely advanced use. |
|
@squidfunk, I have changed the custom layout example. Was unhappy that it duplicated the events, so decided to use celebrating new releases as a use case. Hope that fits the bill. The code got a bit easier, which I think is also good for a tutorial. Template is also pushed to the repo. Have a look to see if you are happy with it. |
|
Perfect! Let's go ahead with that. |
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.mdand can be found underGetting-started, thenTutorials.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.