Skip to content

rendercv.renderer.templater

The rendercv.renderer.templater module contains all the necessary classes and functions for templating the Typst and Markdown files from the RenderCVDataModel object.

TemplatedFile

This class is a base class for TypstFile, and MarkdownFile classes. It contains the common methods and attributes for both classes. These classes are used to generate the Typst and Markdown files with the data model and Jinja2 templates.

Parameters:

  • data_model (RenderCVDataModel) –

    The data model.

  • environment (Environment) –

    The Jinja2 environment.

Source code in rendercv/renderer/templater.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class TemplatedFile:
    """This class is a base class for `TypstFile`, and `MarkdownFile` classes. It
    contains the common methods and attributes for both classes. These classes are used
    to generate the Typst and Markdown files with the data model and Jinja2
    templates.

    Args:
        data_model: The data model.
        environment: The Jinja2 environment.
    """

    def __init__(
        self,
        data_model: data.RenderCVDataModel,
        environment: jinja2.Environment,
    ):
        self.cv = data_model.cv
        self.design = data_model.design
        self.locale = data_model.locale
        self.environment = environment

    def template(
        self,
        theme_name: str,
        template_name: str,
        extension: str,
        entry: Optional[data.Entry] = None,
        **kwargs,
    ) -> str:
        """Template one of the files in the `themes` directory.

        Args:
            template_name: The name of the template file.
            entry: The title of the section.

        Returns:
            The templated file.
        """
        template = self.environment.get_template(
            f"{theme_name}/{template_name}.j2.{extension}"
        )

        # Loop through the entry attributes and make them "" if they are None:
        # This is necessary because otherwise they will be templated as "None" since
        # it's the string representation of None.

        # Only don't touch the date fields, because only date_string is called and
        # setting dates to "" will cause problems.
        fields_to_ignore = ["start_date", "end_date", "date"]

        if entry is not None and not isinstance(entry, str):
            entry_dictionary = entry.model_dump()
            for key, value in entry_dictionary.items():
                if value is None and key not in fields_to_ignore:
                    entry.__setattr__(key, "")

        # The arguments of the template can be used in the template file:
        return template.render(
            cv=self.cv,
            design=self.design,
            locale=self.locale,
            entry=entry,
            today=data.format_date(data.get_date_input()),
            **kwargs,
        )

    def get_full_code(self, main_template_name: str, **kwargs) -> str:
        """Combine all the templates to get the full code of the file."""
        main_template = self.environment.get_template(main_template_name)
        return main_template.render(
            **kwargs,
        )

template(theme_name, template_name, extension, entry=None, **kwargs)

Template one of the files in the themes directory.

Parameters:

  • template_name (str) –

    The name of the template file.

  • entry (Optional[Entry], default: None ) –

    The title of the section.

Returns:

  • str –

    The templated file.

Source code in rendercv/renderer/templater.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
def template(
    self,
    theme_name: str,
    template_name: str,
    extension: str,
    entry: Optional[data.Entry] = None,
    **kwargs,
) -> str:
    """Template one of the files in the `themes` directory.

    Args:
        template_name: The name of the template file.
        entry: The title of the section.

    Returns:
        The templated file.
    """
    template = self.environment.get_template(
        f"{theme_name}/{template_name}.j2.{extension}"
    )

    # Loop through the entry attributes and make them "" if they are None:
    # This is necessary because otherwise they will be templated as "None" since
    # it's the string representation of None.

    # Only don't touch the date fields, because only date_string is called and
    # setting dates to "" will cause problems.
    fields_to_ignore = ["start_date", "end_date", "date"]

    if entry is not None and not isinstance(entry, str):
        entry_dictionary = entry.model_dump()
        for key, value in entry_dictionary.items():
            if value is None and key not in fields_to_ignore:
                entry.__setattr__(key, "")

    # The arguments of the template can be used in the template file:
    return template.render(
        cv=self.cv,
        design=self.design,
        locale=self.locale,
        entry=entry,
        today=data.format_date(data.get_date_input()),
        **kwargs,
    )

get_full_code(main_template_name, **kwargs)

