Demius主题使用文档

主题简介

demius是一款功能丰富的Hugo博客主题，采用现代化的设计风格，支持响应式布局、明暗主题切换、多种布局引擎等特性。

快速开始

1. 安装主题

# 在Hugo站点目录下
git submodule add https://github.com/your-repo/demius.git themes/demius

2. 基础配置

在站点根目录的 hugo.toml 文件中配置：

# 基础配置
baseURL = 'https://your-domain.com'
languageCode = 'zh-CN'
title = '你的博客名称'
theme = 'demius'

# 启用多语言支持
defaultContentLanguage = 'zh'
hasCJKLanguage = true

# 永久链接配置
[permalinks]
  posts = "/posts/:slug.html"

[taxonomies]
  tag = "tags"
  category = "categories"

详细配置说明

站点基础信息

[params]
  author = "你的名字"                      # 网站作者
  description = "网站描述"                # SEO描述
  
  # 布局配置
  homeColumns = 2                         # 首页布局：1=单列, 2=双列
  mainSections = ["posts"]                # 主内容区域
  summaryLength = 120                     # 摘要长度

菜单配置

[menu]
  [[menu.main]]
    name = "首页"
    url = "/"
    weight = 1
    [menu.main.params]
      icon = "/img/icons/home.svg"

  [[menu.main]]
    name = "归档"
    url = "/posts/"
    weight = 2
    [menu.main.params]
      icon = "/img/icons/blog.svg"

  # 多级菜单示例
  [[menu.main]]
    name = "项目"
    identifier = "projects"
    weight = 6

  [[menu.main]]
    name = "Web开发"
    url = "/projects/web/"
    weight = 1
    parent = "projects"

侧边栏配置

[params.aside]
  # 侧栏一体化模式（v2.2.0新增）
  unifiedMode = true  # true=一体化容器，false=分割卡片
  
  # 左侧栏组件
  left = ["author","announcement","recent-Comments","popular-Posts","social-Media","advertisement"]
  
  # 右侧栏组件  
  right = ["toc","related-Posts","tags", "recent-Posts","categories", "archive"]

  # 组件显示控制
  showAuthor = true
  showToc = true
  showTags = true
  showRecent = true
  showCategories = true
  showArchive = true
  showPopularPosts = true
  showRelatedPosts = true
  showSocialMedia = true
  showAdvertisement = true
  showAnnouncement = true

  # 数量控制
  popularCount = 5
  recentCount = 5
  relatedCount = 5
  tagsCount = 20  # 标签云显示数量（0表示全部）

侧栏组件背景配置（v2.7.0+）

所有侧栏组件均支持统一的背景配置参数，默认不启用：

[params.aside.组件名]
  enableBackground = false             # 是否启用背景（默认false）
  backgroundImage = ""                 # 背景图片URL
  backgroundColor = ""                 # 背景色（支持渐变）
  backgroundSize = "cover"             # 背景图尺寸
  backgroundPosition = "center"        # 背景图位置
  backgroundRepeat = "no-repeat"       # 背景图重复
  textColor = ""                       # 文字颜色
  textShadow = false                   # 文字阴影
  overlayColor = ""                    # 遮罩层颜色
  borderRadius = ""                    # 自定义圆角

示例：为热门文章启用渐变背景

[params.aside.popular-Posts]
  enableBackground = true
  backgroundColor = "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
  textColor = "#ffffff"
  textShadow = true

目录组件手机端弹出模式配置（v2.7.6+）

手机端目录按钮支持两种弹出模式，可在配置文件中灵活切换：

[params.aside.toc]
  # 手机端目录按钮弹出内容设置
  mobilePopupMode = "sidebar"  # "sidebar"（弹出整个右侧栏）或 "toc-only"（仅弹出目录）

模式说明：

sidebar（默认）：点击目录按钮弹出整个右侧栏，包含目录、标签、相关文章等所有组件
toc-only：点击目录按钮仅弹出目录内容，专注于目录导航

功能特性：

