mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-23 23:21:00 +01:00
Documentation
This commit is contained in:
squidfunk
parent
23f18866c3
commit
f26cfaaa58
@ -2,6 +2,11 @@
|
||||
|
||||
## Material for MkDocs Insiders
|
||||
|
||||
### 4.53.0 <small>February 24, 2024</small> { id="4.53.0" }
|
||||
|
||||
- Added support for automatic instant previews
|
||||
- Added support for pinned blog posts
|
||||
|
||||
### 4.52.3 <small>February 21, 2024</small> { id="4.52.3" }
|
||||
|
||||
- Fixed resolution of URLs in instant previews
|
||||
|
||||
@ -88,16 +88,17 @@ a handful of them, [thanks to our awesome sponsors]!
|
||||
## What's in it for me?
|
||||
|
||||
The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
|
||||
access to 25 additional features__ that you can __start using now__, and
|
||||
access to 26 additional features__ that you can __start using now__, and
|
||||
which are currently exclusively available to sponsors:
|
||||
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- [x] [Instant previews] :material-alert-decagram:{ .mdx-pulse title="Added on January 28, 2023" }
|
||||
- [x] [Footnote tooltips] :material-alert-decagram:{ .mdx-pulse title="Added on January 24, 2023" }
|
||||
- [x] [Tags plugin: advanced settings] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
|
||||
- [x] [Tags plugin: nested tags] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
|
||||
- [x] [Tags plugin: shadow tags] :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
|
||||
- [x] [Blog plugin: pinned posts] :material-alert-decagram:{ .mdx-pulse title="Added on February 24, 2024" }
|
||||
- [x] [Instant previews] :material-alert-decagram:{ .mdx-pulse title="Added on January 28, 2024" }
|
||||
- [x] [Footnote tooltips] :material-alert-decagram:{ .mdx-pulse title="Added on January 24, 2024" }
|
||||
- [x] [Tags plugin: advanced settings]
|
||||
- [x] [Tags plugin: nested tags]
|
||||
- [x] [Tags plugin: shadow tags]
|
||||
- [x] [Stay on page when switching languages]
|
||||
- [x] [Blog plugin: author profiles]
|
||||
- [x] [Blog plugin: advanced settings]
|
||||
@ -303,6 +304,7 @@ are released for general availability.
|
||||
- [x] [Instant prefetching]
|
||||
- [x] [Blog plugin: advanced settings]
|
||||
- [x] [Blog plugin: author profiles]
|
||||
- [x] [Blog plugin: pinned posts]
|
||||
- [x] [Footnote tooltips]
|
||||
|
||||
[Optimize plugin]: ../plugins/optimize.md
|
||||
@ -313,6 +315,7 @@ are released for general availability.
|
||||
[Instant prefetching]: ../setup/setting-up-navigation.md#instant-prefetching
|
||||
[Blog plugin: advanced settings]: ../setup/setting-up-a-blog.md#advanced-settings
|
||||
[Blog plugin: author profiles]: ../setup/setting-up-a-blog.md#adding-author-profiles
|
||||
[Blog plugin: pinned posts]: ../setup/setting-up-a-blog.md#pinning-a-post
|
||||
[Footnote tooltips]: ../reference/footnotes.md#footnote-tooltips
|
||||
|
||||
#### $ 24,000 – Blockpaprika
|
||||
|
||||
@ -1585,6 +1585,29 @@ draft: true
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting meta.pin -->
|
||||
|
||||
<!-- md:sponsors -->
|
||||
<!-- md:version insiders-4.53.0 -->
|
||||
<!-- md:flag metadata -->
|
||||
<!-- md:default `false` -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
Use this property to pin a post to the top of a view. In case multiple posts are
|
||||
pinned, the pinned posts are sorted by descending order and appear before all
|
||||
other posts. Pin a post with:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
ping: true
|
||||
---
|
||||
|
||||
# Post title
|
||||
...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
#### <!-- md:setting meta.links -->
|
||||
|
||||
<!-- md:sponsors -->
|
||||
|
||||
@ -97,7 +97,7 @@ The following properties are available for each alternate language:
|
||||
[ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
|
||||
[Language selector preview]: ../assets/screenshots/language-selection.png
|
||||
|
||||
#### Stay on page :material-alert-decagram:{ .mdx-pulse title="Added on December 8, 2023" }
|
||||
#### Stay on page
|
||||
|
||||
<!-- md:sponsors -->
|
||||
<!-- md:version insiders-4.47.0 -->
|
||||
|
||||
@ -342,7 +342,7 @@ authors:
|
||||
[authors]: ../plugins/blog.md#authors
|
||||
[authors_file]: ../plugins/blog.md#config.authors_file
|
||||
|
||||
#### Adding author profiles :material-alert-decagram:{ .mdx-pulse title="Added on November 26, 2023" }
|
||||
#### Adding author profiles
|
||||
|
||||
<!-- md:sponsors -->
|
||||
<!-- md:version insiders-4.46.0 -->
|
||||
@ -506,6 +506,29 @@ when the site is being built. Of course, you can also reference assets from
|
||||
posts outside of the `posts` directory. The [built-in blog plugin] ensures that
|
||||
all links are correct.
|
||||
|
||||
#### Pinning a post :material-alert-decagram:{ .mdx-pulse title="Added on February 24, 2024" }
|
||||
|
||||
<!-- md:sponsors -->
|
||||
<!-- md:version insiders-4.53.0 -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
If you want to pin a post to the top of the index page, as well as the archive
|
||||
and category indexes it is part of, you can use the front matter `pin` property:
|
||||
|
||||
``` yaml
|
||||
---
|
||||
date: 2024-01-31
|
||||
pin: true
|
||||
---
|
||||
|
||||
# Hello world!
|
||||
...
|
||||
```
|
||||
|
||||
If multiple posts are pinned, they are sorted by their creation date, with the
|
||||
most recent pinned post being shown first, followed by the other pinned posts in
|
||||
descending order.
|
||||
|
||||
#### Setting the reading time
|
||||
|
||||
When [enabled], the [readtime] package is used to compute the expected reading
|
||||
|
||||
@ -93,8 +93,8 @@ experience.
|
||||
|
||||
Instant previews are a brand new feature that allow the user to preview another
|
||||
site of your documentation without navigating to it. They can be very helpful to
|
||||
keep the user in context. A link can be opted into instant previews with the
|
||||
`data-preview` attribute:
|
||||
keep the user in context. Instant previews can be enabled on any internal link
|
||||
with the `data-preview` attribute:
|
||||
|
||||
```` markdown title="Link with instant preview"
|
||||
``` markdown
|
||||
@ -108,6 +108,59 @@ keep the user in context. A link can be opted into instant previews with the
|
||||
|
||||
</div>
|
||||
|
||||
#### Automatic previews
|
||||
|
||||
<!-- md:sponsors -->
|
||||
<!-- md:version insiders-4.53.0 -->
|
||||
<!-- md:extension -->
|
||||
<!-- md:flag experimental -->
|
||||
|
||||
The recommended way to work with instant previews is to use the Markdown
|
||||
extension that is included with Material for MkDocs, as it allows you to enable
|
||||
instant previews on a per-page or per-section level for your documentation:
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- material.extensions.preview:
|
||||
targets:
|
||||
include:
|
||||
- changelog/index.md
|
||||
- customization.md
|
||||
- insiders/changelog/*
|
||||
- setup/extensions/*
|
||||
```
|
||||
|
||||
The above configuration is what we use for our documentation. We've enabled
|
||||
instant previews for our changelogs, customization guide, and Insiders sections,
|
||||
as well as for all Markdown extensions that we support.
|
||||
|
||||
!!! info "Full configuration example"
|
||||
|
||||
``` yaml
|
||||
markdown_extensions:
|
||||
- material.extensions.preview:
|
||||
sources: # (1)!
|
||||
include:
|
||||
- ...
|
||||
exclude:
|
||||
- ...
|
||||
targets: # (2)!
|
||||
include:
|
||||
- ...
|
||||
exclude:
|
||||
- ...
|
||||
```
|
||||
|
||||
1. Sources specify the pages _on_ which instant previews should be enabled.
|
||||
If this setting is omitted, instant previews will be enabled on all
|
||||
pages. You can use patterns to include or exclude pages. Exclusion is
|
||||
evaluated on top of inclusion, so if a page is matched by both, it will
|
||||
be excluded.
|
||||
|
||||
2. Targets specify the pages _to_ which instant previews should be enabled.
|
||||
This is the recommended way to enable instant previews.
|
||||
---
|
||||
|
||||
Instant previews can also be enabled globally by adding the following lines to
|
||||
`mkdocs.yml`, which will enable instant previews for all internal links,
|
||||
alleviating the need to add data attributes:
|
||||
|
||||
@ -27,7 +27,7 @@ For a list of all settings, please consult the [plugin documentation].
|
||||
|
||||
[plugin documentation]: ../plugins/tags.md
|
||||
|
||||
#### Advanced settings :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
|
||||
#### Advanced settings
|
||||
|
||||
<!-- md:sponsors -->
|
||||
<!-- md:version insiders-4.48.0 -->
|
||||
@ -211,7 +211,7 @@ arbitrary content before and after the marker:
|
||||
[tags.tags_file]: #tags-file
|
||||
[tags index enabled]: ../assets/screenshots/tags-index.png
|
||||
|
||||
### Advanced features :material-alert-decagram:{ .mdx-pulse title="Added on December 23, 2023" }
|
||||
### Advanced features
|
||||
|
||||
[Insiders] ships a __ground up rewrite of the tags plugin__ which is infinitely
|
||||
more powerful than the current version in the community edition. It allows
|
||||
|
||||
Loading…
Reference in New Issue
Block a user