写在前面 本文分享一个个人技术项目：PaperUI —— 基于 Hugo 社区主题 PaperMod 进行的二次开发实践。项目针对个人中文博客的使用场景，添加了一些自用的功能和调整。 PaperMod 是 Hugo 生态中非常优秀的主题，作者 Aditya Telange 和社区贡献者做了大量出色的工作。PaperUI 只是在 PaperMod 的基础上做了一些个人化的补充，并非替代或竞争关系。 一、为什么选择基于 PaperMod 二次开发 1.1 PaperMod 的优势 选择 PaperMod 作为基础，主要看中以下几点： 零外部依赖，性能表现出色 CSS 变量驱动的主题系统，便于定制和覆盖 完善的 SEO 支持（Open Graph、Twitter Cards、JSON-LD） 多语言支持，内置 46 种语言翻译 社区成熟，文档完善，问题排查方便 1.2 二次开发的出发点 在使用过程中，个人有一些额外的需求： 首页希望有更丰富的内容展示形式 想增加侧边栏放置分类、标签等导航元素 移动端导航体验想做一些调整 部分 UI 文字想适配中文语境 这些需求属于个人偏好，并非 PaperMod 的不足。PaperMod 面向全球用户，设计上追求简洁通用，这是它的设计选择。 1.3 开发原则 保持兼容：PaperMod 用户的配置文件切换到 PaperUI 后应基本可用 性能优先：新功能不显著增加页面加载体积 增量修改：尽可能通过参数控制，不破坏原有功能 可回退：新功能都是可选的，不配置就不启用 二、主要功能的技术实现 2.1 首页轮播布局 在首页增加了一个三栏展示区，通过 Hugo 模板和 CSS Grid 实现： ...

hugo.toml 是 Hugo 站点的核心配置文件。本文以本博客当前使用的配置为基础，结合 PaperUI 主题的模板源码，逐段说明每个配置项的实际作用。 如果你只需要快速查阅所有配置参数，推荐先看 PaperUI 完整配置指南与参数说明，那是更紧凑的参考手册。 站点基础 baseURL = 'https://paperui.newmt.fun/' title = '新墨韬' theme = 'PaperUI' defaultContentLanguage = 'zh-cn' enableRobotsTXT = true enableEmoji = true 参数 说明 baseURL 站点域名，上线前必须改成真实域名。末尾 / 不要漏。影响所有链接、RSS、sitemap title 站点标题，出现在浏览器标签页、RSS 标题、OG 标签中 theme 主题文件夹名，对应 themes/PaperUI/ defaultContentLanguage 默认语言代码，需与下方 [languages.zh-cn] 的 key 一致 enableRobotsTXT true 自动生成 /robots.txt enableEmoji true 允许 Markdown 中使用 :smile: 等 Emoji 短码 输出格式 [outputs] home = ['HTML', 'RSS', 'JSON'] HTML：网页 RSS：订阅源（/index.xml） JSON：搜索索引，PaperUI 的搜索功能依赖此项，不要删 [params] 主题参数 环境与 SEO [params] env = 'production' description = '新墨韬 - 个人技术博客' keywords = ['博客', 'Hugo', 'PaperMod', '技术'] 参数 说明 env production 启用 CSS/JS 压缩；本地开发临时改 development description 站点描述，出现在 <meta name="description"> 和搜索结果摘要中 keywords 全局关键词，对现代搜索引擎权重不高但仍有参考意义 外观控制 defaultTheme = 'auto' disableThemeToggle = false disableScrollToTop = false 参数 值 说明 defaultTheme auto 跟随系统偏好，也可设为 light 或 dark disableThemeToggle false 保留深色/浅色切换按钮 disableScrollToTop false 保留"回到顶部"按钮 文章显示开关 ShowReadingTime = true ShowWordCount = true ShowShareButtons = false ShowPostNavLinks = true ShowBreadCrumbs = false ShowCodeCopyButtons = true ShowToc = true 参数 推荐 说明 ShowReadingTime true 估算阅读时间 ShowWordCount true 显示字数统计 ShowCodeCopyButtons true 技术博客强烈推荐，代码块右上角复制按钮 ShowToc true 文章右侧目录，长文章导航 ShowPostNavLinks true 文章底部"上一篇/下一篇" ShowShareButtons false 社交分享按钮，不需要就关 ShowBreadCrumbs false 面包屑导航，扁平博客结构意义不大 列表与分页 ShowPageNums = true ShowRssButtonInSectionTermList = true ShowAllPagesInArchive = false ShowFullTextinRSS = false homePostCount = 8 参数 说明 ShowPageNums 分页显示页码 ShowRssButtonInSectionTermList 分类/标签页显示 RSS 订阅按钮 ShowAllPagesInArchive false 归档页只显示文章；true 会包含所有页面 ShowFullTextinRSS false RSS 只输出摘要；true 输出全文 homePostCount 首页显示的文章数量，建议 8~10 首页展示：homeInfoParams + homeCarousel 这是 PaperUI 首页最核心的配置，也是最容易理解错的地方。先看模板源码： ...

