SuperHTML validation, formatting, and LSP setup

SuperHTML's strict HTML5 validation scope

SuperHTML addresses HTML documents that are syntactically plausible but structurally wrong, especially when those mistakes survive in browsers. It validates syntax, element nesting, and attribute values. That makes it relevant to frontend developers, language-server users, and repository maintainers who want the same HTML5 rules in an editor and in CI.

The project is deliberately opinionated. It targets the WHATWG living standard regardless of the doctype written in a document, and it warns when a document declares an unsupported doctype. It also rejects self-closing syntax for ordinary elements. The README explains that browsers ignore the slash in a form such as `<div/>`, which can make authors misread the DOM structure. Void elements remain a separate matter.

These choices trade browser tolerance for specification-oriented diagnostics. A document that opens successfully in a browser can still produce errors from SuperHTML. In particular, placing `<style>` under `<body>` is reported even though browsers render it, because the project follows the HTML specification rather than browser behavior. Duplicate tokens in `class` are not reported because the specification defines `class` as a space-separated token list, not a list that must contain unique values.

The repository describes itself as a templating language library as well as a validator, formatter, and LSP, but the documented CLI section is centered on HTML validation and formatting. The excerpt does not document a separate command for developing SuperHTML templates, so that part of the project should not be inferred from the CLI examples.

CLI commands and document processing

The executable exposes five commands: `check` for errors, `fmt` for formatting, `lsp` for language-server mode, `help` to show the menu, and `version` for version output. A global `--syntax-only` option disables HTML element and attribute validation, leaving syntax validation in scope.

This separation gives the tool two distinct operating models. Full validation can report document structure and conformance errors. Syntax-only mode is intended for HTML containing unrecognized template constructs, although it gives up the element and attribute checks that make the validator distinctive. The README does not say whether formatting understands template expressions, so using `fmt` on templated files should be approached only after checking the project documentation for that version.

The formatter normalizes whitespace in two areas. First, it adds or removes whitespace between an element's start tag and its content, which controls whether content appears on the same line or on following lines. Second, it aligns attributes after the final attribute in a start tag. The documented output does not alter semantic HTML and presents normalized indentation and attribute alignment.

For CI, the README specifically suggests `superhtml fmt --check`. In that mode, the formatter reports files that are not in its normalized form instead of silently accepting arbitrary layout. Vim integration uses `superhtml fmt --stdin`, which exposes formatted output through the editor's formatting mechanism. The command documentation excerpt does not describe other input modes, so those two documented cases are the safe boundaries for automation.

Installing a SuperHTML release and running check

The README directs users to the repository's GitHub Releases section for downloads; it does not provide package-manager commands or build instructions in the documented section. A user installing the executable needs to place `superhtml` somewhere available to the shell.

The CLI usage is:

superhtml

The output should list `check`, `fmt`, `lsp`, `help`, and `version`, along with `--help`, `-h`, and `--syntax-only`. This confirms that the executable can run before connecting it to an editor.

A first real validation pass can use the documented `check` command:

superhtml check

The excerpt does not state the exact default output for a clean document, so only successful exit and any printed diagnostics should be used to judge the result. For a known template-heavy file, the documented reduced validation mode is:

superhtml check --syntax-only

This retains syntax checking but explicitly disables element and attribute validation. That distinction matters because SuperHTML's full rules are the primary reason to use it.

For editor integration, add the downloaded executable to `PATH`. Neovim can then start the server with the project's documented command:

vim.lsp.start({
    name = "superhtml",
    cmd = { "superhtml", "lsp" },
    root_dir = vim.fs.dirname(vim.fs.find({".git"}, { upward = true })[1])
})

The client runs that command for `html`, `shtml`, and `htm` files. Helix versions later than `24.07` are documented as supporting SuperHTML once the executable is in `PATH`. Vim can use `check` as `makeprg` and `fmt --stdin` as `formatprg`, while Flow is already configured to default to SuperHTML after the executable is available.

Choosing SuperHTML editor integrations

SuperHTML offers native CLI integration and a separate bundled route. For Neovim, the README provides both built-in `vim.lsp.start()` configuration and LspZero configuration. Helix support is built in for versions later than `24.07`, which reduces setup to placing the executable in `PATH`. Vim integration is based on command-oriented output rather than `vim.lsp`.