✅ 配置灵活：可在配置文件中轻松切换
✅ 样式统一：仅目录模式保持与右侧栏相同的位置样式和弹出方式（从右侧滑入）
✅ 交互友好：支持遮罩层关闭、关闭按钮关闭、点击链接自动关闭
✅ 位置一致：仅目录模式从右侧滑入，与右侧栏弹出方式一致

侧栏一体化模式说明

一体化模式（unifiedMode = true）：所有组件整合在一个统一容器中，用细线分割
- 视觉更统一整洁
- 节省屏幕空间
- 减少视觉干扰
分割卡片模式（unifiedMode = false）：每个组件独立显示
- 组件更独立
- 视觉层次分明
- 传统博客风格

详见：侧栏一体化模式使用指南

评论系统配置

[params.comment]
  enable = true
  system = "artalk"

[params.comment.artalk]
  server = "https://your-artalk-server.com"
  site = "your-site-name"
  placeholder = "说点什么吧~"
  useLocal = true  # 使用本地资源

Umami统计配置（v2.4.0新增）

[params.analytics]
  [params.analytics.umami]
    enable = true                          # 是否启用Umami统计
    scriptUrl = "https://umami.demius.tech/script.js"  # Umami统计脚本地址
    websiteId = "your-website-id"          # 网站ID（在Umami后台创建网站后获得）
    showInDataPage = true                  # 是否在数据页面显示统计数据
    apiUrl = "https://your-api.com/"       # 统计数据API地址

配置说明：

enable: 全局开关，控制是否启用Umami统计跟踪
scriptUrl: Umami服务器的跟踪脚本地址
websiteId: 在Umami后台添加网站后获得的唯一ID
showInDataPage: 控制是否在数据页面（/data/）展示统计信息
apiUrl: 统计数据API地址，用于数据页面获取访问统计

功能特性：

✅ 访问统计自动跟踪（PV/UV）
✅ 数据页面实时展示（今日、昨日、本月、本年）
✅ 精美的数据卡片设计，每个指标独特的渐变色图标
✅ 数字递增动画效果，流畅的视觉体验
✅ 完整的PJAX兼容，无缝页面切换
✅ 响应式布局适配，移动端友好
✅ 暗色模式完美支持
✅ 错误处理和友好提示

详细配置请参考： Umami统计配置指南 | 使用示例

社交链接配置

[params.social]
  links = [
    { name = "GitHub", icon = "fab fa-github", url = "https://github.com/yourname", color = "#333333" },
    { name = "微博", icon = "fab fa-weibo", url = "https://weibo.com/yourprofile", color = "#e6162d" },
    { name = "邮箱", icon = "fas fa-envelope", url = "mailto:your@email.com", color = "#ea4335" },
    { name = "RSS", icon = "fas fa-rss", url = "/index.xml", color = "#ffa500" }
  ]

浮动按钮配置

[params.floatButtons]
  position = "right"  # 可选: "left" 或 "right"
  showBackToTop = true
  showThemeToggle = true
  showSidebarToggle = true

页脚配置

[params.footer]
  beian = "粤ICP备12345678号"  # 备案信息
  custom = """
    <div class="footer-links">
      <a href="/about">关于</a>
      <a href="/privacy">隐私政策</a>
    </div>
  """

置顶文章样式配置

# 置顶徽章颜色配置
[params.pinned]
  badgeStartColor = "#FF6B6B"            # 徽章渐变起始颜色
  badgeEndColor = "#FF8E8E"              # 徽章渐变结束颜色
  badgeTextColor = "#FFFFFF"             # 徽章文字颜色
  
  # 暗色模式颜色（可选）
  badgeStartColorDark = "#FF6B6B"        # 暗色模式起始颜色
  badgeEndColorDark = "#FF8E8E"          # 暗色模式结束颜色
  badgeTextColorDark = "#FFFFFF"         # 暗色模式文字颜色

使用说明：

在文章的 Front Matter 中设置 pinned: true 即可置顶
可自定义徽章颜色，避免与封面图颜色重合
支持十六进制、RGB、RGBA等颜色格式
详细配置请参考：置顶样式配置指南

内容管理

创建新文章

hugo new posts/文章标题.md

文章Front Matter示例

