Zola 博客与项目主题 Papaya 完整使用指南安装、多语言配置与图像嵌入深度实践【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址: https://gitcode.com/GitHub_Trending/zo/zolaPapaya 是一款面向博客与项目展示的简洁 Zola 静态站点主题内置自动明暗模式、分类与标签、多语言支持、特色图片、GitHub Star/Fork 计数以及基于 Zola 图像处理能力的智能图片嵌入 shortcode。本文将以 Papaya 主题文档为主线结合当前 Zola 仓库中多语言、分类法、图像处理等底层实现完整演示从安装、启用到逐项深度定制的全过程帮助你直接搭建一个功能完备、可多语言发布、图片体验优秀的个人站点。主题概览为博客与项目而生Papaya 是一个干净整洁的 Zola 主题主要用于博客写作与项目作品集展示其设计灵感来自 Anpufork 自该主题并持续演化。它的核心特性包括博客文章Blog posts与项目页面Project pages两种内容形态自动明暗模式Automatic light/dark mode分类Categories与标签Tags可选的多语言支持Optional multilingual support可定制的区块Sections与导航菜单链接文章/页面特色图片Featured images智能图片嵌入 shortcodeimg()GitHub 仓库 Star/Fork 计数Open Graph ProtocolOGP社交分享标签Utterances基于 GitHub Issues 的评论组件支持社交/联系方式链接主题官方声明达到 100% Google Lighthouse 分数从主题文档的 front matter 可以确认Papaya 要求 Zola 最低版本为0.16.1minimum_version 0.16.1采用 MIT 开源协议当前仓库中的主题索引文件位于 docs/content/themes/papaya/index.md。如上图所示Papaya 首页采用简洁的单栏主布局顶部是Projects/Blog/About导航主体以左右双栏分别展示最近项目与最近博客文章底部提供邮件与 RSS 等订阅入口整体视觉清新克制非常适合个人博客或轻量作品集。安装与启用四步接入你的站点Papaya 的安装遵循 Zola 主题的标准流程具体步骤如下第 1 步将主题克隆到themes目录git clone papaya 主题仓库地址 themes/papaya主题仓库地址可从本仓库主题索引页 docs/content/themes/papaya/index.md 的 front matter 中repository字段获取。克隆完成后themes/papaya下应包含templates/、static/、sass/以及theme.toml等主题必需文件——这也是 Zola 加载主题的标准目录约定可对照本仓库 test_site/themes/sample 观察一个主题的内部结构。第 2 步在config.toml中启用主题theme papaya第 3 步同步配置段从 Papaya 自带示例config.toml中复制以下配置段含内容与取值到你的站点config.toml[languages][languages.en][languages.en.translations][extra.cdn]font_awesome其中[extra.cdn].font_awesome用于指定 Font Awesome 图标库的 CDN 地址主题的社交图标等元素依赖它详见下文社交/联系方式链接一节。第 4 步初始化内容目录在content目录下新建blog与projects两个区块目录从 Papaya 的content/blog复制_index.md到你的content/blog/从 Papaya 的content/projects复制_index.md和categories.json到你的content/projects/。完成后你的内容目录结构应为content ├── blog │ └── _index.md └── projects └── _index.md └── categories.json第 5 步可选开启 GitHub Star/Fork 计数Papaya 的 GitHub 仓库 Star/Fork 计数功能默认关闭目的是避免触发 GitHub API 速率限制。如需启用在zola serve/zola build之前将$ZOLA_ENV环境变量设置为prod# csh/tcsh setenv ZOLA_ENV prod # bash/ksh/zsh export ZOLA_ENVprod这种以环境变量区分开发/生产行为的思路在 Zola 生态中是常见模式本仓库其他主题如 docs/content/themes/zola-astroplate/index.md也采用了ZOLA_ENVdev作为开发态特性门控的写法。项目分类用 categories.json 组织作品集Papaya 的项目页按分类分组展示。在content/projects/categories.json中定义分类文件格式为{ title: keyword }其中title项目页上每个分类分组显示的标题文字keyword在项目页面 front matter 中使用的分类术语taxonomy term。一个项目可以属于多个分类并会在每个所属分类下各显示一次。没有指定分类的项目会自动归入项目页的 Other 分类分组如果不想显示 Other 分组可以把主题的templates/projects.html复制到你自己的templates目录然后删除或注释掉其中的 Other 分类代码。示例categories.json{ Software: software, Films: film }对应项目页 front mattertitle Example software project date 2021-08-11 [taxonomies] categories [software]上例项目页会被归入并显示在项目页的 Software 分类下。从 Zola 底层实现看Papaya 的分类正是建立在 Zola 内置的分类法taxonomies机制之上。Zola 官方文档 docs/content/documentation/content/taxonomies.md 说明分类法用于根据用户自定义类别对内容分组前端在页面 front matter 中以[taxonomies]表声明如categories [software]构建时 Zola 会为每个分类生成聚合页与条目页URL 形如$BASE_URL/$NAME/$SLUG如/categories/software/。配置层面对应 components/config/src/config/taxonomies.rs 中的TaxonomyConfig结构体它支持name、paginate_by、paginate_path、feed、lang、render等字段。本仓库测试站点 test_site/templates/categories 下也提供了list.html与single.html模板展示了分类聚合页的标准渲染方式。明暗模式light / dark / auto 三态切换Papaya 的明暗模式在config.toml中设置可取light、dark或auto三种值。在auto模式下亮色与暗色由 CSS 媒体特性prefers-color-scheme隐式决定主题会根据访客操作系统或用户代理UA的配色偏好自动切换无需任何手动操作也无需 JavaScript 干预。多语言支持中英双语站点搭建全流程Zola 目前提供基础的国际多语言i18n支持详见官方文档 docs/content/documentation/content/multilingual.md。Papaya 以英文和中文为例给出了完整的双语站点搭建步骤第 1 步配置default_language与语言区块在config.toml中添加default_language配置以及[languages.zh]和[languages.en]区块default_language en [languages] [languages.en] [languages.zh] title 中文标题 description 中文描述在[languages.zh]区块下可以覆盖默认配置如title、description等。这与 Zola 源码中 components/config/src/config/languages.rs 的LanguageOptions结构体一致每种语言可独立配置title、description、generate_feeds、feed_filenames、taxonomies、build_search_index、search以及translations哈希表默认语言之外的配置会与默认语言配置进行合并merge方法冲突时如同一字段被指定两次会直接报错。第 2 步翻译所有关键字在[languages.zh.translations]与[languages.en.translations]中补齐所有界面关键字的翻译完整关键字清单见 Papaya 示例config.toml[languages] [languages.en] [languages.en.translations] projects Projects blog Blog about About recent_projects Recent Projects more_projects More Projects recent_blog_posts Recent Blog Posts more_blog_posts More blog posts ... [languages.zh] [languages.zh.translations] projects 项目 blog 博文 about 关于 recent_projects 近期项目 more_projects 更多项目 recent_blog_posts 近期博文 more_blog_posts 更多博文 ...这些翻译键即LanguageOptions.translations类型为HashMapString, String的内容Zola 通过get_translation()方法按语言取词见 components/config/src/config/languages.rs。第 3 步为每个区块添加_index.zh.md例如添加content/blog/_index.zh.md和content/projects/_index.zh.md。Zola 官方文档 docs/content/documentation/content/multilingual.md 特别说明如果默认语言在某个目录下有_index.md则必须为翻译语言补充对应的_index.{code}.md文件因为 Zola 不做语言回退no language fallback。第 4 步为每个待翻译页面提供.zh.md变体为每个需要翻译的页面提供{page-name}.zh.md如果页面是带资源的目录形式则在页面目录中提供index.zh.md。例如content/blog/what-is-zola.zh.mdcontent/blog/blog-with-image/index.zh.mdZola 依靠文件名后缀来识别语言an-article.md属于默认语言an-article.fr.md/an-article.zh.md属于对应语言若文件名中的语言代码未在配置中声明构建会报错。第 5 步添加content/categories.zh.json例如{ 软件: software, 电影: film }完成以上步骤后站点即同时支持英文与中文。由于default_language为en访问{base_url}看到英文版访问{base_url}/zh看到中文版。Zola 会把翻译内容输出到{base_url}/{code}/路径下除非页面在 front matter 中显式指定了path。另外一个页面可以同时存在于两种语言中也可以只存在于其中一种语言且不要求页面必须提供默认语言版本。值得一提的是Zola 官方文档还提示中文与日文搜索索引默认未包含如需支持需使用cargo build --features indexing-ja --features indexing-zh编译且中文索引会使二进制体积增加约 5 MB、日文索引约增加 70 MB因字典体积庞大。这属于多语言站点规划时可参考的权衡点。导航菜单与区块menu_items 的两种形态Papaya 的导航菜单由config.toml中的menu_items列表构建例如[extra] menu_items [ { name projects, url $LANG_BASE_URL/projects, show_recent true, recent_items 3, recent_trans_key recent_projects, more_trans_key more_projects }, { name blog, url $LANG_BASE_URL/blog, show_recent true, recent_items 3, recent_trans_key recent_blog_posts, more_trans_key more_blog_posts }, { name tags, url $LANG_BASE_URL/tags }, { name about, url $LANG_BASE_URL/about }, ]一个menu_item有两种形态指向区块section的链接可选择性配置为在首页展示该区块最近发布的条目指向任意 URL 的链接简单的外部或站内链接。配置区块型菜单项在 Zola 中每当content目录或其子目录内存在_index.md时就会创建一个区块见官方文档 docs/content/documentation/content/section.md。Papaya 默认有两个区块projects与blog你完全可以新增或改名区块。例如新增一个名为Diary日记的区块在content/下创建目录diary在content/diary/内创建_index.md title Diary render true # diary will use blog.html for its template template blog.html 这里的template与render正是 Zola 区块 front matter 的标准字段components/content/src/front_matter/section.rs 定义了区块可指定渲染模板template默认section.html、是否渲染render默认true、页面模板page_template等Papaya 让日记区块复用blog.html模板实现同名但独立的博客区块。在config.toml的[extra]下把该区块加入menu_items[extra] menu_items [ ... { name diary, url $LANG_BASE_URL/diary } ]在[languages.code.translations]下添加区块名称的翻译键[languages] [languages.en] [languages.en.translations] diary Diary [languages.zh] [languages.zh.translations] diary 日记这样导航菜单中就会出现指向Diary区块的简单超链接。若还想在首页展示Diary区块最近发布的条目需要为菜单项追加四个属性show_recent把该区块的最近条目列表添加到首页recent_items显示最近条目的数量recent_trans_key最近条目列表标题文字的翻译键more_trans_key指向该区块的更多超链接文字的翻译键。示例[extra] menu_items [ ... { name diary, url $LANG_BASE_URL/diary, show_recent true, recent_items 3, recent_trans_key recent_diary, more_trans_key more_diary } ]同时补齐翻译键[languages] [languages.en] [languages.en.translations] diary Diary recent_diary Recent Diaries more_diary More Diaries [languages.zh] [languages.zh.translations] diary 日记 recent_diary 近期日记 more_diary 更多日记完成配置后导航菜单会出现Diary链接首页也会展示来自该区块的三条最近条目。配置 URL 型菜单项如果只想在导航菜单中添加一个简单链接就提供一个带name和url的条目[extra] sections [ ... { name tag, url $LANG_BASE_URL/tags } ]同时必须为链接的name添加翻译键[languages] [languages.en] [languages.en.translations] tag Tag [languages.zh] [langauges.zh.translations] tag 标签URL 中支持两个特殊占位符$BASE_URL会被替换为站点的基础 URL$LANG_BASE_URL会被替换为当前语言的基础 URL多语言站点中各语言站点位于不同路径这也是上面所有示例都使用$LANG_BASE_URL的原因。日期格式按语言定制显示风格Papaya 支持不同语言使用不同的日期格式。只需在每个语言的translations区块中设置date_format值[languages] [languages.en] [languages.en.translations] date_format %e %B %Y [languages.zh] [languages.zh.translations] date_format %Y 年 %m 月 %d 日日期格式化使用 Tera 的标准date过滤器可用格式选项与 chrono crate 文档一致例如%e表示不带前导零的日期数字、%B表示完整月份名、%Y表示四位年份。特色图片让文章与项目更出彩文章与项目页面都可以设置特色图片它显示在页面顶部、正文之前[extra] featured_image image.jpg featured_image_alt A lodge overlooks a forested mountain range.特色图片还可以扩展到视口全宽[extra] featured_image image.jpg featured_image_alt A lodge overlooks a forested mountain range. featured_image_extended truefeatured_image_alt提供无障碍替代文本featured_image_extended true则让横幅图片撑满整个视口宽度适合风景类大图展示。Open Graph 社交分享信息在config.toml中添加[extra.ogp]区块即可指定 Open Graph Protocol 的 locale 与 profile 信息。OGP 让你掌控站点内容在社交媒体平台上的展示方式其属性取值规范以官方 OGP 文档为准。示例[extra.ogp] locale en_US first_name Papaya last_name Tiliqua gender female username tiliquasp通过locale指定内容语言区域如en_US通过first_name/last_name/gender/username提供作者 profile 信息社交平台抓取分享卡片时会读取这些元数据。UtterancesGitHub Issues 驱动的评论系统Utterances 是一个构建在 GitHub Issues 之上的评论组件。启用后Papaya 可以在博客文章下方以 GitHub Issues 形式展示评论。启用步骤按照 utterances 官网指引完成配置在Enable Utterances步骤时把以下键写入config.toml[extra.utterances] enabled true repo yourname/yourrepository # put your repositorys short path here post_map pathname label utterances theme preferred-color-scheme其中repo填写你的仓库短路径用户名/仓库名post_map决定评论与文章页面的映射方式label为 Issues 标签theme设为preferred-color-scheme可跟随访客系统配色自动切换。社交/联系方式链接在config.toml中添加[extra.social]区块可指定社交网络/联系方式账号修改后网站页脚的链接会同步更新[extra.social] email papayatiliqua.sp github papaya linkedin papayatiliqua twitter papayathehisser如需添加其他自定义社交网站可把它们加入other列表[extra.social] other [ { name BTC, font_awesome fa-brands fa-btc, url https://www.bitcoin.com/ } ]font_awesome属性指定 Font Awesome 图标的 class可在 Font Awesome 图标库中查找。注意不同版本的 Font Awesome 包含的图标集合不同可通过修改[extra.cdn]中的 CDN 路径来切换 Font Awesome 版本[extra] [extra.cdn] font_awesome https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0-beta2/css/all.min.css图片嵌入 shortcodeimg() 的完整用法Papaya 内置了一个用于在文章中嵌入图片的 shortcodeimg(path, alt, caption, class, extended_width_pct, quality)可以使用./image-path指定相对于当前 Markdown 文件的图片路径。参数说明参数必填说明path是图片路径支持三种形式完整 URL如https://somesite.com/my-image.jpg、相对于content目录的 Zola 路径如/projects/project-1/my-image.jpg、相对于当前 Markdown 文件的路径如./my-image.jpgalt否图片的替代文本caption否图片说明文字支持文本 / HTML / Tera 模板class否附加到图片上的 CSS 类多个类用空格 分隔quality否JPEG 或 WebP 的编码质量百分比仅在编码 JPEG/WebP 时生效默认值为90extended_width_pct否图片宽度超出默认 figure 宽度的百分比最多扩展到配置的最大像素宽度其中extended_width_pct的取值范围是0.0-1.0-1表示强制等于文档宽度。最大像素宽度可在config.toml中用extra.images.max_width定义默认 2500px。为什么推荐用 img() 而不是原生 Markdown 图片相比常规 Markdown/HTML 图片嵌入这个 shortcode 的优势在于图片会自动调整尺寸以获得最佳性能底层调用的是 Zola 的图片处理函数见官方文档 docs/content/documentation/content/image-processing/index.md图片与说明文字自带预设样式图片宽度可以扩展到超出文档宽度见下文扩展宽度图片省去大量 HTML/CSS 样板代码。从源码层面看Zola 的resize_image函数实现在 components/templates/src/functions/images.rs它支持path、width、height、op默认fill、format默认auto、quality、speed、filter默认lanczos3等参数通过search_for_file依次在项目根目录、static、content、public、themes/当前主题/static中查找图片。处理后的图片输出到static/processed_images/子目录文件名由函数参数的哈希决定——因此相同参数下图片只需处理一次后续构建直接复用缓存该机制同样在 components/templates/src/functions/images.rs 的测试用例中得到验证例如/gutenberg.jpg、content/gutenberg.jpg、/content/gutenberg.jpg三种写法解析结果一致。值得注意的差异点Papaya 的img()shortcode 将quality默认值设为90主题层默认而 Zola 内置resize_image的 JPEG 默认质量为75JPEG 范围 1-100WebP 默认无损编码AVIF 默认 80。因此在使用 Papaya 主题时若不显式传quality会以主题的默认值90为准。扩展宽度图片Extended width images通过imgshortcode 嵌入的图片可以配置为超出文档宽度显示这对展示宽幅/横向高分辨率图片尤其友好。默认情况下用imgshortcode 嵌入的图片会作为带默认边距的figure插入{{/* img(pathimage.jpg, altA very cute leopard gecko., captionA very cute leopard gecko. Default sizing.) */}}借助extended_width_pct参数可以指定图片在默认 figure 宽度基础上向外扩展的百分比上限是你配置的最大图片宽度config.extra.images.max_width默认 2500px。extended_width_pct0.1示例{{/* img(pathimage.jpg, altA very cute leopard gecko., captionA very cute leopard gecko. extended_width_pct0.1, extended_width_pct0.1) */}}此时图片以比默认宽度大 10% 的宽度显示并保持原始宽高比。更宽的示例extended_width_pct0.2{{/* img(pathimage.jpg, altA very cute leopard gecko., captionA very cute leopard gecko. extended_width_pct0.2, extended_width_pct0.2) */}}图片会按需提升分辨率直到达到配置的最大图片宽度并在网页上显示到视口最大宽度为止。还可以通过把extended_width_pct设为-1强制图片宽度与文档宽度一致{{/* img(pathimage.jpg, altA very cute leopard gecko., captionA very cute leopard gecko. extended_width_pct-1, extended_width_pct-1) */}}三种取值默认、0.1、0.2、-1覆盖了从标准宽度到超出文档宽度再到贴满文档宽度的完整布局需求配合max_width上限设置可以在保证清晰度的同时避免超大图片拖慢页面。为什么叫 Papaya —— 正如作者在文档末尾给出的答案Papaya 的名字来自一条可爱的豹纹守宫leopard gecko这也是主题文档中反复出现的示例图片主角一个轻松有趣的命名注脚。小结Papaya 用一套简洁的config.toml配置把博客、项目展示、分类法、多语言、明暗模式、社交分享与 GitHub 生态Star 计数、Issues 评论串在一起而它的图像处理与多语言能力都直接建立在 Zola 内置的resize_image/get_image_metadata函数与语言配置体系之上。理解 Papaya 的配置项本质上也是理解 Zola 分类法、区块section与多语言机制的一次实战演练——无论是开箱即用地搭建个人博客还是以它为模板定制自己的 Zola 主题上文从安装、分类、多语言到图片 shortcode 的完整路径都可以直接照做。更多底层细节可继续查阅本仓库的 components/templates/src/functions/images.rs、components/config/src/config/languages.rs 以及官方文档 docs/content/documentation/content/image-processing/index.md 与 docs/content/documentation/content/multilingual.md。【免费下载链接】zolaA fast static site generator in a single binary with everything built-in. https://www.getzola.org项目地址: https://gitcode.com/GitHub_Trending/zo/zola创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考