Documentation

This commit is contained in:
squidfunk
2025-11-07 12:30:13 +01:00
committed by Martin Donath
parent b583ea7765
commit 3815f607a5
182 changed files with 14470 additions and 1627 deletions

View File

@@ -179,11 +179,10 @@ header to indicate that a post is still in draft form.
stage. Remember to remove the `draft` setting in the header when it is time
to publish it.
If you are using the [Insiders Edition], you can also create
a folder to keep your drafts in and use the [Meta plugin] to add the
`draft` header setting to all the posts in that folder. This has the advantage
that it is easier to see which posts are still in draft form. We will cover the
Meta plugin later on.
You can also create a folder to keep your drafts in and use the [Meta plugin]
to add the `draft` header setting to all the posts in that folder. This has the
advantage that it is easier to see which posts are still in draft form. We will
cover the Meta plugin later on.
[Meta plugin]: ../../plugins/meta.md
@@ -232,11 +231,10 @@ your readers will take the read the post.
### Pinning
Sometimes, blog authors want to 'pin' a specific post so that it will always
appear at the top of the index page, no matter what else gets published. If you
are using the [Insiders Edition], you can achieve this by adding the `pin`
attribute in the page header:
appear at the top of the index page, no matter what else gets published. You can
achieve this by adding the `pin` attribute in the page header:
!!! example "Pin a post <!-- md:sponsors -->"
!!! example "Pin a post"
Add the `pin` attribute to your first blog post:
@@ -261,7 +259,7 @@ will want to provide links from blog posts into your other content. One way you
can do this is to have a related links section. The blog plugin can create one
for you if you provide link targets in your page header:
!!! example "Add a related links section <!-- md:sponsors -->"
!!! example "Add a related links section"
Add the following to a blog post:
@@ -320,7 +318,7 @@ together so that they are not only flagged as drafts but also easier to find.
(Otherwise, you would need to inspect the page headers or trace back from the
output to the files to figure out which posts are drafts.)
!!! example "Drafts using the Meta plugin <!-- md:sponsors -->"
!!! example "Drafts using the Meta plugin"
You first need to activate the plugin in your `mkdocs.yaml`:
@@ -356,7 +354,6 @@ output to the files to figure out which posts are drafts.)
post from draft status to published, simply move it outside `drafts/`.
[meta]: ../../plugins/meta.md
[Insiders Edition]: ../../insiders/index.md
## What's next?

View File

@@ -323,11 +323,10 @@ the page header.
Note that `authors` is a list, so you can specify multiple authors.
With the Insiders edition, you can create custom author index pages that
can highlight the contributions of an author as well as provide additional
information about them.
You can create custom author index pages that can highlight the contributions
of an author as well as provide additional information about them.
!!! example "Add author page <!-- md:sponsors -->"
!!! example "Add author page"
First, you need to enable author profiles in the `mkdocs.yml`:

View File

@@ -11,18 +11,7 @@ gain not only an understanding of how to use Material for MkDocs, but also
a template for your own projects. For convenience, these templates are also
available as template repositories on GitHub.
The tutorials assume that you have installed either the [public version] or the
[Insiders edition] of Material for MkDocs and that you have worked through the
[creating your site] setup guide.
Note that where the features we use require the Insiders edition, we mark these
with the heart icon: <!-- md:sponsors --> If you are using the public version
then you can skip these steps. Sometimes there will be ways of achieving the
same goal that differ between the public version and the Insider edition. In
that case, we will show them in a tabbed view so you can see one or the other.
[public version]: ../getting-started.md
[Insiders edition]: ../insiders/getting-started.md
[creating your site]: ../creating-your-site.md
!!! note "Feedback wanted!"

View File

@@ -43,8 +43,8 @@ the `head` element, including one entry that points to the image.
The social plugin has configuration options for changing aspects such as colors,
images, fonts, logos, the title, even the description. You can configure them
for all social cards in the `mkdocs.yml` and, in the Insiders Edition, they can
be overridden in the page header for individual pages.
for all social cards in the `mkdocs.yml` and, they can be overridden in the page
header for individual pages.
!!! example "Change the background color"
@@ -106,17 +106,13 @@ so this is where you should make the `layouts` directory and place the
background image. The default site of the social cards included with the plugin
is 1200x630 pixels, so choose an image that size or one that scales well to it.
## Additional layouts and styles
## Additional layouts and styles
<!-- md:sponsors -->
The Insiders Edition provides additional layouts as well as the option to
configure different styles for different (kinds of) pages.
The Insiders Edition comes with a number of additional layouts for the social
cards. For example, the `default/variant` layout adds a page icon to the card.
You can use this to distinguish social cards visually, depending on what kind
of page you are sharing.
The social plugin provides additional layouts as well as the option to configure
different styles for different (kinds of) pages. It comes with a number of
additional layouts for the social cards. For example, the `default/variant`
layout adds a page icon to the card. You can use this to distinguish social
cards visually, depending on what kind of page you are sharing.
For example, imagine you have a set of pages that advertise events and you want
to include a calendar icon as a visual indication that a card advertises an
@@ -167,14 +163,11 @@ page. If that is not what you want then you will need to modify the social
card template to gets its icons from another source. You can learn how to
do this in the [custom social cards tutorial](custom.md).
## Per-page settings
## Per-page settings
<!-- md:sponsors -->
With the Insiders Edition, you can customize the card layout for each
page by adding settings to the page header. You have effectively done this
in the previous exercise, but using the meta plugin to affect a whole set of
pages.
You can customize the card layout for each page by adding settings to the page
header. You have effectively done this in the previous exercise, but using the
meta plugin to affect a whole set of pages.
Say that in addition to regular events you also have the odd webinar and
for this you want to set a different icon and also set the description to
@@ -196,10 +189,9 @@ indicate that the event is part of the webinar series.
## What's next?
With the Insiders Edition, you can also define custom layouts if the
configuration options introduced above as not enough to meet your needs.
Continue to the [custom social cards tutorial](custom.md) if you want to
find out how to do this.
You can also define custom layouts if the configuration options introduced above
as not enough to meet your needs. Continue to the
[custom social cards tutorial](custom.md) if you want to find out how to do this.
Social cards are particularly useful for blog posts. If you have a blog,
you need to do nothing more than to turn on both plugins to create social cards

View File

@@ -1,6 +1,6 @@
# Custom cards
The Insiders Edition allows you to define custom layouts for your social cards
The social plugin allows you to define custom layouts for your social cards
to suit your specific needs if the configuration options are not enough.
For example, you may want to define a social card to advertise a new release
of your product. It should have an icon indicating a launch announcement as
@@ -12,7 +12,7 @@ You can either design a custom layout from scratch or use an existing layout
as the basis that you add to or otherwise modify. In this tutorial, you will
use the default layout as the basis.
!!! example "Copy default layout to customize <!-- md:sponsors -->"
!!! example "Copy default layout to customize"
Copy the default social card layout from your installation of Material
for MkDocs to a new directory `layouts`. The instructions below assume you
@@ -53,7 +53,7 @@ assumes you have a changelog page with information about each release.
Add the version number of the latest version to the page header (so it does
not need to be parsed out of the Markdown content):
!!! example "Defining the release data <!-- md:sponsors -->"
!!! example "Defining the release data"
Create a page `docs/changelog.md` with the following content:
@@ -139,4 +139,4 @@ If you do not have a blog yet, why not check out the
[blog tutorials](../index.md#blogs) and learn how to set one up? The social
plugin will help you draw attention to your posts on social media.
Check out the [other tutorials](../index.md) we have prepared for you.
Check out the [other tutorials](../index.md) we have prepared for you.