Add current notes about new Blocks feature

facelessuser · Mar 5, 2023 · 1756cba · 1756cba
1 parent 9c5224f
commit 1756cba
Show file tree

Hide file tree

Showing 4 changed files with 38 additions and 5 deletions.
diff --git a/docs/src/markdown/.snippets/blocksbeta.md b/docs/src/markdown/.snippets/blocksbeta.md
@@ -1,7 +1,9 @@
-/// warning | Beta Release
-Blocks is currently only available in the Pymdown Extensions beta release. It is a work in progress and API and
-syntax are subject to change.
+/// new | 9.10 New Experimental Feature
+Blocks is currently a new, experimental extension type available in Pymdown Extensions that allows for writing a new
+kind of block extension in Python Markdown. With this new addition, we've added a number of new extensions utilizing
+this new extension type. While its intention is to hopefully replace extensions like Details and Tabbed, there are
+currently no immediate plans to deprecate those plugins.
 
-Any and all feedback regarding these experimental blocks is appreciated. Let us know what you think so we can improve
-and make these a stable feature. Please provide feedback here: https://github.com/facelessuser/pymdown-extensions/discussions/1961.
+Any and all feedback regarding these new, experimental blocks is appreciated. Please provide feedback here:
+https://github.com/facelessuser/pymdown-extensions/discussions/1973.
 ///
diff --git a/docs/src/markdown/extensions/blocks/plugins/tab.md b/docs/src/markdown/extensions/blocks/plugins/tab.md
@@ -102,6 +102,29 @@ Some content
 ///
 ```
 
+## Tab IDs
+
+By default, tabs generate IDs for each tab using the following template `__tabbed_<tab_set_number>_<tab_number>`. If it
+is desired to implement jumping to a specific tab with more intuitive IDs, it may be preferable to generate IDs from
+slugs. To do so, two [options](#global-options) are provided: `slugify` and `separator`.
+
+/// tip
+Jumping to tabs via IDs may require additional JavaScript to select the targeted tabs.
+///
+
+If `slugify` is given a slug function (you can use any that [ship with Pymdownx Extensions](../../../extras/slugs.md)),
+the Tabbed extension will generate IDs from the tab titles just like headers. `separator` allows for the specifying of
+the word separator (`-` is the default).
+
+## Additional Topics
+
+As Tab shares the same output and functionality as the [Tabbed extension](../../tabbed.md), you can check out the
+documentation there to learn the following:
+
+- [How to style the tabs?](../../tabbed.md#styling-with-css)
+- [How to link tab selection on an entire page?](../../tabbed.md#linked-tabs)
+- [What is the alternate style and how do I style them?](../../tabbed.md#alternate-style)
+
 ## Global Options
 
 Options           | Type     | Descriptions

diff --git a/docs/src/markdown/extensions/details.md b/docs/src/markdown/extensions/details.md
@@ -2,6 +2,10 @@
 
 # Details
 
+/// tip | 9.10 New Approach to Details
+9.10 has added a new approach to creating details. Checkout the new [Details extension here](./blocks/plugins/details.md)!
+///
+
 ## Overview
 
 Details is an extension that creates collapsible elements that hide their content. It uses the HTML5

diff --git a/docs/src/markdown/extensions/tabbed.md b/docs/src/markdown/extensions/tabbed.md
@@ -2,6 +2,10 @@
 
 # Tabbed
 
+/// tip | 9.10 New Approach to Tabs
+9.10 has added a new approach to creating tabs. Checkout the new [Tab extension here](./blocks/plugins/tab.md)!
+///
+
 ## Overview
 
 /// new | New 7.0