Coverage for src / rendercv / renderer / templater / markdown_parser.py: 100%

1import itertools (empty)

2import re (empty)

3from xml.etree.ElementTree import Element (empty)

4 

5import markdown (empty)

6import markdown.core (empty)

7 

8 

9def to_typst_string(elem: Element) -> str: (empty)

10 """Recursively convert XML Element tree to Typst markup string. 

11 

12 Why: 

13 Python Markdown library outputs XML Element tree. Typst requires its 

14 own markup syntax for bold, italic, links, etc. Recursive traversal 

15 converts entire element tree including nested formatting. 

16 

17 Args: 

18 elem: XML Element from Markdown parser. 

19 

20 Returns: 

21 Typst-formatted string. 

22 """ 

23 result = [] (empty)

24 

25 # Handle the element's text content 

26 if elem.text: (empty)

27 result.append(escape_typst_characters(elem.text)) (empty)

28 

29 # Process child elements 

30 for child in elem: (empty)

31 match child.tag: (empty)

32 case "strong": (empty)

33 # Bold: **text** -> #strong[text] 

34 inner = to_typst_string(child) (empty)

35 child_content = f"#strong[{inner}]" (empty)

36 

37 case "em": (empty)

38 # Italic: *text* -> #emph[text] 

39 inner = to_typst_string(child) (empty)

40 child_content = f"#emph[{inner}]" (empty)

41 

42 case "code": (empty)

43 # Inline code: `text` -> `text` 

44 # Code content is already escaped by the parser 

45 child_content = f"`{child.text}`" (empty)

46 

47 case "a": (empty)

48 # Link: [text](url) -> #link("url")[text] 

49 href = child.get("href") if child.get("href") else "https://example.com" (empty)

50 inner = to_typst_string(child) (empty)

51 child_content = f'#link("{href}")[{inner}]' (empty)

52 

53 case "div": (empty)

54 child_content = ( (empty)

55 "#summary[" 

56 + to_typst_string(child).strip("\n").replace("\n", " \\ ") 

57 + "]" 

58 ) 

59 

60 case _: (empty)

61 if getattr(child, "attrib", {}).get("class") == "admonition-title": (empty)

62 continue (empty)

63 child_content = to_typst_string(child) (empty)

64 

65 result.append(child_content) (empty)

66 

67 # Handle tail text (text after the closing tag of child) 

68 if child.tail: (empty)

69 result.append(escape_typst_characters(child.tail)) (empty)

70 

71 return "".join(result) (empty)

72 

73 

74typst_command_pattern = re.compile(r"#([A-Za-z][^\s()\[]*)(\([^)]*\))?(\[[^\]]*\])?") (empty)

75math_pattern = re.compile(r"(\$\$.*?\$\$)") (empty)

76 

77 

78def escape_typst_characters(string: str) -> str: (empty)

79 """Escape Typst special characters while preserving Typst commands and math. 

80 

81 Why: 

82 User content may contain Typst special characters like `#`, `$`, `[` that 

83 would break compilation. Escaping prevents interpretation as commands. 

84 Existing Typst commands and math must remain unescaped. 

85 

86 Args: 

87 string: Text to escape. 

88 

89 Returns: 

90 Escaped string safe for Typst. 

91 """ 

92 if string == "\n": (empty)

93 return string (empty)

94 

95 # Find all the Typst commands, and keep them separate so that nothing is escaped 

96 # inside the commands. 

97 typst_command_mapping = {} (empty)

98 for i, match in enumerate( (empty)

99 itertools.chain( 

100 math_pattern.finditer(string), 

101 typst_command_pattern.finditer(string), 

102 ) 

103 ): 

104 dummy_name = f"RENDERCVTYPSTCOMMANDORMATH{i}" (empty)

105 typst_command_mapping[dummy_name] = match.group(0) (empty)

106 string = string.replace(typst_command_mapping[dummy_name], dummy_name) (empty)

