ReferenceBuilt-in steps

hover-go

The hover-go step: hovers and errors of Go fences with gopls.

uses: hover-go checks the Go code fences of HTML pages with gopls and stores on each the hovers of its symbols (signature and documentation) and its errors, in the shape of the hover-typescript step's results, so that the same renderer (highlight) shows them.

Shape reduce (no group-by)
Default match **/*.html
Default workflow no

What it doesLink to this heading

Every fence of an HTML page that the markdown step wrote with a language of languages (go, golang), and, when trigger is set, whose meta has that word, gets a data-twoslash attribute with twoslash's shape: { "code": ..., "nodes": [...] }, the hovers and the errors. The fence itself is unchanged, and the step sets no metadata.

Each snippet is a package of its own in a generated module: s<n>/main.go, or the file name of the fence's title. A snippet without a package clause gets package main, and statements outside a function go in func _() { ... }. A fence uses the module of its meta's module=name, else the first module whose titles end its title, else the first whose patterns match its code, else default (a module without requirements when modules does not declare it).

Errors fail the build, naming the page, the fence's number on the page and its first line; with errors: warn they are warnings, and the fence renders them. ignore lists diagnostic codes (UnusedVar, UnusedImport, BrokenImport...) that are neither reported nor rendered.

OptionsLink to this heading

Option Type Default Meaning
modules mapping of names to modules default, a module without requirements the generated modules, see below
trigger string none a word the meta of a fence must have to be checked; every fence of languages when not set
ignore string or list none diagnostic codes neither reported nor rendered
version string v0.24.0 the version of gopls to build (a leading v is added when missing)
path string none a gopls executable, relative to the source folder, instead of building it
go string go on the PATH the go executable that builds gopls, adds the requirements and that gopls runs, relative to the source folder
languages string or list [go, golang] the fence languages the step checks
errors string fail fail: a snippet with errors fails the build; warn: it is a warning
tab-width integer, 0 to 16 0 replace tabs with that many spaces first; 0 keeps them
trim boolean true remove the spaces at the end of lines and the blank lines around the code first
processes integer, 1 or more the processor count, at most 4 language servers at once
timeout integer, 1 or more 300 seconds each language server has

Each module of modules:

Field Type Default Meaning
requires mapping of module paths to versions none third-party modules the snippets import (github.com/redis/go-redis/v9: v9.7.0), added with go get
files mapping of paths to paths none shared files of the source folder: a package of stubs at api/api.go is imported as snippets/api; go.mod, go.sum and the folders s<n> are reserved
titles list none fence titles, or their ends (main.go), that select the module
patterns list none regular expressions, one of which the code of a fence must match to select the module when no title matched

RequirementsLink to this heading

  • Go (go, or the PATH's), which also adds the requirements and loads the packages.
  • gopls. It has no prebuilt binaries: without path, on first use, go install golang.org/x/tools/gopls@<version> builds it into <cache>/tools/gopls/<version>/. douze tools install builds it ahead.

douze doctor checks both. A build that has no snippet to check starts no language server.

CachingLink to this heading

Each fence's outcome, errors included, is kept in the cache by its language, its code, its module and file name, and what the step depends on: gopls and its version (or the content of the path file), the Go version, the modules (their fields and the content of their files), ignore, tab-width and trim. A build checks only new snippets.

The step is a reduce: it waits for every page it consumes before it checks them.

ErrorsLink to this heading

douze.yml(7,3): error: option 'modules.m.files' of step 'go' has a reserved path 'go.mod': go.mod, go.sum and the folders s<n> are the module's and its snippets'
douze.yml(7,3): error: module 'm' of step 'go' has an unknown field 'require'; did you mean 'requires'?
douze.yml(7,3): error: option 'modules' of step 'go' must be a mapping of module names to modules
douze.yml(7,3): error: pattern '(' of module 'm' of step 'go' is not a regular expression: ...

ExampleLink to this heading

douze.yml
site:
  content: docs

steps:
  pages:
    inputs: "docs/**"
    uses: frontmatter
  permalink:
    needs: pages
    uses: permalink
    with:
      root: docs
  markdown:
    needs: permalink
    uses: markdown
  go:
    needs: markdown
    uses: hover-go
    with:
      errors: warn
      ignore: [UnusedVar]
      modules:
        default:
          requires:
            github.com/redis/go-redis/v9: v9.7.0
  highlight:
    needs: go
    uses: highlight
  write:
    needs: highlight
    uses: write

Esc to close