Skip to content

Commit

Permalink
Documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
squidfunk committed Feb 24, 2024
1 parent 23f1886 commit f26cfaa
Show file tree
Hide file tree
Showing 7 changed files with 119 additions and 12 deletions.
5 changes: 5 additions & 0 deletions docs/insiders/changelog/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
15 changes: 9 additions & 6 deletions docs/insiders/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
23 changes: 23 additions & 0 deletions docs/plugins/blog.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
Expand Down
2 changes: 1 addition & 1 deletion docs/setup/changing-the-language.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
Expand Down
25 changes: 24 additions & 1 deletion docs/setup/setting-up-a-blog.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
Expand Down Expand Up @@ -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
Expand Down
57 changes: 55 additions & 2 deletions docs/setup/setting-up-navigation.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
4 changes: 2 additions & 2 deletions docs/setup/setting-up-tags.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 -->
Expand Down Expand Up @@ -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
Expand Down

0 comments on commit f26cfaa

Please sign in to comment.