SuperHTML 实用指南：从入门到精通

1 项目概览 📋

SuperHTML 是一个专注于 HTML 开发的语言服务器和模板引擎库，采用 Zig 语言构建，提供语法检查、格式化和 LSP（语言服务器协议）等核心功能。项目采用模块化设计，兼顾性能与可扩展性，适合作为 HTML 开发的辅助工具或集成到编辑器中使用。

1.1 核心目录结构

目录路径	功能描述
src/	源代码主目录，包含 CLI 和解析器核心
src/cli/	命令行工具实现，含 LSP 模块
src/html/	HTML 解析器组件，包含词法分析器和 AST
editors/	编辑器插件，支持 VSCode 等开发环境
tree-sitter-superhtml/	语法高亮和解析器绑定

1.2 技术栈特点

项目基于 Zig 语言开发，具有内存安全和高性能特性。核心依赖包括 Tree-sitter 解析系统和 LSP 协议实现，支持多编辑器集成。代码遵循模块化设计原则，各组件通过明确接口交互，便于扩展和维护。

2 核心功能 🔍

2.1 HTML 语法检查

SuperHTML 提供实时语法错误检测，能识别标签不匹配、重复属性等常见问题。通过词法分析器（Tokenizer）和抽象语法树（AST）构建，实现精准的代码校验。

2.2 代码格式化

支持 HTML 代码自动格式化，可调整缩进、属性排序和标签对齐方式。格式化规则符合 Web 标准，同时允许通过配置文件自定义风格。

2.3 语言服务器协议支持

实现 LSP 协议，提供代码补全、定义跳转和文档提示等 IDE 功能。支持 VSCode 等主流编辑器，提升开发效率。

图 1：SuperHTML 在 VSCode 中实时显示 HTML 语法错误

3 快速上手 ⚡

3.1 环境准备

🔧 安装 Zig 编译器（建议 0.11.0 及以上版本）
🔧 克隆项目仓库：git clone https://gitcode.com/gh_mirrors/su/superhtml
🔧 进入项目目录：cd superhtml

3.2 编译项目

执行构建命令：

zig build

编译成功后，可在 zig-out/bin 目录找到可执行文件。

3.3 基础使用

🔧 语法检查：superhtml check example.html
执行后将输出文件中的语法错误，包括错误位置和类型说明。

🔧 代码格式化：superhtml fmt example.html
格式化后的代码将覆盖原文件，或通过 --write 参数指定输出路径。

图 2：SuperHTML 自动格式化 HTML 代码的实时效果

4 进阶指南 🛠️

4.1 构建配置详解

build.zig 是项目构建配置文件，核心参数说明：

参数	含义	默认值
target	目标平台	native
optimize	优化级别	ReleaseSafe
lsp	启用 LSP 模块	true

4.2 编辑器集成

以 VSCode 为例：

1. 安装扩展：code --install-extension editors/vscode
2. 重启编辑器后自动激活语法高亮和错误检查

4.3 自定义规则

创建 .superhtml.toml 配置文件，可自定义：

• 缩进空格数
• 属性排序规则
• 标签自闭合策略

5 常见问题 ❓

5.1 编译失败提示缺少依赖？

确保已安装最新版 Zig 编译器，并通过 zig env 检查环境变量配置。部分系统可能需要安装 libc 开发包。

5.2 编辑器未显示语法错误？

检查 LSP 服务是否运行：superhtml lsp --check，确保 VSCode 扩展已正确安装并启用。

5.3 格式化结果不符合预期？

通过配置文件调整规则，或提交 issue 反馈特定场景的格式化问题。

6 学习资源

• 官方文档：项目根目录 README.md
• 代码示例：src/fuzz/cases/ 目录下的 HTML 测试用例
• 技术原理：Tree-sitter 官方文档（语法解析框架）

SuperHTML 持续开发中，建议定期拉取最新代码以获取功能更新和性能优化。