Update some API related descriptions, update changelog, and bump version

docs/src/markdown/about/changelog.md

@@ -1,30 +1,10 @@
 # Changelog
 
-## 9.10b5
-
-- **NEW**: Blocks: Add `type_multi` and `type_none` validators.
-- **NEW**: Blocks: Rename on_parse to `on_validate` and pass in parent element as context for validation.
-- **NEW**: Blocks: When a block uses `raw` mode, allow content to be indented to avoid conflicts with HTML parser. `raw`
-  blocks _should_ be indented and are now documented as such. The results will be dedented up to Python Markdown's tab
-  length, so intentional indentation is still possible. `raw` blocks with no indentation will still work, but may have
-  conflicts with other extensions.
-- **FIX**: Blocks: Commenting out all YAML options will not cause a block to invalidate.
-
-## 9.10b4
-
-- **NEW**: Blocks: Add `on_inline_end` event.
-
-## 9.10b3
-
-- **NEW**: Blocks: Ensure inline mode is handled properly.
-- **NEW**: Blocks: When using raw mode, ensure HTML stashed content is extracted.
-- **NEW**: HTML: The Blocks HTML extension should use `inline` specifier instead of `span`.
-
-## 9.10b2
+## 9.10
 
 - **NEW**: Blocks: Add new experimental general purpose blocks that provide a framework for creating fenced block
   containers for specialized parsing. A number of extensions utilizing general purpose blocks are included and are meant
-  to be an alternative to (and maybe one day replace): Admonitions, Details, Definition   Lists, and Tabbed. Also adds a
+  to be an alternative to (and maybe one day replace): Admonitions, Details, Definition Lists, and Tabbed. Also adds a
   new HTML plugin for quick wrapping of content with arbitrary HTML elements.
 - **NEW**: Highlight: When enabling line spans and/or line anchors, if a code block has an ID associated with it, line
   ids will be generated using that code ID instead of the code block count.
@@ -35,38 +15,6 @@
 - **NEW**: MagicLink: Update GitLab links to match recent changes and to be more correct.
 - **NEW**: MagicLink: Relax required hash length when performing link shortening.
 
-## 9.10b1
-
-- **NEW**: HTML General block now accepts Emmet style attribute: `/// html | div.class#id[name=value]`.
-- **NEW**: Block attribute specifier is renamed from `attributes` to `attrs`.
-- **NEW**: Remove `colon_syntax` option and cement that we are using `///` format moving forward.
-- **NEW**: Revise available validators for Block options. Remove unnecessary validators and replace some with new ones.
-- **NEW**: Simplify argument API.
-- **NEW**: Block extensions can now be registered directly as normal Python Markdown extensions.
-
-## 9.10a3
-
-- **NEW**: General blocks now use an indented option block right after the header. `yaml_indent` option has been
-  removed.
-- **NEW**: Added new "Definition" block that allows the creation of definition lists.
-- **NEW**: Simplified argument configuration.
-- **NEW**: Some internal cleanup.
-- **NEW**: Documented current API.
-
-## 9.10a2
-
-- **NEW**: General blocks no longer use YAML fences for per block options, but instead use a special token to denote the
-  line is part of the config.
-- **NEW**: Add temporary alpha/beta option `yaml_indent` to control whether per-block YAML configs use indentation or a
-  leading special character: `/` for `///` syntax and `:` for `:::` syntax (`colon_syntax` must be true to use `:::`
-  syntax).
-- **NEW**: Ensure that `/` character can be escaped when registering the `blocks` extension.
-- **FIX**: Fix some block nesting issues.
-
-## 9.10a1
-
-- **NEW**: Experimental general purpose blocks.
-
 ## 9.9.3
 
 - **FIX**: Highlight: Remove extraneous new lines from end of indented code blocks when using

docs/src/markdown/extensions/blocks/api.md

@@ -273,32 +273,32 @@ def on_markdown(self) -> str:
 ```
 
 The `on_markdown` event is used to declare how the content of the block should be handled by the Markdown parser. A
-string with one of the following values _must_ be returned. All content is stored under the [etree][etree] element
-returned via the [`on_add` event](#on_add-event), regardless of what mode is returned.
+string with one of the following values _must_ be returned. All content is treated as HTML content and is stored under
+the [etree][etree] element returned via the [`on_add` event](#on_add-event).
+
+Only during the [`on_end` event](#on_end-event) will all the content be fully accumulated and processed by relevant
+block processors, and only during the [`on_inline_end` event](#on_inline_end-event) will both block and inline
+processing be completed.
 
 Result\ Value | Description
 ------------- | -----------
 `block`       | Parsed block content will be handled by the Markdown parser as content under a block element.
 `inline`      | Parsed block content will be handled by the Markdown parser as content under an inline element.
-`raw`         | Parsed block content will be preserved as is. No additional Markdown parsing will be applied.
+`raw`         | Parsed block content will be preserved as is. No additional Markdown parsing will be applied. Content is expected to be indented and should be documented as such.
 `auto`        | Depending on whether the wrapping parent is a block element, inline element, or something like a code element, Blocks will choose the best approach for the content. Decision is made based on the element returned by the [`on_add` event](#on_add-event).
 
-Only during the [`on_end` event](#on_end-event) will all the content be fully accumulated and processed by relevant
-block processors, and only during the [`on_inline_end` event](#on_inline_end-event) will both block and inline
-processing be completed.
-
-When using `raw` mode, all text will be accumulated and fully available during the [`on_end` event](#on_end-event).
-Content is accessible under the element returned by the [`on_add` event](#on_add-event) and can be accessed via
-`element.text`. Text content is stored as a Python Markdown [`AtomicString`][atomic]. If desired, the content can be
-stored in the [HTML stash][stash] during the [`on_add` event](#on_add-event)to ensure it makes it through any and all
-Treeprocessors after inline handling. Additionally, when storing in the stash, the developer can HTML escape the content
-to have the text present as literal or store without HTML escaping to present as an altered HTML content.
-
-A `raw` block expects the content to be an indented code block as this is necessary to avoid some Python Markdown's
-internal HTML parser. Content will not have the extra indentation in the final output.
-
-It should be noted that `raw` mode cannot prevent transformations that are applied during Python Markdown's preprocessor
-steps. Blocks will attempt to revert any placeholders within the content that are currently found in the HTML stash.
+When using `raw` mode, all text will be accumulated under the specified element as an [`AtomicString`][atomic]. If
+nothing is done with the content during the [`on_end` event](#on_end-event), all the content will be HTML escaped by the
+Python Markdown parser. If desired, the content can be placed into the Python Markdown [HTML stash][stash] which will
+protect it from any other rouge Treeprocessors. Keep in mind, if the content is stashed HTML escaping will not be
+applied automatically, so HTML escape if it is required.
+
+/// warning | Indent Raw Content
+Because Python Markdown implements HTML processing as a preprocessor, content for a `raw` block must be indented 4
+spaces to avoid the HTML processing step. The content will not be indented when it reaches the [`on_end` event](#on_end-event).
+Failure to indent will still allow the code to be processed, but it may not process as expected. An extension that uses
+`raw` should make clear that this is a requirement to avoid unexpected results.
+///
 
 ## `on_end` Event
 

pymdownx/__meta__.py

@@ -185,5 +185,5 @@ def parse_version(ver, pre=False):
     return Version(major, minor, micro, release, pre, post, dev)
 
 
-__version_info__ = Version(9, 10, 0, "beta", 5)
+__version_info__ = Version(9, 10, 0, "final")
 __version__ = __version_info__._get_canonical()