mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-27 17:00:54 +01:00
Documentation
This commit is contained in:
squidfunk
parent
87d5ca487b
commit
3cc6e4aec8
@ -119,7 +119,7 @@ are still exclusively available to sponsors as part of [Insiders]:
|
||||
- [Boosting pages in search]
|
||||
- [Brand new search plugin]
|
||||
- [Code annotations]
|
||||
- [Code annotations: anchor links]
|
||||
- Code annotations: anchor links
|
||||
- [Code annotations: strip comments]
|
||||
- [Code block titles]
|
||||
- [Code block line anchors]
|
||||
@ -167,7 +167,6 @@ __55__ times, `mkdocs-material-insiders` was shipped __72__ times.
|
||||
[Boosting pages in search]: ../../setup/setting-up-site-search.md#search-boosting
|
||||
[Brand new search plugin]: search-better-faster-smaller.md
|
||||
[Code annotations]: ../../reference/code-blocks.md#adding-annotations
|
||||
[Code annotations: anchor links]: ../../reference/code-blocks.md#anchor-links
|
||||
[Code annotations: strip comments]: ../../reference/code-blocks.md#stripping-comments
|
||||
[Code block titles]: ../../reference/code-blocks.md#adding-a-title
|
||||
[Code block line anchors]: ../../setup/extensions/python-markdown-extensions.md#anchor-linenums
|
||||
|
||||
@ -88,14 +88,16 @@ 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 23 additional features__ that you can start using right away, and
|
||||
access to 25 additional features__ that you can start using right away, and
|
||||
which are currently exclusively available to sponsors:
|
||||
|
||||
<div class="mdx-columns" markdown>
|
||||
|
||||
- [x] [Code range selection] :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
|
||||
- [x] [Code annotations: custom selectors] :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
|
||||
- [x] [Privacy plugin: optimization support] :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
|
||||
- [x] [Optimize plugin] :material-alert-decagram:{ .mdx-pulse title="Added on January 21, 2023" }
|
||||
- [x] [Navigation path] (Breadcrumbs) :material-alert-decagram:{ .mdx-pulse title="Added on January 14, 2023" }
|
||||
- [x] [Optimize plugin]
|
||||
- [x] [Navigation path] (Breadcrumbs)
|
||||
- [x] [Typeset plugin]
|
||||
- [x] [Privacy plugin: external links]
|
||||
- [x] [Navigation subtitles]
|
||||
@ -287,7 +289,7 @@ are released for general availability.
|
||||
- [x] [Blog plugin: related links]
|
||||
- [x] [Blog plugin: custom index pages]
|
||||
- [x] [Tags plugin: additional indexes]
|
||||
- [x] [Tags plugin: allow list] and [custom sorting]
|
||||
- [x] [Tags plugin: allow list] + [custom sorting]
|
||||
- [x] [Navigation subtitles]
|
||||
|
||||
[Meta plugin]: ../reference/index.md#built-in-meta-plugin
|
||||
@ -302,10 +304,10 @@ are released for general availability.
|
||||
|
||||
- [x] [Optimize plugin]
|
||||
- [x] [Typeset plugin]
|
||||
- [x] [Privacy plugin: external links]
|
||||
- [x] [Navigation path] (Breadcrumbs)
|
||||
- [x] [Privacy plugin: optimization support]
|
||||
- [ ] Code block line wrapping
|
||||
- [x] [Privacy plugin: external links]
|
||||
- [ ] Privacy plugin: external link validation
|
||||
|
||||
[Optimize plugin]: ../setup/building-an-optimized-site.md#built-in-optimize-plugin
|
||||
[Typeset plugin]: ../reference/index.md#built-in-typeset-plugin
|
||||
@ -316,7 +318,12 @@ are released for general availability.
|
||||
|
||||
#### $ 24,000 – Blockpaprika
|
||||
|
||||
- [ ] [Instant previews]
|
||||
- [x] [Code range selection]
|
||||
- [x] [Code annotations: custom selectors]
|
||||
- [ ] Code line wrap button
|
||||
|
||||
[Code range selection]: ../reference/code-blocks.md#code-selection-button
|
||||
[Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors
|
||||
|
||||
### Goals completed
|
||||
|
||||
@ -343,14 +350,13 @@ can be used by all users.
|
||||
#### $ 8,000 – Scotch Bonnet
|
||||
|
||||
- [x] [Social cards]
|
||||
- [x] [Code annotations: anchor links]
|
||||
- [x] Code annotations: anchor links
|
||||
- [x] [Code annotations: strip comments]
|
||||
- [x] [Tag icons]
|
||||
- [x] [Table of contents anchor following]
|
||||
- [x] Sidebars automatically scroll to active item
|
||||
|
||||
[Social cards]: ../setup/setting-up-social-cards.md
|
||||
[Code annotations: anchor links]: ../reference/code-blocks.md#anchor-links
|
||||
[Code annotations: strip comments]: ../reference/code-blocks.md#stripping-comments
|
||||
[Tag icons]: ../setup/setting-up-tags.md#tag-icons-and-identifiers
|
||||
[Table of contents anchor following]: ../setup/setting-up-navigation.md#anchor-following
|
||||
|
||||
@ -21,6 +21,8 @@ following lines to `mkdocs.yml`:
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
pygments_lang_class: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
- pymdownx.superfences
|
||||
@ -81,6 +83,47 @@ theme:
|
||||
```
|
||||
````
|
||||
|
||||
### Code selection button :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-4.32.0][Insiders] ·
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
Code blocks can include a button to allow for the selection of line ranges by
|
||||
the user, which is perfect for linking to a specific subsection of a code block. This allows the user to apply [line highlighting] dynamically. Add the following
|
||||
to `mkdocs.yml` to enable it globally:
|
||||
|
||||
``` yaml
|
||||
theme:
|
||||
features:
|
||||
- content.code.select
|
||||
```
|
||||
|
||||
??? info "Enabling or disabling code selection buttons for a specific code block"
|
||||
|
||||
If you don't want to enable code selection buttons globally, you can enable
|
||||
them for a specific code block by using a slightly different syntax based on
|
||||
the [Attribute Lists] extension:
|
||||
|
||||
```` yaml
|
||||
``` { .yaml .select }
|
||||
# Code block content
|
||||
```
|
||||
````
|
||||
|
||||
Note that the language shortcode which has to come first must now also be
|
||||
prefixed by a `.`. Similarly, the selection button can also be disabled for
|
||||
a specific code block:
|
||||
|
||||
```` { .yaml .no-select }
|
||||
``` { .yaml .no-select }
|
||||
# Code block content
|
||||
```
|
||||
````
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[line highlighting]: #highlighting-specific-lines
|
||||
|
||||
### Code annotations
|
||||
|
||||
[:octicons-tag-24: 8.0.0][Code annotations support] ·
|
||||
@ -119,24 +162,45 @@ theme:
|
||||
[Code annotations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
|
||||
[Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
|
||||
|
||||
#### Anchor links
|
||||
#### Custom selectors :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
|
||||
|
||||
[:octicons-tag-24: 8.5.0][Anchor links support] ·
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-4.32.0][Insiders] ·
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
In order to be able to link to code annotations and share them more easily, an
|
||||
anchor link is automatically added to each annotation, which you can copy via
|
||||
right click or open in a new tab:
|
||||
Normally, code annotations can only be [placed in comments], as comments can be
|
||||
considered safe for placement. However, sometimes it might be necessary to place
|
||||
annotations in parts of the code block where comments are not allowed, e.g. in
|
||||
strings.
|
||||
|
||||
Additional selectors can be set per-language:
|
||||
|
||||
``` yaml
|
||||
# (1)!
|
||||
extra:
|
||||
annotate:
|
||||
json: [.s2] # (1)!
|
||||
```
|
||||
|
||||
1. If you ++cmd++ :material-plus::material-cursor-default-outline: me, I'm
|
||||
rendered open in a new tab. You can also right-click me to __copy link
|
||||
address__ to share me with others.
|
||||
1. [`.s2`][s2] is the name of the lexeme that [Pygments] generates for double-quoted
|
||||
strings. If you want to use a code annotation in another lexeme than a
|
||||
comment, inspect the code block and determine which lexeme needs to be added
|
||||
to the list of additional selectors.
|
||||
|
||||
[Anchor links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
|
||||
__Important__: Code annotations cannot be split between lexemes.
|
||||
|
||||
Now, code annotations can be used from within strings in JSON:
|
||||
|
||||
``` json
|
||||
{
|
||||
"key": "value (1)"
|
||||
}
|
||||
```
|
||||
|
||||
1. :man_raising_hand: I'm a code annotation! I can contain `code`, __formatted
|
||||
text__, images, ... basically anything that can be written in Markdown.
|
||||
|
||||
[placed in comments]: #adding-annotations
|
||||
[s2]: https://github.com/squidfunk/mkdocs-material/blob/87d5ca487b9d9ab95c41ee72813149d214048693/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss#L45
|
||||
|
||||
## Usage
|
||||
|
||||
|
||||
@ -325,7 +325,7 @@ The following configuration options are available for external assets:
|
||||
[technical limitations]: #limitations
|
||||
[built-in optimize plugin]: building-an-optimized-site.md#built-in-optimize-plugin
|
||||
|
||||
#### External links :material-alert-decagram:{ .mdx-pulse title="Added on October 18, 2022" }
|
||||
#### External links
|
||||
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
|
||||
[:octicons-tag-24: insiders-4.26.0][Insiders] ·
|
||||
|
||||
@ -94,6 +94,8 @@ hooks:
|
||||
|
||||
# Customization
|
||||
extra:
|
||||
annotate:
|
||||
json: [.s2]
|
||||
analytics:
|
||||
provider: google
|
||||
property: !ENV GOOGLE_ANALYTICS_KEY
|
||||
@ -132,6 +134,8 @@ markdown_extensions:
|
||||
emoji_index: !!python/name:materialx.emoji.twemoji
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
line_spans: __span
|
||||
pygments_lang_class: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.keys
|
||||
- pymdownx.magiclink:
|
||||
|
||||
Loading…
Reference in New Issue
Block a user