很多朋友问我：PaperMod 已经很优秀了，为什么要再做二次开发？这篇文章聊聊我的思考过程和技术决策。 出发点：解决实际痛点 在使用 PaperMod 搭建中文博客的过程中，我遇到了几个实际的问题： 1. 首页太"空"了 PaperMod 的首页默认只有标题、简介和一列文章列表。对于内容型博客来说，首页是流量入口，需要承载更多导航和发现功能。 2. 内容发现路径单一 在标准 PaperMod 中，读者找到感兴趣内容的路径基本只有两条：按时间线浏览文章列表，或者使用搜索。缺少按分类浏览、按标签筛选、随机推荐等发现方式。 3. 中文适配不够精细 这不是 PaperMod 的问题 —— 它面向全球用户，不可能为每种语言做深度优化。但作为中文博客，我需要页脚文案中文化、存档月份显示"1月"而非"January"、面包屑导航的中文语义等细节。 4. 移动端体验可以更好 PaperMod 在桌面端体验很好，但移动端的导航和布局还有优化空间。 技术决策：为什么是"改进"而非"重写" 面对这些问题，我有两个选择： 从零写一个新主题：完全自由，但需要重新实现 PaperMod 已经做得很好的部分（SEO、多语言、性能优化等），工作量大且容易遗漏 在 PaperMod 基础上定制：继承其核心优势，专注做增量改进 我选择了后者，原因很简单： 不要重新发明轮子，除非你确定能做出更好的轮子。 PaperMod 在性能、SEO、可访问性方面的积累是经过数千个站点验证的。在这些基础上做增量优化，比从零开始更有价值。 开发原则 在开发过程中，我遵循了几个原则： 不破坏原有配置：PaperMod 用户迁移到 PaperUI，只需改 theme = 'PaperUI' 并添加新参数即可 性能不退化：新增功能不能显著增加页面体积和加载时间 渐进增强：新功能都是可选的，不配置就不加载相关代码 保持可升级性：目录结构与 PaperMod 保持一致，方便合并上游更新 PaperUI 新增了哪些功能 关于 PaperUI 具体增加了哪些功能模块、做了哪些中文化改进，请参见： PaperUI：一个更懂中文博客的 Hugo 主题 开源与合作 PaperUI 在 GitHub 上以 MIT 协议开源（与 PaperMod 保持一致），欢迎所有人使用、修改和贡献。项目地址： github.com/scenlinx/PaperUI ...

上一篇文章聊了为什么要做 PaperUI，这篇我们逐一看看每个新增功能的设计思路和使用效果。 1. 首页轮播系统 功能说明 PaperUI 新增了 homeCarousel 配置项，可以在首页展示三栏图片导航： [params.homeCarousel] slides = [ { image = '/images/hero-1.webp', url = '/posts/paperui-introduction/' }, { image = '/images/hero-2.webp', url = '/posts/papermod-advantages/' }, { image = '/images/hero-3.webp', url = '/posts/git-guide/' }, ] middle = [ { image = '/images/square-1.webp', url = '/posts/python-tips/' }, { image = '/images/square-2.webp', url = '/posts/linux-commands/' }, ] right = { image = '/images/portrait-1.webp', url = '/about/' } 设计细节 左侧主轮播：16:9 比例，自动播放（4 秒间隔），支持前后导航按钮和指示点 中部卡片：1:1 正方形图片，适合展示方形封面 右侧竖图：3:4 比例，适合展示竖版图片或头像 交互细节：鼠标悬停暂停轮播，焦点状态可访问，所有图片点击跳转到对应链接 响应式：移动端自动切换为单列堆叠布局 这个设计灵感来自传统杂志的封面排版 —— 大图吸引注意力，小图提供更多入口。 2. 双栏布局系统 首页双栏 首页采用 home-layout 双栏布局： 左侧（主内容区）：文章列表 右侧（侧边栏）：搜索框、分类列表、标签云、随机文章、近期文章 [params] # 首页显示文章数量 homePostCount = 8 侧边栏的每个小部件都有明确的用途： ...