Combine all the templates to get the full code of the file.

Source code in rendercv/renderer/templater.py 
85
86
87
88
89
90
def get_full_code(self, main_template_name: str, **kwargs) -> str:
    """Combine all the templates to get the full code of the file."""
    main_template = self.environment.get_template(main_template_name)
    return main_template.render(
        **kwargs,
    )

TypstFile

Bases: TemplatedFile

This class represents a Typst file. It generates the Typst code with the data model and Jinja2 templates.

Source code in rendercv/renderer/templater.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
class TypstFile(TemplatedFile):
    """This class represents a Typst file. It generates the Typst code with the
    data model and Jinja2 templates.
    """

    def __init__(
        self,
        data_model: data.RenderCVDataModel,
        environment: jinja2.Environment,
    ):
        typst_file_data_model = copy.deepcopy(data_model)

        if typst_file_data_model.cv.sections_input is not None:
            transformed_sections = transform_markdown_sections_to_typst_sections(
                typst_file_data_model.cv.sections_input
            )
            typst_file_data_model.cv.sections_input = transformed_sections

        super().__init__(typst_file_data_model, environment)

    def render_templates(self) -> tuple[str, str, list[tuple[str, list[str], str]]]:
        """Render and return all the templates for the Typst file.

        Returns:
            The preamble, header, and sections of the Typst file.
        """
        # All the template field names:
        all_template_names = [
            "main_column_first_row_template",
            "main_column_second_row_template",
            "main_column_second_row_without_url_template",
            "main_column_second_row_without_journal_template",
            "date_and_location_column_template",
            "template",
            "degree_column_template",
        ]

        # All the placeholders used in the templates:
        sections_input: dict[str, list[pydantic.BaseModel]] = self.cv.sections_input  # type: ignore
        # Loop through the sections and entries to find all the field names:
        placeholder_keys: set[str] = set()
        if sections_input:
            for section in sections_input.values():
                for entry in section:
                    if isinstance(entry, str):
                        break
                    entry_dictionary = entry.model_dump()
                    for key in entry_dictionary:
                        placeholder_keys.add(key.upper())

        pattern = re.compile(r"(?<!^)(?=[A-Z])")

        def camel_to_snake(name: str) -> str:
            return pattern.sub("_", name).lower()

        # Template the preamble, header, and sections:
        preamble = self.template("Preamble")
        header = self.template("Header")
        sections: list[tuple[str, list[str], str]] = []
        for section in self.cv.sections:
            section_beginning = self.template(
                "SectionBeginning",
                section_title=escape_typst_characters(section.title),
                entry_type=section.entry_type,
            )

            templates = {
                template_name: getattr(
                    getattr(
                        getattr(self.design, "entry_types", None),
                        camel_to_snake(section.entry_type),
                        None,
                    ),
                    template_name,
                    None,
                )
                for template_name in all_template_names
            }

            entries: list[str] = []
            for i, entry in enumerate(section.entries):
                # Prepare placeholders:
                placeholders = {}
                for placeholder_key in placeholder_keys:
                    components_path = (
                        pathlib.Path(__file__).parent.parent / "themes" / "components"
                    )
                    lowercase_placeholder_key = placeholder_key.lower()
                    if (
                        components_path / f"{lowercase_placeholder_key}.j2.typ"
                    ).exists():
                        placeholder_value = super().template(
                            "components",
                            lowercase_placeholder_key,
                            "typ",
                            entry,
                            section_title=section.title,
                        )
                    else:
                        placeholder_value = getattr(entry, placeholder_key, None)

                    placeholders[placeholder_key] = (
                        placeholder_value if placeholder_value != "None" else None
                    )

                # Substitute the placeholders in the templates:
                templates_with_substitutions = {
                    template_name: (
                        input_template_to_typst(
                            templates[template_name],
                            placeholders,  # type: ignore
                        )
                        if templates.get(template_name)
                        else None
                    )
                    for template_name in all_template_names
                }

                entries.append(
                    self.template(
                        section.entry_type,
                        entry=entry,
                        section_title=section.title,
                        entry_type=section.entry_type,
                        is_first_entry=i == 0,
                        **templates_with_substitutions,  # all the templates
                    )
                )
            section_ending = self.template(
                "SectionEnding",
                section_title=section.title,
                entry_type=section.entry_type,
            )
            sections.append((section_beginning, entries, section_ending))

        return preamble, header, sections

    def template(
        self,
        template_name: str,
        entry: Optional[data.Entry] = None,
        **kwargs,
    ) -> str:
        """Template one of the files in the `themes` directory.

        Args:
            template_name: The name of the template file.
            entry: The data model of the entry.

        Returns:
            The templated file.
        """
        return super().template(
            self.design.theme,
            template_name,
            "typ",
            entry,
            **kwargs,
        )

    def get_full_code(self) -> str:
        """Get the Typst code of the file.

        Returns:
            The Typst code.
        """
        preamble, header, sections = self.render_templates()
        code: str = super().get_full_code(
            "main.j2.typ",
            preamble=preamble,
            header=header,
            sections=sections,
        )
        return code

    def create_file(self, file_path: pathlib.Path):
        """Write the Typst code to a file."""
        file_path.write_text(self.get_full_code(), encoding="utf-8")

