{"id":"e7b835ae3d500cb4","repo":"gohugoio/hugo","slug":"asciidoctor-not-found-in-path-cannot-render-q","errorCode":null,"errorMessage":"asciidoctor not found in $PATH, cannot render %q","messagePattern":"asciidoctor not found in \\$PATH, cannot render %q","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"markup/asciidocext/internal/converter.go","lineNumber":91,"sourceCode":"\tcontent, toc, err := a.extractTOC(b)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn asciiDocResult{\n\t\tResultRender: converter.Bytes(content),\n\t\ttoc:          toc,\n\t}, nil\n}\n\nfunc (a *AsciiDocConverter) Supports(_ identity.Identity) bool {\n\treturn false\n}\n\n// GetAsciiDocContent calls asciidoctor as an external helper to convert\n// AsciiDoc content to HTML.\nfunc (a *AsciiDocConverter) GetAsciiDocContent(src []byte, ctx converter.DocumentContext) ([]byte, error) {\n\tif !hexec.InPath(asciiDocBinaryName) {\n\t\treturn nil, fmt.Errorf(\"asciidoctor not found in $PATH, cannot render %q\", ctx.DocumentName)\n\t}\n\n\targs, err := a.ParseArgs(ctx)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\targs = append(args, \"-\") // read from stdin\n\n\ta.Cfg.Logger.Infof(\"Rendering %s using Asciidoctor args %s ...\", ctx.DocumentName, args)\n\n\treturn internal.ExternallyRenderContent(a.Cfg, ctx, src, asciiDocBinaryName, args)\n}\n\nfunc (a *AsciiDocConverter) ParseArgs(ctx converter.DocumentContext) ([]string, error) {\n\tcfg := a.Cfg.MarkupConfig().AsciiDocExt\n\targs := []string{}\n\n\targs = a.AppendArg(args, \"-b\", cfg.Backend, asciidocext_config.CliDefault.Backend, asciidocext_config.AllowedBackend)","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/gohugoio/hugo/blob/8a468df065a75c1c7cf9f6850f32148746590ea5/markup/asciidocext/internal/converter.go#L73-L109","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Install Asciidoctor: `gem install asciidoctor` (or `apt install asciidoctor` / `brew install asciidoctor`).","Ensure the gem bin directory is on `$PATH` in the environment running Hugo (especially CI); verify with `asciidoctor --version`.","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.","If AsciiDoc isn't intended, rename/remove the `.adoc` files so Hugo doesn't invoke the converter."],"exampleFix":"# before: CI image lacks asciidoctor\nhugo\n# after\ngem install asciidoctor\nexport PATH=\"$(ruby -e 'print Gem.user_dir')/bin:$PATH\"\nhugo","handlingStrategy":"validation","validationCode":"if _, err := exec.LookPath(\"asciidoctor\"); err != nil {\n    log.Fatal(\"asciidoctor not in PATH; install it or drop .adoc content\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check `exec.LookPath(\"asciidoctor\")` at startup before building sites with .adoc content","Pin asciidoctor in your CI image/Dockerfile","Document the AsciiDoc dependency in your project README"],"tags":["hugo","asciidoc","asciidoctor","path","external-binary"],"analyzedSha":"8a468df065a75c1c7cf9f6850f32148746590ea5","analyzedAt":"2026-07-31T21:23:07.045Z","schemaVersion":2}