SuperHTML Documentation

The autoformatter manages horizontal and vertical alignment using two main rules:

1. Whitespace between start tag and content: Controls whitespace between the element's start tag and its inner content.
2. Whitespace between last attribute and closing >: Controls whitespace between the final attribute of a start tag and the closing bracket.

Example Rule 1 (Content Alignment): Before:

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

After:

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

Example Rule 2 (Attribute Alignment): Before:

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

After:

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

You can integrate SuperHTML into Emacs using the built-in eglot client (available in Emacs 29+). To use this integration, ensure the superhtml binary is present in your $PATH.

If you use a mode other than web-mode, substitute it in the configuration. The :language-id "html" property is required to ensure eglot correctly identifies the content type as HTML when communicating with the server.

;; Using use-package
(use-package eglot
  :defer t
  :hook ((web-mode . eglot-ensure)
         )
  :config
  (add-to-list 'eglot-server-programs '((web-mode :language-id "html") . ("superhtml" "lsp"))))

To use SuperHTML as the Language Server Protocol (LSP) provider in BBEdit, you must override the default HTML language settings. This replaces the default vscode-html-languageserver with superhtml.

1. Open BBEdit Settings (via BBEdit > Settings or ⌘+,).
2. Navigate to the Languages tab.
3. Select the Custom Settings sub-tab.
4. If HTML is not already listed, click the + dropdown and select HTML.
5. In the new sheet window, select the Server tab.
6. Clear the existing html-languageserver and —stdio values.
7. Enter superhtml in the Command text box.
8. Enter lsp in the Arguments box.
9. Verify a green checkmark appears indicating the server is ready.
10. Click OK to apply settings.

Once configured, SuperHTML will provide error and warning diagnostics for HTML documents opened in BBEdit.

To use SuperHTML in Neovim, download a prebuilt version of superhtml and ensure it is in your PATH. You can configure it using the built-in LSP client or LspZero.

# Neovim Built-In
vim.api.nvim_create_autocmd("Filetype", {
	pattern = { "html", "shtml", "htm" },
	callback = function()
		vim.lsp.start({
			name = "superhtml",
			cmd = { "superhtml", "lsp" },
			root_dir = vim.fs.dirname(vim.fs.find({".git"}, { upward = true })[1])
		})
	end
})

# LspZero
local lsp = require("lsp-zero")

require('lspconfig.configs').superhtml = {
		default_config = {
			name = 'superhtml',
			cmd = {'superhtml', 'lsp'},
			filetypes = {'html', 'shtml', 'htm'},
			root_dir = require('lspconfig.util').root_pattern('.git')
		}
}

lsp.configure('superhtml', {force_setup = true})

The SuperHTML VSCode extension provides a Language Server for HTML that performs syntax validation, element nesting checks, and attribute value validation.

IMPORTANT: Disable Built-in HTML Extension

To avoid conflicts with end tag suggestions, you must disable the built-in VSCode HTML extension. SuperHTML cannot disable these suggestions automatically. You can find manual instructions for disabling the built-in extension here.

Use the check command to validate documents for syntax, element nesting, and attribute values. Use the fmt command to autoformat documents.

Tip: Use superhtml fmt --check in your CI/CD pipelines to enforce that all changes are performed on normalized HTML files.

If you do not use use-package, you can configure SuperHTML for eglot by requiring the library and using with-eval-after-load to add the server program to the eglot-server-programs list.

(require 'eglot)
(with-eval-after-load 'eglot
  (add-to-list 'eglot-server-programs
               `((web-mode :language-id "html") . ("superhtml" "lsp"))))

You can use SuperHTML in Vim by setting makeprg for error checking via :make and formatprg for formatting via gq motions.

" for any html file, a :make<cr> action will populate the quickfix menu
autocmd filetype html setlocal makeprg=superhtml\ check\ %

" if you want to use gq{motion} to format sections or the whole buffer (with gggqG)
autocmd filetype html setlocal formatprg=superhtml\ fmt\ --stdin