render_templates()

Render and return all the templates for the Typst file.

Returns:

  • tuple[str, str, list[tuple[str, list[str], str]]] –

    The preamble, header, and sections of the Typst file.

Source code in rendercv/renderer/templater.py 
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
def render_templates(self) -> tuple[str, str, list[tuple[str, list[str], str]]]:
    """Render and return all the templates for the Typst file.

    Returns:
        The preamble, header, and sections of the Typst file.
    """
    # All the template field names:
    all_template_names = [
        "main_column_first_row_template",
        "main_column_second_row_template",
        "main_column_second_row_without_url_template",
        "main_column_second_row_without_journal_template",
        "date_and_location_column_template",
        "template",
        "degree_column_template",
    ]

    # All the placeholders used in the templates:
    sections_input: dict[str, list[pydantic.BaseModel]] = self.cv.sections_input  # type: ignore
    # Loop through the sections and entries to find all the field names:
    placeholder_keys: set[str] = set()
    if sections_input:
        for section in sections_input.values():
            for entry in section:
                if isinstance(entry, str):
                    break
                entry_dictionary = entry.model_dump()
                for key in entry_dictionary:
                    placeholder_keys.add(key.upper())

    pattern = re.compile(r"(?<!^)(?=[A-Z])")

    def camel_to_snake(name: str) -> str:
        return pattern.sub("_", name).lower()

    # Template the preamble, header, and sections:
    preamble = self.template("Preamble")
    header = self.template("Header")
    sections: list[tuple[str, list[str], str]] = []
    for section in self.cv.sections:
        section_beginning = self.template(
            "SectionBeginning",
            section_title=escape_typst_characters(section.title),
            entry_type=section.entry_type,
        )

        templates = {
            template_name: getattr(
                getattr(
                    getattr(self.design, "entry_types", None),
                    camel_to_snake(section.entry_type),
                    None,
                ),
                template_name,
                None,
            )
            for template_name in all_template_names
        }

        entries: list[str] = []
        for i, entry in enumerate(section.entries):
            # Prepare placeholders:
            placeholders = {}
            for placeholder_key in placeholder_keys:
                components_path = (
                    pathlib.Path(__file__).parent.parent / "themes" / "components"
                )
                lowercase_placeholder_key = placeholder_key.lower()
                if (
                    components_path / f"{lowercase_placeholder_key}.j2.typ"
                ).exists():
                    placeholder_value = super().template(
                        "components",
                        lowercase_placeholder_key,
                        "typ",
                        entry,
                        section_title=section.title,
                    )
                else:
                    placeholder_value = getattr(entry, placeholder_key, None)

                placeholders[placeholder_key] = (
                    placeholder_value if placeholder_value != "None" else None
                )

            # Substitute the placeholders in the templates:
            templates_with_substitutions = {
                template_name: (
                    input_template_to_typst(
                        templates[template_name],
                        placeholders,  # type: ignore
                    )
                    if templates.get(template_name)
                    else None
                )
                for template_name in all_template_names
            }

            entries.append(
                self.template(
                    section.entry_type,
                    entry=entry,
                    section_title=section.title,
                    entry_type=section.entry_type,
                    is_first_entry=i == 0,
                    **templates_with_substitutions,  # all the templates
                )
            )
        section_ending = self.template(
            "SectionEnding",
            section_title=section.title,
            entry_type=section.entry_type,
        )
        sections.append((section_beginning, entries, section_ending))

    return preamble, header, sections

