Skip to content

Commit 71f7394

Browse files
jmooringjmooring
authored
content: Reformat procedures to use description lists instead of H3 elements
1 parent 420a788 commit 71f7394

File tree

21 files changed

+1186
-1338
lines changed

21 files changed

+1186
-1338
lines changed

‎content/en/configuration/markup.md‎

Lines changed: 41 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -246,49 +246,47 @@ workingFolderCurrent
246246

247247
Follow the steps below to enable syntax highlighting.
248248

249-
#### Step 1
250-
251-
Set the `source-highlighter` attribute in your site configuration. For example:
252-
253-
{{< code-toggle file=hugo >}}
254-
[markup.asciidocExt.attributes]
255-
source-highlighter = 'rouge'
256-
{{< /code-toggle >}}
257-
258-
#### Step 2
259-
260-
Generate the highlighter CSS. For example:
261-
262-
```text
263-
rougify style monokai.sublime > assets/css/syntax.css
264-
```
265-
266-
#### Step 3
267-
268-
In your base template add a link to the CSS file:
269-
270-
```go-html-template {file="layouts/baseof.html"}
271-
<head>
272-
...
273-
{{ with resources.Get "css/syntax.css" }}
274-
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
275-
{{ end }}
276-
...
277-
</head>
278-
```
279-
280-
Then add the code to be highlighted to your markup:
281-
282-
```text
283-
[#hello,ruby]
284-
----
285-
require 'sinatra'
286-
287-
get '/hi' do
288-
"Hello World!"
289-
end
290-
----
291-
```
249+
Step 1
250+
: Set the `source-highlighter` attribute in your site configuration. For example:
251+
252+
{{< code-toggle file=hugo >}}
253+
[markup.asciidocExt.attributes]
254+
source-highlighter = 'rouge'
255+
{{< /code-toggle >}}
256+
257+
Step 2
258+
: Generate the highlighter CSS. For example:
259+
260+
```text
261+
rougify style monokai.sublime > assets/css/syntax.css
262+
```
263+
264+
Step 3
265+
: In your base template add a link to the CSS file:
266+
267+
```go-html-template {file="layouts/baseof.html"}
268+
<head>
269+
...
270+
{{ with resources.Get "css/syntax.css" }}
271+
<link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
272+
{{ end }}
273+
...
274+
</head>
275+
```
276+
277+
Step 4
278+
: Add the code to be highlighted to your markup:
279+
280+
```text
281+
[#hello,ruby]
282+
----
283+
require 'sinatra'
284+
285+
get '/hi' do
286+
"Hello World!"
287+
end
288+
----
289+
```
292290

293291
### Troubleshooting
294292

‎content/en/configuration/output-formats.md‎

Lines changed: 43 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -44,25 +44,25 @@ isHTML
4444
: (`bool`) Whether to classify the output format as HTML. Hugo uses this value to determine when to create alias redirects and when to inject the LiveReload script. Default is `false`.
4545

4646
isPlainText
47-
: (`bool`) Whether to parse templates for this output format with Go's [text/template] package instead of the [html/template] package. Default is `false`.
47+
: (`bool`) Whether to parse templates for this output format with Go's [text/template][] package instead of the [html/template][] package. Default is `false`.
4848

4949
mediaType
50-
: (`string`) The [media type](g) of the published file. This must match one of the [configured media types].
50+
: (`string`) The [media type](g) of the published file. This must match one of the [configured media types][].
5151

5252
notAlternative
53-
: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`] method on a `Page` object. Default is `false`.
53+
: (`bool`) Whether to exclude this output format from the values returned by the [`AlternativeOutputFormats`][] method on a `Page` object. Default is `false`.
5454

5555
noUgly
56-
: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`] are enabled in your site configuration. Default is `false`.
56+
: (`bool`) Whether to disable ugly URLs for this output format when [`uglyURLs`][] are enabled in your site configuration. Default is `false`.
5757

