Multiline callouts

Author: mDuo13

dactyl/dactyl_build.py

@@ -539,7 +539,7 @@ def main(cli_args, config):
             exit("FATAL: --vars value was improperly formatted: %s" % repr(e))
 
     if cli_args.title:
-        target.gain_keys({"display_name": cli_args.title})
+        target.gain_fields({"display_name": cli_args.title})
 
     if not cli_args.no_cover and not target.data.get("no_cover", False):
         target.add_cover()

dactyl/filter_callouts.py

@@ -19,6 +19,8 @@
 ]
 DEFAULT_CALLOUT_CLASS = "dactyl-callout"
 
+from bs4.element import Tag
+
 def filter_soup(soup, currentpage={}, config={}, **kwargs):
     """
     Find patterns that look like callouts, for example **Note:**, and add
@@ -38,4 +40,11 @@ def filter_soup(soup, currentpage={}, config={}, **kwargs):
         if not c.previous_sibling: #This callout starts a block
             callout_type = c.string.replace(":","").lower()
             if callout_type in callout_classes:
-                c.parent["class"] = [callout_base_class, callout_type]
+                if (c.parent.parent.name == "blockquote" and Tag not in
+                    [type(u) for u in c.parent.previous_siblings]):
+                    # Special case for blockquotes, to allow multiline callouts.
+                    # First element of BQ must start with a callout keyword
+                    callout_el = c.parent.parent
+                else:
+                    callout_el = c.parent
+                callout_el["class"] = [callout_base_class, callout_type]

dactyl/target.py

@@ -124,8 +124,7 @@ def es_index_name(self):
 
     def add_cover(self):
         """
-        Add the default cover page to the pagelist where self.load_pages()
-        will find it.
+        Instantiate the default cover page so self.load_pages() can include it.
         """
         coverpage_data = self.config["cover_page"]
         coverpage_data["targets"] = [self.name]

dactyl/version.py

@@ -1 +1 @@
-__version__ = '0.10.0-a123'
+__version__ = '0.10.0-a129'

examples/content/filter-examples/callouts.md

@@ -25,3 +25,45 @@ In order to use callouts, the page (or target) has to have the `callouts` filter
 |-------|-------|
 | **Warning:** Callout syntax in table cells is weird. | So it's probably best not to do that. |
 | Probably. | **Caution:** It could maybe work better with better CSS. |
+
+> **Tip:** Multiline callouts with blockquotes are now possible.
+>
+> - Do this to include bulleted lists.
+> - Or other types of lists.
+>
+
+If you have a callout word like **tip** bolded mid-paragraph, it should not become a callout.
+
+> Please **note** that this also applies to blockquotes.
+
+There is a difficult edge case for blockquotes where a paragraph other than the first one starts with a callout keyword:
+
+> This is the start of a blockquote that is not, itself, a callout.
+>
+> **Note:** This callout occurs in the middle of a blockquote.
+>
+> But the blockquote containing it is not, itself, a callout.
+
+Also, note that you can cannot use code fences in blockquotes.
+
+> **Caution:** Code fences in blockquotes don't work right.
+>
+> ```js
+> if (true) {
+>     console.log('this line of code should be indented');
+> }
+> ```
+>
+> The code fence gets treated as inlined code text instead. This is a limitation of Python-Markdown.
+
+You can, however, use indented code blocks in blockquotes:
+
+> **Tip:** To get a proper code block in a blockquote, provide a single
+> line of just the blockquote intro `>`, and indent the code block 5 spaces.
+>
+>     print("Hello world!")
+>     if True:
+>         print("Note that extra spaces beyond the initial 5 carry over.")
+>
+> To continue the block quote afterwords, leave a near-blank line similarly.
+> Do not use code fences in a blockquote: they don't work as expected.

releasenotes.md

@@ -212,6 +212,26 @@ This release improves several aspects of OpenAPI (Swagger) specification parsing
 
 However, OpenAPI spec parsing should still be considered experimental.
 
+### Multiline Callouts
+
+The built-in callouts filter now supports multi-line callouts using Markdown's blockquote syntax. A blockquote must be set off from paragraph text by blank lines before and after. Within the blockquote, each line must start with `> `. (The space is optional but recommended.) For example:
+
+```md
+Some paragraph text.
+
+> **Tip:** This begins a multiline callout.
+>
+> - It can have lists.
+>     - Indentation does not count the space in the `> ` as part of its
+>       requirements, so things that would normally need to be indented 4 spaces
+>       must be indented 5 instead.
+> - That's just Markdown syntax for you.
+
+More paragraph text
+```
+
+Build the [examples](examples/) to see it in action and to see some samples of specific edge cases.
+
 ## Bug Fixes and Other Cleanup
 
 - `--skip_preprocessor` (when using a config file) works again. It had been broken since v0.40.0.

tests/unit_target.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python3
+import unittest
+import os
+
+from unit_shared import *
+
+from dactyl.target import DactylTarget
+
+
+class TestDactylPage(unittest.TestCase):
+    def test_target_from_pages(self):
+        files=["../examples/content/filter-examples/badges.md","../examples/content/filter-examples/buttonize.md"]
+        t = DactylTarget(config=mockconfig, inpages=files)
+        t.load_pages()
+
+
+
+if __name__ == '__main__':
+    unittest.main()