PaperUI

基于 Hugo PaperMod 的二次开发实践：PaperUI 主题的技术实现分享

写在前面本文分享一个个人技术项目：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 + PaperUI 配置文件逐行详解

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 首页最核心的配置，也是最容易理解错的地方。先看模板源码： ...

PaperUI：一个更懂中文博客的 Hugo 主题

如果你正在使用 Hugo 搭建个人博客，一定听说过 PaperMod —— 它是 Hugo 生态中最受欢迎的主题之一，GitHub 上拥有超过 15,000 个 Star。PaperMod 以简洁、快速、轻量著称，但它的设计偏向英文博客场景，对中文用户来说还有一些可以改进的空间。 PaperUI 正是在 PaperMod 的基础上，针对中文博客的实际需求进行深度定制的优化版本。它不是重新造轮子，而是站在巨人的肩膀上，让轮子滚得更顺畅。 PaperUI 的定位 PaperUI 保留了 PaperMod 的全部核心优势 —— 极快的构建速度、完善的 SEO 支持、响应式布局、深色/浅色模式切换 —— 同时增加了以下特性：首页轮播系统：支持 16:9 主轮播图 + 正方形卡片 + 竖版图片的三栏展示双栏布局：首页和内页均可启用侧边栏，展示分类、标签、搜索等小部件彩色标签系统：8 色循环配色，让标签和分类视觉更丰富搜索增强：首页侧边栏搜索框 + 搜索模态框 + Ctrl+K 快捷键移动端优化：汉堡菜单 + 侧滑导航，移动端自动隐藏侧边栏中文深度本地化：面包屑、页脚、存档格式等全部中文化 LLM 友好：内置 llms.txt 模板，方便 AI 搜索引擎索引为什么叫 PaperUI？ Paper 代表它源自 PaperMod 的设计基因 —— 像纸张一样干净、纯粹；UI 则强调在用户界面和交互体验上的改进。两个词合在一起，表达了在保持简洁本质的同时，追求更好的用户界面体验。技术栈 PaperUI 基于 Hugo v0.146.0+ 开发，前端使用纯 CSS 变量实现主题定制，JavaScript 仅用于必要的交互（搜索、轮播、主题切换），不引入任何第三方前端框架。构建后的页面体积极小，首屏加载速度飞快。 ...

PaperMod 为什么是 Hugo 社区最受欢迎的主题

在 Hugo 官方主题库中，PaperMod 长期占据着最受欢迎的位置。截至 2026 年，它在 GitHub 上的 Star 数超过 15,000，被数万个个人博客和文档站点使用。这篇文章来分析它为什么能获得如此广泛认可。设计哲学：做减法而非加法 PaperMod 的核心设计理念是"克制"。它不追求功能的大而全，而是专注于把博客最核心的需求做好：阅读体验优先：单栏布局，宽窄适中的内容区域（约 720px），配合合适的字体大小和行高，让长文阅读不疲劳视觉噪音最小化：没有花哨的动画、没有多余的装饰元素，让读者的注意力集中在内容上主题切换自然：支持自动跟随系统、手动切换浅色/深色模式，过渡平滑性能：快得几乎无感 PaperMod 在性能方面做了大量细致的工作：零外部依赖：不引入任何第三方 CSS 框架或 JS 库（搜索功能可选 fuse.js） CSS 变量驱动：主题色、间距、字体等全部使用 CSS 变量，方便定制且不会产生冗余样式按需加载：搜索 JS、评论系统等仅在需要时加载资源最小化：Hugo 内置的 asset pipeline 自动压缩和指纹化静态资源实际测试中，PaperMod 构建的站点 Lighthouse 得分通常在 95-100 分之间。 SEO：开箱即用的搜索引擎优化 PaperMod 内置了完善的 SEO 支持：Open Graph、Twitter Cards、JSON-LD 结构化数据、Canonical URL、robots.txt、RSS 等。PaperUI 完全继承了这些能力。详细的 SEO 优化实践请参考 PaperUI 的 SEO 优化实践指南。多语言支持 PaperMod 内置了 46 种语言的翻译文件，从英语、中文到阿拉伯语（RTL）都有覆盖。多语言站点的切换体验流畅自然。开发者友好配置驱动：几乎所有功能都通过 hugo.toml 参数控制，不需要修改模板代码扩展点丰富：extend_head.html、extend_footer.html 等扩展模板，可以无侵入地添加自定义代码完善的文档：官方 Wiki 覆盖了从安装到高级定制的方方面面活跃的社区 PaperMod 的 GitHub Issues 和 Discussions 非常活跃，作者 Aditya Telange 响应迅速。大量用户贡献了使用案例、配置技巧和问题解答，形成了良好的社区生态。 ...

