静态站点前端开发工具【免费下载链接】kit Describe your site, AI builds it, you own it as Markdown. Snap together Tailwind blocks like Lego — landing pages, blogs, portfolios, docs more. No AI slop. Free to deploy anywhere 项目地址https://gitcode.com/gh_mirrors/hu/kit点击查看免费下载导读Experience 组件是 Hugo Blox 系列起步模板以本仓库starters-bootstrap/portfolio为例中用于展示个人职业经历的核心页面区块它把title、company、起止时间、地点、Logo 与职责描述等结构化数据渲染成一条带时间线的卡片列表。本文以 experience.md 配置实例 为骨架逐字段讲解 YAML 配置语法、日期格式、多行描述与design.columns布局规则并深入modules/blox-bootstrap源码揭示其时间线渲染、公司 Logo 加载与Present至今文案的底层实现。读完本文你可以在任何 Hugo Blox 项目中熟练新增、排序、定制 Experience 区块并理解其与 Education 组件的复用关系。一、Experience 组件在 Hugo Blox 模板中的定位在 Hugo Blox 的组件体系中页面由多个区块block堆叠而成每个区块对应一个widget类型的独立 Markdown 文件。Experience 组件就是其中之一其配置文件通过 front matter 声明widget: experience来指定渲染所使用的模板。在 portfolio 起步模板 中个人经历区块被放在content/about/目录下与 about.mdAbout 组件、education.mdEducation 组件、accomplishments.md、contact.md共同构成一个关于我页面。目录入口由 index.md 通过type: widget_page声明说明该目录下的各组件文件按weight字段依次渲染成同一页面中的多个区块。关联文档 experience.md 的weight: 20即决定了它在页面上的顺序about.md为 10简介在最前、experience.md为 20、education.md为 30依此类推。想调整区块先后顺序直接修改各文件的weight值即可。二、front matter 结构逐项解析Experience 组件的完整配置如下取自关联文档原文字段注释为原文档自带说明--- # An instance of the Experience widget. # Documentation: https://docs.hugoblox.com/page-builder/ widget: experience # This file represents a page section. headless: true # Order that this section appears on the page. weight: 20 title: Experience subtitle: # Date format for experience # Refer to https://docs.hugoblox.com/customization/#date-format date_format: Jan 2006 # Experiences. # Add/remove as many experience items below as you like. # Required fields are title, company, and date_start. # Leave date_end empty if its your current employer. # Begin multi-line descriptions with YAMLs |2- multi-line prefix. experience: - title: CEO company: GenCoin company_url: company_logo: org-gc location: California date_start: 2021-01-01 date_end: description: |2- Responsibilities include: * Analysing * Modelling * Deploying - title: Professor of Semiconductor Physics company: University X company_url: company_logo: org-x location: California date_start: 2016-01-01 date_end: 2020-12-31 description: Taught electronic engineering and researched semiconductor physics. design: columns: 1 ---2.1 顶层键widget / headless / weight / title / subtitle键取值含义widgetexperience声明本文件是一个 Experience 区块实例Hugo 将按该值查找对应模板headlesstrue本文件仅作为页面区块被渲染不生成独立 URL 页面weight整数如20区块在 widget page 上的出现顺序数值越小越靠前title字符串区块标题如Experience渲染为section-heading下的h1subtitle字符串可留空标题下方的副标题可省略或留空字符串从 parse_block_v2.html 的源码可以看到title与subtitle在渲染时经过markdownify与emojify处理——也就是说你可以在标题中直接写 Markdown 和 emoji 表情Hugo 会自动转换后输出。2.2 日期格式date_format: Jan 2006date_format控制经历条目起止时间的显示格式采用 Go 的时间格式化参考时间语法2006表示年份、Jan表示月份缩写、January表示完整月份名。默认值为Jan 2006输出形如Jan 2021。从 experience.html 源码可见其实际用法{{ (time .date_start) | time.Format ($block.Params.date_format | default January 2006) }} –即先通过time函数把 YAML 字符串解析为时间对象再用time.Format按date_format格式化若该字段未配置模板兜底使用January 2006完整月份名年份如January 2021。常见可选格式date_format取值输出示例Jan 2006Jan 2021January 2006January 20212006.012021.0102 Jan 200601 Jan 202120062021三、experience条目字段详解experience是一个 YAML 列表每个-开头的缩进项代表一条职业经历。原文档明确指出必填字段为title、company与date_start其余均为可选。字段类型说明源码行为titlestring职位/头衔必填渲染为卡片标题.exp-title经markdownify | emojify处理companystring公司/机构名称必填渲染为.exp-company同样支持 Markdown 与 emojicompany_urlstring公司官网链接可留空非空时标题与 Logo 均包裹a target_blank relnoopener外链company_logostring品牌 Logo 资源名如org-gc映射到assets/media/icons/brands/name.svg见下文 4.1locationstring工作地点如California渲染在日期之后以.middot-divider圆点分隔date_startdateYAML 中加引号开始日期如2021-01-01必填经time解析后按date_format格式化date_enddate结束日期留空表示至今为空时显示 i18npresent见下文 4.2descriptionstring职责/成就描述支持 Markdown 与多行渲染为.card-text经markdownify | emojify处理3.1 多行描述的 YAML 语法|2-原文档特别强调多行描述必须以 YAML 的|2-块标量前缀开始。例如description: |2- Responsibilities include: * Analysing * Modelling * Deploying其中|表示保留换行的字面块literal block2表示内容块缩进 2 个空格与description:后的标准缩进对齐-表示去掉末尾多余的换行符。这样写出的字符串在渲染时会被完整保留换行配合 Markdown 列表*即可输出结构清晰的职责清单。3.2 时间线的至今语义date_end留空原文档注明Leavedate_endempty if its your current employer。这一约定直接决定了渲染结果当date_end为空字符串时experience.html 不会输出结束日期而是输出国际化文案{{ if .date_end}} {{ (time .date_end) | time.Format ... }} {{else}} {{ i18n present | default Present }} {{end}}i18n present会从语言包读取翻译。以 i18n/en.yaml 为例present对应的默认文案为Present当前时间至今同时时间线圆点badge也会因date_end为空而加上exp-fill类以实心样式突出在职中的条目。若启用其他语言仓库内置 40 语言包该文案会自动本地化。四、源码级深入Experience 区块的渲染原理4.1 公司 Logo 的加载机制与资源路径配置中的company_logo: org-gc并非图片文件名而是一个资源名。从 experience.html 源码可以看出其真实解析逻辑{{- $svg_icon : resources.Get (printf media/icons/brands/%s.svg .company_logo) -}} {{ if not $svg_icon }}{{ errorf Brand logo not found at assets/media/icons/brands/%s.svg .company_logo }}{{end}}即 Hugo 会到assets/media/icons/brands/目录下查找company_logo.svg文件例如org-gc.svg、org-x.svg。这带来两个关键结论Logo 必须是 SVG 文件放置路径必须为assets/media/icons/brands/name.svg若找不到该资源构建会直接抛出错误errorf并给出明确的缺失路径提示——因此配置company_logo前务必确认对应 SVG 已存在。渲染时 Logo 以56×56尺寸输出并带有loadinglazy延迟加载若company_url非空Logo 和公司名都会成为指向官网的外链target_blank relnoopener。若不需要 Logo将company_logo留空或删除该键即可卡片会自动省略 Logo 区域。4.2 时间线结构exp-fill圆点与边框连线Experience 区块的时间线外观同样来自模板源码experience.html每条经历渲染为一个.row.experience左侧是竖向的圆形徽章badge badge-pill border与上下两段垂直连线border-right。其中当前条目date_end为空的圆点带exp-fill类呈现实心强调效果首条与末条条目分别省略上、下连线保证时间线两端自然收口。4.3 布局与列数design.columnsdesign.columns控制区块内容的布局宽度原文档默认配置为1。其生效逻辑在 parse_block_v2.html 与 experience.html 中相互配合experience被列入use_cols区块类型与collection、accomplishments、portfolio等同组意味着其内容位于一个.row栅格容器内当columns: 1时区块标题居中内容占满单列col-12当columns: 2时标题位于左侧四分之一宽col-lg-4经历卡片区占右侧col-lg-8形成经典的标题在左、内容在右双栏布局。在 experience.html 中对应代码为div classcol-12 {{if eq $columns 2}}col-lg-8{{end}}可见列数切换完全由design.columns驱动。4.4 区块渲染的完整调用链Experience 区块被渲染时走的是 Hugo Blox 的统一区块管线widget_page页面加载content/about/下所有headless: true的组件文件parse_block_v2.html 解析 front matter读取widget: experience映射到模板blocks/experience.html并注入design.columns、背景、间距等样式参数blocks/experience.html遍历experience列表逐条输出时间线卡片。该管线对experience、education、accomplishments等区块完全通用——这也是为什么 education.md 与 experience.md 结构几乎一致同为widget: experience加experience:列表仅在weight、title与条目内容上不同。你可以用同样方式把 Experience 区块复用到简历、主页等任意 widget page。五、实战在 Portfolio 模板中自定义经历区块5.1 三步上手编辑条目打开 experience.md在experience:列表下按格式增删条目。复制一个已有条目再修改是最不容易出错的方式。准备 Logo如需显示公司 Logo将对应 SVG 放入assets/media/icons/brands/如org-gc.svg并在条目中填写company_logo: org-gc。调整顺序与布局修改顶层weight改变区块在页面中的位置修改design.columns为1或2切换单列/双栏布局。5.2 完整可复制的最小配置--- widget: experience headless: true weight: 20 title: Experience subtitle: date_format: Jan 2006 experience: - title: CEO company: GenCoin company_url: https://example.com company_logo: org-gc location: California date_start: 2021-01-01 date_end: description: |2- Responsibilities include: * Analysing * Modelling * Deploying design: columns: 1 ---要点速查必填title、company、date_start三个都缺失时渲染结果不完整当前雇主date_end留空模板自动显示Present并加粗时间线圆点多行描述以|2-开头正文缩进 2 个空格内部可自由使用 Markdown 列表、换行公司 Logo资源必须存在于assets/media/icons/brands/name.svg否则构建报错日期格式使用 Go 参考时间语法Jan 2006、January 2006等可全局按date_format统一调整。5.3 与 Education 区块共用组件由于 Education 组件education.md同样基于widget: experience与experience:列表实现你可以把本文的所有字段规则原样套用于教育经历配置只需将title改为学位名称如MEng Electronic Engineering、company改为学校如University X、company_logo换成学校 Logo 资源名即可。两个区块共享同一套渲染模板维护成本极低。六、常见问题与排错现象原因与解决构建报Brand logo not found at assets/media/icons/brands/xxx.svgcompany_logo指向的 SVG 不存在。将对应.svg放入assets/media/icons/brands/或删除company_logo字段结束日期显示为Presentdate_end为空字符串所致属预期行为若需显示实际结束日期填入如2020-12-31日期显示为January 2021而非Jan 2021date_format未配置或格式不符。设置date_format: Jan 2006并按 Go 参考时间语法书写描述中的换行/列表不生效多行描述需使用|2-块标量前缀且内容缩进与列表层级保持一致标题不居中/布局不对称检查design.columns是否为1居中单列或2左标题右内容双栏结语Experience 组件是 Hugo Blox 页面构建体系中配置驱动渲染的典型代表一份几十行的 YAML front matter经由widget: experience挂载到 experience.html 模板即可产出带时间线、品牌 Logo、外链与本地化文案的完整职业经历区块。本文从关联文档 experience.md 出发覆盖了从字段语义、YAML 多行语法、日期格式到资源加载与布局管线的全部细节——掌握这套规则后你不仅能熟练定制 Portfolio 模板的经历区块也能举一反三地理解 Hugo Blox 中education、accomplishments等同构组件的配置方式真正实现改配置即改页面。赞分享静态站点前端开发工具【免费下载链接】kit Describe your site, AI builds it, you own it as Markdown. Snap together Tailwind blocks like Lego — landing pages, blogs, portfolios, docs more. No AI slop. Free to deploy anywhere 项目地址https://gitcode.com/gh_mirrors/hu/kit点击查看免费下载相关推荐Hugo Site.Menus 方法完全指南从菜单配置、模板渲染到源码级实现原理Hugo Site.Menus 方法完全指南从菜单配置、模板渲染到源码级实现原理 本指南围绕 Hugo 站点对象上的 Menus 方法展开它返回当前站点的全开发工具前端CLIHugo Blox 空白组件Blank Widget页面原型完全指南配置详解与渲染原理Hugo Blox 空白组件Blank Widget页面原型完全指南配置详解与渲染原理 本指南以 Hugo Blox 主题模块blox bootstra静态站点前端开发工具Hugo Blox 学术模板会议论文页面完全指南front matter 配置、引用导入与源码渲染原理Hugo Blox 学术模板会议论文页面完全指南front matter 配置、引用导入与源码渲染原理 本文以 Hugo Blox 学术模板 starter静态站点前端开发工具上一篇革命你的 Neovim 工作流legendary.nvim 全功能指南下一篇ReactQL服务器端渲染原理从Koa到客户端水合创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考