中文 | English

Amigo 是一款为 Hugo 打造的极简博客主题，其设计灵感来源于 微信朋友圈 (WeChat Moments)。它旨在提供一个私密、亲切且易于阅读的动态分享空间，支持 PJAX 无刷新加载和多种评论系统。

• 📱 朋友圈 UI：高度还原微信朋友圈视觉体验，支持九宫格图片展示
• 🖼️ 智能多图布局：自动适配 1/2/3/4/6/9 张图片排列，支持 Live Photo 混排
• 🎵 音乐播放器：集成 Meting API，支持网易云音乐在线播放，PJAX 页面切换音乐不中断
• 🎬 视频播放器：支持普通视频和哔哩哔哩视频嵌入，自定义控件
• 🎤 语音消息：微信风格语音气泡，自动检测时长
• 📄 长文章卡片：首页自动识别长文章，以博客卡片形式展示
• 💬 朋友圈评论：Artalk 深度集成，支持点赞、弹幕、IP 归属地显示
• ⏰ 人性化时间：朋友圈风格时间显示（"刚刚"、"5分钟前"、"昨天"）
• 🚀 全站 PJAX：丝滑的无刷新页面切换
• 🌓 深色模式：支持手动切换及系统跟随
• 🖼️ 图片灯箱：集成 ViewImage.js，点击图片放大浏览
• 🎨 精美排版：本地化中文字体优化，阅读体验更佳
• 🛠️ 响应式设计：完美适配手机、平板及桌面端
• 🔍 搜索功能：支持本地搜索，无需外部服务

访问 Amigo 主题演示站点 查看实际效果。

• Hugo：建议使用 0.128.2+ 版本
• 评论系统（三选一）：
  • Artalk：推荐 2.8.7+，支持点赞、弹幕等完整功能
  • Twikoo：无需服务器，支持 EdgeOne 部署
  • Giscus：基于 GitHub Discussions

git clone https://github.com/zqlit/Hugo-Theme-Amigo.git themes/Amigo

将主题目录下的 hugo.toml 复制到站点根目录，或添加以下基本配置：

theme = "Amigo"

[params]
  username = "您的昵称"
  avatar = "/images/avatar.jpg"
  description = "一句话简介"
  cover = "/images/header.png"

  # 评论模式: "artalk"、"twikoo"、"giscus"、"none"
  commentMode = "artalk"

  # Artalk 配置
  artalkServer = "https://your-artalk-server.com"
  artalkSite = "您的站点名称"
  enableDanmaku = true  # 首页弹幕

commentMode = "artalk"  # "artalk" / "twikoo" / "giscus" / "none"

# Artalk
artalkServer = "https://artalk.example.com"
artalkSite = "我的博客"
enableDanmaku = true

# Twikoo
twikooEnvId = "your-env-id"
twikooLang = "zh-CN"

# Giscus
giscusRepo = "user/repo"
giscusRepoId = "R_xxxxx"
giscusCategory = "Announcements"
giscusCategoryId = "DIC_xxxxx"

showTags = true          # 显示文章标签
showLocation = true      # 显示地点信息
enableSearch = true      # 本地搜索
enableDarkMode = true    # 深色模式切换
enablePjax = true        # PJAX 无刷新加载
enableLightbox = true    # 图片灯箱

fontFamily = "ZQL"  # "ZQL" / "PingFangQiaoMuTi" / "AlimamaFangYuanTi"

[[menu.main]]
  name = "首页"
  url = "/"
  weight = 1

[[menu.main]]
  name = "关于"
  url = "/about.html"
  weight = 2

content/
├── posts/           # 朋友圈动态
├── about.md         # 关于页面
└── friends.md       # 友链页面

---
title: "周末去爬山"
date: 2026-02-20
author: "Vaica"
location: "武汉·东湖"
tags: ["生活", "摄影"]
---

今天天气真好，去公园散步。🌸

![photo1.jpg](photo1.jpg)
![photo2.jpg](photo2.jpg)

主题会自动根据图片数量选择最佳布局：

卡片式音乐播放器，支持本地音频和 Meting API：

{{< music-card
    src="https://example.com/song.mp3"
    cover="/images/cover.jpg"
    name="歌曲名"
    artist="艺术家"
    accent="#d43c33"
>}}

