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

这篇文章将带你从零开始，在 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 方式，更简单直观。 ...