template(template_name, entry=None, **kwargs)

Template one of the files in the themes directory.

Parameters:

  • template_name (str) –

    The name of the template file.

  • entry (Optional[Entry], default: None ) –

    The data model of the entry.

Returns:

  • str –

    The templated file.

Source code in rendercv/renderer/templater.py 
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
def template(
    self,
    template_name: str,
    entry: Optional[data.Entry] = None,
    **kwargs,
) -> str:
    """Template one of the files in the `themes` directory.

    Args:
        template_name: The name of the template file.
        entry: The data model of the entry.

    Returns:
        The templated file.
    """
    return super().template(
        self.design.theme,
        template_name,
        "typ",
        entry,
        **kwargs,
    )

get_full_code()

Get the Typst code of the file.

Returns:

  • str –

    The Typst code.

Source code in rendercv/renderer/templater.py 
253
254
255
256
257
258
259
260
261
262
263
264
265
266
def get_full_code(self) -> str:
    """Get the Typst code of the file.

    Returns:
        The Typst code.
    """
    preamble, header, sections = self.render_templates()
    code: str = super().get_full_code(
        "main.j2.typ",
        preamble=preamble,
        header=header,
        sections=sections,
    )
    return code

create_file(file_path)

Write the Typst code to a file.

Source code in rendercv/renderer/templater.py 
268
269
270
def create_file(self, file_path: pathlib.Path):
    """Write the Typst code to a file."""
    file_path.write_text(self.get_full_code(), encoding="utf-8")

MarkdownFile

Bases: TemplatedFile

This class represents a Markdown file. It generates the Markdown code with the data model and Jinja2 templates. Markdown files are generated to produce an HTML which can be copy-pasted to Grammarly for proofreading.

Source code in rendercv/renderer/templater.py 
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
class MarkdownFile(TemplatedFile):
    """This class represents a Markdown file. It generates the Markdown code with the
    data model and Jinja2 templates. Markdown files are generated to produce an HTML
    which can be copy-pasted to [Grammarly](https://app.grammarly.com/) for
    proofreading.
    """

    def render_templates(self) -> tuple[str, list[tuple[str, list[str]]]]:
        """Render and return all the templates for the Markdown file.

        Returns:
            The header and sections of the Markdown file.
        """
        # Template the header and sections:
        header = self.template("Header")
        sections: list[tuple[str, list[str]]] = []
        for section in self.cv.sections:
            section_beginning = self.template(
                "SectionBeginning",
                section_title=section.title,
                entry_type=section.entry_type,
            )
            entries: list[str] = []
            for i, entry in enumerate(section.entries):
                is_first_entry = bool(i == 0)
                entries.append(
                    self.template(
                        section.entry_type,
                        entry=entry,
                        section_title=section.title,
                        entry_type=section.entry_type,
                        is_first_entry=is_first_entry,
                    )
                )
            sections.append((section_beginning, entries))

        result: tuple[str, list[tuple[str, list[str]]]] = (header, sections)
        return result

    def template(
        self,
        template_name: str,
        entry: Optional[data.Entry] = None,
        **kwargs,
    ) -> str:
        """Template one of the files in the `themes` directory.

        Args:
            template_name: The name of the template file.
            entry: The data model of the entry.

        Returns:
            The templated file.
        """
        return super().template(
            "markdown",
            template_name,
            "md",
            entry,
            **kwargs,
        )

    def get_full_code(self) -> str:
        """Get the Markdown code of the file.

        Returns:
            The Markdown code.
        """
        header, sections = self.render_templates()
        code: str = super().get_full_code(
            "main.j2.md",
            header=header,
            sections=sections,
        )
        return code

    def create_file(self, file_path: pathlib.Path):
        """Write the Markdown code to a file."""
        file_path.write_text(self.get_full_code(), encoding="utf-8")