使用 Meting API 时，src 填入 API 地址即可自动解析：

{{< music-card
    src="https://open.motues.top/music?server=netease&type=song&id=182402"
    name="歌曲名"
    artist="艺术家"
>}}

基础版音乐播放器，带进度条和上/下一首控制：

{{< music
    src="https://example.com/song.mp3"
    cover="/images/cover.jpg"
    name="歌曲名"
    artist="艺术家"
>}}

类似 iPhone 实况照片效果，鼠标悬停播放视频：

{{< motion-photo
    image="cover.jpg"
    video="video.mp4"
    alt="描述文字"
    ratio="3/4"
    delay="500"
>}}

Apple 风格实况照片，带实况/静音按钮：

{{< livephoto image="cover.jpg" video="video.mp4" >}}
{{< livephoto src="photo.avif" >}}

带播放控制、音量调节和进度条的卡片式实况照片：

{{< livephoto-card
    src="cover.jpg"
    video="video.mp4"
    caption="图片说明"
>}}

自定义视频播放器，支持播放/暂停、进度条、静音和全屏。同时支持哔哩哔哩视频嵌入：

{{< video src="video.mp4" >}}

带封面图和自定义比例：

{{< video src="video.mp4" poster="cover.jpg" ratio="4/3" >}}

自动播放 + 循环：

{{< video src="video.mp4" autoplay="true" loop="true" muted="true" >}}

哔哩哔哩视频（自动识别 BV 号或 aid）：

{{< video src="https://www.bilibili.com/video/BV1xx411c7mu" >}}
{{< video src="https://www.bilibili.com/video/BV1xx411c7mu" page="2" >}}

模仿微信语音消息样式的音频播放器：

{{< voice src="audio.mp3" >}}

指定时长显示：

{{< voice src="audio.mp3" duration="12" >}}

当文章超过 500 字或在 Front Matter 中设置 isLongArticle: true 时，首页会以博客卡片形式展示，包含封面图、标题和摘要。

---
title: "我的长文章"
isLongArticle: true
cover: "cover.jpg"
---

正文内容...

封面图抓取优先级：

1. cover 参数（Front Matter 显式设置）
2. images 参数第一张
3. 正文 <img> 第一张
4. 无图时显示纯文字卡片

• Posts：默认开启，comments: false 关闭
• Pages：默认关闭，comments: true 开启

创建 data/friends.yml：

- name: "Vaica"
  url: "https://usj.cc"
  avatar: "https://github.com/zqlit"
  description: "开发者"

在 content/friends.md 中设置 layout: "friends"

• SSG: Hugo
• Icons: Remix Icon
• Comments: Artalk / Twikoo / Giscus
• Music: Meting API
• JS: ViewImage.js, PJAX.js

如果你觉得这个主题还不错，欢迎请作者喝杯咖啡！

微信支付

支付宝

本项目采用 MIT License 协议。

感谢使用 Amigo！如果喜欢，欢迎点个 Star ⭐️

Amigo is a minimalist Hugo blog theme inspired by WeChat Moments. It provides an intimate, easy-to-read space for sharing updates, with PJAX navigation and multi-comment system support.

• 📱 Moments UI: Faithful recreation of WeChat Moments with grid image layout
• 🖼️ Smart Grid Layout: Auto-adapts to 1/2/3/4/6/9 images, supports Live Photo mixing
• 🎵 Music Player: Meting API integration, music persists across PJAX page transitions
• 🎬 Video Player: Supports regular videos and Bilibili embeds with custom controls
• 🎤 Voice Message: WeChat-style voice bubble with auto duration detection
• 📄 Long Article Card: Auto-detects long articles and displays as blog cards on homepage
• 💬 Moments Comments: Deep Artalk integration with likes, danmaku, IP geolocation
• ⏰ Human-friendly Time: WeChat-style display ("just now", "5 min ago", "yesterday")
• 🚀 PJAX Navigation: Smooth page transitions without full reloads
• 🌓 Dark Mode: Manual toggle with system preference detection
• 🖼️ Lightbox: ViewImage.js integration for image zoom
• 🎨 Typography: Optimized Chinese font rendering
• 🛠️ Responsive: Perfect on mobile, tablet, and desktop
• 🔍 Search: Local search, no external service required

Visit the Amigo Demo Site to see it in action.

