Back

Somnia

Without further ado
| markdown

Somnia 是一个 Alpine.js + Swup.js 的主题。下面是自定义主题的一些概述。

基础

  • Hugo 查找优先级。如 website/assets/js/custom.js > website/themes/Somnia/assets/js/custom.js。前者存在时，优先使用。
    这为非侵入式 Hugo 主题的自定义提供了基础。方便后续更新主题。

重要文件位置

Somnia 是主题名，也是文件夹名称。如果是 Hugo-Landscape 主题，则为目录前缀为 Hugo-Landscape。

  • Somnia/layouts/partials/head/css.html 或 Somnia/layouts/_partials/head/css.html
  • Somnia/layouts/partials/head/js.html 或 Somnia/layouts/_partials/head/js.html
  • Somnia/assets/css/
  • Somnia/assets/js/
  • Somnia/layouts/partials/data.html 或 Somnia/layouts/_partials/data.html

主要文件 - JS

整体 js 逻辑：

  • 主题代码初始化内联防闪烁
  • 定义变量，主要逻辑，库的引入加载，Alpine.js 组件函数。
  • 引入 Swup.js 实现无刷新页面过渡。
  • 引入 Alpine.js 实现响应式界面。简化 Swup.js 页面切换前后组件 js 逻辑。
  • 引入 Async Alpine 实现异步加载 Alpine.js。切分 js 文件，适用于大型、独立、低频组件。如评论系统。简化 shortcodes 开发。
  • Swup.js 初始化，定义页面切换逻辑。注册 sw.js 。

Somnia/layouts/partials/head/js.html - Hugo 模板引擎中用于管理和引入 JavaScript 文件的配置。js 位置：

Somnia/assets/js
.
|-- alpinejs.min.js
|-- async-alpine.min.js
|-- components.js
|-- custom.js
|-- main.js
|-- medium-zoom.min.js
|-- sw.js
|-- swup
|   |-- Swup.umd.js
|   |-- preload-plugin.js
|   `-- scroll-plugin.js
`-- variable.js
text

variable.js

  • 存储全局变量、配置参数
  • 在各个模块间共享的数据

main.js

  • 主入口文件
  • 负责初始化整个应用
  • 协调各个模块的加载和调用

components.js

  • Alpine.store('somnia') 存储响应式全局状态
  • function somniaData() 处理页面数据 负责动态加载 js 等
  • 自定义组件逻辑

custom.js

  • 用户 layouts/partials/head/js.html 覆盖
  • 欢迎内容
  • 修改变量
  • 定义 Swup.js 页面切换逻辑

第三方库 - JS

async-alpine.min.js

Code splitting and lazy-loading components for Alpine.js!
https://async-alpine.dev/ ↗

  • Alpine.js的异步加载版本
  • 优化页面加载性能
  • 支持延迟加载Alpine组件

alpinejs.min.js

Your new, lightweight, JavaScript framework.

Simple.
Lightweight.
Powerful as hell.

Alpine is a rugged, minimal tool for composing behavior directly in your markup. Think of it like jQuery for the modern web. Plop in a script tag and get going.

Alpine is a collection of 15 attributes, 6 properties, and 2 methods.

https://alpinejs.dev/ ↗

  • Alpine.js框架核心库
  • 轻量级的JavaScript框架，类似Vue/React的响应式特性
  • 用于处理DOM交互、数据绑定、事件监听等

medium-zoom.min.js

Medium Zoom - A JavaScript library for zooming images like Medium
https://medium-zoom.francoischalifour.com/ ↗

  • Medium风格图片缩放库
  • 点击图片可实现平滑放大预览
  • 提供优雅的图片查看体验

swup/Swup.umd.js

Versatile and extensible page transition library for server-rendered websites
https://swup.js.org/ ↗

  • Swup页面切换库核心
  • 实现无刷新的页面过渡动画
  • 提升单页应用(SPA)体验

swup/scroll-plugin.js

A swup plugin for customizable smooth scrolling.
https://swup.js.org/plugins/scroll-plugin/ ↗

  • Swup的滚动位置管理插件
  • 在页面切换时保存和恢复滚动位置
  • 确保用户在不同页面间导航时滚动位置正确

其余逻辑 - JS

  • Swup.js 初始化
  • Swup.js 定义页面切换逻辑
  • PWA 支持（可选）

整体作用 - JS

这套配置主要实现：

  1. 模块化开发 - 按功能拆分JS文件
  2. 增强交互 - 通过 Alpine.js 实现响应式界面。简化开发，提高可维护性。
  3. 改善体验 - Swup 实现平滑页面切换，medium-zoom 优化图片查看
  4. 性能优化 - 异步加载 Alpine 方便开发

这套配置适用：内容型网站（如博客、文档）或轻量级Web应用，在保持SEO友好的同时提供接近SPA的流畅体验。

主要文件 - CSS

Somnia/layouts/partials/head/css.html - Hugo 模板引擎中用于管理和引入 CSS 文件的配置。

注意：CSS import 是在 Hugo >= v0.158.0 时才支持的。

Docs