gohugoio/hugo · error

asciidoctor not found in $PATH, cannot render %q

Error message

asciidoctor not found in $PATH, cannot render %q

What it means

Hugo's AsciiDoc support shells out to the external Ruby `asciidoctor` binary; before rendering, `GetAsciiDocContent` checks `hexec.InPath("asciidoctor")` and fails fast with this error if the binary is not on `$PATH`. Hugo itself contains no AsciiDoc renderer, so `.adoc`/`.asciidoc` content cannot be built without it.

Source

Thrown at markup/asciidocext/internal/converter.go:91

	content, toc, err := a.extractTOC(b)
	if err != nil {
		return nil, err
	}
	return asciiDocResult{
		ResultRender: converter.Bytes(content),
		toc:          toc,
	}, nil
}

func (a *AsciiDocConverter) Supports(_ identity.Identity) bool {
	return false
}

// GetAsciiDocContent calls asciidoctor as an external helper to convert
// AsciiDoc content to HTML.
func (a *AsciiDocConverter) GetAsciiDocContent(src []byte, ctx converter.DocumentContext) ([]byte, error) {
	if !hexec.InPath(asciiDocBinaryName) {
		return nil, fmt.Errorf("asciidoctor not found in $PATH, cannot render %q", ctx.DocumentName)
	}

	args, err := a.ParseArgs(ctx)
	if err != nil {
		return nil, err
	}
	args = append(args, "-") // read from stdin

	a.Cfg.Logger.Infof("Rendering %s using Asciidoctor args %s ...", ctx.DocumentName, args)

	return internal.ExternallyRenderContent(a.Cfg, ctx, src, asciiDocBinaryName, args)
}

func (a *AsciiDocConverter) ParseArgs(ctx converter.DocumentContext) ([]string, error) {
	cfg := a.Cfg.MarkupConfig().AsciiDocExt
	args := []string{}

	args = a.AppendArg(args, "-b", cfg.Backend, asciidocext_config.CliDefault.Backend, asciidocext_config.AllowedBackend)

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Install Asciidoctor: `gem install asciidoctor` (or `apt install asciidoctor` / `brew install asciidoctor`).
2. Ensure the gem bin directory is on `$PATH` in the environment running Hugo (especially CI); verify with `asciidoctor --version`.
3. In CI, use an image or setup step that includes Ruby and asciidoctor, and add `asciidoctor` to `security.exec.allow` if you've customized Hugo's security config.
4. If AsciiDoc isn't intended, rename/remove the `.adoc` files so Hugo doesn't invoke the converter.

Example fix

# before: CI image lacks asciidoctor
hugo
# after
gem install asciidoctor
export PATH="$(ruby -e 'print Gem.user_dir')/bin:$PATH"
hugo

if _, err := exec.LookPath("asciidoctor"); err != nil {
    log.Fatal("asciidoctor not in PATH; install it or drop .adoc content")
}

When it happens

Trigger: Building a site containing `.adoc`, `.asciidoc`, or `.ad` content files (or content with `markup: asciidocext`) on a machine where the `asciidoctor` executable is not in `$PATH` — including CI containers and minimal Docker images.

Common situations: CI pipelines using the plain Hugo Docker image without Ruby/asciidoctor installed, fresh dev machines missing the gem, PATH not including the gem bin dir (e.g. rbenv/asdf shims not initialized in non-interactive shells).

Related errors

• pandoc not found in $PATH, cannot render %q
• rst2html / rst2html.py not found in $PATH, cannot render %q
• the AsciiDoc converter (%s) is not installed
• abort: jekyll root contains neither posts nor drafts
• no Dart Sass binary found in $PATH

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/e7b835ae3d500cb4.json. Report an issue: GitHub ↗.