The VSCode extension follows a different delivery model. The README says it bundles a WASM build of the language server and does not require the CLI tool. That is the practical alternative for VSCode users who do not want to manage a separate executable or build the Zig project. The trade-off is that this route is tied to the extension, while CLI and native LSP configurations expose SuperHTML in scripts, CI, and other editors.

Zed is not documented as built in. The README points to `WeetHet/superhtml-zed`, making that repository the named integration path for Zed users. Other editors need their own Language Server configuration instructions. The SuperHTML CLI does not remove this client-specific work because LSP transport configuration remains an editor concern.

For Vim, the documented configuration is concise:

autocmd filetype html setlocal makeprg=superhtml\ check\ %
autocmd filetype html setlocal formatprg=superhtml\ fmt\ --stdin

The first setting populates Vim's quickfix results after `:make`. The second supports formatting with `gq{motion}`, including a whole buffer with `gggqG`. This is useful when a full editor client is unnecessary, although it does not provide the same documented diagnostic experience as the LSP path.

Formatter normalization and CI constraints

SuperHTML's formatter is designed to produce normalized HTML, not to offer multiple configurable layout styles. Its two documented normalization rules address start-tag spacing and attribute alignment. For inline content, it can keep elements together:

<div><p>Foo</p></div>

For block content, it inserts line breaks and indentation:

<div>
    <p>Foo</p>
</div>

Long attribute sets are placed in a vertical alignment, with the closing bracket on its own line:

<div foo="bar"
     style="verylongstring"
     hidden
>
    Foo
</div>

Because formatting is normalized, CI use can turn formatting differences into explicit failures. The recommended check is:

superhtml fmt --check

A repository adopting this command must be willing to accept the formatter's layout decisions. This is a real compatibility consideration for teams with hand-maintained line wrapping or HTML style rules that differ from SuperHTML. The documentation does not list formatting configuration files or rule toggles, so it offers no documented way to preserve those competing layouts.

The formatter's focus is whitespace, not template syntax. Full validation rejects several common templating languages, and the excerpt does not establish that formatting safely recognizes their expressions. CI should therefore treat plain HTML formatting and templated-document formatting as separate use cases unless the relevant version documents otherwise.

Maintenance, releases, and MIT adoption cost

The repository is not archived. Its last push was on 2026-09-26, and the listed releases include `v0.7.0` on 2026-06-09, `v0.6.2` on 2025-10-13, and `v0.6.1` on 2025-10-03. That release history shows recent project activity, but it does not document a stable-release policy or a long-term-support branch.

For teams embedding the language server, maintenance work includes tracking CLI releases and deciding when editor configuration should be retested. Teams using the WASM-backed VSCode extension have a different upgrade path because the extension bundles the server, but the excerpt does not document how extension and CLI versions are coordinated. Native LSP users should verify the downloaded executable and editor client independently.

The project uses the MIT License and includes `THIRD_PARTY_NOTICES` in the repository layout. The MIT identifier indicates an MIT-licensed project, while `THIRD_PARTY_NOTICES` signals that third-party terms should also be reviewed when redistributing or bundling it. This is a licensing inventory point, not legal advice.

The main upgrade risk is behavioral rather than packaging alone. SuperHTML enforces strict HTML5 choices, including rejecting self-closing non-void tags and reporting spec-defined placement errors that browsers tolerate. An upgrade can therefore expose previously accepted documents. Teams should first verify the current formatter output and run the exact template-versus-standard HTML boundary through their intended editor mode.

Editorial conclusion

Adopt SuperHTML when your team wants strict WHATWG HTML5 diagnostics from an editor, a command, or CI, and can accept its deliberate rejection of self-closing syntax. Do not adopt full validation for Jinja2, Angular, Mustache, or similar templates; verify first that `--syntax-only` is acceptable, or test the bundled SuperHTML VSCode extension without the CLI. The clearest adoption boundary is that SuperHTML targets HTML5 documents, not unrestricted templated markup.

Frequently asked questions

Official sources

1. Issues
2. kristoff-it/superhtml on GitHub
3. License: MIT
4. README
5. Releases