Skip to content

Commit

Permalink
Improve goldmark config docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jmooring
jmooring authored Oct 13, 2023
1 parent 4476329 commit 5bd9772
Show file tree
Hide file tree
Showing 2 changed files with 117 additions and 56 deletions.
49 changes: 3 additions & 46 deletions content/en/content-management/formats.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,7 @@ Hugo passes reasonable default arguments to these external helpers by default:
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.
{{% /note %}}

### External helper Asciidoctor
### Asciidoctor

The Asciidoctor community offers a wide set of tools for the AsciiDoc format that can be installed additionally to Hugo.
[See the Asciidoctor docs for installation instructions](https://asciidoctor.org/docs/install-toolchain/). Make sure that also all
Expand All @@ -59,52 +59,9 @@ optional extensions like `asciidoctor-diagram` or `asciidoctor-html5s` are insta
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:
Some Asciidoctor parameters can be customized in Hugo. See [details].

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`.
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" />}}

Notice that for security concerns only extensions that do not have path separators (either `\`, `/` or `.`) are allowed. That means that extensions can only be invoked if they are in one's ruby's `$LOAD_PATH` (ie. most likely, the extension has been installed by the user). Any extension declared relative to the website's path will not be accepted.

Example of how to set extensions and attributes:

```yml
[markup.asciidocExt]
extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
workingFolderCurrent = true
[markup.asciidocExt.attributes]
my-base-url = "https://example.com/"
my-attribute-name = "my value"
```

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

```txt
INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
```
[details]: /getting-started/configuration-markup/#asciidoc

## Learn markdown

Expand Down
124 changes: 114 additions & 10 deletions content/en/getting-started/configuration-markup.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,21 +12,47 @@ slug: configuration-markup
toc: true
---

## Default configuration
## Default handler

See [Goldmark](#goldmark) for settings related to the default markdown handler in Hugo.
By default, Hugo uses [Goldmark] to render markdown to HTML.

Below are all markup related configuration in Hugo with their default settings:
{{< code-toggle file=hugo copy=false >}}
[markup]
defaultMarkdownHandler = 'goldmark'
{{< /code-toggle >}}

{{< code-toggle config="markup" />}}
Files with the `.md` or `.markdown` extension are processed as markdown, provided that you have not specified a different [content format] using the `markup` field in front matter.

**See each section below for details.**
To use a different renderer for markdown files, specify one of `asciidocext`, `org`, `pandoc`, or `rst` in your site configuration.

## Goldmark
defaultMarkdownHandler|Description
:--|:--
`asciidocext`|[AsciiDoc]
`goldmark`|[Goldmark]
`org`|[Emacs Org Mode]
`pandoc`|[Pandoc]
`rst`|[reStructuredText]

To use Asciidoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].

{{% note %}}
Unless you need a unique capability provided by one of the alternate markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the [CommonMark] specification, and is compatible with [GitHub Flavored Markdown] (GFM).

[commonmark]: https://spec.commonmark.org/0.30/
[github flavored markdown]: https://github.github.com/gfm/
{{% /note %}}

[Goldmark](https://github.com/yuin/goldmark/) is from Hugo 0.60 the default library used for Markdown. It's fast, it's [CommonMark](https://spec.commonmark.org/current/) compliant and it's very flexible.
[asciidoc]: https://asciidoc.org/
[content format]: /content-management/formats/#list-of-content-formats
[emacs org mode]: https://orgmode.org/
[goldmark]: https://github.com/yuin/goldmark/
[pandoc]: https://pandoc.org/
[restructuredtext]: https://docutils.sourceforge.io/rst.html
[security policy]: /about/security-model/#security-policy

This is the default configuration:
## Goldmark

This is the default configuration for the Goldmark markdown renderer:

{{< code-toggle config="markup.goldmark" />}}

Expand All @@ -41,7 +67,21 @@ unsafe
: By default, Goldmark does not render raw HTML and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on.

typographer
: This extension substitutes punctuations with typographic entities like [smartypants](https://daringfireball.net/projects/smartypants/).
: The typographer extension replaces certain character combinations with HTML entities as specified below:

Markdown|Replaced by|Description
:--|:--|:--
`...`|`&hellip;`|horizontal ellipsis
`'`|`&rsquo;`|apostrophe
`--`|`&ndash;`|endash
`---`|`&emdash;`|emdash

Check warning on line 77 in content/en/getting-started/configuration-markup.md

View workflow job for this annotation

GitHub Actions / spellcheck 

Unknown word (emdash)
`«`|`&laquo;`|left angle quote
`“`|`&ldquo;`|left double quote
`‘`|`&lsquo;`|left single quote
`»`|`&raquo;`|right angle quote
`”`|`&rdquo;`|right double quote
`’`|`&rsquo;`|right single quote


attribute
: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets (`{.myclass class="class1 class2" }`) and placing it _after the Markdown element it decorates_, on the same line for titles and on a new line directly below for blocks.
Expand Down Expand Up @@ -82,6 +122,70 @@ Note that attributes in [code fences](/content-management/syntax-highlighting/#h
autoHeadingIDType ("github")
: The strategy used for creating auto IDs (anchor names). Available types are `github`, `github-ascii` and `blackfriday`. `github` produces GitHub-compatible IDs, `github-ascii` will drop any non-Ascii characters after accent normalization, and `blackfriday` will make the IDs compatible with Blackfriday, the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the [anchorize](/functions/urls/anchorize) template func.

## Asciidoc

This is the default configuration for the AsciiDoc markdown renderer:

{{< code-toggle config="markup.asciidocExt" />}}

attributes
: (`map`) Variables to be referenced in your AsciiDoc file. This is a list of variable name/value maps. See Asciidoctor’s [attributes].

[attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions

backend:
: (`string`) Don’t change this unless you know what you are doing.

extensions
: (`[]string`) Possible extensions are `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, and `asciidoctor-question`.

failureLevel
: (`string`) The minimum logging level that triggers a non-zero exit code (failure).

noHeaderOrFooter
: (`bool`) 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.

preserveTOC
: (`bool`) By default, Hugo removes the table of contents generated by Asciidoctor and provides it through the built-in variable `.TableOfContents` 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.

safeMode
: (`string`) Safe mode level `unsafe`, `safe`, `server`, or `secure`. Don’t change this unless you know what you are doing.

sectionNumbers
: (`bool`) Auto-number section titles.

trace
: (`bool`) Include backtrace information on errors.

verbose
: (`bool`) Verbosely print processing information and configuration file checks to stderr.

workingFolderCurrent
: (`bool`) Sets the working directory to be the same as that of the AsciiDoc file being processed, so that [include] will work with relative paths. This setting uses the asciidoctor cli parameter --base-dir and attribute outdir=. For rendering diagrams with [asciidoctor-diagram], `workingFolderCurrent` must be set to `true`.

[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
[include]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files

Notice that for security concerns only extensions that do not have path separators (either `\`, `/` or `.`) are allowed. That means that extensions can only be invoked if they are in the Ruby's `$LOAD_PATH` (ie. most likely, the extension has been installed by the user). Any extension declared relative to the website's path will not be accepted.

Example of how to set extensions and attributes:

```yml
[markup.asciidocExt]
extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
workingFolderCurrent = true
[markup.asciidocExt.attributes]
my-base-url = "https://example.com/"
my-attribute-name = "my value"
```

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

```txt
INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...
```

## Highlight

This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/).
Expand Down Expand Up @@ -110,6 +214,6 @@ endLevel
ordered
: If `true`, generates an ordered list instead of an unordered list.

## Markdown render hooks
## Render hooks

See [Markdown Render Hooks](/templates/render-hooks/).

0 comments on commit 5bd9772

Please sign in to comment.