# Somnia


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

<!--more-->

## 基础

- 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 位置：

```{open=true}
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
```

### `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.**<br>
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.<br>
> Alpine is a collection of 15 attributes, 6 properties, and 2 methods.<br>
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 时才支持的。