Demius Theme Config Reference
2026/9/13大约 8 分钟
Demius Theme Config Reference
这份文档是 hugo.toml 的开发参考，不追求逐行复制配置文件，而是按模块整理出最常用、最关键、最容易互相影响的参数。
配套阅读：
- 架构与维护入口见 development-guide.md
- 各功能使用说明见 README.md 中的专题文档
1. 配置文件定位
主配置文件：
它当前承担了四类职责：
- Hugo 站点基础配置
- 菜单与输出配置
- 主题功能参数
- 第三方服务接入参数
当前文件已经比较大。继续扩展时建议优先复用现有分组，不要新增语义重复的参数。
2. 站点基础配置
2.1 站点与语言
关键参数：
baseURLlanguageCodetitlethemedefaultContentLanguagehasCJKLanguage
说明：
baseURL影响 canonical、RSS、链接输出和部分脚本拼接- 中文站点建议保留
hasCJKLanguage = true
2.2 RSS、分页、输出
关键参数：
copyrightrssLimit[pagination].pagerSize[outputs].home
说明：
- 本地搜索依赖
home = ["HTML", "RSS", "JSON"]里的JSON - 单列和双列首页会受
pagerSize影响 - 三列瀑布流当前不走分页
2.3 永久链接与分类法
关键参数：
[permalinks].posts[taxonomies].tag[taxonomies].category
说明：
- 当前文章固定输出到
/posts/:slug.html - 如果要修改文章 URL 规则，要连带检查友链、分享、SEO、旧链接兼容
3. 菜单配置
配置区块：
[menu][[menu.main]][menu.main.params]
常用字段：
nameurlweightidentifierparentparams.icon
说明：
- 主题导航支持多级菜单
identifier用于作为父级节点引用parent用于挂载二级或三级菜单- 菜单图标依赖
params.icon
对应模板：
4. 全站主题参数
配置入口：
[params]
4.1 基础信息与全局开关
关键参数：
authordescriptiondarkModepjaxstickyHeadertocOpengrayscaleMode
说明：
author和description会进入 meta、版权区、部分侧栏pjax会影响几乎所有前端模块初始化方式stickyHeader和顶部公告、移动端导航行为有关
4.2 首页布局
关键参数：
homeColumnsmainSectionssummaryLength
说明：
homeColumns = 1/2/3对应三种首页引擎mainSections控制首页文章来源summaryLength控制列表摘要截断长度
对应模板：
themes/demius/layouts/index.htmlthemes/demius/layouts/partials/main/engine-1.htmlthemes/demius/layouts/partials/main/engine-2.htmlthemes/demius/layouts/partials/main/engine-3.html
4.3 透明背景模式
关键参数：
postCardTransparentModepostCardTransparentTypepostPageTransparentModepostPageTransparentTypeparams.aside.transparentModeparams.carousel.transparentModeparams.carousel.transparentType
说明：
- 这组参数控制首页卡片、文章页、侧栏、轮播图的透明/毛玻璃表现
Type通常为glass或full
建议：
- 继续扩展透明样式时保持命名一致，不要再引入新的模式命名
5. 字体、图片与背景
5.1 字体
配置区块：
[params.font]
关键参数：
enabletypeonlineUrlfontFamilylocalNamelocalPathlocalFormat
说明：
type = "online"时走在线字体type = "local"时走本地字体文件- 本地字体文件通常放在
static/fonts或主题静态资源目录
5.2 图片
配置区块：
[params.images]
关键参数：
avatardefaultCoverfallbackImagefaviconlogo
说明：
- 这些是多个模板和组件共用的默认资源位
- 替换资源时尽量优先改这里，不要到模板里硬编码路径
5.3 背景图
配置区块：
[params.background][params.background.site]
关键参数：
effect_modesite.enablesite.imagesite.blursite.brightnesssite.opacity
说明：
effect_mode是三栏容器背景表现site.*是整站背景图- 首页大图
mode2可选择覆盖整站背景图
5.4 粒子特效
配置区块：
[params.particleEffect]
关键参数：
enablecountcolorlineColorlineDistancespeedradiusinteractivezIndex
建议：
- 这个功能明显吃性能，默认值不建议继续上调
6. 首页与视觉模块
6.1 首页大图
配置区块：
[params.homeBigImage][params.homeBigImage.mode1][params.homeBigImage.mode2]
关键参数：
enablemodetitlesubtitlemode1.backgroundImagemode1.arrowAnimationmode1.scrollSpeedmode1.cardAnimationmode2.fullScreenmode2.overlayOpacitymode2.customBackgroundImagemode2.typewriterEnablemode2.typewriterSpeedmode2.typewriterDelaymode2.typewriterCursormode2.typewriterLoop
说明：
mode1是中间栏大图mode2是整屏欢迎区- 打字机效果只对
mode2副标题生效
6.2 轮播图
配置区块：
[params.carousel]
关键参数：
enableheightautoplayintervaldirectionshowOnPagestransparentModetransparentType
数据源：
说明：
- 轮播项本身不再写在
hugo.toml - 这里只控制行为和显示模式
6.3 浮动按钮
配置区块：
[params.floatButtons]
关键参数：
positionshowBackToTopshowThemeToggleshowSidebarToggle
7. 文章页与内容增强
7.1 文章互动
配置区块：
[params.postActions.like][params.postActions.share]
关键参数：
like.enablelike.iconlike.textlike.likedTextshare.enableshare.iconshare.textshare.platforms
说明：
- 分享平台可自定义 URL 模板
platforms中的{url}、{title}、{description}会在前端替换
7.2 打赏
配置区块：
[params.reward]
关键参数：
enablebuttonTexttitlewechatalipay
7.3 视频
配置区块：
[params.video]
关键参数：
enable
7.4 置顶样式
配置区块：
[params.pinned]
关键参数：
iconColortextColoriconColorDarktextColorDark
说明：
- 这里只控制置顶徽章视觉
- 是否置顶仍然由文章 front matter 中的
pinned控制
7.5 加密
配置区块：
[params.encryption]
关键参数：
enablefullHintpartialHintwrongPasswordHintpopupTextColorpopupBackgroundColorpopupBackgroundImagepartialPopupTextColorpartialPopupBackgroundColorpartialPopupBackgroundImage
说明：
- 全文加密和局部加密分别有独立弹窗样式
- 真正密码内容通常来自文章 front matter 或短代码参数
7.6 链接卡片与跳转中转
配置区块：
[params.linkCard][params.linkRedirect]
关键参数：
linkCard.enablelinkCard.defaultTypelinkCard.openInNewTablinkCard.showArticleInfolinkCard.showArticleDatelinkCard.showArticleSummarylinkCard.showUrllinkCard.internalIconlinkCard.externalIconlinkRedirect.enablelinkRedirect.pagePathlinkRedirect.countdownlinkRedirect.showCountdownlinkRedirect.showButtonlinkRedirect.safeMessagelinkRedirect.processShortcodeLinkslinkRedirect.skipPatternslinkRedirect.pageWhitelistlinkRedirect.elementWhitelistlinkRedirect.safeWhitelist
说明：
linkCard主要用于短代码展示linkRedirect主要用于外链中转页和安全提示
8. 侧栏系统
配置入口：
[params.aside]
这是当前最复杂的一组配置。
8.1 全局行为
关键参数：
unifiedModetransparentModewideModeleftright
说明：
left、right控制组件顺序wideMode可用false/"normal"、"medium"、true/"wide"
8.2 组件开关
常见字段：
showAuthorshowTocshowTagsshowRecentshowCategoriesshowArchiveshowPopularPostsshowRelatedPostsshowSocialMediashowAdvertisementshowAnnouncementshowLifeTimeshowDataStatsshowHitokotoshowVisitorInfoshowRandomImageshowMusic
说明：
- 组件是否出现，通常先受
showXxx控制 - 某些组件还会有自身的
enabled或enable字段
8.3 数量控制
关键参数：
popularCountrecentCountrelatedCounttagsCount
8.4 侧栏组件通用样式字段
很多组件都重复使用同一套背景字段：
enableBackgroundbackgroundImagebackgroundColorbackgroundSizebackgroundPositionbackgroundRepeattextColortextShadowoverlayColorborderRadius
涉及的典型组件：
authorannouncementlifeTimedataStatshitokotorandomImagevisitorInfomusicsocial-Mediarecent-Postsrelated-Poststoctagscategoriesadvertisementpopular-PostsrecentCommentsarchiveseriesPosts
建议：
- 后续如果继续维护，优先考虑把这套字段抽象成统一 schema 文档
- 新增组件时尽量复用这套字段，避免每个 widget 发明一套新的背景参数
8.5 侧栏中特别重要的组件
aside.toc
关键参数：
mobilePopupMode
说明：
- 控制移动端弹出目录时是只弹目录还是整块右侧栏
aside.dataStats
关键参数：
showPostsCountshowTagsCountshowCategoriesCountshowRunningYearshowTotalWordsshowResponseTimeshowLastUpdateshowCommentCount
aside.hitokoto
关键参数：
enabledapiTypeshowFromnsmaoApiKeynsmaoApiUrl
aside.randomImage
关键参数：
enabledapisrefreshIntervalshowRefreshButton
aside.visitorInfo
关键参数：
enabledapiKeycustomLatcustomLngsiteNamefontColorshowFriendsLinkstravellingsLinkblogsClubLink
aside.music
关键参数：
enableditems
每个 items 条目常见字段：
servertypeidbadgeautoplaylistFoldedurlnameartistcover
aside.archive
关键参数：
defaultOpenCurrentYeardefaultOpenCurrentMonthshowStatsgroupBy
aside.seriesPosts
关键参数：
enableenableCarouselcarouselIntervalseries
每个 series 条目常见字段：
namedescriptionslugs
9. 侧栏外的内容组件
9.1 相关文章
配置区块：
[related][[related.indices]]
关键参数：
thresholdincludeNewertoLowerindices[].nameindices[].weight
说明：
- 当前主要通过
tags与categories计算相关文章
9.2 公告与广告
配置区块：
[params.advertisement][params.announcement][params.announcement.link]
关键参数：
- 广告：
enable、title、description、image、link - 公告：
enable、allowHtml、important、title、content、date - 公告链接：
enable、text、url
9.3 社交与联系信息
配置区块：
[params.contact][params.social][params.social.custom]
关键参数：
contact.emailsocial.linkssocial.custom.enablesocial.custom.titlesocial.custom.content
10. 评论、弹幕与统计
10.1 评论系统
配置区块：
[params.comment][params.comment.artalk]
关键参数：
comment.enablecomment.systemartalk.serverartalk.siteartalk.placeholderartalk.darkModeartalk.localeartalk.gravatarartalk.pageSizeartalk.emoticonsartalk.heightLimitartalk.useLocalartalk.cdnartalk.cdnIndex
说明：
- 当前主题重点适配的是 Artalk
useLocal = true时优先读取本地资源，否则走指定 CDN
10.2 弹幕
配置区块：
[params.danmaku]
关键参数：
enablescopespeedfontSizeopacitymaxCountupdateIntervalshowAvatarshowTimelooprandomPositioncolorfulantiOverlap
10.3 Umami 统计
配置区块：
[params.analytics.umami][params.data]
关键参数：
umami.enableumami.scriptUrlumami.websiteIdumami.showInDataPageumami.apiUrlumami.useForPostViewsdata.showTotalWordsdata.showTotalPostsdata.showResponseTimedata.showLastUpdatedata.showCommentCount
说明：
- Umami 既用于数据页，也可用于文章浏览量
- 数据页部分统计项也会受
params.data控制
11. 页面型功能配置
11.1 分类 / 标签页
配置区块：
[params.taxonomy]
关键参数：
colorModecustomColor
11.2 友链页
配置区块：
[params.links]
关键参数：
cardColorModecardCustomColor
数据源：
11.3 网友圈页
配置区块：
[params.friendsCircle][[params.friendsCircle.groupArticleDays]]
关键参数：
preGeneratedJsonUrlinitialDisplayCountloadMoreCountcardColorModecardCustomColortabColorModetabCustomColordefaultArticleDaysgroupArticleDaysrssTimeoutrssCacheTime
说明：
- 页面展示依赖预生成 JSON
- 分组时间规则支持全局默认值和分组覆盖值
11.4 书单页
配置区块：
[params.booklist]
关键参数：
cardColorModecardCustomColor
11.5 音乐与悬浮音乐播放器
配置区块：
[params.music][params.floatMusicPlayer]
关键参数：
music.metingApifloatMusicPlayer.enabledfloatMusicPlayer.sectionTitlefloatMusicPlayer.autoplayfloatMusicPlayer.listFolded
说明：
[params.music]主要是 MetingJS 全局支持[params.floatMusicPlayer]是独立悬浮播放器- 侧栏音乐组件配置在
params.aside.music
11.6 页脚
配置区块：
[params.footer][params.footer.runningTime]
关键参数：
customrunningTime.enablerunningTime.startDaterunningTime.prefix
11.7 弹窗公告
配置区块：
[params.popup]
关键参数：
enablezIndex
11.8 顶部公告栏
配置区块：
[params.topAnnouncement][params.topAnnouncement.custom][params.topAnnouncement.shuoshuo]
关键参数：
enablemodeheightstickyWithHeadercustom.textcustom.linkcustom.linkTextshuoshuo.apiUrlshuoshuo.countshuoshuo.intervalshuoshuo.transitionDurationshuoshuo.showAvatarshuoshuo.showTimeshuoshuo.cacheDurationshuoshuo.clickableshuoshuo.shuoshuoPageUrl
12. 内容渲染
配置区块：
[markup.tableOfContents]
关键参数：
startLevelendLevelordered
说明：
- 目录生成层级会直接影响文章页 TOC 与移动端目录弹层
13. 维护建议
13.1 新增参数前先检查
- 是否已有同义参数
- 是否已有对应的页面/组件分组
- 是否应该放到
data/*.yaml而不是hugo.toml
13.2 参数命名建议
- 布尔值使用
enable或enabled其一，后续尽量统一 - 同类视觉参数沿用
background*、textColor、overlayColor、borderRadius - 页面型配置统一以页面名作为分组入口
13.3 长期建议
未来若继续扩展，建议把 hugo.toml 拆分到 config/_default/，至少拆成：
hugo.toml或site.tomlmenus.tomlparams-core.tomlparams-aside.tomlparams-pages.tomlservices.toml
这样会比继续在单文件里堆参数更可维护。