Skip to main content
Back to Extensions Directory
coc.nvim fallback icon

coc-htmlview

asmodeus812

Browser-style HTML and CSS rendering into Neovim buffers for coc.nvim extensions

Installation CommandVim prompt
:CocInstall coc-htmlview
GitHub owner
asmodeus812
Version
v0.2.1
npm package
coc-htmlview
Requirements
coc ^0.0.82
License
MIT
Repository
GitHub
npm latest published 2026-11-21Registry summary

Published Package Summary

coc-htmlview

Browser-style HTML and CSS rendering into Neovim buffers, as a coc.nvim extension. Other coc extensions hand it an HTML string and stylesheet paths; it computes the cascade, lays the document out for the window width and shows it in a read-only buffer with colours taken from your colorscheme. It is built for extension authors who have HTML to show (rule descriptions, release notes, documentation pages) and for users who want to read that HTML inside the editor instead of a browser.

Screenshots

A release-notes page rendered in a float titled "Harbor 2.4" A complex HTML page (headings, cards, lists, content-sized table) in a Neovim float, habamax colours.

A blog article in a float: site header, byline, figure, lists, quote A traditional web page (header, nav, article) in a float titled "Article".

The article in a split next to a Lua file The same page in a split beside a code file (retrobox).

The article with a light colorscheme The same page with background=light and the default colorscheme.

Features

  • A real CSS cascade: a built-in user-agent sheet, your stylesheets, the caller's stylesheets, the document's <style> blocks and style="" attributes, with specificity and !important.
  • Computed style: inheritance, var() with fallbacks, shorthands, ::before/::after/::marker content and counters.
  • Box layout on a character grid: margins, padding, borders, blocks, inline flow, tables, lists with markers, row flex and inline-blocks.
  • Tabs and contexts through :checked: radio and checkbox labels act as tabs you switch with a key.
  • Code blocks highlighted with treesitter when a parser is installed, else with highlight.js.
  • Link targets optionally shown as virtual text next to the link (htmlview.linkTargets).
  • Colours follow the colorscheme and refresh on :colorscheme and :set background.
  • VS Code webview compatibility: the vscode-light/vscode-dark body class and the --vscode-* theme variables, mapped to Neovim highlight groups.

Requirements

  • Neovim 0.10 or newer and coc.nvim. Neovim 0.9 is the floor: it lacks inline virtual text, so link targets (when shown) move to the end of the line.
  • Vim works with a reduced view: always a split, no virtual text, no treesitter, no refresh on resize or colorscheme change.

Installation

From GitHub (coc runs npm install, which builds the extension):

:CocInstall https://github.com/asmodeus812/coc-htmlview

Or from a local clone:

git clone https://github.com/asmodeus812/coc-htmlview
cd coc-htmlview && npm ci && npm run build
ln -s "$PWD" ~/.config/coc/extensions/node_modules/coc-htmlview

Quick start

Users

coc-htmlview has no commands of its own. Install it next to an extension that uses it; that extension's views then render through it. Choose where views open and add your own stylesheets with the settings below. Inside a view, q closes it, <CR> follows a link and <Tab> jumps to the next link; :help coc-htmlview lists every key.

Extension authors

import { extensions } from "coc.nvim";

const ext = extensions.getExtensionById("coc-htmlview");
const api = ext?.exports as HtmlViewApi | undefined;
if (api !== undefined && api.version === 1) {
    const view = await api.render("<h1>Hello</h1><p>From <b>HTML</b>.</p>", {
        root: context.extensionPath, // relative stylesheets resolve here
        stylesheets: ["styles/my.css"],
        view: { name: "myext://hello", reuse: true }
    });
    await view.closed;
}

HtmlViewApi and the option types are in lib/api.d.ts; copy the interface into your extension, there is no compile-time dependency. The full API, with every option, is in :help coc-htmlview-api.

Highlight groups

Every colour of the built-in sheet and of the --vscode-* variables comes from a role group, HtmlViewHost<Role> (for example HtmlViewHostLink, HtmlViewHostHeading1, HtmlViewHostCodeBlock), linked by default to standard groups such as @markup.link, Title or FloatBorder. Override a role with :hi to restyle every view. The role table, the per-rule groups, the HtmlViewBorder<rrggbb> groups of literal border colours and how overrides survive a colorscheme change are in :help coc-htmlview-highlights.

Known limitations

  • ::before/::after content on a block is not rewrapped with the block's text.
  • rowspan is ignored in tables.
  • Flex is row only; flex-wrap, gap and inline-flex are not computed.
  • No fonts or font sizes: headings are colours and markers (an inherited author color wins over the heading colour), weight 600 or more is bold.
  • Form controls other than radio and checkbox are not rendered; images show their alt text.

Development

npm ci
npm run build     # lib/index.js and lib/api.d.ts
npm test          # unit tests (tests/ mirrors src/)
npm run typecheck

How it works

html ─(caller pre-pass)─▶ dom ─▶ style (UA sheet, settings sheets, caller sheets,
<style>, inline; cascade, var(), counters) ─▶ layout (boxes, inline flow, tables,
flex rows, code regions, links) ─▶ highlight (treesitter, then highlight.js) ─▶ view
PartFolderRole
domsrc/engine/dom/HTML parsing: implied structure, auto-closing, raw-text elements, entities
csssrc/engine/css/sheet and selector parsing, matching, cascade order
stylesrc/engine/style/computed styles, the user-agent sheet ua.css, host roles and highlight groups
layoutsrc/engine/layout/boxes and placement into lines, marks, links, anchors and virtual text
interactsrc/engine/interact/:checked state of radio and checkbox tabs
highlightsrc/highlight/code highlighting and the language table
viewsrc/view/the only Neovim-facing part: buffer, window, groups, extmarks, keys, refresh
commonsrc/common/the display-cell rules shared by every part

src/api.ts is the public contract (emitted as lib/api.d.ts); src/render.ts composes the pipeline, keeps the parsed document and restyles or lays out again when the view reports a resize, a tab switch or a colorscheme change.

Conventions the parts rely on:

  • Everything but the view is pure data in, data out: no Neovim calls, no module state, never throwing on real-world input (bad CSS drops the declaration, odd HTML is repaired). Text is never dropped or duplicated, except inside display: none and visibility: hidden.
  • Layout never looks at a tag name or class: it reads the computed display and the --htmlview-* hints (code, heading, link, replaced, toggle, break) that ua.css or a stylesheet sets.
  • Lines are 0-based; columns are display cells (2 for wide characters, 0 for combining marks) everywhere except the view, which converts to UTF-8 bytes for extmarks. CSS lengths become cells in style only (ch 1, em 1, px /8 across and /16 down).
  • Mark priority grows with element depth, so inner elements and later rules win; code tokens sit above styles.

Acceptance checks

  • Golden snapshot: node scripts/golden/dump.mjs <dir> renders the fixtures in tests/fixtures/ through the whole pipeline; diff two dumps to review every visible change.
  • Firefox oracle: tests/fixtures/oracle/*.json holds Firefox's computed styles for the fixtures, and the oracle tests require the engine to agree. Re-capture after changing a fixture or ua.css with node scripts/oracle/capture.mjs [name ...] (needs firefox).

License

MIT, see LICENSE.

Read the complete README
  • Browser-style HTML and CSS rendering into Neovim buffers for coc.nvim extensions
Activation Events
  • *
Developer Resources

Want to build, test, or contribute to coc.nvim extensions? Explore our official SDK and testing toolkits.

Open Developer Guide

Version History

This published npm package does not include a history.md or changelog.md file. Browse its npm versions or repository releases for available release information.