---
title: "文章标题"
date: 2024-01-01T10:00:00+08:00
lastmod: 2024-01-02T15:30:00+08:00
draft: false
description: "文章描述"
cover: "/images/cover.jpg"  # 封面图片
categories: ["技术"]
tags: ["Hugo", "主题"]
toc: true  # 启用目录
---

功能特性详解

1. 布局系统

三种首页布局：

单列布局 (homeColumns = 1)：传统博客布局
双列布局 (homeColumns = 2)：网格卡片布局
瀑布流布局 (homeColumns = 3)：动态加载布局

2. 主题切换

支持明暗主题自动切换
用户偏好设置自动保存
评论系统主题同步

3. 搜索功能

启用搜索功能：

[outputs]
  home = ["HTML", "JSON"]  # 必须启用JSON输出

[params.search]
  engine = "local"
  indexPath = "/index.json"

说明：

本主题保留“导航栏右上角”的搜索入口与搜索模态框。
侧栏搜索组件已在 v2.7.2 版本中移除，无需也无需再配置侧栏搜索相关项。

4. 侧边栏组件

可用组件：

author - 作者信息
toc - 文章目录（支持手机端弹出模式配置 v2.7.6+）
tags - 标签云
recent-Posts - 最新文章
categories - 分类列表
archive - 文章归档
popular-Posts - 热门文章
related-Posts - 相关文章
social-Media - 社交媒体
advertisement - 广告位
announcement - 公告栏
recent-Comments - 最新评论
series-posts - 系列文章（v2.7.0+）

手机端目录按钮配置（v2.7.6+）：

在 [params.aside.toc] 中设置 mobilePopupMode
支持 sidebar（弹出整个右侧栏）或 toc-only（仅弹出目录）
仅目录模式保持与右侧栏相同的位置样式和弹出方式（从右侧滑入）

5. 评论系统

支持Artalk自托管评论系统，配置说明：

# Artalk配置
[params.comment.artalk]
  server = "https://your-artalk-server.com"  # Artalk后端地址
  site = "your-site-name"                   # 站点名称
  useLocal = true                            # 使用本地资源
  
  # 可选CDN配置
  cdn = [
    { name = "jsDelivr", css = "https://cdn.jsdelivr.net/npm/artalk@2.9.1/dist/Artalk.css", js = "https://cdn.jsdelivr.net/npm/artalk@2.9.1/dist/Artalk.js" }
  ]
  cdnIndex = 0

6. 文章内容增强功能 ✨

音乐播放器 🎵（v2.5.0 全面升级）

基于 MetingJS 的全新音乐播放器，支持多平台、多类型：

支持的平台：

网易云音乐 (netease)
QQ音乐 (tencent)
酷狗音乐 (kugou)
虾米音乐 (xiami)
百度音乐 (baidu)

支持的类型：

单曲 (song)
播放列表 (playlist)
专辑 (album)
搜索 (search)
歌手 (artist)
本地文件 (local)

使用示例：

<!-- 单曲 -->
{{< music server="netease" type="song" id="27583305" >}}

<!-- 播放列表 -->
{{< music server="tencent" type="playlist" id="9602925225" >}}

<!-- 专辑 -->
{{< music server="netease" type="album" id="16937" >}}

<!-- 搜索 -->
{{< music server="netease" type="search" id="海阔天空" >}}

<!-- 歌手 -->
{{< music server="netease" type="artist" id="2118" >}}

<!-- 本地文件 -->
{{< music name="歌曲名" artist="歌手" url="/audio/demo.mp3" cover="/img/default-cover.webp" >}}

<!-- 自定义选项 -->
{{< music 
  server="netease" 
  type="song" 
  id="27583305" 
  autoplay="false" 
  theme="#FF6B6B" 
  loop="all" 
  volume="0.7" 
>}}

可用参数：

