From 45c665d396ed368261f4a63ceee753c7f6dc5bf9 Mon Sep 17 00:00:00 2001 From: Helder Pereira Date: Thu, 23 Jul 2020 14:59:48 +0100 Subject: [PATCH] Fix Asciidoctor args * Fix Asciidoctor args * Fix Asciidoctor args documentation * Update AsciiDoc documentation Co-authored-by: Derk Muenchhausen Fixes #7493 --- docs/content/en/content-management/formats.md | 15 ++-- .../asciidocext/asciidocext_config/config.go | 16 ++-- markup/asciidocext/convert.go | 32 ++++---- markup/asciidocext/convert_test.go | 76 +++++++++++++++++-- 4 files changed, 104 insertions(+), 35 deletions(-) diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md index f84d912bab9..94d7e0f1731 100644 --- 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,14 +74,14 @@ 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`. @@ -89,7 +89,6 @@ workingfoldercurrent | `false` | Set the working folder to the rendered `adoc` f [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 index aef998b516e..79d103dc7ed 100644 --- 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 index 5c794819b5f..7dd3e3533aa 100644 --- 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 index 7fa1035c395..dc9d76c0776 100644 --- 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,8 +138,8 @@ 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) { @@ -88,6 +147,7 @@ func TestAsciidoctorWorkingFolderCurrent(t *testing.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,