Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

added tutorials page and blog tutorial #7014

Merged
merged 30 commits into from
May 28, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
53647ba
added tutorials page and blog tutorial
alexvoss Apr 5, 2024
6f61627
proof reading, some language improvements
alexvoss Apr 10, 2024
ab01ac1
split blog tutorial into parts
alexvoss Apr 17, 2024
c9925f4
+ custom slugify function example
alexvoss Apr 18, 2024
e0a5b29
+blog tutorial on engagement
alexvoss Apr 18, 2024
5de5a4f
+ section blog ToC
alexvoss Apr 19, 2024
186c1c1
+ instructions for X/FB share buttons and started discussion system
alexvoss Apr 25, 2024
cc19431
fix: module name `code` shadowed Python standard library module
alexvoss Apr 30, 2024
876e7c6
added What's next section
alexvoss May 1, 2024
cd15b11
+blog tutorial engagement part
alexvoss May 2, 2024
790ff4d
fix: updated Giscus code snippet
alexvoss May 2, 2024
3a3ae8d
trying multiple tutorials with headings for each group
alexvoss May 2, 2024
4c16ada
+ basic social cards tutorial
alexvoss May 5, 2024
5291d41
+ custom social card tutorial
alexvoss May 5, 2024
6a4957d
+ estimated time for custom card tutorial
alexvoss May 5, 2024
5b9f720
added tutorial sections to nav
alexvoss May 8, 2024
a41c36b
fixed typos, removed sponsor icon from level one heading
alexvoss May 8, 2024
fa75401
removed "tutorial" from level one heading
alexvoss May 8, 2024
1bff14d
added headings to custom layout example
alexvoss May 11, 2024
66debda
fixed broken link
alexvoss May 14, 2024
69501b2
fixes after run-through, added links to template repos
alexvoss May 17, 2024
a4bda94
Merge branch 'master' into blogtutorial
squidfunk May 24, 2024
fc26e52
added comment for @squidfunk
alexvoss May 17, 2024
3c9c651
clarified use of logos, some proof-reading
alexvoss May 26, 2024
da76ed7
removed question I left for @squidfunk
alexvoss May 26, 2024
b77de62
clarified relationship between background color and image
alexvoss May 27, 2024
c971fd3
added override for the background image
alexvoss May 28, 2024
4d0b869
fixed wording and indentation
alexvoss May 28, 2024
9f9299e
changed example to be releases, not events
alexvoss May 28, 2024
2545872
being more specific where to add the last bit of code in the layout
alexvoss May 28, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
59 changes: 59 additions & 0 deletions docs/tutorials.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Tutorials

In addition to the basic getting started guides, we offer tutorials that aim to
show how Material for MkDocs can be used in different use cases. In contrast to
the getting started guides or the reference documentation, the tutorials show
the breadth of functionality available with Material for MkDocs but also within
the wider MkDocs ecosystem.

* [Blogs](tutorials/blogs.md)

## Tutorial Structure

The tutorials guide you through worked examples, so following them you should
gain not only and understanding of how Material for MkDocs can be used but also
a template for your own projects. For convenience, these templates are also
available as [template repositories on GitHub].

<!-- TODO -->
[template repositories on GitHub]: templates.md

Each tutorial is a single page, so use the Table of Contents navigation to move
between numbered steps. They start by mentioning prerequisites and giving an
overview of the content as well as describing the outcomes.

### Instructions

Tutorials contain a mix of explanation, demonstrations, and instructions that you
should follow as you work your way through the individual steps. Those instructions
are shown in the form of admonitions to separate them from the rest of the
tutorial:

!!! example "Instructions to follow"

Whenever you see a box like this you know it is time to get hands on and
apply material just covered as well as reflect on how you would it in your
work work.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


### Tips and warnings

Likewise, helpful tips and warnings appear in boxes of their own:

!!! tip "A hot tip!"

Tips look like this...

!!! warning "Warning!"

...and warnings like this!

## Feeback wanted
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Sponsor Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Noh prlblemo!


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? -->
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


Note, however, that suggestions should be specific and feasible. We want to
focus on creating more content instead of developing a specific styling or
behaviour for the tutorials. If there are worthwhile improvements that can
be made through simple customization we are happy to consider those.