• Hugo: Version 0.128.2+ recommended
• Comment System (choose one):
  • Artalk: Full features (likes, danmaku, IP geolocation)
  • Twikoo: Serverless, deploy on EdgeOne
  • Giscus: GitHub Discussions based

git clone https://github.com/zqlit/Hugo-Theme-Amigo.git themes/Amigo

Copy hugo.toml from the theme directory to your site root, or add:

theme = "Amigo"

[params]
  username = "Your Name"
  avatar = "/images/avatar.jpg"
  description = "A short bio"
  cover = "/images/cover.jpg"
  commentMode = "artalk"
  artalkServer = "https://your-artalk-server.com"
  artalkSite = "My Blog"

commentMode = "artalk"  # "artalk" / "twikoo" / "giscus" / "none"

# Artalk
artalkServer = "https://artalk.example.com"
artalkSite = "My Blog"
enableDanmaku = true

# Twikoo
twikooEnvId = "your-env-id"

# Giscus
giscusRepo = "user/repo"
giscusRepoId = "R_xxxxx"
giscusCategory = "Announcements"
giscusCategoryId = "DIC_xxxxx"

showTags = true
showLocation = true
enableSearch = true
enableDarkMode = true
enablePjax = true
enableLightbox = true

[[menu.main]]
  name = "Home"
  url = "/"
  weight = 1

[[menu.main]]
  name = "About"
  url = "/about.html"
  weight = 2

---
title: "Weekend Hiking"
date: 2026-02-20
author: "Vaica"
location: "Wuhan, China"
tags: ["life", "photography"]
---

Beautiful weather today! 🌸

![photo1.jpg](photo1.jpg)
![photo2.jpg](photo2.jpg)

The theme automatically selects the best layout based on image count:

Card-style music player with Meting API support:

{{< music-card
    src="https://example.com/song.mp3"
    cover="/images/cover.jpg"
    name="Song Name"
    artist="Artist"
    accent="#d43c33"
>}}

Basic music player with progress bar and prev/next controls:

{{< music
    src="https://example.com/song.mp3"
    cover="/images/cover.jpg"
    name="Song Name"
    artist="Artist"
>}}

iPhone-style live photo effect, plays video on hover:

{{< motion-photo
    image="cover.jpg"
    video="video.mp4"
    alt="Description"
    ratio="3/4"
    delay="500"
>}}

Apple-style live photo with live/mute buttons:

{{< livephoto image="cover.jpg" video="video.mp4" >}}

Card-style live photo with playback controls, volume, and progress bar:

{{< livephoto-card
    src="cover.jpg"
    video="video.mp4"
    caption="Photo description"
>}}

Custom video player with play/pause, progress bar, mute, and fullscreen. Also supports Bilibili video embeds:

{{< video src="video.mp4" >}}

With poster image and custom ratio:

{{< video src="video.mp4" poster="cover.jpg" ratio="4/3" >}}

Autoplay + loop:

{{< video src="video.mp4" autoplay="true" loop="true" muted="true" >}}

Bilibili video (auto-detects BV ID or aid):

{{< video src="https://www.bilibili.com/video/BV1xx411c7mu" >}}
{{< video src="https://www.bilibili.com/video/BV1xx411c7mu" page="2" >}}

WeChat-style voice message audio player:

{{< voice src="audio.mp3" >}}

With explicit duration display:

{{< voice src="audio.mp3" duration="12" >}}

When an article exceeds 500 characters or has isLongArticle: true in front matter, it displays as a blog card on the homepage with cover image, title, and excerpt.

---
title: "My Long Article"
isLongArticle: true
cover: "cover.jpg"
---

Content here...

Cover image priority:

1. cover param (explicit front matter)
2. First image from images param
3. First <img> in content
4. Text-only card if no image

Create data/friends.yml:

- name: "Vaica"
  url: "https://usj.cc"
  avatar: "https://github.com/zqlit"
  description: "Developer"

Set layout: "friends" in content/friends.md.

• SSG: Hugo
• Icons: Remix Icon
• Comments: Artalk / Twikoo / Giscus
• Music: Meting API
• JS: ViewImage.js, PJAX.js

This project is licensed under the MIT License.

Made with ❤️ by Vaica | Star this repo if you like it! ⭐️