render_templates()

Render and return all the templates for the Markdown file.

Returns:

  • tuple[str, list[tuple[str, list[str]]]] –

    The header and sections of the Markdown file.

Source code in rendercv/renderer/templater.py 
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
def render_templates(self) -> tuple[str, list[tuple[str, list[str]]]]:
    """Render and return all the templates for the Markdown file.

    Returns:
        The header and sections of the Markdown file.
    """
    # Template the header and sections:
    header = self.template("Header")
    sections: list[tuple[str, list[str]]] = []
    for section in self.cv.sections:
        section_beginning = self.template(
            "SectionBeginning",
            section_title=section.title,
            entry_type=section.entry_type,
        )
        entries: list[str] = []
        for i, entry in enumerate(section.entries):
            is_first_entry = bool(i == 0)
            entries.append(
                self.template(
                    section.entry_type,
                    entry=entry,
                    section_title=section.title,
                    entry_type=section.entry_type,
                    is_first_entry=is_first_entry,
                )
            )
        sections.append((section_beginning, entries))

    result: tuple[str, list[tuple[str, list[str]]]] = (header, sections)
    return result

template(template_name, entry=None, **kwargs)

Template one of the files in the themes directory.

Parameters:

  • template_name (str) –

    The name of the template file.

  • entry (Optional[Entry], default: None ) –

    The data model of the entry.

Returns:

  • str –

    The templated file.

Source code in rendercv/renderer/templater.py 
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
def template(
    self,
    template_name: str,
    entry: Optional[data.Entry] = None,
    **kwargs,
) -> str:
    """Template one of the files in the `themes` directory.

    Args:
        template_name: The name of the template file.
        entry: The data model of the entry.

    Returns:
        The templated file.
    """
    return super().template(
        "markdown",
        template_name,
        "md",
        entry,
        **kwargs,
    )

get_full_code()

Get the Markdown code of the file.

Returns:

  • str –

    The Markdown code.

Source code in rendercv/renderer/templater.py 
335
336
337
338
339
340
341
342
343
344
345
346
347
def get_full_code(self) -> str:
    """Get the Markdown code of the file.

    Returns:
        The Markdown code.
    """
    header, sections = self.render_templates()
    code: str = super().get_full_code(
        "main.j2.md",
        header=header,
        sections=sections,
    )
    return code

create_file(file_path)

Write the Markdown code to a file.

Source code in rendercv/renderer/templater.py 
349
350
351
def create_file(self, file_path: pathlib.Path):
    """Write the Markdown code to a file."""
    file_path.write_text(self.get_full_code(), encoding="utf-8")

input_template_to_typst(input_template, placeholders)

Convert an input template to Typst.

Parameters:

  • input_template (Optional[str]) –

    The input template.

  • placeholders (dict[str, Optional[str]]) –

    The placeholders and their values.

Returns:

  • str –

    Typst string.