107 typst_command_mapping[dummy_name] = typst_command_mapping[dummy_name].replace( (empty)

108 "$$", "$" 

109 ) 

110 

111 # Add the tail after the last match 

112 escape_dictionary = { (empty)

113 "[": "\\[", 

114 "]": "\\]", 

115 "\\": "\\\\", 

116 '"': '\\"', 

117 "#": "\\#", 

118 "$": "\\$", 

119 "@": "\\@", 

120 "%": "\\%", 

121 "~": "\\~", 

122 "_": "\\_", 

123 "/": "\\/", 

124 ">": "\\>", 

125 "<": "\\<", 

126 } 

127 

128 string = string.translate(str.maketrans(escape_dictionary)) (empty)

129 

130 # string.translate() only supports single-character replacements, so we need to 

131 # handle the longer replacements separately. 

132 longer_escape_dictionary = { (empty)

133 "* ": "#sym.ast.basic ", 

134 "*": "#sym.ast.basic#h(0pt, weak: true) ", 

135 } 

136 for key, value in longer_escape_dictionary.items(): (empty)

137 string = string.replace(key, value) (empty)

138 

139 # Replace the dummy names with the full Typst commands 

140 for dummy_name, full_command in typst_command_mapping.items(): (empty)

141 string = string.replace(dummy_name, full_command) (empty)

142 

143 return string (empty)

144 

145 

146# Create a Markdown instance 

147md = markdown.core.Markdown(extensions=["admonition"]) (empty)

148md.output_formats["typst"] = to_typst_string # pyright: ignore[reportArgumentType] (empty)

149md.set_output_format("typst") # pyright: ignore[reportArgumentType] (empty)

150md.parser.blockprocessors.deregister("hashheader") (empty)

151md.parser.blockprocessors.deregister("setextheader") (empty)

152md.parser.blockprocessors.deregister("olist") (empty)

153md.parser.blockprocessors.deregister("ulist") (empty)

154md.parser.blockprocessors.deregister("quote") (empty)

155md.stripTopLevelTags = False (empty)

156 

157 

158def markdown_to_typst(markdown_string: str) -> str: (empty)

159 """Convert Markdown string to Typst markup. 

160 

161 Why: 

162 Users write content in Markdown for readability. Typst compilation 

163 requires Typst markup. Lines are processed independently to prevent 

164 emphasis markers on adjacent lines from interacting in the Markdown 

165 parser (single-newline-separated lines form one paragraph in Markdown, 

166 causing cross-line marker interference). Admonition blocks are kept 

167 together since they span multiple lines by design. 

168 

169 Args: 

170 markdown_string: Markdown content. 

171 

172 Returns: 

173 Typst-formatted string. 

174 """ 

175 lines = markdown_string.split("\n") (empty)

176 result_parts: list[str] = [] (empty)

177 i = 0 (empty)

178 while i < len(lines): (empty)

179 if lines[i].startswith("!!!"): (empty)

180 # Admonition block: collect the !!! line + all following indented lines 

181 block = [lines[i]] (empty)

182 i += 1 (empty)

183 while i < len(lines) and lines[i].startswith(" "): (empty)

184 block.append(lines[i]) (empty)

185 i += 1 (empty)

186 md.reset() (empty)

187 result_parts.append(md.convert("\n".join(block))) (empty)

188 else: 

189 md.reset() (empty)

190 result_parts.append(md.convert(lines[i])) (empty)

191 i += 1 (empty)

192 return "\n".join(result_parts) (empty)

193 

194 

195def markdown_to_html(markdown_string: str) -> str: (empty)

196 """Convert Markdown string to HTML using python-markdown library. 

197 

198 Args: 

199 markdown_string: Markdown content. 

200 

201 Returns: 

202 HTML-formatted string. 

203 """ 

204 return markdown.markdown(markdown_string) (empty)