autoplay: 自动播放 (true/false)
theme: 主题颜色 (默认 #2980b9)
loop: 循环模式 (all/one/none)
order: 播放顺序 (list/random)
volume: 音量 (0-1)
lrcType: 歌词类型 (0/1/3)
listFolded: 列表折叠 (true/false)
listMaxHeight: 列表最大高度
fixed: 固定模式 (true/false)
mini: 迷你模式 (true/false)

详细使用说明：音乐播放器功能使用示例

彩色文字 🎨

<!-- 预设颜色 -->
{{< color "red" >}}红色文字{{< /color >}}
{{< color "blue" >}}蓝色文字{{< /color >}}

<!-- 自定义颜色 -->
{{< color "#FF5733" >}}自定义颜色{{< /color >}}

<!-- 主题色 -->
{{< color "primary" >}}主题色{{< /color >}}

详细使用说明：彩色文字功能使用示例

评论可见内容 🔒

{{< reply-visible id="unique-id" >}}
评论后才能看到的内容
{{< /reply-visible >}}

详细使用说明：评论可见功能使用示例

内容折叠 📦

{{< collapse "点击展开" >}}
折叠的内容
{{< /collapse >}}

<!-- 默认展开 -->
{{< collapse "标题" "open" >}}
默认展开的内容
{{< /collapse >}}

详细使用说明：内容折叠功能使用示例

时间线 📅

{{< timeline >}}

{{< timeline-item "2025-10-25" "标题" "success" "star" >}}
时间线内容
{{< /timeline-item >}}

{{< timeline-item "2025-10-20" "标题2" "info" "check" >}}
更多内容
{{< /timeline-item >}}

{{< /timeline >}}

可用类型：default, success, warning, danger, info
可用图标：default, check, star, warning, info, plus

详细使用说明：时间线功能使用示例

选项卡 📑

{{< tabs id="demo" tabs="选项卡1,选项卡2" >}}

{{< tab index="1" >}}
第一个选项卡的内容
{{< /tab >}}

{{< tab index="2" >}}
第二个选项卡的内容
{{< /tab >}}

{{< /tabs >}}

详细使用说明：选项卡功能使用示例

相册 🖼️

{{< gallery >}}
{{</* gallery-item 
  image="/img/photo1.jpg"
  caption="照片说明1"
>}}
{{< /gallery-item >}}

{{< gallery-item 
  image="/img/photo2.jpg"
  caption="照片说明2"
>}}
{{< /gallery-item >}}
{{< /gallery >}}

详细使用说明：相册功能使用示例

文章加密 🔐

全文加密：

---
title: "加密文章"
password: "myPassword"
passwordHint: "自定义提示（可选）"
---
文章内容...

部分内容加密：

{{< encrypt password="pwd" hint="提示" >}}
加密内容
{{< /encrypt >}}

配置选项：

[params.encryption]
  enable = true
  fullHint = "🔒 此文章已加密，请输入密码查看完整内容"
  partialHint = "🔐 此部分内容已加密，请输入密码查看"
  wrongPasswordHint = "❌ 密码错误，请重试"
  
  # 全文加密弹窗样式配置（v2.7.1+）
  popupTextColor = "#ffffff"              # 全文加密弹窗文字和图标颜色（默认白色）
  popupBackgroundColor = ""               # 全文加密弹窗背景色（支持单色或渐变，如："#667eea" 或 "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"）
  popupBackgroundImage = "/img/bj.jpg"    # 全文加密弹窗背景图路径（留空则不使用背景图）
  
  # 部分加密弹窗样式配置（独立设置，互不影响）（v2.7.1+）
  partialPopupTextColor = "#ffffff"             # 部分加密弹窗文字和图标颜色（留空则使用默认主题色）
  partialPopupBackgroundColor = "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"  # 部分加密弹窗背景色（支持单色或渐变，留空则使用默认背景）
  partialPopupBackgroundImage = ""       # 部分加密弹窗背景图路径（留空则不使用背景图）

安全特性（v2.7.7+）：

🔒 内容加密：加密内容在页面源码中以 base64 编码存储，不会暴露明文
🔐 密码保护：使用 SHA256 哈希验证密码，确保安全性
🔓 动态解码：密码验证通过后，从编码的 data 属性中解码并显示内容
💾 状态记忆：解锁状态保存在 sessionStorage 中，刷新页面后仍保持解锁状态
🔄 PJAX 兼容：支持 PJAX 无刷新切换，自动重新初始化加密逻辑

使用说明：

✅ 全文加密：在文章 Front Matter 中添加 password 字段
✅ 部分加密：使用 {{< encrypt >}} shortcode 包裹需要加密的内容
✅ 密码提示：可自定义密码提示文字（passwordHint 或 hint 参数）
✅ 样式定制：支持自定义弹窗文字颜色、背景色、背景图

详细使用说明：文章加密功能使用示例

视频嵌入 🎬

<!-- B站视频 -->
{{< video "https://www.bilibili.com/video/BV1xx411c7mu" >}}

<!-- YouTube视频 -->
{{< video "https://www.youtube.com/watch?v=dQw4w9WgXcQ" >}}

<!-- 本地视频 -->
{{< video "/video/demo.mp4" >}}

详细使用说明：视频嵌入使用示例

7. 页脚配置 ⏱️

[params.footer]
  # 自定义内容
  custom = """
    <div class="footer-links">
      <a href="/about">关于</a>
      <a href="/sitemap.xml">网站地图</a>
    </div>
  """
  
  # 运行时间显示
  [params.footer.runningTime]
    enable = true
    startDate = "2024-01-01"  # 建站日期
    prefix = "本站已运行"       # 前缀文字

显示效果：

版权信息（自动显示年份范围）
运行时间（动态更新，精确到秒）
自定义链接
备案信息（可选）

自定义样式

添加自定义CSS

在 assets/css/ 目录下创建自定义CSS文件：

/* 自定义样式 */
:root {
  --primary-color: #你的主色;
  --accent-color: #你的强调色;
}

/* 覆盖主题样式 */
.your-custom-class {
  /* 你的样式 */
}

自定义JavaScript

在 assets/js/ 目录下添加自定义脚本：

// 页面加载完成后执行
document.addEventListener('DOMContentLoaded', function() {
  // 你的自定义逻辑
});

图片资源管理

默认图片配置

[params.images]
  avatar = "/img/avatar.png"             # 作者头像
  defaultCover = "/img/default-cover.jpg" # 默认封面
  fallbackImage = "/img/404.jpg"         # 备用图片
  favicon = "/img/favicon.ico"           # 网站图标
  logo = "/img/logo.png"                 # 网站LOGO

图片目录结构

static/
  img/
    avatar.png          # 作者头像
    default-cover.jpg   # 默认封面
    404.jpg            # 404图片
    favicon.ico        # 网站图标
    logo.png           # 网站LOGO
    icons/             # 图标目录
      home.svg
      blog.svg
      cat.svg
      tag.svg
      link.svg
      mr.svg

高级功能

1. 相关文章配置

[related]
  threshold = 80
  includeNewer = true
  toLower = true
  
  [[related.indices]]
    name = "tags"
    weight = 100
    
  [[related.indices]]
    name = "categories"
    weight = 80

2. 目录生成配置

[markup]
  [markup.tableOfContents]
    startLevel = 2    # 从h2开始
    endLevel = 6      # 到h6结束
    ordered = false   # 不显示序号

部署说明

构建站点

hugo --minify

部署到GitHub Pages

创建 .github/workflows/gh-pages.yml：

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          fetch-depth: 0
      
      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 'latest'
          extended: true
      
      - name: Build
        run: hugo --minify
      
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

故障排除

常见问题

主题不显示
- 检查 theme = "demius" 配置
- 确认主题目录存在
评论系统不工作
- 检查Artalk服务器配置
- 确认站点名称匹配
搜索功能失效
- 确保启用了JSON输出
- 检查索引文件路径
图片加载失败
- 检查图片路径配置
- 确认图片文件存在

更新日志

v2.7.7 (2025-11-03)

🔒 优化加密逻辑安全性：加密内容 base64 编码存储，页面源码中不暴露明文
🛡️ 增强密码保护：使用 SHA256 哈希验证，动态解码显示
🧹 移除控制台调试信息：保持控制台干净，仅保留必要的错误日志
✅ 完全兼容现有功能，支持 PJAX 和 sessionStorage 状态记忆

v2.7.6 (2025-11-02)

📱 优化手机端首页文章卡片标题样式，与PC端保持一致
🔘 新增手机端目录按钮弹出模式配置（支持弹出整个右侧栏或仅弹出目录）
🎨 仅目录模式保持与右侧栏相同的位置样式和弹出方式（从右侧滑入）

v2.7.5 (2025-11-01)

🎨 优化系列文章序号颜色，亮色模式黑色文字，暗色模式白色文字
🔘 修复首页悬浮按钮显示问题，提高z-index层级
📐 修复侧栏隐藏时布局顺序问题，确保中间栏和右侧栏顺位滑动

v2.7.4 (2025-10-31)

📚 新增小说书单功能，支持三种状态分类（已读、在读、想读）
🌈 标签和文字随机颜色系统，12种配色循环
🎨 精美的卡片式布局，封面展示，响应式适配，暗色模式支持

v2.7.3 (2025-10-31)

🎬 新增追番星球功能，展示B站追番追剧记录
📊 三种状态分类（想看、在看、看过），进度条可视化
🎨 精美的卡片式布局，响应式适配，暗色模式支持

v2.7.2 (2025-10-30)

🗑️ 移除侧栏搜索组件（保留导航栏右上角搜索）
🎯 精简 _search.css：移除仅侧栏使用样式，保留通用样式
🛡️ 不影响现有样式/功能/布局与本地预览端口

v2.7.1 (2025-10-29)

🔐 加密弹窗仅覆盖文章内容（定位与z-index优化）
🔙 浏览器返回/PJAX切换自动清理加密遮罩
🏠 Mode2全屏大图修复首次侧栏闪烁，改为 display:none + 动画显示
🎨 新增加密弹窗样式配置（文字颜色、背景色、背景图）

v2.7.0 (2025-10-29)

🎨 侧栏组件背景系统：12个组件支持背景图/渐变色（默认关闭）
🧩 统一参数：backgroundImage/backgroundColor/textColor/overlayColor 等
🛡️ 安全：使用 safeCSS 防止渐变被转义（ZgotmplZ）
💬 新增留言板功能，专属页面 + 评论系统
🔐 新增文章加密功能（全文加密 + 部分加密）
🌈 新增评论弹幕功能，20种彩色弹幕，智能防重叠
🔘 浮动按钮组增强（阅读进度、沉浸式阅读、侧栏切换、弹幕控制）
❤️ 互动功能（点赞收藏、8平台分享、状态记忆）

v2.2.0 (2025-10-26)

✨ 新增侧栏一体化模式
🎨 统一侧栏组件视觉样式
🔄 支持一键切换分割/一体化模式
📱 响应式自适应优化
🌓 完整暗色模式支持
📚 新增侧栏配置使用文档

v2.1.2 (2025-10-26)

🐛 修复PJAX评论加载问题
🔧 优化Artalk资源加载策略
🎯 修复页面路由跳转问题
📐 修复双列布局标题截断
🗑️ 移除热门文章阅读量显示
📱 增强PJAX视觉反馈

v2.1.1 (2025-10-25)

🎨 新增置顶文章徽章颜色配置
🌈 支持自定义图标和文字颜色
🌓 独立的暗色模式配色
📚 新增置顶样式配置指南

v2.1.0 (2025-10-25)

✨ 新增音乐播放器功能
✨ 新增彩色文字功能
✨ 新增评论可见内容功能
✨ 新增页脚配置功能（运行时间、网站地图）
🎨 优化页脚样式
🐛 修复多项已知问题
📚 完善功能文档

v2.0.0 (2025-10-24)

✨ 新增时间线功能
✨ 新增内容折叠功能
✨ 新增相册功能
✨ 新增选项卡功能
🎨 统一视觉风格
📚 创建14个功能文档

v1.0.0

基础布局系统
评论系统集成
搜索功能
响应式设计
明暗主题切换

功能文档

完整的功能使用文档请访问：

功能使用示例文章：

技术支持

如有问题，请通过以下方式联系：

GitHub Issues: [项目地址]
邮箱: demius@qq.com
文档评论区

本文档最后更新：2025年11月2日
当前版本：v2.7.6