RenderCV 模板覆写完全指南深入定制 Typst 与 Markdown 简历模板【免费下载链接】rendercvResume builder for academics and engineers项目地址: https://gitcode.com/GitHub_Trending/re/rendercv本文聚焦 RenderCV 提供的模板覆写Template Override能力当design与design.templates配置项不足以满足排版需求时如何通过直接修改 Typst/Markdown 模板文件来彻底掌控简历的版式结构、条目渲染逻辑乃至自定义 Typst 函数与包。读完本文你将掌握两种覆写方法快速覆写与自定义主题、模板文件结构与 Jinja2 Typst 混合语法、模板内可用变量以及 RenderCV 如何按优先级解析本地模板的底层原理。什么时候需要覆写模板RenderCV 的默认设计体系已经覆盖了颜色、字体、间距、页边距、章节标题样式、条目文本布局等大量选项这些均通过 design 配置 暴露。但在以下场景中设计选项无法满足需求就需要直接覆写模板需要改变简历的基础布局结构例如重组页头信息、照片与文字的相对位置需要引入自定义 Typst 函数或第三方 Typst 包如在Preamble.j2.typ中#import额外包需要修改条目的渲染方式且超出了 design.templates 允许的范围例如改变条目两栏的划分逻辑、添加新的视觉元素希望做出完全脱离内置主题设计选项的原创设计。对于更轻量的定制官方建议优先尝试design控制颜色、字体、间距等全局视觉参数design.templates以占位符字符串的形式控制条目文本的排版如**NAME**\nSUMMARY\nHIGHLIGHTS。只有这两层都不够用才进入模板覆写阶段。两种覆写方法RenderCV 提供了两种模板覆写路径对应不同使用场景。方法一快速模板定制Quick Template Customization适用于只想对某个现有主题的模板做微调、不想创建一个完整自定义主题的场景。第 1 步在简历 YAML 旁生成模板文件。rendercv new Your Name --create-typst-templates命令执行后会在当前目录生成如下结构Your_Name_CV.yaml classic/ Preamble.j2.typ Header.j2.typ SectionBeginning.j2.typ entries/ NormalEntry.j2.typ ...从 new_command.py 的源码可以看到rendercv new除了生成 YAML 输入文件还会在传入--create-typst-templates时把内置 Typst 模板复制到以--theme参数默认classic命名的目录下复制逻辑由 copy_templates.py 实现它从包内renderer/templater/templates/typst目录整体复制并忽略__init__.py与__pycache__。如果你的classic/目录已经存在命令会跳过复制并在终端面板中提示 Not modified (already exist)不会覆盖你已有的修改。第 2 步修改classic/目录下的任意模板文件。第 3 步正常渲染。rendercv render Your_Name_CV.yamlRenderCV 会自动使用本地模板替代内置模板无需任何额外参数。这一行为的关键在于 templater.py 中构造的 Jinja2FileSystemLoader它把「输入 YAML 文件所在目录」放在加载器列表首位、把「内置模板目录」放在第二位同时 render_single_template 对 Typst 模板会先尝试加载{design.theme}/{relative_template_path}例如classic/Header.j2.typ找不到再回退到内置typst/Header.j2.typ。因此本地模板天然获得最高优先级。方法二创建自定义主题Custom Theme适用于构建一个可复用、自带设计选项的完整主题。第 1 步创建自定义主题。rendercv create-theme mytheme这会生成mytheme/ __init__.py Preamble.j2.typ Header.j2.typ SectionBeginning.j2.typ entries/ NormalEntry.j2.typ ...从 create_theme_command.py 可以看出该命令会把内置 Typst 模板复制到以主题名命名的文件夹并额外生成__init__.py由 create_init_file_for_theme.py 负责如果目标文件夹已存在会直接报错。第 2 步修改模板文件并可选在__init__.py中添加自定义设计选项。__init__.py支持三件事向 YAML 输入文件中暴露你自己的设计选项、修改现有选项的默认值、或者直接删除它如果只想定制模板。第 3 步在 YAML 文件中使用该主题。design: theme: mytheme # Your custom design options work here第 4 步渲染。rendercv render Your_Name_CV.yaml两种方法的本质区别方法一仍然使用内置主题如classic的设计选项仅覆写其模板文件方法二则创建了一个全新的主题标识可以在__init__.py中定义自己的一套设计选项并作为design.theme使用。渲染时render_single_template 会优先在{design.theme}/目录下查找模板因此两种方法都遵循「用户模板优先、内置模板兜底」的解析顺序。模板结构Jinja2 语法 Typst 代码模板文件本质上是Jinja2 模板 Typst 代码的混合体外层控制流{% ... %}和变量输出{{ ... }}由 Jinja2 负责渲染后产出的最终文本则是 Typst 源码。官方文档给出的NormalEntry.j2.typ示例展示了这种混合写法// Example: entries/NormalEntry.j2.typ #regular-entry( [ {% for line in entry.main_column.splitlines() %} {{ line }} {% endfor %} ], [ {% for line in entry.date_and_location_column.splitlines() %} {{ line }} {% endfor %} ], )仓库内置的 NormalEntry.j2.typ 比文档示例更完整它展示了真实模板如何使用design.entries.short_second_row动态决定第一行包含哪些内容、用entry.main_column.splitlines()[:first_row_lines]切分主栏与第二行并通过{{ line|indent(4) }}输出缩进后的文本{% if not design.entries.short_second_row %} {% set first_row_lines entry.date_and_location_column.splitlines()|length %} {% if first_row_lines 0 %} {% set first_row_lines 1 %} {% endif %} {% else %} {% set first_row_lines entry.main_column.splitlines()|length %} {% endif %} #regular-entry( [ {% for line in entry.main_column.splitlines()[:first_row_lines] %} {{ line|indent(4) }} {% endfor %} ], [ {% for line in entry.date_and_location_column.splitlines() %} {{ line|indent(4) }} {% endfor %} ], {% if not design.entries.short_second_row %} main-column-second-row: [ {% for line in entry.main_column.splitlines()[first_row_lines:] %} {{ line|indent(4) }} {% endfor %} ], {% endif %} )其他内置条目模板同样遵循这一模式例如 EducationEntry.j2.typ 增加了对design.templates.education_entry.degree_column的判断有值时才输出独立的学位列而 OneLineEntry.j2.typ 则极为简单直接输出{{entry.main_column}}。这意味着模板文件可以按需保持极简缺失的部分由内置版本兜底。Markdown 模板同理例如内置的 NormalEntry.j2.md 用## {{ entry.main_column.splitlines()[0] }}生成二级标题并遍历主栏剩余行、剔除!!! summary标记后输出摘要内容。模板内可用的变量在模板上下文中RenderCV 通过 render_single_template 统一注入以下变量cv全部简历数据姓名、各 section、连接方式等design全部设计选项locale本地化字符串月份名称、翻译文本等settings渲染设置如 PDF 标题、解析后的当前日期entry当前条目数据仅条目模板内可用随entry关键字参数传入。此外渲染章节时会额外传入section_title、snake_case_section_title、entry_type等变量见 render_full_template 中对SectionBeginning.j2.typ的调用HTML 渲染则额外传入html_body。以官方文档中的Preamble.j2.typ片段为例// In Preamble.j2.typ #show: rendercv.with( page-size: {{ design.page.size }}, colors-body: {{ design.colors.body.as_rgb() }}, typography-font-family-body: {{ design.typography.font_family.body }}, // ... )仓库内置的 Preamble.j2.typ 完整展示了rendercv.with(...)能接收的全部参数从page-size、四个页边距、page-show-footer、page-show-top-note到colors-body/name/headline/connections/section-titles/links/footer/top-note各颜色通道再到typography-line-spacing、各元素的字体族、字号、small-caps、bold开关以及header-*、section-titles-*、sections-*、entries-*等数十个参数。其中布尔值统一通过{{ ...|lower }}过滤器输出小写true/false而高亮项目符号entries-highlights-bullet还针对●做了特殊处理渲染为 Typst 的text(13pt, [•], baseline: -0.6pt)。这些值全部来自 YAML 中的design字段因此覆写模板后你在 YAML 里配置的颜色、字体依然生效。locale变量在模板中的典型用法见 Header.j2.typ模板通过cv.photo判断是否渲染照片用design.header.photo_position决定照片在左栏还是右栏再按cv.name、cv.headline、cv._connections依次输出姓名、标语与连接信息。Markdown 模板定制除了 Typst 模板两种方法也都支持 Markdown 模板定制。在rendercv new时传入--create-markdown-templates即可rendercv new Your Name --create-typst-templates --create-markdown-templates根据 new_command.py 的选项定义--create-markdown-templates会把内置 Markdown 模板复制到markdown/目录而非以主题命名的目录。Markdown 模板的文件名与 Typst 模板一一对应Header.j2.md、SectionBeginning.j2.md、entries/EducationEntry.j2.md等修改、渲染流程与 Typst 模板完全一致生成的.md文件会作为后续 HTML 输出的中间产物参见 render_html 中 Markdown 转 HTML 的流程。实用技巧与注意事项从小处着手先复制模板、做小改动并即时渲染验证避免一次性大改导致难以定位问题牢记模板是 Jinja2 Typst这不是纯 Typst 文件Jinja2 的{% %}、{{ }}语法会在渲染时先被执行同理修改内置模板后若语法错误错误信息会同时涉及 Jinja2 与 Typst 两个阶段按需删除模板文件对于不想定制的模板直接删除对应文件即可——RenderCV 会回退到内置版本不会报错。这一行为由 render_single_template 中的jinja2.TemplateNotFound抑制逻辑保证理解模板加载优先级本地{theme}/目录 内置typst/目录输入 YAML 所在目录 包内模板目录design.templates与模板文件的分工design.templates以占位符字符串控制「文本内容如何拼装」如**NAME**\nSUMMARY\nHIGHLIGHTS完整占位符说明见 classic_theme.py而模板文件控制「排版结构如何呈现」两者可以组合使用模板文件中的{{ entry.main_column }}拿到的正是design.templates.*加工后的文本列。对于想深入研究的读者可以继续阅读 design 配置文档 了解全部设计选项参考 customtheme 效果图 观察自定义主题的典型产出并通过 templater 测试目录 中的用例理解模板渲染的边界行为。【免费下载链接】rendercvResume builder for academics and engineers项目地址: https://gitcode.com/GitHub_Trending/re/rendercv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
RenderCV 模板覆写完全指南：深入定制 Typst 与 Markdown 简历模板
RenderCV 模板覆写完全指南深入定制 Typst 与 Markdown 简历模板【免费下载链接】rendercvResume builder for academics and engineers项目地址: https://gitcode.com/GitHub_Trending/re/rendercv本文聚焦 RenderCV 提供的模板覆写Template Override能力当design与design.templates配置项不足以满足排版需求时如何通过直接修改 Typst/Markdown 模板文件来彻底掌控简历的版式结构、条目渲染逻辑乃至自定义 Typst 函数与包。读完本文你将掌握两种覆写方法快速覆写与自定义主题、模板文件结构与 Jinja2 Typst 混合语法、模板内可用变量以及 RenderCV 如何按优先级解析本地模板的底层原理。什么时候需要覆写模板RenderCV 的默认设计体系已经覆盖了颜色、字体、间距、页边距、章节标题样式、条目文本布局等大量选项这些均通过 design 配置 暴露。但在以下场景中设计选项无法满足需求就需要直接覆写模板需要改变简历的基础布局结构例如重组页头信息、照片与文字的相对位置需要引入自定义 Typst 函数或第三方 Typst 包如在Preamble.j2.typ中#import额外包需要修改条目的渲染方式且超出了 design.templates 允许的范围例如改变条目两栏的划分逻辑、添加新的视觉元素希望做出完全脱离内置主题设计选项的原创设计。对于更轻量的定制官方建议优先尝试design控制颜色、字体、间距等全局视觉参数design.templates以占位符字符串的形式控制条目文本的排版如**NAME**\nSUMMARY\nHIGHLIGHTS。只有这两层都不够用才进入模板覆写阶段。两种覆写方法RenderCV 提供了两种模板覆写路径对应不同使用场景。方法一快速模板定制Quick Template Customization适用于只想对某个现有主题的模板做微调、不想创建一个完整自定义主题的场景。第 1 步在简历 YAML 旁生成模板文件。rendercv new Your Name --create-typst-templates命令执行后会在当前目录生成如下结构Your_Name_CV.yaml classic/ Preamble.j2.typ Header.j2.typ SectionBeginning.j2.typ entries/ NormalEntry.j2.typ ...从 new_command.py 的源码可以看到rendercv new除了生成 YAML 输入文件还会在传入--create-typst-templates时把内置 Typst 模板复制到以--theme参数默认classic命名的目录下复制逻辑由 copy_templates.py 实现它从包内renderer/templater/templates/typst目录整体复制并忽略__init__.py与__pycache__。如果你的classic/目录已经存在命令会跳过复制并在终端面板中提示 Not modified (already exist)不会覆盖你已有的修改。第 2 步修改classic/目录下的任意模板文件。第 3 步正常渲染。rendercv render Your_Name_CV.yamlRenderCV 会自动使用本地模板替代内置模板无需任何额外参数。这一行为的关键在于 templater.py 中构造的 Jinja2FileSystemLoader它把「输入 YAML 文件所在目录」放在加载器列表首位、把「内置模板目录」放在第二位同时 render_single_template 对 Typst 模板会先尝试加载{design.theme}/{relative_template_path}例如classic/Header.j2.typ找不到再回退到内置typst/Header.j2.typ。因此本地模板天然获得最高优先级。方法二创建自定义主题Custom Theme适用于构建一个可复用、自带设计选项的完整主题。第 1 步创建自定义主题。rendercv create-theme mytheme这会生成mytheme/ __init__.py Preamble.j2.typ Header.j2.typ SectionBeginning.j2.typ entries/ NormalEntry.j2.typ ...从 create_theme_command.py 可以看出该命令会把内置 Typst 模板复制到以主题名命名的文件夹并额外生成__init__.py由 create_init_file_for_theme.py 负责如果目标文件夹已存在会直接报错。第 2 步修改模板文件并可选在__init__.py中添加自定义设计选项。__init__.py支持三件事向 YAML 输入文件中暴露你自己的设计选项、修改现有选项的默认值、或者直接删除它如果只想定制模板。第 3 步在 YAML 文件中使用该主题。design: theme: mytheme # Your custom design options work here第 4 步渲染。rendercv render Your_Name_CV.yaml两种方法的本质区别方法一仍然使用内置主题如classic的设计选项仅覆写其模板文件方法二则创建了一个全新的主题标识可以在__init__.py中定义自己的一套设计选项并作为design.theme使用。渲染时render_single_template 会优先在{design.theme}/目录下查找模板因此两种方法都遵循「用户模板优先、内置模板兜底」的解析顺序。模板结构Jinja2 语法 Typst 代码模板文件本质上是Jinja2 模板 Typst 代码的混合体外层控制流{% ... %}和变量输出{{ ... }}由 Jinja2 负责渲染后产出的最终文本则是 Typst 源码。官方文档给出的NormalEntry.j2.typ示例展示了这种混合写法// Example: entries/NormalEntry.j2.typ #regular-entry( [ {% for line in entry.main_column.splitlines() %} {{ line }} {% endfor %} ], [ {% for line in entry.date_and_location_column.splitlines() %} {{ line }} {% endfor %} ], )仓库内置的 NormalEntry.j2.typ 比文档示例更完整它展示了真实模板如何使用design.entries.short_second_row动态决定第一行包含哪些内容、用entry.main_column.splitlines()[:first_row_lines]切分主栏与第二行并通过{{ line|indent(4) }}输出缩进后的文本{% if not design.entries.short_second_row %} {% set first_row_lines entry.date_and_location_column.splitlines()|length %} {% if first_row_lines 0 %} {% set first_row_lines 1 %} {% endif %} {% else %} {% set first_row_lines entry.main_column.splitlines()|length %} {% endif %} #regular-entry( [ {% for line in entry.main_column.splitlines()[:first_row_lines] %} {{ line|indent(4) }} {% endfor %} ], [ {% for line in entry.date_and_location_column.splitlines() %} {{ line|indent(4) }} {% endfor %} ], {% if not design.entries.short_second_row %} main-column-second-row: [ {% for line in entry.main_column.splitlines()[first_row_lines:] %} {{ line|indent(4) }} {% endfor %} ], {% endif %} )其他内置条目模板同样遵循这一模式例如 EducationEntry.j2.typ 增加了对design.templates.education_entry.degree_column的判断有值时才输出独立的学位列而 OneLineEntry.j2.typ 则极为简单直接输出{{entry.main_column}}。这意味着模板文件可以按需保持极简缺失的部分由内置版本兜底。Markdown 模板同理例如内置的 NormalEntry.j2.md 用## {{ entry.main_column.splitlines()[0] }}生成二级标题并遍历主栏剩余行、剔除!!! summary标记后输出摘要内容。模板内可用的变量在模板上下文中RenderCV 通过 render_single_template 统一注入以下变量cv全部简历数据姓名、各 section、连接方式等design全部设计选项locale本地化字符串月份名称、翻译文本等settings渲染设置如 PDF 标题、解析后的当前日期entry当前条目数据仅条目模板内可用随entry关键字参数传入。此外渲染章节时会额外传入section_title、snake_case_section_title、entry_type等变量见 render_full_template 中对SectionBeginning.j2.typ的调用HTML 渲染则额外传入html_body。以官方文档中的Preamble.j2.typ片段为例// In Preamble.j2.typ #show: rendercv.with( page-size: {{ design.page.size }}, colors-body: {{ design.colors.body.as_rgb() }}, typography-font-family-body: {{ design.typography.font_family.body }}, // ... )仓库内置的 Preamble.j2.typ 完整展示了rendercv.with(...)能接收的全部参数从page-size、四个页边距、page-show-footer、page-show-top-note到colors-body/name/headline/connections/section-titles/links/footer/top-note各颜色通道再到typography-line-spacing、各元素的字体族、字号、small-caps、bold开关以及header-*、section-titles-*、sections-*、entries-*等数十个参数。其中布尔值统一通过{{ ...|lower }}过滤器输出小写true/false而高亮项目符号entries-highlights-bullet还针对●做了特殊处理渲染为 Typst 的text(13pt, [•], baseline: -0.6pt)。这些值全部来自 YAML 中的design字段因此覆写模板后你在 YAML 里配置的颜色、字体依然生效。locale变量在模板中的典型用法见 Header.j2.typ模板通过cv.photo判断是否渲染照片用design.header.photo_position决定照片在左栏还是右栏再按cv.name、cv.headline、cv._connections依次输出姓名、标语与连接信息。Markdown 模板定制除了 Typst 模板两种方法也都支持 Markdown 模板定制。在rendercv new时传入--create-markdown-templates即可rendercv new Your Name --create-typst-templates --create-markdown-templates根据 new_command.py 的选项定义--create-markdown-templates会把内置 Markdown 模板复制到markdown/目录而非以主题命名的目录。Markdown 模板的文件名与 Typst 模板一一对应Header.j2.md、SectionBeginning.j2.md、entries/EducationEntry.j2.md等修改、渲染流程与 Typst 模板完全一致生成的.md文件会作为后续 HTML 输出的中间产物参见 render_html 中 Markdown 转 HTML 的流程。实用技巧与注意事项从小处着手先复制模板、做小改动并即时渲染验证避免一次性大改导致难以定位问题牢记模板是 Jinja2 Typst这不是纯 Typst 文件Jinja2 的{% %}、{{ }}语法会在渲染时先被执行同理修改内置模板后若语法错误错误信息会同时涉及 Jinja2 与 Typst 两个阶段按需删除模板文件对于不想定制的模板直接删除对应文件即可——RenderCV 会回退到内置版本不会报错。这一行为由 render_single_template 中的jinja2.TemplateNotFound抑制逻辑保证理解模板加载优先级本地{theme}/目录 内置typst/目录输入 YAML 所在目录 包内模板目录design.templates与模板文件的分工design.templates以占位符字符串控制「文本内容如何拼装」如**NAME**\nSUMMARY\nHIGHLIGHTS完整占位符说明见 classic_theme.py而模板文件控制「排版结构如何呈现」两者可以组合使用模板文件中的{{ entry.main_column }}拿到的正是design.templates.*加工后的文本列。对于想深入研究的读者可以继续阅读 design 配置文档 了解全部设计选项参考 customtheme 效果图 观察自定义主题的典型产出并通过 templater 测试目录 中的用例理解模板渲染的边界行为。【免费下载链接】rendercvResume builder for academics and engineers项目地址: https://gitcode.com/GitHub_Trending/re/rendercv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