这篇文章将带你从零开始，在 5 分钟内完成 PaperUI 的安装和基础配置。 前置要求 Hugo v0.146.0 或更高版本（推荐使用最新版） Git（用于主题安装） 基础的命令行操作能力 检查 Hugo 版本： hugo version # 应显示: hugo v0.146.0 或更高版本 方式一：Git Submodule 安装（推荐） 这是最传统的安装方式，适合大多数用户： # 1. 创建新站点 hugo new site my-blog cd my-blog # 2. 初始化 Git 仓库 git init # 3. 添加 PaperUI 主题作为子模块 git submodule add https://github.com/scenlinx/PaperUI.git themes/PaperUI # 4. 在配置文件中启用主题 echo "theme = 'PaperUI'" >> hugo.toml 方式二：Hugo Modules 安装 如果你使用 Hugo Modules 管理依赖： # 1. 初始化 Hugo Modules hugo mod init my-blog # 2. 在 hugo.toml 中配置 # theme = 'PaperUI' # 删除或注释掉这行 # 3. 编辑 go.mod 或使用 hugo mod get # 具体配置参见 Hugo Modules 文档 目前推荐使用 Git Submodule 方式，更简单直观。 ...

这篇文章是 PaperUI 主题的完整配置参考手册。你可以把它当作速查表来查阅。 如果你想知道每个参数在模板层面的具体作用逻辑，推荐阅读 Hugo + PaperUI 配置文件逐行详解，它以本博客真实配置为例，结合模板源码进行拆解。 基础站点配置 baseURL = 'https://你的域名.com/' # 站点 URL，上线前务必修改 title = '站点标题' # 显示在浏览器标签页和 header 中 theme = 'PaperUI' # 主题名称 defaultContentLanguage = 'zh-cn' # 默认语言 enableRobotsTXT = true # 自动生成 robots.txt enableEmoji = true # 支持 Emoji 输出格式 [outputs] home = ['HTML', 'RSS', 'JSON'] # 首页输出 HTML、RSS 和搜索索引 JSON 全局参数 [params] env = 'production' # 环境：development 或 production description = '站点描述' # SEO 描述，显示在搜索引擎结果中 keywords = ['博客', 'Hugo'] # SEO 关键词 defaultTheme = 'auto' # 默认主题：auto / dark / light disableThemeToggle = false # 禁用主题切换按钮 disableScrollToTop = false # 禁用回到顶部按钮 # 文章展示相关 ShowReadingTime = true # 显示阅读时间估算 ShowWordCount = true # 显示字数统计 ShowShareButtons = false # 显示分享按钮 ShowPostNavLinks = true # 显示上一篇/下一篇文章链接 ShowBreadCrumbs = false # 显示面包屑导航 ShowCodeCopyButtons = true # 显示代码块复制按钮 ShowToc = true # 显示文章目录（侧边栏） ShowPageNums = true # 分页显示页码 ShowRssButtonInSectionTermList = true # 分类/标签页显示 RSS 按钮 ShowAllPagesInArchive = false # 归档页显示所有文章（不推荐大量文章时开启） ShowFullTextinRSS = false # RSS 中显示全文 homePostCount = 8 # 首页显示文章数量 首页信息 [params.homeInfoParams] Title = '欢迎来到我的博客' # 首页标题 Content = '分享技术和思考' # 首页简介 首页轮播配置 [params.homeCarousel] # 左侧主轮播（16:9 比例） slides = [ { image = '/images/hero-1.webp', url = '/posts/post-1/' }, { image = '/images/hero-2.webp', url = '/posts/post-2/' }, { image = '/images/hero-3.webp', url = '/posts/post-3/' }, ] # 中部正方形卡片（1:1 比例） middle = [ { image = '/images/square-1.webp', url = '/posts/post-4/' }, { image = '/images/square-2.webp', url = '/posts/post-5/' }, ] # 右侧竖版图片（3:4 比例） right = { image = '/images/portrait-1.webp', url = '/about/' } 不配置 homeCarousel 时，首页使用标准的 homeInfoParams 模式。 ...