5858
path
59-
: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`]. If omitted, Hugo will use the file's original content path for publishing.
59+
: (`string`) The first segment of the publication path for this output format. This path segment is relative to the root of your [`publishDir`][]. If omitted, Hugo will use the file's original content path for publishing.
6060

6161
permalinkable
62-
: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`] and [`RelPermalink`] methods on a `Page` object. See&nbsp;[details](#link-to-output-formats). Enabled by default for the `html` and `amp` output formats. Default is `false`.
62+
: (`bool`) Whether to return the rendering output format rather than main output format when invoking the [`Permalink`][] and [`RelPermalink`][] methods on a `Page` object. See&nbsp;[details](#link-to-output-formats). Enabled by default for the `html` and `amp` output formats. Default is `false`.
6363

6464
protocol
65-
: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`] parameter in your site configuration, typically `https://`.
65+
: (`string`) The protocol (scheme) of the URL for this output format. For example, `https://` or `webcal://`. Default is the scheme of the [`baseURL`][] parameter in your site configuration, typically `https://`.
6666

6767
rel
6868
: (`string`) If provided, you can assign this value to `rel` attributes in `link` elements when iterating over output formats in your templates. Default is `alternate`.
@@ -93,56 +93,52 @@ The example above shows that when you modify a default content format, you only
9393

9494
You can create new output formats as needed. For example, you may wish to create an output format to support Atom feeds.
9595

96-
### Step 1
96+
Step 1
97+
: Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types][], you must create it first.
9798

98-
Output formats require a specified media type. Because Atom feeds use `application/atom+xml`, which is not one of the [default media types], you must create it first.
99+
{{< code-toggle file=hugo >}}
100+
[mediaTypes.'application/atom+xml']
101+
suffixes = ['atom']
102+
{{< /code-toggle >}}
99103

100-
{{< code-toggle file=hugo >}}
101-
[mediaTypes.'application/atom+xml']
102-
suffixes = ['atom']
103-
{{< /code-toggle >}}
104-
105-
See [configure media types] for more information.
106-
107-
### Step 2
108-
109-
Create a new output format:
110-
111-
{{< code-toggle file=hugo >}}
112-
[outputFormats.atom]
113-
mediaType = 'application/atom+xml'
114-
noUgly = true
115-
{{< /code-toggle >}}
104+
See [configure media types][] for more information.
116105

117-
Note that we use the default settings for all other output format properties.
106+
Step 2
107+
: Create a new output format:
118108

119-
### Step 3
109+
{{< code-toggle file=hugo >}}
110+
[outputFormats.atom]
111+
mediaType = 'application/atom+xml'
112+
noUgly = true
113+
{{< /code-toggle >}}
120114

121-
Specify the page [kinds](g) for which to render this output format:
115+
Note that we use the default settings for all other output format properties.
122116

123-
{{< code-toggle file=hugo >}}
124-
[outputs]
125-
home = ['html', 'rss', 'atom']
126-
section = ['html', 'rss', 'atom']
127-
taxonomy = ['html', 'rss', 'atom']
128-
term = ['html', 'rss', 'atom']
129-
{{< /code-toggle >}}
117+
Step 3
118+
: Specify the page [kinds](g) for which to render this output format:
130119

131-
See [configure outputs] for more information.
120+
{{< code-toggle file=hugo >}}
121+
[outputs]
122+
home = ['html', 'rss', 'atom']
123+
section = ['html', 'rss', 'atom']
124+
taxonomy = ['html', 'rss', 'atom']
125+
term = ['html', 'rss', 'atom']
126+
{{< /code-toggle >}}
132127

133-
### Step 4
128+
See [configure outputs][] for more information.
134129

135-
Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path:
130+
Step 4
131+
: Create a template to render the output format. Since Atom feeds are lists, you need to create a list template. Consult the [template lookup order] to find the correct template path:
136132

137-
```text
138-
layouts/list.atom.atom
139-
```
133+
```text
134+
layouts/list.atom.atom
135+
```
140136

141-
We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template].
137+
We leave writing the template code as an exercise for you. Aim for a result similar to the [embedded RSS template][].
142138

143139
## List output formats
144140

145-
To access output formats, each `Page` object provides two methods: [`OutputFormats`] (for all formats, including the current one) and [`AlternativeOutputFormats`]. Use `AlternativeOutputFormats` to create a link `rel` list within your site's `head` element, as shown below:
141+
To access output formats, each `Page` object provides two methods: [`OutputFormats`][] (for all formats, including the current one) and [`AlternativeOutputFormats`][]. Use `AlternativeOutputFormats` to create a link `rel` list within your site's `head` element, as shown below:
146142

147143
```go-html-template
148144
{{ range .AlternativeOutputFormats }}
@@ -152,7 +148,7 @@ To access output formats, each `Page` object provides two methods: [`OutputForma
152148

153149
## Link to output formats
154150

155-
By default, a `Page` object's [`Permalink`] and [`RelPermalink`] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used.
151+
By default, a `Page` object's [`Permalink`][] and [`RelPermalink`][] methods return the URL of the [primary output format](g), typically `html`. This behavior remains consistent regardless of the template used.
156152

157153
For example, in `page.json.json`, you'll see:
158154

@@ -163,7 +159,7 @@ For example, in `page.json.json`, you'll see:
163159
{{ end }}
164160
```
165161

166-
To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`] setting to `true` for that format.
162+
To make these methods return the URL of the _current_ template's output format, you must set the [`permalinkable`][] setting to `true` for that format.
167163

168164
With `permalinkable` set to true for `json` in the same `page.json.json` template:
169165

@@ -176,7 +172,7 @@ With `permalinkable` set to true for `json` in the same `page.json.json` templat
176172

177173
## Template lookup order
178174

179-
Each output format requires a template conforming to the [template lookup order].
175+
Each output format requires a template conforming to the [template lookup order][].
180176

181177
For the highest specificity in the template lookup order, include the page kind, output format, and suffix in the file name:
182178

@@ -204,7 +200,7 @@ Output format|Template path
204200
[configure outputs]: /configuration/outputs/
205201
[configured media types]: /configuration/media-types/
206202
[default media types]: /configuration/media-types/
207-
[embedded RSS template]: {{% eturl rss %}}
203+
[embedded RSS template]: <{{% eturl rss %}}>
208204
[html/template]: https://pkg.go.dev/html/template
209205
[template lookup order]: /templates/lookup-order/
210206
[text/template]: https://pkg.go.dev/text/template

0 commit comments

Comments
 (0)