Source code in rendercv/renderer/templater.py 
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
def input_template_to_typst(
    input_template: Optional[str], placeholders: dict[str, Optional[str]]
) -> str:
    """Convert an input template to Typst.

    Args:
        input_template: The input template.
        placeholders: The placeholders and their values.

    Returns:
        Typst string.
    """
    if input_template is None:
        return ""

    output = replace_placeholders_with_actual_values(
        markdown_to_typst(input_template),
        placeholders,
    )

    # If \n is escaped, revert:
    output = output.replace("\\n", "\n")

    # If there are blank italics and bolds, remove them:
    output = output.replace("#emph[]", "")
    output = output.replace("#strong[]", "")

    # Check if there are any letters in the input template. If not, return an empty
    if not re.search(r"[a-zA-Z]", input_template):
        return ""

    # Find italic and bold links and fix them:
    # For example:
    # Convert `#emph[#link("https://google.com")[italic link]]` to
    # `#link("https://google.com")[#emph[italic link]]`
    output = re.sub(
        r"#emph\[#link\(\"(.*?)\"\)\[(.*?)\]\]",
        r'#link("\1")[#emph[\2]]',
        output,
    )
    output = re.sub(
        r"#strong\[#link\(\"(.*?)\"\)\[(.*?)\]\]",
        r'#link("\1")[#strong[\2]]',
        output,
    )
    output = re.sub(
        r"#strong\[#emph\[#link\(\"(.*?)\"\)\[(.*?)\]\]\]",
        r'#link("\1")[#strong[#emph[\2]]]',
        output,
    )

    # Replace all multiple \n with a double \n:
    output = re.sub(r"\n+", r"\n\n", output)

    # Strip whitespace
    output = output.strip()

    # Strip non-alphanumeric, non-typst characters from the beginning and end of the
    # string. For example, when location is not given in a template like this:
    # "NAME -- LOCATION", "NAME -- " should become "NAME".
    output = re.sub(r"^[^\w\s#\[\]\n\(\)]*", "", output)
    output = re.sub(r"[^\w\s#\[\]\n\(\)]*$", "", output)

    return output  # noqa: RET504

escape_characters(string, escape_dictionary)

Escape characters in a string by using escape_dictionary, where keys are characters to escape and values are their escaped versions.

Example 

escape_characters("This is a # string.", {"#": "\#"})
returns "This is a \# string."

Parameters:

  • string (str) –

    The string to escape.

  • escape_dictionary (dict[str, str]) –

    The dictionary of escape characters.

Returns:

  • str –

    The escaped string.

Source code in rendercv/renderer/templater.py 
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
def escape_characters(string: str, escape_dictionary: dict[str, str]) -> str:
    """Escape characters in a string by using `escape_dictionary`, where keys are
    characters to escape and values are their escaped versions.

    Example:
        ```python
        escape_characters("This is a # string.", {"#": "\\#"})
        ```
        returns
        `"This is a \\# string."`

    Args:
        string: The string to escape.
        escape_dictionary: The dictionary of escape characters.

    Returns:
        The escaped string.
    """

    translation_map = str.maketrans(escape_dictionary)

    # Don't escape urls as hyperref package will do it automatically:
    # Find all the links in the sentence:
    links = re.findall(r"\[(.*?)\]\((.*?)\)", string)

    # Replace the links with a dummy string and save links with escaped characters:
    new_links = []
    for i, link in enumerate(links):
        placeholder = link[0]
        escaped_placeholder = placeholder.translate(translation_map)
        url = link[1]

        original_link = f"[{placeholder}]({url})"
        string = string.replace(original_link, f"!!-link{i}-!!")

        new_link = f"[{escaped_placeholder}]({url})"
        new_links.append(new_link)

    # If there are equations in the sentence, don't escape the special characters:
    # Find all the equations in the sentence:
    equations = re.findall(r"(\$\$.*?\$\$)", string)
    new_equations = []
    for i, equation in enumerate(equations):
        string = string.replace(equation, f"!!-equation{i}-!!")

        # Keep only one dollar sign for inline equations:
        new_equation = equation.replace("$$", "$")
        new_equations.append(new_equation)

    # Loop through the letters of the sentence and if you find an escape character,
    # replace it with their equivalent:
    string = string.translate(translation_map)

    # Replace !!-link{i}-!!" with the original urls:
    for i, new_link in enumerate(new_links):
        string = string.replace(f"!!-link{i}-!!", new_link)

    # Replace !!-equation{i}-!!" with the original equations:
    for i, new_equation in enumerate(new_equations):
        string = string.replace(f"!!-equation{i}-!!", new_equation)

    return string

escape_typst_characters(string)

Escape Typst characters in a string by adding a backslash before them.

Example 

escape_typst_characters("This is a # string.")
returns "This is a \# string."

Parameters:

  • string (str) –

    The string to escape.

Returns:

  • str –

    The escaped string.

