mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2026-08-02 02:38:53 -04:00
Documentation
This commit is contained in:
@@ -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?
|
||||
|
||||
|
||||
@@ -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`:
|
||||
|
||||
|
||||
@@ -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!"
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user