diff options
Diffstat (limited to 'docs/content/en/getting-started')
| -rw-r--r-- | docs/content/en/getting-started/configuration-markup.md | 126 | ||||
| -rw-r--r-- | docs/content/en/getting-started/configuration.md | 17 | ||||
| -rw-r--r-- | docs/content/en/getting-started/glossary.md | 6 |
3 files changed, 127 insertions, 22 deletions
diff --git a/docs/content/en/getting-started/configuration-markup.md b/docs/content/en/getting-started/configuration-markup.md index dca2b3c52..02c4ea998 100644 --- a/docs/content/en/getting-started/configuration-markup.md +++ b/docs/content/en/getting-started/configuration-markup.md @@ -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" />}} @@ -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 +:--|:--|:-- +`...`|`…`|horizontal ellipsis +`'`|`’`|apostrophe +`--`|`–`|en dash +`---`|`—`|em dash +`«`|`«`|left angle quote +`“`|`“`|left double quote +`‘`|`‘`|left single quote +`»`|`»`|right angle quote +`”`|`”`|right double quote +`’`|`’`|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. @@ -80,7 +120,71 @@ 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/anchorize/) template func. +: 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 @@ -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/). diff --git a/docs/content/en/getting-started/configuration.md b/docs/content/en/getting-started/configuration.md index 978412bb9..2187540ae 100644 --- a/docs/content/en/getting-started/configuration.md +++ b/docs/content/en/getting-started/configuration.md @@ -428,7 +428,7 @@ URL to be used as a placeholder when a page reference cannot be found in `ref` o Removes [non-spacing marks](https://www.compart.com/en/unicode/category/Mn) from [composite characters](https://en.wikipedia.org/wiki/Precomposed_character) in content paths. ```text -content/post/hügó.md --> https://example.org/post/hugo/ +content/post/hügó.md → https://example.org/post/hugo/ ``` ### rssLimit @@ -477,7 +477,7 @@ Timeout for generating page contents, specified as a [duration](https://pkg.go.d ### timeZone -The time zone (or location), e.g. `Europe/Oslo`, used to parse front matter dates without such information and in the [`time` function](/functions/time/). The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). +The time zone (or location), e.g. `Europe/Oslo`, used to parse front matter dates without such information and in the [`time`] function. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). ### title @@ -555,8 +555,6 @@ useResourceCacheWhen The `build.cachebusters` configuration option was added to support development using Tailwind 3.x's JIT compiler where a `build` configuration may look like this: -<!-- TODO (jmm) writeStats => build.buildStats --> - {{< code-toggle file="hugo" >}} [build] [build.buildStats] @@ -644,7 +642,7 @@ status = 404 ## Configure title case -Set `titleCaseStyle` to specify the title style used by the [title](/functions/title/) template function and the automatic section titles in Hugo. +Set `titleCaseStyle` to specify the title style used by the [title](/functions/strings/title) template function and the automatic section titles in Hugo. Can be one of: @@ -712,10 +710,6 @@ To set configuration parameters, prefix the name with `HUGO_PARAMS_` If you are using snake_cased variable names, the above will not work. Hugo determines the delimiter to use by the first character after `HUGO`. This allows you to define environment variables on the form `HUGOxPARAMSxAPI_KEY=abcdefgh`, using any [allowed](https://stackoverflow.com/questions/2821043/allowed-characters-in-linux-environment-variable-names#:~:text=So%20names%20may%20contain%20any,not%20begin%20with%20a%20digit.) delimiter. -{{< todo >}} -Test and document setting parameters via JSON env var. -{{< /todo >}} - ## Ignore content and data files when rendering **Note:** This works, but we recommend you use the newer and more powerful [includeFiles and excludeFiles](/hugo-modules/configuration/#module-configuration-mounts) mount options. @@ -827,7 +821,7 @@ dir [`.Site.Params`]: /variables/site/ [directory structure]: /getting-started/directory-structure -[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf [lookup order]: /templates/lookup-order/ [Output Formats]: /templates/output-formats/ [templates]: /templates/ @@ -849,3 +843,6 @@ If this is not set, Hugo will use, in order of preference: 1. In a `hugo_cache_$USER` directory below the OS temp dir. If you want to know the current value of `cacheDir`, you can run `hugo config`, e.g: `hugo config | grep cachedir`. + + +[`time`]: /functions/time/astime diff --git a/docs/content/en/getting-started/glossary.md b/docs/content/en/getting-started/glossary.md index 834f72ec5..c15af5170 100644 --- a/docs/content/en/getting-started/glossary.md +++ b/docs/content/en/getting-started/glossary.md @@ -64,6 +64,10 @@ A markup language for creating content. Typically markdown, but may also be HTML A classification of content inferred from the top-level directory name or the `type` set in [front matter](#front-matter). Pages in the root of the content directory, including the home page, are of type "page". Accessed via `.Page.Type` in [templates](#template). See [details](/content-management/types/). +### content view + +A template called with the `.Page.Render` method. See [details](/templates/views/). + ### context Represented by a period "." within a [template action](#template-action), context is the current location in a data structure. For example, while iterating over a [collection](#collection) of pages, the context within each iteration is the page's data structure. The context received by each template depends on template type and/or how it was called. See [details](/templates/introduction/#the-dot). @@ -250,7 +254,7 @@ A packaged combination of [archetypes](#archetype), assets, content, data, [temp ### token -An identifier within a format string, beginning with a colon and replaced with a value when rendered. For example, use tokens in format strings for both [permalinks](/content-management/urls/#permalinks) and [dates](/functions/dateformat/#datetime-formatting-layouts). +An identifier within a format string, beginning with a colon and replaced with a value when rendered. For example, use tokens in format strings for both [permalinks](/content-management/urls/#permalinks) and [dates](/functions/time/format/#localization). ### type |