Source code in rendercv/renderer/templater.py 
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
def escape_typst_characters(string: str) -> str:
    """Escape Typst characters in a string by adding a backslash before them.

    Example:
        ```python
        escape_typst_characters("This is a # string.")
        ```
        returns
        `"This is a \\# string."`

    Args:
        string: The string to escape.

    Returns:
        The escaped string.
    """
    escape_dictionary = {
        "[": "\\[",
        "]": "\\]",
        "(": "\\(",
        ")": "\\)",
        "\\": "\\\\",
        '"': '\\"',
        "#": "\\#",
        "$": "\\$",
        "@": "\\@",
        "%": "\\%",
        "~": "\\~",
        "_": "\\_",
    }

    return escape_characters(string, escape_dictionary)

markdown_to_typst(markdown_string)

Convert a Markdown string to Typst.

Example 
markdown_to_typst(
    "This is a **bold** text with an [*italic link*](https://google.com)."
)

returns

"This is a *bold* text with an #link("https://google.com")[_italic link_]."

Parameters:

  • markdown_string (str) –

    The Markdown string to convert.

Returns:

  • str –

    The Typst string.

Source code in rendercv/renderer/templater.py 
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
def markdown_to_typst(markdown_string: str) -> str:
    """Convert a Markdown string to Typst.

    Example:
        ```python
        markdown_to_typst(
            "This is a **bold** text with an [*italic link*](https://google.com)."
        )
        ```

        returns

        `"This is a *bold* text with an #link("https://google.com")[_italic link_]."`

    Args:
        markdown_string: The Markdown string to convert.

    Returns:
        The Typst string.
    """
    # convert links
    links = re.findall(r"\[([^\]\[]*)\]\((.*?)\)", markdown_string)
    if links is not None:
        for link in links:
            link_text = link[0]
            link_url = link[1]

            old_link_string = f"[{link_text}]({link_url})"
            new_link_string = f'#link("{link_url}")[{link_text}]'

            markdown_string = markdown_string.replace(old_link_string, new_link_string)

    # Process escaped asterisks in the yaml (such that they are actual asterisks,
    # and not markers for bold/italics). We need to temporarily replace them with
    # a dummy string.

    ONE_STAR = "ONE_STAR"

    # NOTE: We get a mix of escape levels depending on whether the star is in a quoted
    #       or unquoted yaml entry. This is a bit of a mess but below seems to work
    #       as i would instinctively expect.
    markdown_string = markdown_string.replace("\\\\*", ONE_STAR)
    markdown_string = markdown_string.replace("\\*", ONE_STAR)

    # convert bold and italic:
    bold_and_italics = re.findall(r"\*\*\*(.+?)\*\*\*", markdown_string)
    if bold_and_italics is not None:
        for bold_and_italic_text in bold_and_italics:
            old_bold_and_italic_text = f"***{bold_and_italic_text}***"
            new_bold_and_italic_text = f"#strong[#emph[{bold_and_italic_text}]]"

            markdown_string = markdown_string.replace(
                old_bold_and_italic_text, new_bold_and_italic_text
            )

    # convert bold
    bolds = re.findall(r"\*\*(.+?)\*\*", markdown_string)
    if bolds is not None:
        for bold_text in bolds:
            old_bold_text = f"**{bold_text}**"
            new_bold_text = f"#strong[{bold_text}]"
            markdown_string = markdown_string.replace(old_bold_text, new_bold_text)

    # convert italic
    italics = re.findall(r"\*(.+?)\*", markdown_string)
    if italics is not None:
        for italic_text in italics:
            old_italic_text = f"*{italic_text}*"
            new_italic_text = f"#emph[{italic_text}]"

            markdown_string = markdown_string.replace(old_italic_text, new_italic_text)

    # Revert normal asterisks then convert them to Typst's asterisks
    markdown_string = markdown_string.replace(ONE_STAR, "*")

    # convert any remaining asterisks to Typst's asterisk
    # - Asterisk with a space can just be replaced.
    # - Asterisk without a space needs a zero-width box to delimit it.
    TYPST_AST = "#sym.ast.basic"
    ZERO_BOX = "#h(0pt, weak: true)"
    markdown_string = markdown_string.replace("* ", TYPST_AST + " ")
    markdown_string = markdown_string.replace("*", TYPST_AST + ZERO_BOX)

    # At this point, the document ought to have absolutely no '*' characters left!
    # NOTE: The final typst file might still have some asterisks when specifying a
    #       size, for example `#v(design-text-font-size * 0.4)`
    # XXX: Maybe put this behind some kind of debug flag? -MK
    # assert "*" not in markdown_string

    return markdown_string  # noqa: RET504

