Fix Asciidoctor args

* Fix Asciidoctor args * Fix Asciidoctor args documentation * Update AsciiDoc documentation Co-authored-by: Derk Muenchhausen <[email protected]> Fixes #7493
gohugoio · Jul 23, 2020 · 45c665d · 45c665d
1 parent a06c06a
commit 45c665d
Show file tree

Hide file tree

Showing 4 changed files with 104 additions and 35 deletions.
diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md
@@ -33,7 +33,7 @@ The current list of content formats in Hugo:
 | Blackfriday | blackfriday  |Blackfriday will eventually be deprecated.|
 |MMark|mmark|Mmark is deprecated and will be removed in a future release.|
 |Emacs Org-Mode|org|See [go-org](https://github.com/niklasfasching/go-org).|
-|AsciiDoc|asciidoc, adoc, ad|Needs AsciiDoc or [Asciidoctor][ascii] installed.|
+|AsciiDoc|asciidocext, adoc, ad|Needs [Asciidoctor][ascii] installed.|
 |RST|rst|Needs [RST](http://docutils.sourceforge.net/rst.html) installed.|
 |Pandoc|pandoc, pdc|Needs [Pandoc](https://www.pandoc.org/) installed.|
 |HTML|html, htm|To be treated as a content file, with layout, shortcodes etc., it must have front matter. If not, it will be copied as-is.|
@@ -44,17 +44,17 @@ The `markup identifier` is fetched from either the `markup` variable in front ma
 ## External Helpers
 
 Some of the formats in the table above needs external helpers installed on your PC. For example, for AsciiDoc files, 
-Hugo will try to call the `asciidoctor` or `asciidoc` command. This means that you will have to install the associated 
+Hugo will try to call the `asciidoctor` command. This means that you will have to install the associated
 tool on your machine to be able to use these formats.
 
 Hugo passes reasonable default arguments to these external helpers by default:
 
-- `asciidoctor`: `--no-header-footer -v -`
+- `asciidoctor`: `--no-header-footer --trace -`
 - `rst2html`: `--leave-comments --initial-header-level=2`
 - `pandoc`: `--mathjax`
 
 {{% warning "Performance of External Helpers" %}}
-Because additional formats are external commands generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
+Because additional formats are external commands, generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome.
 {{% /warning %}}
 
 ### External Helper AsciiDoc
@@ -74,22 +74,21 @@ Asciidoctor parameters can be customized in Hugo:
 Parameter | Default | Comment
 --- | --- | --- 
 backend | `html5` | Don't change this unless you know what you are doing.
-doctype | `article` | Document type (article, book or manpage).
+doctype | `article` | Currently supported Document type is `article`.
 extensions | | Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`,	`asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, `asciidoctor-question`, `asciidoctor-rouge`.
 attributes | | Variables to be referenced in your `adoc` file. This is a list of variable name/value maps. See [Asciidoctor#attributes](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions).
 noheaderorfooter | true | Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Don't change this unless you know what you are doing. 
 safemode | `unsafe` | Safe mode level `unsafe`, `safe`, `server` or `secure`. Don't change this unless you know what you are doing.
 sectionnumbers | `false` | Auto-number section titles.
-verbose | `true` | Verbosely print processing information and configuration file checks to stderr.
-trace | `false` | Include backtrace information on errors.
+verbose | `false` | Verbosely print processing information and configuration file checks to stderr.
+trace | `true` | Include backtrace information on errors.
 failurelevel | `fatal` | The minimum logging level that triggers a non-zero exit code (failure).
 workingfoldercurrent | `false` | Set the working folder to the rendered `adoc` file, so [include](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files) will work with relative paths. This setting uses the `asciidoctor` cli parameter `--base-dir` and attribute `outdir=`. For rendering [asciidoctor-diagram](https://asciidoctor.org/docs/asciidoctor-diagram/)  `workingfoldercurrent` must be set to `true`.
 
 ```
 [markup.asciidocext]
     extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
     workingFolderCurrent = true
-    trace = true
     [markup.asciidocext.attributes]
         my-base-url = "https://example.com/"
         my-attribute-name = "my value"

diff --git a/markup/asciidocext/asciidocext_config/config.go b/markup/asciidocext/asciidocext_config/config.go
@@ -14,23 +14,28 @@
 // Package asciidoc_config holds asciidoc related configuration.
 package asciidocext_config
 
-// DefaultConfig holds the default asciidoc configuration.
-// These values are asciidoctor cli defaults (see https://asciidoctor.org/docs/user-manual/)
 var (
+	// Default holds Hugo's default asciidoc configuration.
 	Default = Config{
 		Backend:              "html5",
-		DocType:              "article",
 		Extensions:           []string{},
 		Attributes:           map[string]string{},
 		NoHeaderOrFooter:     true,
 		SafeMode:             "unsafe",
 		SectionNumbers:       false,
-		Verbose:              true,
-		Trace:                false,
+		Verbose:              false,
+		Trace:                true,
 		FailureLevel:         "fatal",
 		WorkingFolderCurrent: false,
 	}
 
+	// CliDefault holds Asciidoctor CLI defaults (see https://asciidoctor.org/docs/user-manual/)
+	CliDefault = Config{
+		Backend:      "html5",
+		SafeMode:     "unsafe",
+		FailureLevel: "fatal",
+	}
+
 	AllowedExtensions = map[string]bool{
 		"asciidoctor-html5s":           true,
 		"asciidoctor-bibtex":           true,
@@ -72,7 +77,6 @@ var (
 // Config configures asciidoc.
 type Config struct {
 	Backend              string
-	DocType              string
 	Extensions           []string
 	Attributes           map[string]string
 	NoHeaderOrFooter     bool

diff --git a/markup/asciidocext/convert.go b/markup/asciidocext/convert.go
@@ -69,7 +69,6 @@ func (a *asciidocConverter) getAsciidocContent(src []byte, ctx converter.Documen
 	}
 
 	args := a.parseArgs(ctx)
-	args = append(args, "--trace")
 	args = append(args, "-")
 
 	a.cfg.Logger.INFO.Println("Rendering", ctx.DocumentName, "with", path, "using asciidoctor args", args, "...")
@@ -81,9 +80,7 @@ func (a *asciidocConverter) parseArgs(ctx converter.DocumentContext) []string {
 	var cfg = a.cfg.MarkupConfig.AsciidocExt
 	args := []string{}
 
-	if asciidocext_config.AllowedBackend[cfg.Backend] && cfg.Backend != asciidocext_config.Default.Backend {
-		args = append(args, "-b", cfg.Backend)
-	}
+	args = a.appendArg(args, "-b", cfg.Backend, asciidocext_config.CliDefault.Backend, asciidocext_config.AllowedBackend)
 
 	for _, extension := range cfg.Extensions {
 		if !asciidocext_config.AllowedExtensions[extension] {
@@ -147,29 +144,36 @@ func (a *asciidocConverter) parseArgs(ctx converter.DocumentContext) []string {
 		a.cfg.Logger.WARN.Println("asciidoctor parameter NoHeaderOrFooter is expected for correct html rendering")
 	}
 
-	if cfg.SectionNumbers != asciidocext_config.Default.SectionNumbers {
+	if cfg.SectionNumbers {
 		args = append(args, "--section-numbers")
 	}
 
-	if cfg.Verbose != asciidocext_config.Default.Verbose {
-		args = append(args, "-v")
+	if cfg.Verbose {
+		args = append(args, "--verbose")
 	}
 
-	if cfg.Trace != asciidocext_config.Default.Trace {
+	if cfg.Trace {
 		args = append(args, "--trace")
 	}
 
-	if asciidocext_config.AllowedFailureLevel[cfg.FailureLevel] && cfg.FailureLevel != asciidocext_config.Default.FailureLevel {
-		args = append(args, "--failure-level", cfg.FailureLevel)
-	}
+	args = a.appendArg(args, "--failure-level", cfg.FailureLevel, asciidocext_config.CliDefault.FailureLevel, asciidocext_config.AllowedFailureLevel)
 
-	if asciidocext_config.AllowedSafeMode[cfg.SafeMode] && cfg.SafeMode != asciidocext_config.Default.SafeMode {
-		args = append(args, "--safe-mode", cfg.SafeMode)
-	}
+	args = a.appendArg(args, "--safe-mode", cfg.SafeMode, asciidocext_config.CliDefault.SafeMode, asciidocext_config.AllowedSafeMode)
 
 	return args
 }
 
+func (a *asciidocConverter) appendArg(args []string, option, value, defaultValue string, allowedValues map[string]bool) []string {
+	if value != defaultValue {
+		if allowedValues[value] {
+			args = append(args, option, value)
+		} else {
+			a.cfg.Logger.ERROR.Println("Unsupported asciidoctor value `" + value + "` for option " + option + " was passed in and will be ignored.")
+		}
+	}
+	return args
+}
+
 func getAsciidoctorExecPath() string {
 	path, err := exec.LookPath("asciidoctor")
 	if err != nil {

diff --git a/markup/asciidocext/convert_test.go b/markup/asciidocext/convert_test.go
@@ -18,13 +18,12 @@
 package asciidocext
 
 import (
-	"github.com/gohugoio/hugo/markup/markup_config"
 	"path/filepath"
-	"strings"
 	"testing"
 
 	"github.com/gohugoio/hugo/common/loggers"
 	"github.com/gohugoio/hugo/markup/converter"
+	"github.com/gohugoio/hugo/markup/markup_config"
 	"github.com/spf13/viper"
 
 	qt "github.com/frankban/quicktest"
@@ -51,8 +50,68 @@ func TestAsciidoctorDefaultArgs(t *testing.T) {
 	c.Assert(ac, qt.Not(qt.IsNil))
 
 	args := ac.parseArgs(converter.DocumentContext{})
-	c.Assert(args, qt.Not(qt.IsNil))
-	c.Assert(strings.Join(args, " "), qt.Equals, "--no-header-footer")
+	expected := []string{"--no-header-footer", "--trace"}
+	c.Assert(args, qt.DeepEquals, expected)
+}
+
+func TestAsciidoctorNonDefaultArgs(t *testing.T) {
+	c := qt.New(t)
+	cfg := viper.New()
+	mconf := markup_config.Default
+	mconf.AsciidocExt.Backend = "manpage"
+	mconf.AsciidocExt.NoHeaderOrFooter = false
+	mconf.AsciidocExt.SafeMode = "safe"
+	mconf.AsciidocExt.SectionNumbers = true
+	mconf.AsciidocExt.Verbose = true
+	mconf.AsciidocExt.Trace = false
+	mconf.AsciidocExt.FailureLevel = "warn"
+	p, err := Provider.New(
+		converter.ProviderConfig{
+			Cfg:          cfg,
+			MarkupConfig: mconf,
+			Logger:       loggers.NewErrorLogger(),
+		},
+	)
+	c.Assert(err, qt.IsNil)
+
+	conv, err := p.New(converter.DocumentContext{})
+	c.Assert(err, qt.IsNil)
+
+	ac := conv.(*asciidocConverter)
+	c.Assert(ac, qt.Not(qt.IsNil))
+
+	args := ac.parseArgs(converter.DocumentContext{})
+	expected := []string{"-b", "manpage", "--section-numbers", "--verbose", "--failure-level", "warn", "--safe-mode", "safe"}
+	c.Assert(args, qt.DeepEquals, expected)
+}
+
+func TestAsciidoctorDisallowedArgs(t *testing.T) {
+	c := qt.New(t)
+	cfg := viper.New()
+	mconf := markup_config.Default
+	mconf.AsciidocExt.Backend = "disallowed-backend"
+	mconf.AsciidocExt.Extensions = []string{"disallowed-extention"}
+	mconf.AsciidocExt.Attributes = map[string]string{"outdir": "disallowed-attribute"}
+	mconf.AsciidocExt.SafeMode = "disallowed-safemode"
+	mconf.AsciidocExt.FailureLevel = "disallowed-failurelevel"
+	p, err := Provider.New(
+		converter.ProviderConfig{
+			Cfg:          cfg,
+			MarkupConfig: mconf,
+			Logger:       loggers.NewErrorLogger(),
+		},
+	)
+	c.Assert(err, qt.IsNil)
+
+	conv, err := p.New(converter.DocumentContext{})
+	c.Assert(err, qt.IsNil)
+
+	ac := conv.(*asciidocConverter)
+	c.Assert(ac, qt.Not(qt.IsNil))
+
+	args := ac.parseArgs(converter.DocumentContext{})
+	expected := []string{"--no-header-footer", "--trace"}
+	c.Assert(args, qt.DeepEquals, expected)
 }
 
 func TestAsciidoctorDiagramArgs(t *testing.T) {
@@ -62,7 +121,7 @@ func TestAsciidoctorDiagramArgs(t *testing.T) {
 	mconf.AsciidocExt.NoHeaderOrFooter = true
 	mconf.AsciidocExt.Extensions = []string{"asciidoctor-html5s", "asciidoctor-diagram"}
 	mconf.AsciidocExt.Backend = "html5s"
-
+	mconf.AsciidocExt.Trace = false
 	p, err := Provider.New(
 		converter.ProviderConfig{
 			Cfg:          cfg,
@@ -79,15 +138,16 @@ func TestAsciidoctorDiagramArgs(t *testing.T) {
 	c.Assert(ac, qt.Not(qt.IsNil))
 
 	args := ac.parseArgs(converter.DocumentContext{})
-	c.Assert(len(args), qt.Equals, 7)
-	c.Assert(strings.Join(args, " "), qt.Equals, "-b html5s -r asciidoctor-html5s -r asciidoctor-diagram --no-header-footer")
+	expected := []string{"-b", "html5s", "-r", "asciidoctor-html5s", "-r", "asciidoctor-diagram", "--no-header-footer"}
+	c.Assert(args, qt.DeepEquals, expected)
 }
 
 func TestAsciidoctorWorkingFolderCurrent(t *testing.T) {
 	c := qt.New(t)
 	cfg := viper.New()
 	mconf := markup_config.Default
 	mconf.AsciidocExt.WorkingFolderCurrent = true
+	mconf.AsciidocExt.Trace = false
 	p, err := Provider.New(
 		converter.ProviderConfig{
 			Cfg:          cfg,
@@ -121,6 +181,7 @@ func TestAsciidoctorWorkingFolderCurrentAndExtensions(t *testing.T) {
 	mconf.AsciidocExt.Extensions = []string{"asciidoctor-html5s", "asciidoctor-diagram"}
 	mconf.AsciidocExt.Backend = "html5s"
 	mconf.AsciidocExt.WorkingFolderCurrent = true
+	mconf.AsciidocExt.Trace = false
 	p, err := Provider.New(
 		converter.ProviderConfig{
 			Cfg:          cfg,
@@ -156,6 +217,7 @@ func TestAsciidoctorAttributes(t *testing.T) {
 	cfg := viper.New()
 	mconf := markup_config.Default
 	mconf.AsciidocExt.Attributes = map[string]string{"my-base-url": "https://gohugo.io/", "my-attribute-name": "my value"}
+	mconf.AsciidocExt.Trace = false
 	p, err := Provider.New(
 		converter.ProviderConfig{
 			Cfg:          cfg,