mkdocs-material
mkdocs-material copied to clipboard
squidfunk
added tutorials page and blog tutorial
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.
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.
This looks pretty good! Cutting the tutorial into multiple parts makes them way more digestible ☺️ Two things that caught my attention immediately:
- 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
- Maybe too many admonitions are used. Note that admonitions are not linkable, as they do not feature a distinctive
idattribute. It might be a good idea to convert some admonitions to sections, especially at the end of the third part.
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 card_include and cards_exclude options in the social plugin? I realize that what I did above with the meta plugin could also be done using these. It would be good to show both but not using the same example.
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.