> For AI agents: the complete documentation index is available at https://docs.halo.run/llms.txt, the full documentation bundle is available at https://docs.halo.run/llms-full.txt.

# 主题端 HTML Head 标签处理

主题端 HTML Head 标签处理扩展点的作用是干预 HTML 页面中的 Head 标签内容，可以添加自定义的 CSS、JS 及 meta 标签等，以满足特定的定制化需求。

如果标签可能同时由主题或其他插件提供，应提供可关闭的插件设置并检查最终页面，避免重复或冲突。完整边界参考[与主题集成](https://docs.halo.run/developer-guide/plugin/theme-integration.md#%E6%89%A9%E5%B1%95%E6%9C%80%E7%BB%88%E9%A1%B5%E9%9D%A2%E8%BE%93%E5%87%BA)。

## 使用场景

- **添加自定义样式或脚本**：在 HTML Head 中插入额外的 CSS 文件或 JavaScript 脚本文件，以增强页面的交互性或样式。
- **定制 Meta 标签**：为特定页面添加或修改 meta 标签，如描述、作者、关键词等，以提高 SEO 和页面信息的完整性。
- **引入第三方库**：引入第三方库（如 Google Fonts、Font Awesome 等），以满足页面的特殊功能或风格需求。
- **定制 Open Graph 等社交媒体标签**：为社交媒体分享优化页面标签内容。

## 扩展点定义

主题端 HTML Head 标签处理的扩展点定义为 `TemplateHeadProcessor`，对应的 `ExtensionPoint` 类型为 `MULTI_INSTANCE`，即可以有多个实现类。

```java
@FunctionalInterface
public interface TemplateHeadProcessor extends ExtensionPoint {

    Mono<Void> process(ITemplateContext context, IModel model,
        IElementModelStructureHandler structureHandler);
}
```

`TemplateHeadProcessor` 对应的 `ExtensionPointDefinition` 资源描述如下：

```yaml
apiVersion: plugin.halo.run/v1alpha1
kind: ExtensionPointDefinition
metadata:
  name: template-head-processor
spec:
  className: run.halo.app.theme.dialect.TemplateHeadProcessor
  displayName: TemplateHeadProcessor
  type: MULTI_INSTANCE
  description: "Provides a way to extend the head tag content in the theme-side HTML page."
```

即声明 `ExtensionDefinition` 自定义模型对象时对应的 `extensionPointName` 为 `template-head-processor`。

## 示例实现

以下是一个简单的 TemplateHeadProcessor 插件实现示例：

```java
@Component
public class CustomHeadProcessor implements TemplateHeadProcessor {

    @Override
    public Mono<Void> process(ITemplateContext context, IModel model,
        IElementModelStructureHandler structureHandler) {
        var factory = context.getModelFactory();
        // 添加自定义 CSS 文件
        model.add(factory.createStandaloneElementTag(
            "link",
            Map.of("rel", "stylesheet", "href", "/custom/styles.css"),
            AttributeValueQuotes.DOUBLE,
            false,
            true
        ));

        // 添加自定义 Meta 标签
        model.add(factory.createStandaloneElementTag(
            "meta",
            Map.of("name", "author", "content", "Your Name"),
            AttributeValueQuotes.DOUBLE,
            false,
            true
        ));
        return Mono.empty();
    }
}
```

多个处理器会按 Spring `@Order` 顺序执行。源码参考：[TemplateHeadProcessor](https://github.com/halo-dev/halo/blob/58fbb339d49511e221ec760478490e1c880f7d2a/api/src/main/java/run/halo/app/theme/dialect/TemplateHeadProcessor.java)。

声明 ExtensionDefinition 自定义模型对象时对应的 extensionPointName 为 template-head-processor。

```yaml
apiVersion: plugin.halo.run/v1alpha1
kind: ExtensionDefinition
metadata:
  name: custom-head-extension
spec:
  extensionPointName: template-head-processor
  className: com.example.CustomHeadProcessor
  displayName: "Custom Head Extension"
  description: "Adds custom CSS and meta tags to the head section."
```

## 使用此扩展点的插件

- [集成 highlight.js 为文章提供代码块高亮渲染](https://github.com/halo-sigs/plugin-highlightjs)
- [集成 lightgallery.js，支持在内容页面放大显示图片](https://github.com/halo-sigs/plugin-lightgallery)
- [Halo 2.0 对 Umami 的集成](https://github.com/halo-sigs/plugin-umami)