| 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.|
## 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
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"
// 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,
// Config configures asciidoc.
type Config struct {
Backend string
- DocType string
Extensions []string
Attributes map[string]string
NoHeaderOrFooter bool
}
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, "...")
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] {
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 {
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"
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) {
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,
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) {
cfg := viper.New()
mconf := markup_config.Default
mconf.AsciidocExt.WorkingFolderCurrent = true
+ mconf.AsciidocExt.Trace = false
p, err := Provider.New(
converter.ProviderConfig{
Cfg: cfg,
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,
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,
projects / brevno-suite / hugo / commitdiff