为什么我选择在 PaperMod 基础上开发 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 新增功能全面解析

上一篇文章聊了为什么要做 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 侧边栏的每个小部件都有明确的用途： ...

PaperUI 安装与快速上手指南

这篇文章将带你从零开始，在 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 完整配置指南与参数说明

这篇文章是 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 模式。 ...

PaperUI 的 SEO 优化实践指南

SEO（搜索引擎优化）对技术博客来说至关重要 —— 好的内容需要被看见。PaperUI 继承了 PaperMod 完善的 SEO 体系，并在此基础上做了一些增强。这篇文章分享具体的优化实践。 PaperUI 内置的 SEO 能力 1. Open Graph 标签每篇文章自动生成完整的 OG 标签，这是社交媒体分享时显示卡片的基础： <meta property="og:title" content="文章标题" /> <meta property="og:description" content="文章摘要" /> <meta property="og:type" content="article" /> <meta property="og:url" content="https://你的域名/posts/xxx/" /> <meta property="og:image" content="https://你的域名/images/cover.jpg" /> <meta property="og:site_name" content="站点名称" /> 2. Twitter Cards 同样自动生成 Twitter 分享卡片： <meta name="twitter:card" content="summary_large_image" /> <meta name="twitter:title" content="文章标题" /> <meta name="twitter:description" content="文章摘要" /> 3. JSON-LD 结构化数据这是对搜索引擎最重要的部分。PaperUI 自动生成 Schema.org 的结构化数据： { "@context": "https://schema.org", "@type": "BlogPosting", "headline": "文章标题", "datePublished": "2026-05-24T00:00:00+08:00", "description": "文章摘要", "author": { "@type": "Person", "name": "作者名" } } JSON-LD 帮助 Google 等搜索引擎理解你的内容结构，可能在搜索结果中展示富文本片段（Rich Snippets）。 4. Canonical URL 避免重复内容被搜索引擎惩罚： ...

PaperUI 博客部署到生产环境的完整方案

上一篇聊了 SEO 优化，这篇我们讲部署 —— 把本地写好的 PaperUI 博客发布到互联网上。构建静态文件在部署之前，先生成静态文件： # 清理旧文件并重新构建（--cleanDestinationDir 自动清理废弃文件） hugo --minify --cleanDestinationDir --minify 参数会压缩 HTML、CSS、JS，减小文件体积。构建后的文件在 public/ 目录中。方案一：GitHub Pages（免费）适用场景使用 GitHub 管理博客源代码免费托管自定义域名支持步骤 1. 创建部署仓库在 GitHub 上创建用户名.github.io 仓库（用于用户/组织站点）。 2. 推送代码 cd my-blog git init git remote add origin https://github.com/用户名/用户名.github.io.git git add . git commit -m "初始化博客" git push -u origin main 3. 配置 GitHub Actions 创建 .github/workflows/deploy.yml： name: Deploy Hugo site on: push: branches: [main] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: submodules: true fetch-depth: 0 - name: Setup Hugo uses: peaceiris/actions-hugo@v3 with: hugo-version: '0.146.0' extended: true - name: Build run: hugo --minify --cleanDestinationDir - name: Deploy uses: peaceiris/actions-gh-pages@v4 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./public 4. 设置 GitHub Pages ...