Add custom blockquote extension (#2817)

Resolves #2814

Author: facelessuser

.github/workflows/build.yml

@@ -49,15 +49,15 @@ jobs:
         allow-prereleases: true
     - name: Install dependencies
       run: |
-        python -m pip install --upgrade pip build tox coverage codecov
+        python -m pip install --upgrade pip build tox coverage
     - name: Test
       run: |
         python -m tox
     - name: Upload Results
       if: success()
-      uses: codecov/codecov-action@v4
+      uses: codecov/codecov-action@v5
       with:
-        file: ./coverage.xml
+        files: ./coverage.xml
         flags: unittests
         name: ${{ matrix.platform }}-${{ matrix.tox-env }}
         token: ${{ secrets.CODECOV_TOKEN }} # required

docs/src/dictionary/en-custom.txt

@@ -12,6 +12,8 @@ CDN
 CDNs
 CSS
 CVE
+Callout
+Callouts
 Changelog
 Cloudflare
 CodeHilite
@@ -44,6 +46,7 @@ GitHub
 GitHubEmoji
 GitLab
 Gitter
+Gruber
 HeaderAnchor
 Hunspell
 Inline
@@ -84,13 +87,11 @@ PlainHTML
 Pomaceous
 Postprocessor
 ProgressBar
-EmojiOne
 PyMdown
 PyPI
 PyYAML
 PyYaml
 Pygments
-Gruber
 Pymdownx
 Reindent
 Rosaceae
@@ -134,6 +135,8 @@ blockquotes
 bool
 boolean
 builtins
+callout
+callouts
 checkbox
 checkboxes
 cmd

docs/src/markdown/.snippets/links.md

@@ -20,6 +20,7 @@
 [_mark]: https://github.com/facelessuser/pymdown-extensions/blob/master/pymdownx/mark.py "Source"
 [_pathconverter]: https://github.com/facelessuser/pymdown-extensions/blob/master/pymdownx/pathconverter.py "Source"
 [_progressbar]: https://github.com/facelessuser/pymdown-extensions/blob/master/pymdownx/progressbar.py "Source"
+[_quotes]: https://github.com/facelessuser/pymdown-extensions/blob/master/pymdownx/quotes.py "Source"
 [_saneheaders]: https://github.com/facelessuser/pymdown-extensions/blob/master/pymdownx/saneheaders.py "Source"
 [_slugs]: https://github.com/facelessuser/pymdown-extensions/blob/master/pymdownx/slugs.py "Source"
 [_smartsymbols]: https://github.com/facelessuser/pymdown-extensions/blob/master/pymdownx/smartsymbols.py "Source"
@@ -36,6 +37,7 @@
 [atomic]: https://python-markdown.github.io/extensions/api/#working_with_et
 [attr-list]: https://python-markdown.github.io/extensions/attr_list/
 [bleach]: https://pypi.python.org/pypi/bleach
+[blockquotes]: https://daringfireball.net/projects/markdown/syntax#blockquote
 [codehilite]: https://python-markdown.github.io/extensions/code_hilite/
 [coverage]: https://coverage.readthedocs.io
 [critic-markup]: http://criticmarkup.com/
@@ -50,6 +52,7 @@
 [footnotes]: https://python-markdown.github.io/extensions/footnotes/
 [gemoji-index]: https://github.com/facelessuser/pymdown-extensions/blob/master/pymdownx/gemoji_db.py
 [gemoji]: https://github.com/github/gemoji
+[github-alerts]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
 [github-api-emoji]: https://developer.github.com/v3/emojis/
 [github-api-oauth]: https://developer.github.com/v3/oauth/
 [highlightjs]: https://highlightjs.org/
@@ -64,6 +67,7 @@
 [mkdocs-config]: https://github.com/facelessuser/pymdown-extensions/blob/master/mkdocs.yml
 [mkdocs-material]: https://github.com/squidfunk/mkdocs-material
 [mkdocs]: https://github.com/mkdocs/mkdocs
+[multimarkdown-critic]: https://fletcher.github.io/MultiMarkdown-6/syntax/critic.html
 [nested-markdown]: https://python-markdown.github.io/extensions/extra/#nested-markdown-inside-html-blocks
 [nl2br]: https://python-markdown.github.io/extensions/nl2br/
 [octicons]: https://octicons.github.com/

docs/src/markdown/about/changelog.md

@@ -3,6 +3,15 @@ icon: lucide/scroll-text
 ---
 # Changelog
 
+## 10.20
+
+-   **NEW**: Quotes: New blockquotes extension added that uses a more modern approach when compared to Python Markdown's
+    default. Quotes specifically will not group consecutive blockquotes together in the same lazy fashion that the
+    default Python Markdown does which follows a more modern trend to how parsers these days handle block quotes.
+
+    In addition, Quotes also provides an optional feature to enable specifying callouts/alerts in the style used by
+    GitHub and Obsidian.
+
 ## 10.19.1
 
 -   **FIX**: Arithmatex: Fix issue where block `$$` math used inline within a paragraph could result in nested math

docs/src/markdown/extensions/betterem.md

@@ -24,7 +24,7 @@ import markdown
 md = markdown.Markdown(extensions=['pymdownx.betterem'])
 ```
 
-/// danger | Reminder
+/// important | Reminder
 Remember to read the [Usage Notes](../usage_notes.md) for information that may be relevant when using this
 extension!
 ///

docs/src/markdown/extensions/critic.md

@@ -194,24 +194,19 @@ will work quite well.  But when trying to render the edits visually **and** tryi
 things can get ugly.  I think this is the one unfortunate problem with CriticMarkup.  The existence of the critic edits
 can alter the actual source.  Its a fantastic idea, but it should be understood that when using CriticMarkup beyond
 inline or block paragraphs, there is a possibility that invalid HTML will be created for the preview (especially in
-relation to lists or if breaking up Markdown syntax).  I think Fletcher of [MultiMarkdown][multi-markdown] said it best
-here:
+relation to lists or if breaking up Markdown syntax).  I think Fletcher of [MultiMarkdown][multimarkdown-critic] said it
+best.
 
-> I view CriticMarkup as two things:
+/// quote
+I view CriticMarkup as two things (in addition to the actual tools that implement these concepts):
 
-> 1.  A syntax for documenting editing notes and changes, and for collaborating amongst coauthors.
+1.  A syntax for documenting editing notes and changes, and for collaborating amongst coauthors.
 
-> 2.  A means to display those notes/changes in the HTML output.
+2.  A means to display those notes/changes in the HTML output.
 
-> I believe that \#1 is a really great idea, and well implemented. \#2 is not so well implemented, largely due to the
-  "orthogonal" nature of CriticMarkup and the underlying Markdown syntax.
-
-> CM is designed as a separate layer on top of Markdown/MultiMarkdown. This means that a Markdown span could, for
-  example, start in the middle of a CriticMarkup structure, but end outside of it. This means that an algorithm to
-  properly convert a CM/Markdown document to HTML would be quite complex, with a huge number of edge cases to consider.
-  I've tried a few (fairly creative, in my opinion) approaches, but they didn't work. Perhaps someone else will come up
-  with a better solution, or will be so interested that they put the work in to create the complex algorithm. I have no
-  current plans to do so.
+I believe that \#1 is a really great idea, and well implemented. \#2 is not so well implemented, largely due to the
+"orthogonal" nature of CriticMarkup and the underlying Markdown syntax.
+///
 
 The Critic extension does its best by employing a preprocessor to inject the critic tags before all other parsing and a
 post-processor to clean up some of the weird side effects of the injection (only selected odd cases as others are more

docs/src/markdown/extensions/quotes.md

@@ -0,0 +1,165 @@
+---
+icon: lucide/quote
+---
+[:octicons-file-code-24:][_quotes]{: .source-link }
+
+# Quotes
+
+## Overview
+
+Quotes is an extension that offers a more modern take on blockquotes compared to the one that ships with Python Markdown
+by default.
+
+Python Markdown is an old-school parser that aims to follow the original Markdown specification. When implementing
+blockquotes, it follows the guidance that describes the ability to lazily specify content under a blockquote as shown
+below. Notice that two blocks of text can be specified without having to specify `>` on the empty lines between the
+blocks.
+
+```text title="Lazy Blockquote Handling"
+> This is a paragraph
+
+> This is another paragraph.
+```
+
+/// html | div.result
+```md-render
+> This is a paragraph
+
+> This is another paragraph.
+```
+///
+
+The problem with this approach is that if you have a need to have two separate blockquotes, this because difficult.
+
+The Quotes extensions follows logic that is seen in more modern approaches to Markdown.
+
+```text title="Separate Blockquotes"
+> This is a paragraph
+
+> This is another paragraph.
+```
+
+/// html | div.result
+> This is a paragraph
+
+> This is another paragraph.
+///
+
+It should be noted that since this extension does not use lazy formatting, you should be stricter with your leading
+blockquote `>`. For instance, when using [SuperFences](./superfences.md), you will find that these must be fully
+contained in the blockquotes. In the past, the lazy handling would have allowed for 
+
+````text title="Blockquotes and SuperFences"
+> ```
+> Test
+>
+> Test
+> ```
+
+This will not.
+
+> ```
+> Test
+
+> Test
+> ```
+````
+
+/// html | div.result
+This will work.
+
+> ```
+> Test
+>
+> Test
+> ```
+
+This will not.
+
+> ```
+> Test
+
+> Test
+> ```
+///
+
+## Callouts
+
+[GitHub][github-alerts] and [Obsidian](https://help.obsidian.md/callouts) allow for specifying admonitions (also known
+as alerts or callouts) by using a special syntax at the start of a blockquote. While Obsidian does this with a more
+feature rich syntax, GitHub offers a more stripped down version.
+
+The Quotes extensions allows you to opt-in approach to specifying admonitions in a similar approach that is compatible
+with Obsidian and GitHub if usage is limited to what they offer.
+
+Quotes will take the special blockquote syntax and output HTML that matches the output of [Admonitions][admonition] or
+[Details](./details.md).
+
+To specify normal callouts, simply ensure the that the first line of a blockquote contains a class name in within
+`[!...]`.
+
+```text title="Callout"
+> [!note]
+> Here is a note
+```
+
+/// html | div.result
+> [!note]
+> Here is a note
+///
+
+/// note
+GitHub only supports the simple class notation, and only recognizes the classes: note, tip, important, warning, caution.
+
+There are no restrictions as to which classes you can specify, but if cross compliance is desired, take note of what
+GitHub supports. Learn more [here][github-alerts].
+///
+
+Borrowing from Obsidian, Quotes also enables a few more advanced features. If you'd like a custom title, simply provide
+one on the same line as the class specifier. If one is not provided, a title is sourced from the first the class.
+
+```text title="Callout with Custom Title"
+> [!tip] Here's a tip
+> Use a custom title!
+```
+
+/// html | div.result
+> [!tip] Here's a tip
+> Use a custom title!
+///
+
+To make a collapsible callout, just add `+` (open) or `-` (closed) immediately after the class specifier.
+
+```text title="Collapsible Callout"
+> [!danger]- Click to see more
+> I'm collapsible.
+```
+
+/// html | div.result
+> [!danger]- Click to see more
+> I'm collapsible.
+///
+
+Lastly, if you need to specify more multiple classes, you can utilize the Obsidian approach and and separate each class
+with `|`. The first class will be used as the main title if no title is provided, but all classes will be applied to the
+callout.
+
+```text title="Collapsible Callout"
+> [!warning | inline | end]
+> Make inline and set at the end.
+
+A paragraph.
+```
+
+/// html | div.result
+> [!warning | inline | end]
+> Make inline and set at the end.
+
+A paragraph.
+///
+
+## Options
+
+Option               | Type    | Default      | Description
+-------------------- | ------- | ------------ |------------
+`callouts`           | bool    | `#!py3 False`| Enable the ability to create special callouts using blockquotes.

docs/src/markdown/extensions/superfences.md

@@ -42,15 +42,15 @@ md = markdown.Markdown(extensions=['pymdownx.superfences'])
     exempted.
 
 5.  If you are using a fenced block inside a blockquote, at the very least, the first line of the fenced block needs to
-    have the appropriate number of `>` characters signifying the quote depth.
+    have the appropriate number of `>` characters signifying the quote depth. This i
 
     ````
     > ```
       a fenced block
       ```
     ````
 
-6.  Too many blank lines will cause a blockquote to terminate, so remember to use `>` markers accordingly if not marking
+    Too many blank lines will cause a blockquote to terminate, so remember to use `>` markers accordingly if not marking
     every line.
 
     ````
@@ -61,7 +61,22 @@ md = markdown.Markdown(extensions=['pymdownx.superfences'])
       ```
     ````
 
-7.  If using a fenced block as the first line of a list, you will have to leave the first line blank, but remember that
+    If you are using the [Quotes](./quotes.md) extension, you must include the entire fenced code block within the
+    blockquote as Quotes purposely does not use lazy blockquote logic.
+
+    ````
+    > ```
+    > a fenced block
+    > ```
+    ````
+
+    /// tip
+    If you always include the entire code block within the blockquote, you will always get good results and is generally
+    the recommended approach regardless if you are using the default lazy blockquote logic that comes stock with Python
+    Markdown or using the [Quotes](./quotes.md) extension.
+    ///
+
+6.  If using a fenced block as the first line of a list, you will have to leave the first line blank, but remember that
     the list marker must be immediately followed by at least one space. To avoid accidentally deleting the space and to
     make your intentions clear, you might want to also add an explicit unicode space (` `) as shown here:
 
@@ -78,7 +93,7 @@ md = markdown.Markdown(extensions=['pymdownx.superfences'])
         ```
     ````
 
-8.  Fenced blocks should be separated from other blocks by an empty line.
+7.  Fenced blocks should be separated from other blocks by an empty line.
 
     ````
     Paragraph.

docs/src/markdown/faq.md

@@ -76,7 +76,8 @@ extensions = [
     'pymdownx.emoji',
     'pymdownx.tasklist',
     'pymdownx.superfences',
-    'pymdownx.saneheaders'
+    'pymdownx.saneheaders',
+    'pymdownx.quotes'
 ]
 
 extension_configs = {
@@ -103,6 +104,9 @@ extension_configs = {
             "image_path": "https://github.githubassets.com/images/icons/emoji/unicode/",
             "non_standard_image_path": "https://github.githubassets.com/images/icons/emoji/"
         }
+    },
+    "pymdownx.quotes": {
+        "callouts": True
     }
 }
 ```