Merge pull request #679 from mgoonde/escape_alias

Add backslash as escape for alias

docs/user_guide/writing_documentation.rst

@@ -243,7 +243,7 @@ There are three predefined macros:
 - ``|media|``: the (absolute) path to the `media directory <option-media_dir>`
 - ``|page|``: the `static page directory <option-page_dir>`
 
-You can defined additional custom aliases with the `alias
+You can define additional custom aliases with the `alias
 <option-alias>` option.
 
 .. note::
@@ -262,6 +262,11 @@ You can defined additional custom aliases with the `alias
    This avoids clashes between the syntax for the two features.
 
 
+.. note::
+   An alias can be escaped with a prepended baskslash, such that `|foo|` will
+   be replaced with its alias, while `\|foo|` will be rendered as `|foo|`.
+
+
 .. _writing-links:
 
 Links

ford/_markdown.py

@@ -131,9 +131,14 @@ def convert(
 
 class AliasPreprocessor(Preprocessor):
     """Substitute text aliases of the form ``|foo|`` from a dictionary
-    of aliases and their replacements"""
+    of aliases and their replacements.
+    The backslash ``\`` acts as an escape character, aliases of the
+    form ``\|foo|`` will not be replaced, but instead copied verbatim
+    without the preceding backslash.
+    """
 
-    ALIAS_RE = re.compile(r"\|([^ ].*?[^ ]?)\|")
+    # pattern to match alias only if not preceded by `\`
+    ALIAS_RE = re.compile(r"(?<!\\)\|([^ ].*?[^ ]?)\|")
 
     def __init__(self, md: Markdown, aliases: Dict[str, str]):
         self.aliases = aliases
@@ -149,7 +154,11 @@ def _lookup(self, m: re.Match):
 
     def run(self, lines: List[str]) -> List[str]:
         for line_num, line in enumerate(lines):
-            lines[line_num] = self.ALIAS_RE.sub(self._lookup, line)
+            # replace the real aliases
+            line = self.ALIAS_RE.sub(self._lookup, line)
+            # replace the escaped aliases verbatim, without the preceding `\`
+            line = re.sub(r"\\(\|([^ ].*?[^ ]?)\|)", r"\g<1>",line)
+            lines[line_num]=line
         return lines
 
 

test/test_markdown.py

@@ -5,9 +5,25 @@
 
 def test_sub_alias():
     result = MetaMarkdown(aliases={"a": "b"}).convert("|a|")
-
     assert result == "<p>b</p>"
 
+    result = MetaMarkdown(aliases={"a": "b"}).convert("|undefined|")
+    assert result == "<p>|undefined|</p>"
+
+
+def test_sub_alias_escape():
+    def_alias={"a":"b"}
+
+    result = MetaMarkdown(aliases=def_alias).convert("\|a|")
+    assert result == "<p>|a|</p>"
+
+    result = MetaMarkdown(aliases=def_alias).convert("*|a|")
+    assert result == "<p>*b</p>"
+
+    result = MetaMarkdown(aliases=def_alias).convert("\|undefined|")
+    assert result == "<p>|undefined|</p>"
+
+
 
 def test_sub_alias_with_equals():
     result = MetaMarkdown(aliases={"a": "b=c"}).convert("|a|")