markup.asciidocExt site variable to configure AsciiDocget-leaf-text shortcode to get a snippet in the current leaf bundleFor a long time I’ve wanted to modernize the Infinite Ink website and in 2017,[2] I tentatively decided to use AsciiDoc and Hugo to do that. I chose the AsciiDoc markup language because I wanted to use a lightweight markup language that is richer and more standardized than Markdown. I chose the Hugo static site generator because I wanted a generator that supports AsciiDoc and has no dependencies (other than an implementation of AsciiDoc such as Asciidoctor).
For more than two years, this decision was tentative and I wrote my articles in pure AsciiDoc. This involved…
putting an AsciiDoc Document Header just below the Hugo front matter of each article,[3]
using a lot of AsciiDoc attributes,
using AsciiDoc include directives,
using AsciiDoc’s ifdef and friends,
doing convoluted things with paths,
thinking that I needed to learn how to use AsciiDoc’s code-block syntax highlighting,
and thinking that I needed an easy way to update Ruby and the Asciidoctor Ruby gem.
In 2020, I decided to no longer be tentative about this and to no longer write in pure AsciiDoc. Instead, I now promiscuously use Hugo shortcodes throughout my writing. This means that for the Infinite Ink website, AsciiDoc and Hugo are intertwingled and if I ever decide to change either my markup language or site generator, it will be a PITA. In other words, I’m committed to this AsciiDoc+Hugo marriage and I hope it works out!🤞
markup.asciidocExt site variable to configure AsciiDocStarting with
Hugo v0.74.0,
which was released 2020-July-13,
you can
configure AsciiDoc in your Hugo config file.
Here is an excerpt of
Infinite Ink’s config.yaml:
markup:
asciidocExt:
preserveTOC: true
workingFolderCurrent: false # default is false
attributes:
toc: macro
hide-uri-scheme: true@ # trailing @ means ok to override
sectlinks: true
octothorpe: # # hash
colon: :
rsolidus: \ # backslash
underscore: _
Note:
The hide-uri-scheme attribute hides the scheme part, such as https://, of a
raw URI.
For example, if
https://www.ii.com
is in a source file, it will be
displayed
as
www.ii.com
in the
rendered
destination file.
An article where I turned off this attribute (via
The
emphasized
workingFolderCurrent and sectlinks
settings
are discussed in
section 5
below.
Asciidoctor supports code-block syntax highlighting, but it involves installing and maintaining a Ruby gem. Instead of messing around with Ruby, I prefer to use Hugo’s built-in highlight shortcode.
Here is the source code behind the YAML fragment in the previous section that is displayed with syntax highlighting.
{{< highlight yaml "hl_lines=4 8" >}}
markup:
asciidocExt:
preserveTOC: true
workingFolderCurrent: false # default is false
attributes:
toc: macro
hide-uri-scheme: true@ # trailing @ means ok to override
sectlinks: true
octothorpe: # # hash
colon: :
rsolidus: \ # backslash
underscore: _
{{< /highlight >}}The first and last lines of this source code call Hugo’s built-in highlight shortcode. To learn about this shortcode, see the highlight section of Infinite Ink’s Hugo Shortcodes.
Before my decision to commit to AsciiDoc+Hugo, all my reusable content snippets were in AsciiDoc attributes and AsciiDoc includes. I now use Hugo shortcodes for some AsciiDoc content snippets. Below is an example of one of Infinite Ink’s snippets.
The following Hugo shortcode comprises pure AsciiDoc markup at the top and a Go Template comment block at the bottom.
The home page layout file can be named either `home.html` or `index.html`.
I prefer to name it `home.html` because the word `index` is
https://wikipedia.org/wiki/Semantic_overload[semantically overloaded,title="'Semantic overload' at Wikipedia"]
in Hugo.
{{- /*
USAGE: {{% snippets/hugo-home-v-index %}}
PATH: layouts/shortcodes/snippets/hugo-home-v-index.adoc
N2S: This entire file is *published* in intertwingling-asciidoc-hugo
*/ -}}This shortcode is rendered…
in the Hugo Tutorial in the section Non-standard Hugo preferences and in endnote #26;
and in this page in an “example block” just below this line:
The home page layout file can be named either home.html or index.html.
I prefer to name it home.html because the word index is
semantically overloaded
in Hugo.
💡 |
|
An AsciiDoc include is better than a Hugo shortcode…
if the snippet resides somewhere other than
a project’s layouts/shortcodes/ directory, which is where Hugo reusable shortcodes must reside,
or if you do not want the safety features that Hugo shortcodes (and Go Templates in general) enforce,
or if you want to use an AsciiDoc include feature, such as
indenting (or unindenting) lines,
level offsetting,
or including only specific lines.
In
the source code of
section 3
of
Infinite Ink’s
Linkified Section Headings in Hugo-Generated Web Pages,
I use the following AsciiDoc include to display lines 1, 2, and 3 of
the Infinite Ink render hook located at
layouts/_default/_markup/render-heading.html.
include::layouts/_default/_markup/render-heading.html[lines=1..3]
To display all lines of an AsciiDoc include file, use the following syntax.
include::layouts/_default/_markup/render-heading.html[]
This second
AsciiDoc
include line is used in the source code of this section of this page
and is rendered
right here:
<h{{ .Level }} id="{{ .Anchor | safeURL }}">
<a href="#{{ .Anchor | safeURL }}">{{ .Text | safeHTML }}</a>
</h{{ .Level }}>
{{- /*
PATH: layouts/_default/_markup/render-heading.html
FORKED FROM: https://gohugo.io/getting-started/configuration-markup/#heading-link-example
NOTE TO SELF:
* Lines 1-3 of this file are *published* in linkified-section-headings-in-hugo-generated-web-pages
* This entire file is *published* in intertwingling-asciidoc-hugo
*/ -}}Note that
this
included
file
is a Hugo
Markdown render hook
and it
does
for
Markdown what
the
sectlinks: true
config
setting
(from section 2 above)
does for AsciiDoc, i.e.,
linkify section headings.
You can see it
in action in
Infinite Ink’s
Ordinary and Extraordinary Markdown,
which is
an
Infinite Ink page
that’s
written
in
Markdown rather than
AsciiDoc or
raw HTML.[6]
‼ |
|
In the source of Infinite Ink’s AsciiDoc Kitchen Sink, I use an include like this:
include::content/path/to/bundle/dir/include.forked.txt[leveloffset=+1]
^^^^^^^^^^^^^^
NoteTo learn about this, see:
docs.asciidoctor.org/asciidoc/latest/directives/include-with-leveloffset/
and the section How I included the above “Asciidoctor Demo” on this page in Infinite Ink’s AsciiDoc Kitchen Sink.
get-leaf-text shortcode to get a snippet in the current leaf bundleIf a snippet is used in only one page,
you can
turn that page into a Hugo bundle
and
put the snippet inside the bundle directory.
This is what I did with the markup.asciidocExt snippet that is
used in
both
sections 2 and 3
above.
The
directory structure of
this
page, which is a
leaf bundle,
looks
like this:
2020-12-21-intertwingling-asciidoc-hugo/ ├── index.adoc └── markupdotasciidocext.yaml
In index.adoc, the source code of
section 2 includes this fragment:
{{< highlight yaml "hl_lines=4 8" >}}
{{% get-leaf-text "markupdotasciidocext.yaml" %}}
{{< /highlight >}}
And the source code of section 3 includes this fragment:
[%nowrap]
----
{{</* highlight yaml "hl_lines=4 8" */>}}
{{% get-leaf-text "markupdotasciidocext.yaml" %}}
{{</* /highlight */>}}
----Note:
In AsciiDoc,
code blocks are delimited with
four dashes (
In
the
source files
of
a Hugo project,
shortcode calls can be escaped with
syntax like
{{</*
and
*/>}}.
I do this when I write about a
shortcode, rather than actually use a shortcode.
To learn about Infinite Ink’s get-leaf-text custom shortcode,
see the
get-leaf-text section
of Infinite Ink’s
Hugo Shortcodes.
To learn more about intertwingling AsciiDoc and Hugo, see…
Infinite Ink’s Hugo Shortcodes, especially
Infinite Ink’s Linkified Section Headings in Hugo-Generated Web Pages
Infinite Ink’s Hugo’s RenderString Method (featuring GoAT in AsciiDoc)
Your public comment or question might immediately improve this page or help me to (eventually) improve this page.