diff options
Diffstat (limited to 'content/en/content-management/formats.md')
| -rw-r--r-- | content/en/content-management/formats.md | 55 |
1 files changed, 35 insertions, 20 deletions
diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md index f8ccffefd..576ce2fa3 100644 --- a/content/en/content-management/formats.md +++ b/content/en/content-management/formats.md @@ -43,7 +43,7 @@ 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, +Some of the formats in the table above need external helpers installed on your PC. For example, for AsciiDoc files, 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. @@ -69,33 +69,48 @@ The Asciidoctor community offers a wide set of tools for the AsciiDoc format tha [See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/). Make sure that also all optional extensions like `asciidoctor-diagram` or `asciidoctor-html5s` are installed if required. -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` | 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 | `false` | Verbosely print processing information and configuration file checks to stderr. -trace | `false` | 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`. +{{% note %}} +External `asciidoctor` command requires Hugo rendering to _disk_ to a specific destination directory. It is required to run Hugo with the command option `--destination`. +{{% /note %}} + +Some [Asciidoctor](https://asciidoctor.org/man/asciidoctor/) parameters can be customized in Hugo: + +Parameter | Comment +--- | --- +backend | Don't change this unless you know what you are doing. +doctype | Currently, the only document type supported in Hugo 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 AsciiDoc file. This is a list of variable name/value maps. See [Asciidoctor's attributes](https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions). +noHeaderOrFooter | 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 | Safe mode level `unsafe`, `safe`, `server` or `secure`. Don't change this unless you know what you are doing. +sectionNumbers | Auto-number section titles. +verbose | Verbosely print processing information and configuration file checks to stderr. +trace | Include backtrace information on errors. +failureLevel | The minimum logging level that triggers a non-zero exit code (failure). + +Hugo provides additional settings that don't map directly to Asciidoctor's CLI options: + +workingFolderCurrent +: Sets the working directory to be the same as that of the AsciiDoc file being processed, so that [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 diagrams with [asciidoctor-diagram](https://asciidoctor.org/docs/asciidoctor-diagram/), `workingFolderCurrent` must be set to `true`. + +preserveTOC +: By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable [`.TableOfContents`](/content-management/toc/) to enable further customization and better integration with the various Hugo themes. This option can be set to `true` to preserve Asciidoctor's TOC in the generated page. + +Below are all the AsciiDoc related settings in Hugo with their default values: + +{{< code-toggle config="markup.asciidocExt" />}} + +Example of how to set extensions and attributes: ``` -[markup.asciidocext] +[markup.asciidocExt] extensions = ["asciidoctor-html5s", "asciidoctor-diagram"] workingFolderCurrent = true - [markup.asciidocext.attributes] + [markup.asciidocExt.attributes] my-base-url = "https://example.com/" my-attribute-name = "my value" ``` -Important: External `asciidoctor` requires Hugo rendering to _disk_ to a specific destination folder. It is required to run Hugo with the command option `--destination`! - In a complex Asciidoctor environment it is sometimes helpful to debug the exact call to your external helper with all parameters. Run Hugo with `-v`. You will get an output like |