拓冰网站定制 
RenderCV NormalEntry 模板机制剖析从 YAML 字段到 Markdown 双栏条目渲染【免费下载链接】rendercvResume builder for academics and engineers项目地址: https://gitcode.com/GitHub_Trending/re/rendercv本指南以 RenderCV 的NormalEntry条目类型及其 Markdown 渲染模板NormalEntry.j2.md为核心系统讲解「通用条目」如何从 YAML 输入经过数据模型校验、占位符展开、双栏拆分最终渲染为 Markdown 文档的全链路。读完你将掌握 NormalEntry 的字段语义、main_column/date_and_location_column两大模板槽位的展开规则、SUMMARY/HIGHLIGHTS等特殊占位符的处理细节并能据此自定义自己的条目模板。NormalEntry 是什么通用条目的定位在 RenderCV 的条目体系中NormalEntry 是覆盖「项目Project、活动Event、奖项Award」等通用场景的条目类型。它不是经验、教育、论文这类带强结构字段的专用条目而是只有name这一个必填语义字段、其余字段全部可选的最小通用载体。从源码看它的模型定义非常精简src/rendercv/schema/models/cv/entries/normal.pyclass BaseNormalEntry(BaseEntry): name: str pydantic.Field( examples[Some Project, Some Event, Some Award], ) # This approach ensures NormalEntryBase keys appear first in the key order: class NormalEntry(BaseEntryWithComplexFields, BaseNormalEntry): passname字段的示例值Some Project、Some Event、Some Award直接说明了它的适用场景。而通过多重继承BaseEntryWithComplexFieldsNormalEntry 自动获得了下面这些「复杂字段」字段类型说明示例namestr必填条目名称/标题Some Projectdateint \| str可选单日或非精确日期支持YYYY-MM-DD、YYYY-MM、YYYY或任意文本如Fall 20232021-09、Fall 2023start_date/end_dateExactDate可选日期范围起止严格格式YYYY-MM-DD/YYYY-MM/YYYYend_date可用present表示进行中2020-09、presentlocationstr可选地点Istanbul, Türkiye、Remotesummarystr可选概述段落Led a team of 5 engineers...highlightslist[str]可选要点列表渲染为无序列表[Increased performance by 40%...]其中日期校验逻辑由 entry_with_complex_fields.py 的check_and_adjust_dates模型校验器统一处理只提供date时忽略start_date/end_date只提供end_date时视为单日事件等价于只提供date只提供start_date时自动视为进行中事件即end_date present同时提供起止日期时会校验start_date不得晚于end_date。一个真实的 NormalEntry 示例RenderCV 官方示例文件docs/user_guide/sample_entries.yaml给出了完整的 NormalEntry 写法normal_entry: name: Some Project date: 2021-09 summary: This is a summary of the project. highlights: - Developed a web application with **React** and **Django**. - Implemented a **RESTful API**注意这里highlights中的文本可以直接使用 Markdown 语法**React**加粗、链接等这些标记会原样保留到最终 Markdown 输出中这正是模板渲染只做占位符替换、不做内容转义的体现。双栏结构main_column 与 date_and_location_columnNormalEntry 在版面上天然分为两栏主栏main_column和日期/地点栏date_and_location_column。渲染前数据模型处理器会把经过模板展开后的文本分别存入这两个属性Markdown 与 Typst 模板再各自消费它们。这两栏的默认模板定义在 classic_theme.pyclass NormalEntryTemplate(BaseModelWithoutExtraKeys): main_column: str pydantic.Field( default**NAME**\nSUMMARY\nHIGHLIGHTS, description( Template for normal entry main column. Available placeholders:\n - NAME: Entry name/title\n- SUMMARY: Summary text\n - HIGHLIGHTS: Bullet points list\n- LOCATION: Location text\n - DATE: Formatted date or date range\n\n You can also add arbitrary keys to entries and use them as UPPERCASE placeholders.\n\n The default value is **NAME**\nSUMMARY\nHIGHLIGHTS. ), ) date_and_location_column: str pydantic.Field( defaultLOCATION\nDATE, description( Template for normal entry date/location column. Available placeholders:\n - NAME: Entry name/title\n- SUMMARY: Summary text\n - HIGHLIGHTS: Bullet points list\n- LOCATION: Location text\n - DATE: Formatted date or date range\n\n You can also add arbitrary keys to entries and use them as UPPERCASE placeholders.\n\n The default value is LOCATION\nDATE. ), )也就是说NormalEntry 的默认双栏布局是主栏**NAME**→SUMMARY→HIGHLIGHTS三行日期/地点栏LOCATION→DATE两行。Markdown 模板逐行拆解NormalEntry 的 Markdown 渲染模板全文如下src/rendercv/renderer/templater/templates/markdown/entries/NormalEntry.j2.md## {{ entry.main_column.splitlines()[0] }} {% for line in entry.date_and_location_column.splitlines() %} {{ line }} {% endfor %} {% for line in entry.main_column.splitlines()[1:] %} {%- if line ! !!! summary -%}{{ line|replace( , ) }} {% endif -%} {% endfor %}别看它只有十几行却完整实现了「标题行 双栏信息 主栏余下内容」的三段式输出。逐段解释如下。第一段标题行## {{ entry.main_column.splitlines()[0] }}取main_column的第一行作为条目的##二级标题。由于默认模板主栏第一行是**NAME**因此标题即加粗的条目名称例如## **Some Project**。第二段日期/地点栏{% for line in entry.date_and_location_column.splitlines() %} {{ line }} {% endfor %}遍历date_and_location_column的每一行默认是LOCATION和DATE两行逐行原样输出。在 Markdown 双栏布局下这两行会被渲染在条目的右侧日期/地点区域。第三段主栏余下内容{% for line in entry.main_column.splitlines()[1:] %} {%- if line ! !!! summary -%}{{ line|replace( , ) }} {% endif -%} {% endfor %}这是最复杂的部分做了三件事切片跳过标题splitlines()[1:]跳过第一行已被用作##标题只渲染 SUMMARY、HIGHLIGHTS 等剩余行过滤摘要标记line ! !!! summary跳过摘要的定位标记行其作用详见下文「SUMMARY 占位符」一节去缩进line|replace( , )把摘要内容行开头的 4 空格缩进去掉保证摘要正文在 Markdown 中作为普通段落渲染。三个控制细节模板中还有几个值得注意的 Jinja2 细节{%- if ... -%}的-空白控制符{%-吃掉前一循环迭代留下的空行-%}吃掉本块后随的空行确保输出的 Markdown 中每个条目块之间恰好只留一个空行避免出现大片空白。空行布局{{ line }}后紧跟一个空行把每一行内容隔开形成 Markdown 段落。无副作用输出被过滤掉的!!! summary行本身不输出任何内容只承担「占位」职责。上游管线占位符如何被展开为可渲染文本模板消费的main_column/date_and_location_column并非 YAML 原始字段而是经过 render_entry_templates 处理后的产物。这条管线是理解 NormalEntry 渲染的关键其核心步骤如下1. 字段名大写化entry_fields: dict[str, str] { key.upper(): value for key, value in entry.model_dump(exclude_noneTrue).items() }name→NAME、summary→SUMMARY、highlights→HIGHLIGHTS全部转为大写字面量以便与模板中的占位符精确匹配。2. 特殊占位符的预处理HIGHLIGHTS由 process_highlights 把列表转换为 Markdown 无序列表且支持 - 子要点语法highlights [- highlight.replace( - , \n - ) for highlight in highlights]例如Reduced costs - Server optimization会生成嵌套的两级列表项。SUMMARY仅当模板把SUMMARY作为独立一行放置时summary_is_standalone判断才调用 process_summary将其包装为 Markdown 提示块return f!!! summary\n{textwrap.indent(summary, )}这解释了模板中line ! !!! summary与replace( , )的由来——!!! summary是 Typst 渲染器识别摘要块的标记行Markdown 模板则将其过滤并还原缩进后的正文。DATE/START_DATE/END_DATE由 process_date 依据 locale 与show_time_span设置格式化为单日期或日期区间end_datepresent时以渲染当天的current_date为参照参见 entry_with_complex_fields.py 的get_date_object。URL由 process_url 转为显示文本Markdown 链接显示文本经clean_url去掉协议前缀。3. 缺失占位符的清理remove_not_provided_placeholders 会先识别模板中出现但字段中缺失的占位符然后用connector_word_pattern删除缺失占位符之间的连接词如in、at避免出现Engineer at这样的孤儿文本用正则删除占位符本身及其邻近的非空格字符如逗号、冒号用clean_trailing_parts清理行尾遗留的分隔符。例如模板**NAME**, LOCATION而用户未填location时输出会干净地变成**Some Project**而不是**Some Project**,。4. 最终占位符替换最后substitute_placeholders按「最长优先」匹配规则把所有剩余占位符替换为字段值见 string_processor.py结果分别写回main_column与date_and_location_column供 Markdown / Typst 模板消费。与 Typst 模板的对照同一数据模型双格式渲染Markdown 模板并非孤例。NormalEntry 还有一份等价的 Typst 模板src/rendercv/renderer/templater/templates/typst/entries/NormalEntry.j2.typ二者消费完全相同的main_column/date_and_location_column只是输出语法不同#regular-entry( [{{ entry.main_column.splitlines()[:first_row_lines] | join }}], [{{ entry.date_and_location_column.splitlines() | join }}], main-column-second-row: [ ... ], )Typst 模板还受设计配置design.entries.short_second_row默认true见 classic_theme.py控制为false时主栏不截断main-column-second-row占据完整宽度为true时第二行缩短以对齐日期/地点栏。这一对照表明NormalEntry 的渲染逻辑是格式无关的数据层完成模板展开后Markdown 与 Typst 只是两种不同的「视图」。如何自定义 NormalEntry 模板得益于上述管线自定义 NormalEntry 的展示完全不需要改代码只需在 YAML 的design中覆盖模板design: theme: classic entries: normal_entry: main_column: **NAME**\nSUMMARY\nHIGHLIGHTS date_and_location_column: LOCATION\nDATE几点实战建议可用占位符NAME、SUMMARY、HIGHLIGHTS、LOCATION、DATE、START_DATE、END_DATE以及你在条目里自定义的任何任意键以大写形式引用即 arbitrary keys 机制官方说明见 docs/user_guide/how_to/arbitrary_keys_in_entries.md占位符必须全大写模板匹配对大小写敏感小写写法的占位符不会展开行序决定渲染顺序main_column内第一行恒为 Markdown 的##标题其余行依次渲染想要调整标题内容只需调整第一行模板SUMMARY独立成行摘要若要被 Typst 特殊渲染应让SUMMARY独占一行未提供summary时该占位符连同其行会被自动清除。验证测试用例如何锁定渲染行为仓库测试tests/renderer/templater/test_entry_templates_from_input.py直接验证了 NormalEntry 模板展开的结果例如entry NormalEntry(nameSolo) assert entry.main_column **Solo** entry NormalEntry(nameProject, highlights[Alpha, Beta]) assert entry.main_column **Project**\n- Alpha\n- Beta这些断言说明仅提供name时SUMMARY/HIGHLIGHTS占位符会被完全移除主栏只剩**Solo**提供highlights时则按-前缀展开为无序列表。此外测试还覆盖了normal_entry模板中START_DATE / END_DATE / LOCATION / DATE混排、缺失字段清理等边界场景可作为理解模板行为的可执行参考。小结NormalEntry 的 Markdown 模板虽然只有十余行背后却串联起 Pydantic 数据校验normal.py、entry_with_complex_fields.py、占位符预处理管线entry_templates_from_input.py、双栏字段构造classic_theme.py以及 Jinja2 模板渲染templater.py四层机制。理解这四层之后你不仅能预判任意 YAML 输入的输出形态还能通过覆写模板自由定制「项目 / 活动 / 奖项」条目的排版这正是 RenderCV 主题系统详见 docs/developer_guide/how_to/add_theme.md的扩展入口所在。【免费下载链接】rendercvResume builder for academics and engineers项目地址: https://gitcode.com/GitHub_Trending/re/rendercv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 RenderCV NormalEntry 模板机制剖析：从 YAML 字段到 Markdown 双栏条目渲染
RenderCV NormalEntry 模板机制剖析从 YAML 字段到 Markdown 双栏条目渲染【免费下载链接】rendercvResume builder for academics and engineers项目地址: https://gitcode.com/GitHub_Trending/re/rendercv本指南以 RenderCV 的NormalEntry条目类型及其 Markdown 渲染模板NormalEntry.j2.md为核心系统讲解「通用条目」如何从 YAML 输入经过数据模型校验、占位符展开、双栏拆分最终渲染为 Markdown 文档的全链路。读完你将掌握 NormalEntry 的字段语义、main_column/date_and_location_column两大模板槽位的展开规则、SUMMARY/HIGHLIGHTS等特殊占位符的处理细节并能据此自定义自己的条目模板。NormalEntry 是什么通用条目的定位在 RenderCV 的条目体系中NormalEntry 是覆盖「项目Project、活动Event、奖项Award」等通用场景的条目类型。它不是经验、教育、论文这类带强结构字段的专用条目而是只有name这一个必填语义字段、其余字段全部可选的最小通用载体。从源码看它的模型定义非常精简src/rendercv/schema/models/cv/entries/normal.pyclass BaseNormalEntry(BaseEntry): name: str pydantic.Field( examples[Some Project, Some Event, Some Award], ) # This approach ensures NormalEntryBase keys appear first in the key order: class NormalEntry(BaseEntryWithComplexFields, BaseNormalEntry): passname字段的示例值Some Project、Some Event、Some Award直接说明了它的适用场景。而通过多重继承BaseEntryWithComplexFieldsNormalEntry 自动获得了下面这些「复杂字段」字段类型说明示例namestr必填条目名称/标题Some Projectdateint \| str可选单日或非精确日期支持YYYY-MM-DD、YYYY-MM、YYYY或任意文本如Fall 20232021-09、Fall 2023start_date/end_dateExactDate可选日期范围起止严格格式YYYY-MM-DD/YYYY-MM/YYYYend_date可用present表示进行中2020-09、presentlocationstr可选地点Istanbul, Türkiye、Remotesummarystr可选概述段落Led a team of 5 engineers...highlightslist[str]可选要点列表渲染为无序列表[Increased performance by 40%...]其中日期校验逻辑由 entry_with_complex_fields.py 的check_and_adjust_dates模型校验器统一处理只提供date时忽略start_date/end_date只提供end_date时视为单日事件等价于只提供date只提供start_date时自动视为进行中事件即end_date present同时提供起止日期时会校验start_date不得晚于end_date。一个真实的 NormalEntry 示例RenderCV 官方示例文件docs/user_guide/sample_entries.yaml给出了完整的 NormalEntry 写法normal_entry: name: Some Project date: 2021-09 summary: This is a summary of the project. highlights: - Developed a web application with **React** and **Django**. - Implemented a **RESTful API**注意这里highlights中的文本可以直接使用 Markdown 语法**React**加粗、链接等这些标记会原样保留到最终 Markdown 输出中这正是模板渲染只做占位符替换、不做内容转义的体现。双栏结构main_column 与 date_and_location_columnNormalEntry 在版面上天然分为两栏主栏main_column和日期/地点栏date_and_location_column。渲染前数据模型处理器会把经过模板展开后的文本分别存入这两个属性Markdown 与 Typst 模板再各自消费它们。这两栏的默认模板定义在 classic_theme.pyclass NormalEntryTemplate(BaseModelWithoutExtraKeys): main_column: str pydantic.Field( default**NAME**\nSUMMARY\nHIGHLIGHTS, description( Template for normal entry main column. Available placeholders:\n - NAME: Entry name/title\n- SUMMARY: Summary text\n - HIGHLIGHTS: Bullet points list\n- LOCATION: Location text\n - DATE: Formatted date or date range\n\n You can also add arbitrary keys to entries and use them as UPPERCASE placeholders.\n\n The default value is **NAME**\nSUMMARY\nHIGHLIGHTS. ), ) date_and_location_column: str pydantic.Field( defaultLOCATION\nDATE, description( Template for normal entry date/location column. Available placeholders:\n - NAME: Entry name/title\n- SUMMARY: Summary text\n - HIGHLIGHTS: Bullet points list\n- LOCATION: Location text\n - DATE: Formatted date or date range\n\n You can also add arbitrary keys to entries and use them as UPPERCASE placeholders.\n\n The default value is LOCATION\nDATE. ), )也就是说NormalEntry 的默认双栏布局是主栏**NAME**→SUMMARY→HIGHLIGHTS三行日期/地点栏LOCATION→DATE两行。Markdown 模板逐行拆解NormalEntry 的 Markdown 渲染模板全文如下src/rendercv/renderer/templater/templates/markdown/entries/NormalEntry.j2.md## {{ entry.main_column.splitlines()[0] }} {% for line in entry.date_and_location_column.splitlines() %} {{ line }} {% endfor %} {% for line in entry.main_column.splitlines()[1:] %} {%- if line ! !!! summary -%}{{ line|replace( , ) }} {% endif -%} {% endfor %}别看它只有十几行却完整实现了「标题行 双栏信息 主栏余下内容」的三段式输出。逐段解释如下。第一段标题行## {{ entry.main_column.splitlines()[0] }}取main_column的第一行作为条目的##二级标题。由于默认模板主栏第一行是**NAME**因此标题即加粗的条目名称例如## **Some Project**。第二段日期/地点栏{% for line in entry.date_and_location_column.splitlines() %} {{ line }} {% endfor %}遍历date_and_location_column的每一行默认是LOCATION和DATE两行逐行原样输出。在 Markdown 双栏布局下这两行会被渲染在条目的右侧日期/地点区域。第三段主栏余下内容{% for line in entry.main_column.splitlines()[1:] %} {%- if line ! !!! summary -%}{{ line|replace( , ) }} {% endif -%} {% endfor %}这是最复杂的部分做了三件事切片跳过标题splitlines()[1:]跳过第一行已被用作##标题只渲染 SUMMARY、HIGHLIGHTS 等剩余行过滤摘要标记line ! !!! summary跳过摘要的定位标记行其作用详见下文「SUMMARY 占位符」一节去缩进line|replace( , )把摘要内容行开头的 4 空格缩进去掉保证摘要正文在 Markdown 中作为普通段落渲染。三个控制细节模板中还有几个值得注意的 Jinja2 细节{%- if ... -%}的-空白控制符{%-吃掉前一循环迭代留下的空行-%}吃掉本块后随的空行确保输出的 Markdown 中每个条目块之间恰好只留一个空行避免出现大片空白。空行布局{{ line }}后紧跟一个空行把每一行内容隔开形成 Markdown 段落。无副作用输出被过滤掉的!!! summary行本身不输出任何内容只承担「占位」职责。上游管线占位符如何被展开为可渲染文本模板消费的main_column/date_and_location_column并非 YAML 原始字段而是经过 render_entry_templates 处理后的产物。这条管线是理解 NormalEntry 渲染的关键其核心步骤如下1. 字段名大写化entry_fields: dict[str, str] { key.upper(): value for key, value in entry.model_dump(exclude_noneTrue).items() }name→NAME、summary→SUMMARY、highlights→HIGHLIGHTS全部转为大写字面量以便与模板中的占位符精确匹配。2. 特殊占位符的预处理HIGHLIGHTS由 process_highlights 把列表转换为 Markdown 无序列表且支持 - 子要点语法highlights [- highlight.replace( - , \n - ) for highlight in highlights]例如Reduced costs - Server optimization会生成嵌套的两级列表项。SUMMARY仅当模板把SUMMARY作为独立一行放置时summary_is_standalone判断才调用 process_summary将其包装为 Markdown 提示块return f!!! summary\n{textwrap.indent(summary, )}这解释了模板中line ! !!! summary与replace( , )的由来——!!! summary是 Typst 渲染器识别摘要块的标记行Markdown 模板则将其过滤并还原缩进后的正文。DATE/START_DATE/END_DATE由 process_date 依据 locale 与show_time_span设置格式化为单日期或日期区间end_datepresent时以渲染当天的current_date为参照参见 entry_with_complex_fields.py 的get_date_object。URL由 process_url 转为显示文本Markdown 链接显示文本经clean_url去掉协议前缀。3. 缺失占位符的清理remove_not_provided_placeholders 会先识别模板中出现但字段中缺失的占位符然后用connector_word_pattern删除缺失占位符之间的连接词如in、at避免出现Engineer at这样的孤儿文本用正则删除占位符本身及其邻近的非空格字符如逗号、冒号用clean_trailing_parts清理行尾遗留的分隔符。例如模板**NAME**, LOCATION而用户未填location时输出会干净地变成**Some Project**而不是**Some Project**,。4. 最终占位符替换最后substitute_placeholders按「最长优先」匹配规则把所有剩余占位符替换为字段值见 string_processor.py结果分别写回main_column与date_and_location_column供 Markdown / Typst 模板消费。与 Typst 模板的对照同一数据模型双格式渲染Markdown 模板并非孤例。NormalEntry 还有一份等价的 Typst 模板src/rendercv/renderer/templater/templates/typst/entries/NormalEntry.j2.typ二者消费完全相同的main_column/date_and_location_column只是输出语法不同#regular-entry( [{{ entry.main_column.splitlines()[:first_row_lines] | join }}], [{{ entry.date_and_location_column.splitlines() | join }}], main-column-second-row: [ ... ], )Typst 模板还受设计配置design.entries.short_second_row默认true见 classic_theme.py控制为false时主栏不截断main-column-second-row占据完整宽度为true时第二行缩短以对齐日期/地点栏。这一对照表明NormalEntry 的渲染逻辑是格式无关的数据层完成模板展开后Markdown 与 Typst 只是两种不同的「视图」。如何自定义 NormalEntry 模板得益于上述管线自定义 NormalEntry 的展示完全不需要改代码只需在 YAML 的design中覆盖模板design: theme: classic entries: normal_entry: main_column: **NAME**\nSUMMARY\nHIGHLIGHTS date_and_location_column: LOCATION\nDATE几点实战建议可用占位符NAME、SUMMARY、HIGHLIGHTS、LOCATION、DATE、START_DATE、END_DATE以及你在条目里自定义的任何任意键以大写形式引用即 arbitrary keys 机制官方说明见 docs/user_guide/how_to/arbitrary_keys_in_entries.md占位符必须全大写模板匹配对大小写敏感小写写法的占位符不会展开行序决定渲染顺序main_column内第一行恒为 Markdown 的##标题其余行依次渲染想要调整标题内容只需调整第一行模板SUMMARY独立成行摘要若要被 Typst 特殊渲染应让SUMMARY独占一行未提供summary时该占位符连同其行会被自动清除。验证测试用例如何锁定渲染行为仓库测试tests/renderer/templater/test_entry_templates_from_input.py直接验证了 NormalEntry 模板展开的结果例如entry NormalEntry(nameSolo) assert entry.main_column **Solo** entry NormalEntry(nameProject, highlights[Alpha, Beta]) assert entry.main_column **Project**\n- Alpha\n- Beta这些断言说明仅提供name时SUMMARY/HIGHLIGHTS占位符会被完全移除主栏只剩**Solo**提供highlights时则按-前缀展开为无序列表。此外测试还覆盖了normal_entry模板中START_DATE / END_DATE / LOCATION / DATE混排、缺失字段清理等边界场景可作为理解模板行为的可执行参考。小结NormalEntry 的 Markdown 模板虽然只有十余行背后却串联起 Pydantic 数据校验normal.py、entry_with_complex_fields.py、占位符预处理管线entry_templates_from_input.py、双栏字段构造classic_theme.py以及 Jinja2 模板渲染templater.py四层机制。理解这四层之后你不仅能预判任意 YAML 输入的输出形态还能通过覆写模板自由定制「项目 / 活动 / 奖项」条目的排版这正是 RenderCV 主题系统详见 docs/developer_guide/how_to/add_theme.md的扩展入口所在。【免费下载链接】rendercvResume builder for academics and engineers项目地址: https://gitcode.com/GitHub_Trending/re/rendercv创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考