transform_markdown_sections_to_something_else_sections(sections, functions_to_apply)

Recursively loop through sections and update all the strings by applying the functions_to_apply functions, given as an argument.

Parameters:

  • sections (dict[str, SectionContents]) –

    Sections with Markdown strings.

  • functions_to_apply (list[Callable]) –

    Functions to apply to the strings.

Returns:

  • Optional[dict[str, SectionContents]] –

    Sections with updated strings.

Source code in rendercv/renderer/templater.py 
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
def transform_markdown_sections_to_something_else_sections(
    sections: dict[str, data.SectionContents],
    functions_to_apply: list[Callable],
) -> Optional[dict[str, data.SectionContents]]:
    """
    Recursively loop through sections and update all the strings by applying the
    `functions_to_apply` functions, given as an argument.

    Args:
        sections: Sections with Markdown strings.
        functions_to_apply: Functions to apply to the strings.

    Returns:
        Sections with updated strings.
    """

    def apply_functions_to_string(string: str):
        for function in functions_to_apply:
            string = function(string)
        return string

    for key, value in sections.items():
        transformed_list = []
        for entry in value:
            if isinstance(entry, str):
                # Then it means it's a TextEntry.
                result = apply_functions_to_string(entry)
                transformed_list.append(result)
            else:
                # Then it means it's one of the other entries.
                fields_to_skip = ["doi"]
                entry_as_dict = entry.model_dump()
                for entry_key, inner_value in entry_as_dict.items():
                    if entry_key in fields_to_skip:
                        continue
                    if isinstance(inner_value, str):
                        result = apply_functions_to_string(inner_value)
                        setattr(entry, entry_key, result)
                    elif isinstance(inner_value, list):
                        for j, item in enumerate(inner_value):
                            if isinstance(item, str):
                                inner_value[j] = apply_functions_to_string(item)
                        setattr(entry, entry_key, inner_value)
                transformed_list.append(entry)

        sections[key] = transformed_list

    return sections

transform_markdown_sections_to_typst_sections(sections)

Recursively loop through sections and convert all the Markdown strings (user input is in Markdown format) to Typst strings.

Parameters:

  • sections (dict[str, SectionContents]) –

    Sections with Markdown strings.

Returns:

  • Optional[dict[str, SectionContents]] –

    Sections with Typst strings.

Source code in rendercv/renderer/templater.py 
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
def transform_markdown_sections_to_typst_sections(
    sections: dict[str, data.SectionContents],
) -> Optional[dict[str, data.SectionContents]]:
    """
    Recursively loop through sections and convert all the Markdown strings (user input
    is in Markdown format) to Typst strings.

    Args:
        sections: Sections with Markdown strings.

    Returns:
        Sections with Typst strings.
    """
    return transform_markdown_sections_to_something_else_sections(
        sections,
        [escape_typst_characters, markdown_to_typst],
    )

replace_placeholders_with_actual_values(text, placeholders)

Replace the placeholders in a string with actual values.

This function can be used as a Jinja2 filter in templates.

Parameters:

  • text (str) –

    The text with placeholders.

  • placeholders (dict[str, Optional[str]]) –

    The placeholders and their values.

Returns:

  • str –

    The string with actual values.

Source code in rendercv/renderer/templater.py 
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
def replace_placeholders_with_actual_values(
    text: str,
    placeholders: dict[str, Optional[str]],
) -> str:
    """Replace the placeholders in a string with actual values.

    This function can be used as a Jinja2 filter in templates.

    Args:
        text: The text with placeholders.
        placeholders: The placeholders and their values.

    Returns:
        The string with actual values.
    """
    for placeholder, value in placeholders.items():
        if value:
            text = text.replace(placeholder, str(value))
        else:
            text = text.replace(placeholder, "")

    return text