Markup for advanced comments

docs/index.rst

@@ -198,7 +198,15 @@ unsets an environment variable.
 #doitlive commentecho: [true|false]
 ************************************
 
-Whether to echo comments or not. If enabled, non-magic comments will be echoed back in bold yellow before each prompt. This can be useful for providing some annotations for yourself and the audience.
+Whether to echo comments or not. If enabled, non-magic comments will be echoed back before each prompt. This can be useful for providing some annotations for yourself and the audience.
+Non-magic comments can be optionally preceded by markup to enable different colors to be used (for callouts) and blank lines added before and/or after the comment.
+
+   #XA:B#  This is the comment that will be coloured
+
+in which:
+- X is an optional letter (T for title, W for warning, I for info)
+- A is an optional number, which indicates the number of blank lines to add before the comment (defaults to 0)
+- B is an optional number, which indicates the number of blank lines to add after the comment (defaults to 0)
 
 
 Python mode

doitlive/cli.py

@@ -12,6 +12,7 @@
 from click_didyoumean import DYMGroup
 
 from doitlive.__version__ import __version__
+from doitlive.comments import display_comment
 from doitlive.exceptions import SessionError
 from doitlive.keyboard import (
     RETURNS,
@@ -189,8 +190,7 @@ def run(
                 func = OPTION_MAP[option]
                 func(state, arg)
             elif state.commentecho():
-                comment = command.lstrip("#")
-                secho(comment, fg="yellow", bold=True)
+                display_comment(command)
             continue
         # Handle 'export' and 'alias' commands by storing them in SessionState
         elif command_as_list and command_as_list[0] in ["alias", "export"]:

doitlive/comments.py

@@ -0,0 +1,73 @@
+import re
+
+from click import echo, secho
+
+
+def display_comment(command):
+    # Triple ### = comment not to be output
+    if command.startswith("###"):
+        return
+
+    # Double ## optionally containing instructions 
+    # = special treatment
+    applied = special_comment(command)
+    if applied:
+        return
+
+    else:
+        comment = re.sub(r"^#+\d*\s*", '', command)
+        simple_comment(comment)
+
+
+def special_comment(comment):
+    pattern = r'^#([WIT])?(?:(\d+)?(?::?(\d+)?)?)#'
+    match = re.search(pattern, comment)
+
+    if match:
+        callout = match.group(1)
+        a = match.group(2)
+        b = match.group(3)
+
+        a = int(a) if a is not None else 0
+        b = int(b) if b is not None else 0
+
+        stripped_s = re.sub(pattern, '', comment).lstrip()
+
+        for i in range(a):
+            echo()
+        comment_callout(stripped_s, callout)
+        for i in range(b):
+            echo()
+        return stripped_s
+
+
+def comment_callout(comment, callout):
+    color_mapping = dict(
+        W=("red", True, "❗️"),
+        I=("cyan", False, "💡"),
+        T=("blue", True, None)
+    )    
+    color = color_mapping.get(callout)
+
+    if callout == "T":
+        # title
+        echo()
+        echo("=" * len(comment))
+
+    if color:
+        # prefix with optional icon
+        if color[2]:
+            comment = color[2] + "  " + comment
+
+        secho(comment, fg=color[0], bold=color[1])
+    else:
+        simple_comment(comment)
+
+    if callout == "T":
+        echo()
+
+    return comment
+
+
+def simple_comment(comment):
+    secho(comment, fg="yellow", bold=True)

examples/comments.sh

@@ -0,0 +1,22 @@
+#doitlive shell: /bin/bash
+#doitlive prompt: default
+#doitlive speed: 2
+#doitlive commentecho: true
+
+### This comment stays in the file and is not displayed
+# There is a comment in the .sh file above this one, but as it starts with "###", it is not echoed
+
+#T# This is a title
+# This is a normal comment after the title. Any whitespace after the initial "#" is stripped out.
+# simply because that makes the .sh file more readable overall.
+
+#2:2# This comment is preceded by 2 blank lines, and followed by 2. It is marked up with #2:2#
+
+## This comment is preceded by one blank line. It starts with "##". It's the short-hand equivalent of "#1#" or "#1:0#"
+
+#W# This is a warning callout, it starts with "#W#"
+
+#I1:1# This is an info callout. We can also add blank lines around callouts: #I1:1#.
+
+doitlive -h
+