TheCloud/hugoDocs
1
0
Fork 0
mirror of https://github.com/gohugoio/hugoDocs.git synced 2025-09-08 16:24:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Refactor code shortcode

Browse Source
This commit is contained in:
Joe Mooring 2023-04-02 08:07:36 -07:00 committed by Joe Mooring
parent ad65d2931d
commit 3afac22fc1
29 changed files with 187 additions and 329 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
content/en/about/license.md
View File

@ -144,7 +144,7 @@ _END OF TERMS AND CONDITIONS_
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives.
{{< code file="apache-notice.txt" download="apache-notice.txt" >}}
{{< code file="apache-notice.txt" >}}
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");

4
content/en/content-management/build-options.md
View File

@ -76,7 +76,7 @@ _build:
render: false
{{< /code-toggle >}}
{{< code file="layouts/index.html" copy="false" >}}
{{< code file="layouts/index.html" copy=false >}}
<section id="who-we-are">
{{ with site.GetPage "who-we-are" }}
{{ .Content }}
@ -100,7 +100,7 @@ cascade:
list: true # default
{{< /code-toggle >}}
{{< code file="layouts/_defaults/testimonials.html" copy="false" >}}
{{< code file="layouts/_defaults/testimonials.html" copy=false >}}
<section id="testimonials">
{{ range first 5 .Pages }}
<blockquote cite="{{ .Params.cite }}">

2
content/en/content-management/sections.md
View File

@ -59,7 +59,7 @@ If you need a specific template for a sub-section, you need to adjust either the
With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation:
{{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}}
{{< code file="layouts/partials/breadcrumb.html" >}}
<nav aria-label="breadcrumb">
<ol>
{{ range .Ancestors.Reverse }}

4
content/en/content-management/toc.md
View File

@ -48,7 +48,7 @@ The built-in `.TableOfContents` variables outputs a `<nav id="TableOfContents">`
The following is an example of a very basic [single page template]:
{{< code file="layout/_default/single.html" download="single.html" >}}
{{< code file="layout/_default/single.html" >}}
{{ define "main" }}
<main>
<article>
@ -68,7 +68,7 @@ The following is an example of a very basic [single page template]:
The following is a [partial template][partials] that adds slightly more logic for page-level control over your table of contents. It assumes you are using a `toc` field in your content's [front matter] that, unless specifically set to `false`, will add a TOC to any page with a `.WordCount` (see [Page Variables][pagevars]) greater than 400. This example also demonstrates how to use [conditionals] in your templating:
{{< code file="layouts/partials/toc.html" download="toc.html" >}}
{{< code file="layouts/partials/toc.html" >}}
{{ if and (gt .WordCount 400 ) (.Params.toc) }}
<aside>
<header>

2
content/en/content-management/urls.md
View File

@ -315,7 +315,7 @@ public/
The alias from the previous URL to the new URL is a client-side redirect:
{{< code file="posts/previous-file-name/index.html" copy="false" >}}
{{< code file="posts/previous-file-name/index.html" copy=false >}}
<!DOCTYPE html>
<html lang="en-us">
<head>

349
content/en/contribute/documentation.md
View File

@ -1,322 +1,169 @@
---
title: Contribute to the Hugo Docs
linktitle: Documentation
description: Documentation is an integral part of any open source project. The Hugo docs are as much a work in progress as the source it attempts to cover.
description: Documentation is an integral part of any open source project. The Hugo documentation is as much a work in progress as the source it attempts to cover.
categories: [contribute]
keywords: [docs,documentation,community, contribute]
menu:
docs:
parent: contribute
weight: 20
toc: true
weight: 20
aliases: [/contribute/docs/]
toc: true
---
## Create Your Fork
## GitHub workflow
It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of [hugoDocs](https://github.com/gohugoio/hugoDocs) on GitHub and cloned the repository locally on your machine. For more information, you can see [GitHub's documentation on "forking"][ghforking] or follow along with [Hugo's development contribution guide][hugodev].
Step 1
: Fork the [documentation repository].
You can then create a separate branch for your additions. Be sure to choose a descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:
Step 2
: Clone your fork.
```txt
git checkout -b jon-doe-showcase-addition
Step 3
: Create a new branch with a descriptive name.
```bash
git checkout -b fix/typos-site-variables
```
## Add New Content
Step 4
: Make changes.
The Hugo docs make heavy use of Hugo's [archetypes] feature. All content sections in Hugo documentation have an assigned archetype.
Step 5
: Commit your changes with a descriptive commit message, typically 50 characters or less. Included the "Closes" keyword if your change addresses one or more open [issues].
Adding new content to the Hugo docs follows the same pattern, regardless of the content section:
```bash
git commit -m "Fix typos on site variables page
```txt
hugo new <DOCS-SECTION>/<new-content-lowercase>.md
Closes #1234
Closes #5678"
```
### Add a New Function
Step 5
: Push the new branch to your fork of the documentation repository.
Once you have cloned the Hugo repository, you can create a new function via the following command. Keep the filename lowercase.
Step 6
: Visit the [documentation repository] and create a pull request (PR).
```txt
hugo new functions/newfunction.md
```
[documentation repository]: https://github.com/gohugoio/hugoDocs/
[issues]: https://github.com/gohugoio/hugoDocs/issues
The archetype for `functions` according to the Hugo docs is as follows:
Step 7
: A project maintainer will review your PR, and may request changes. You may delete your branch after the maintainer merges your PR.
{{< code file="archetypes/functions.md" >}}
{{< readfile file="/archetypes/functions.md">}}
{{< /code >}}
## Including sample code
#### New Function Required Fields
### Fenced code blocks
Here is a review of the front matter fields automatically generated for you using `hugo new functions/*`:
Include the language when using a fenced code block.
***`title`***
: this will be auto-populated in all lowercase when you use `hugo new` generator.
***`linktitle`***
: the function's actual casing (e.g., `replaceRE` rather than `replacere`).
***`description`***
: a brief description used to populate the [Functions Quick Reference](/functions/).
`categories`
: currently auto-populated with 'functions` for future-proofing and portability reasons only; ignore this field.
`tags`
: only if you think it will help end users find other related functions
`signature`
: this is a signature/syntax definition for calling the function (e.g., `apply SEQUENCE FUNCTION [PARAM...]`).
`relatedfuncs`
: other [templating functions] you feel are related to your new function to help fellow Hugo users.
`{{ .Content }}`
: an extended description of the new function; examples are not only welcomed but encouraged.
In the body of your function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs [`code` shortcode](#add-code-blocks).
## Add Code Blocks
Code blocks are crucial for providing examples of Hugo's new features to end users of the Hugo docs. Whenever possible, create examples that you think Hugo users will be able to implement in their own projects.
### Standard Syntax
Across many pages on the Hugo docs, the typical triple-back-tick Markdown syntax (```` ``` ````) is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard GitHub-flavored Markdown.
````txt
````text
```go-html-template
{{ range site.RegularPages }}
<h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
{{ if eq $foo "bar" }}
{{ print "foo is bar" }}
{{ end }}
```
````
### Code Block Shortcode
The Hugo documentation comes with a very robust shortcode for adding interactive code blocks.
{{% note %}}
With the `code` shortcodes, *you must include triple back ticks and a language declaration*. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the Hugo docs.
{{% /note %}}
### `code`
`code` is the Hugo docs shortcode you'll use most often. `code` requires has only one named parameter: `file`. Here is the pattern:
Rendered:
```go-html-template
{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
A whole bunch of coding going on up in here!
{{%/* /code */%}}
{{ if eq $foo "bar" }}
{{ print "foo is bar" }}
{{ end }}
```
The following are the arguments passed into `code`:
### The code shortcode
***`file`***
: the only *required* argument. `file` is needed for styling but also plays an important role in helping users create a mental model around Hugo's directory structure. Visually, this will be displayed as text in the top left of the code block.
Use the `code` shortcode to include the file name and a copy-to-clipboard button. This shortcode accepts these optional parameters:
`download`
: if omitted, this will have no effect on the rendered shortcode. When a value is added to `download`, it's used as the filename for a downloadable version of the code block.
copy
: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `true`.
`copy`
: a copy button is added automatically to all `code` shortcodes. If you want to keep the filename and styling of `code` but don't want to encourage readers to copy the code (e.g., a "Do not do" snippet in a tutorial), use `copy="false"`.
file
: (`string`) The file name to display. If you do not provide a `lang` parameter, the file extension determines the code language.
#### Example `code` Input
lang
: (`string`) The code language. Default is `text`.
This example HTML code block tells Hugo users the following:
1. This file *could* live in `layouts/_default`, as demonstrated by `layouts/_default/single.html` as the value for `file`.
2. This snippet is complete enough to be downloaded and implemented in a Hugo project, as demonstrated by `download="single.html"`.
```go-html-template
{{</* code file="layouts/_default/single.html" download="single.html" */>}}
{{ define "main" }}
<main>
<article>
<header>
<h1>{{ .Title }}</h1>
{{ with .Params.subtitle }}
<span>{{ . }}</span>
</header>
<div>
{{ .Content }}
</div>
<aside>
{{ .TableOfContents }}
</aside>
</article>
</main>
````text
{{</* code file="layouts/_default_/single.html" */>}}
{{ if eq $foo "bar" }}
{{ print "foo is bar" }}
{{ end }}
{{</* /code */>}}
```
##### Example 'code' Display
````
The output of this example will render to the Hugo docs as follows:
Rendered:
{{< code file="layouts/_default/single.html" download="single.html" >}}
{{ define "main" }}
<main>
<article>
<header>
<h1>{{ .Title }}</h1>
{{ with .Params.subtitle }}
<span>{{ . }}</span>
</header>
<div>
{{ .Content }}
</div>
<aside>
{{ .TableOfContents }}
</aside>
</article>
</main>
{{< code file="layouts/_default_/single.html" >}}
{{ if eq $foo "bar" }}
{{ print "foo is bar" }}
{{ end }}
{{< /code >}}
<!-- #### Output Code Block
### The code-toggle shortcode
The `output` shortcode is almost identical to the `code` shortcode but only takes and requires `file`. The purpose of `output` is to show *rendered* HTML and therefore almost always follows another basic code block *or* and instance of the `code` shortcode:
Use the `code-toggle` shortcode to display examples of site configuration, front matter, or data files. This shortcode accepts these optional parameters:
```
{{%/* output file="posts/my-first-post/index.html" */%}}
<h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p>
{{%/* /output */%}}
copy
: (`bool`) If `true`, displays a copy-to-clipboard button. Default is `true`.
file
: (`string`) The file name to display. Omit the file extension for site configuration and data file examples.
fm
: (`bool`) If `true`, displays the code as front matter. Default is `false`.
#### Site configuration example
```text
{{</* code-toggle file="config" */>}}
baseURL = 'https://example.org'
languageCode = 'en-US'
title = "Example Site"
{{</* /code-toggle */>}}
```
The preceding `output` example will render as follows to the Hugo docs:
Rendered:
{{< output file="posts/my-first-post/index.html" >}}
<h1>This is my First Hugo Blog Post</h1>
<p>I am excited to be using Hugo.</p>
{{< /output >}} -->
{{< code-toggle file="config" >}}
baseURL = 'https://example.org'
languageCode = 'en-US'
title = "Example Site"
{{< /code-toggle >}}
## Blockquotes
#### Front matter example
Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]:
```md
> Without the threat of punishment, there is no joy in flight.
```text
{{</* code-toggle file="content/about.md" fm=true */>}}
title = "About"
date = 2023-04-02T12:47:24-07:00
draft = false
{{</* /code-toggle */>}}
```
The preceding blockquote will render as follows in the Hugo docs:
Rendered:
> Without the threat of punishment, there is no joy in flight.
However, you can add a quick and easy `<cite>` element (added on the client via JavaScript) by separating your main blockquote and the citation with a hyphen with a single space on each side:
```md
> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)
```
Which will render as follows in the Hugo docs:
> Without the threat of punishment, there is no joy in flight. - [Kobo Abe][abe]
{{% note "Blockquotes `!=` Admonitions" %}}
Previous versions of Hugo documentation used blockquotes to draw attention to text. This is *not* the [intended semantic use of `<blockquote>`](https://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting. To note or warn your user of specific information, use the admonition shortcodes that follow.
{{% /note %}}
{{< code-toggle file="content/about.md" fm=true >}}
title = "About"
date = 2023-04-02T12:47:24-07:00
draft = false
{{< /code-toggle >}}
## Admonitions
**Admonitions** are common in technical documentation. The most popular is that seen in [reStructuredText Directives][sourceforge]. From the SourceForge documentation:
Use the `note` shortcode to draw attention to content. Use the `{{%/* */%}}` notation when calling this shortcode.
> Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - [SourceForge][sourceforge]
The Hugo docs contain three admonitions: `note`, `tip`, and `warning`.
### `note` Admonition
Use the `note` shortcode when you want to draw attention to information subtly. `note` is intended to be less of an interruption in content than is `warning`.
#### Example `note` Input
{{< code file="note-with-heading.md" >}}
```text
{{%/* note */%}}
Here is a piece of information I would like to draw your **attention** to.
This is **bold** text.
{{%/* /note */%}}
{{< /code >}}
#### Example `note` Output
{{< output file="note-with-heading.html" >}}
{{% note %}}
Here is a piece of information I would like to draw your **attention** to.
{{% /note %}}
{{< /output >}}
#### Example `note` Display
```
{{% note %}}
Here is a piece of information I would like to draw your **attention** to.
This is **bold** text.
{{% /note %}}
### `tip` Admonition
Use the `tip` shortcode when you want to give the reader advice. `tip`, like `note`, is intended to be less of an interruption in content than is `warning`.
#### Example `tip` Input
{{< code file="using-tip.md" >}}
{{%/* tip */%}}
Here's a bit of advice to improve your productivity with Hugo.
{{%/* /tip */%}}
{{< /code >}}
#### Example `tip` Output
{{< output file="tip-output.html" >}}
{{% tip %}}
Here's a bit of advice to improve your productivity with Hugo.
{{% /tip %}}
{{< /output >}}
#### Example `tip` Display
{{% tip %}}
Here's a bit of advice to improve your productivity with Hugo.
{{% /tip %}}
### `warning` Admonition
Use the `warning` shortcode when you want to draw the user's attention to something important. A good usage example is for articulating breaking changes in Hugo versions, known bugs, or templating "gotchas."
#### Example `warning` Input
{{< code file="warning-admonition-input.md" >}}
{{%/* warning */%}}
This is a warning, which should be reserved for *important* information like breaking changes.
{{%/* /warning */%}}
{{< /code >}}
#### Example `warning` Output
{{< output file="warning-admonition-output.html" >}}
{{% warning %}}
This is a warning, which should be reserved for *important* information like breaking changes.
{{% /warning %}}
{{< /output >}}
#### Example `warning` Display
{{% warning %}}
This is a warning, which should be reserved for *important* information like breaking changes.
{{% /warning %}}
{{% note "Pull Requests and Branches" %}}
Similar to [contributing to Hugo development](/contribute/development/), the Hugo team expects you to create a separate branch/fork when you make your contributions to the Hugo docs.
{{% /note %}}
[abe]: https://en.wikipedia.org/wiki/Kobo_Abe
[archetypes]: /content-management/archetypes/
[bqsyntax]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes
[charcount]: https://www.lettercount.com/
[`docs/static/images/showcase/`]: https://github.com/gohugoio/hugo/tree/master/docs/static/images/showcase/
[ghforking]: https://help.github.com/articles/fork-a-repo/
[hugodev]: /contribute/development/
[shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
[sourceforge]: https://docutils.sourceforge.io/docs/ref/rst/directives.html#admonitions
[templating function]: /functions/

2
content/en/functions/after.md
View File

@ -27,7 +27,7 @@ You can use `after` in combination with the [`first` function] and Hugo's [power
1. The top row is titled "Featured" and shows only the most recently published article (i.e. by `publishdate` in the content files' front matter).
2. The second row is titled "Recent Articles" and shows only the 2nd- to 4th-most recently published articles.
{{< code file="layouts/section/articles.html" download="articles.html" >}}
{{< code file="layouts/section/articles.html" >}}
{{ define "main" }}
<section class="row featured-article">
<h2>Featured Article</h2>

6
content/en/functions/apply.md
View File

@ -45,7 +45,7 @@ However, it is not possible to provide the output of a range to the [`delimit` f
If you have `post-tag-list.html` and `post-tag-link.html` as [partials], you *could* use the following snippets, respectively:
{{< code file="layouts/partials/post-tag-list.html" copy="false" >}}
{{< code file="layouts/partials/post-tag-list.html" copy=false >}}
{{ with .Params.tags }}
<div class="tags-list">
Tags:
@ -63,7 +63,7 @@ If you have `post-tag-list.html` and `post-tag-link.html` as [partials], you *co
{{ end }}
{{< /code >}}
{{< code file="layouts/partials/post-tag-link.html" copy="false" >}}
{{< code file="layouts/partials/post-tag-link.html" copy=false >}}
<a class="post-tag post-tag-{{ . | urlize }}" href="/tags/{{ . | urlize }}">{{ . }}</a>
{{< /code >}}
@ -85,7 +85,7 @@ This first version of `layouts/partials/post-tag-list.html` separates all of the
Now in the completed version, you can sort the tags, convert the tags to links with `layouts/partials/post-tag-link.html`, [chomp] off stray newlines, and join the tags together in a delimited list for presentation. Here is an even DRYer version of the preceding example:
{{< code file="layouts/partials/post-tag-list.html" download="post-tag-list.html" >}}
{{< code file="layouts/partials/post-tag-list.html" >}}
{{ with .Params.tags }}
<div class="tags-list">
Tags:

6
content/en/functions/default.md
View File

@ -43,7 +43,7 @@ Both of the above `default` function calls return `Roboto`.
A `default` value, however, does not need to be hard coded like the previous example. The `default` value can be a variable or pulled directly from the front matter using dot notation:
{{< code file="variable-as-default-value.html" copy="false" >}}
{{< code file="variable-as-default-value.html" copy=false >}}
{{ $old := .Params.oldparam }}
<p>{{ .Params.newparam | default $old }}</p>
{{< /code >}}
@ -70,14 +70,14 @@ The following have equivalent return values but are far less terse. This demonst
Using `if`:
{{< code file="if-instead-of-default.html" copy="false" >}}
{{< code file="if-instead-of-default.html" copy=false >}}
<title>{{ if .Params.seo_title }}{{ .Params.seo_title }}{{ else }}{{ .Title }}{{ end }}</title>
=> Sane Defaults
{{< /code >}}
Using `with`:
{{< code file="with-instead-of-default.html" copy="false" >}}
{{< code file="with-instead-of-default.html" copy=false >}}
<title>{{ with .Params.seo_title }}{{ . }}{{ else }}{{ .Title }}{{ end }}</title>
=> Sane Defaults
{{< /code >}}

2
content/en/functions/dict.md
View File

@ -24,7 +24,7 @@ The partial below creates an SVG and expects `fill`, `height` and `width` from t
### Partial definition
{{< code file="layouts/partials/svgs/external-links.svg" download="external-links.svg" >}}
{{< code file="layouts/partials/svgs/external-links.svg" >}}
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink"
fill="{{ .fill }}" width="{{ .width }}" height="{{ .height }}" viewBox="0 0 32 32" aria-label="External Link">
<path d="M25.152 16.576v5.696q0 2.144-1.504 3.648t-3.648 1.504h-14.848q-2.144 0-3.648-1.504t-1.504-3.648v-14.848q0-2.112 1.504-3.616t3.648-1.536h12.576q0.224 0 0.384 0.16t0.16 0.416v1.152q0 0.256-0.16 0.416t-0.384 0.16h-12.576q-1.184 0-2.016 0.832t-0.864 2.016v14.848q0 1.184 0.864 2.016t2.016 0.864h14.848q1.184 0 2.016-0.864t0.832-2.016v-5.696q0-0.256 0.16-0.416t0.416-0.16h1.152q0.256 0 0.416 0.16t0.16 0.416zM32 1.152v9.12q0 0.48-0.352 0.8t-0.8 0.352-0.8-0.352l-3.136-3.136-11.648 11.648q-0.16 0.192-0.416 0.192t-0.384-0.192l-2.048-2.048q-0.192-0.16-0.192-0.384t0.192-0.416l11.648-11.648-3.136-3.136q-0.352-0.352-0.352-0.8t0.352-0.8 0.8-0.352h9.12q0.48 0 0.8 0.352t0.352 0.8z"></path>

4
content/en/functions/param.md
View File

@ -33,7 +33,7 @@ display_toc = false
**Template**
{{< code file="layouts/_default/single.html" copy="false" >}}
{{< code file="layouts/_default/single.html" copy=false >}}
{{ if .Param "display_toc" }}
{{ .TableOfContents }}
{{ end }}
@ -41,6 +41,6 @@ display_toc = false
The `.Param` method returns the value associated with the given `KEY`, regardless of whether the value is truthy or falsy. If you need to ignore falsy values, use this construct instead:
{{< code file="layouts/_default/single.html" copy="false" >}}
{{< code file="layouts/_default/single.html" copy=false >}}
{{ or .Params.foo site.Params.foo }}
{{< /code >}}

6
content/en/functions/safeURL.md
View File

@ -16,7 +16,7 @@ Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are cons
The following examples use a [site `config.toml`][configuration] with the following [menu entry][menus]:
{{< code file="config.toml" copy="false" >}}
{{< code file="config.toml" copy=false >}}
[[menu.main]]
name = "IRC: #golang at freenode"
url = "irc://irc.freenode.net/#golang"
@ -24,7 +24,7 @@ The following examples use a [site `config.toml`][configuration] with the follow
The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example:
{{< code file="layouts/partials/bad-url-sidebar-menu.html" copy="false" >}}
{{< code file="layouts/partials/bad-url-sidebar-menu.html" copy=false >}}
<!-- This unordered list may be part of a sidebar menu -->
<ul>
{{ range .Site.Menus.main }}
@ -44,7 +44,7 @@ This partial would produce the following HTML output:
The odd output can be remedied by adding ` | safeURL` to our `.URL` page variable:
{{< code file="layouts/partials/correct-url-sidebar-menu.html" copy="false" >}}
{{< code file="layouts/partials/correct-url-sidebar-menu.html" copy=false >}}
<!-- This unordered list may be part of a sidebar menu -->
<ul>
<li><a href="{{ .URL | safeURL }}">{{ .Name }}</a></li>

10
content/en/functions/sort.md
View File

@ -27,7 +27,7 @@ grades = ['b','a','c']
Sort slice elements in ascending order using either of these constructs:
{{< code file="layouts/_default/single.html" copy="false" >}}
{{< code file="layouts/_default/single.html" copy=false >}}
{{ sort site.Params.grades }} → [a b c]
{{ sort site.Params.grades "value" "asc" }} → [a b c]
{{< /code >}}
@ -38,7 +38,7 @@ In the examples above, `value` is the `KEY` representing the value of the slice
Sort slice elements in descending order:
{{< code file="layouts/_default/single.html" copy="false" >}}
{{< code file="layouts/_default/single.html" copy=false >}}
{{ sort site.Params.grades "value" "desc" }} → [c b a]
{{< /code >}}
@ -68,7 +68,7 @@ When sorting maps, the `KEY` argument must be lowercase.
Sort map objects in ascending order using either of these constructs:
{{< code file="layouts/_default/single.html" copy="false" >}}
{{< code file="layouts/_default/single.html" copy=false >}}
{{ range sort site.Params.authors "firstname" }}
{{ .firstName }}
{{ end }}
@ -88,7 +88,7 @@ Jean Marius Victor
Sort map objects in descending order:
{{< code file="layouts/_default/single.html" copy="false" >}}
{{< code file="layouts/_default/single.html" copy=false >}}
{{ range sort site.Params.authors "firstname" "desc" }}
{{ .firstName }}
{{ end }}
@ -116,7 +116,7 @@ Although you can use the `sort` function to sort a page collection, Hugo provide
In this contrived example, sort the site's regular pages by `.Type` in descending order:
{{< code file="layouts/_default/home.html" copy="false" >}}
{{< code file="layouts/_default/home.html" copy=false >}}
{{ range sort site.RegularPages "Type" "desc" }}
<h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}

2
content/en/functions/urlize.md
View File

@ -20,7 +20,7 @@ tags = ["pizza","beer","hot dogs"]
The following might be used as a partial within a [single page template][singletemplate]:
{{< code file="layouts/partials/content-header.html" download="content-header.html" >}}
{{< code file="layouts/partials/content-header.html" >}}
<header>
<h1>{{ .Title }}</h1>
{{ with .Params.location }}

6
content/en/hosting-and-deployment/hosting-on-netlify.md
View File

@ -57,23 +57,21 @@ You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus-
For production:
{{< code file="netlify.toml" codeLang="toml" >}}
{{< code file="netlify.toml" >}}
[context.production.environment]
HUGO_VERSION = "0.99.1"
{{< /code >}}
For testing:
{{< code file="netlify.toml" codeLang="toml" >}}
{{< code file="netlify.toml" >}}
[context.deploy-preview.environment]
HUGO_VERSION = "0.99.1"
{{< /code >}}
The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`:
{{< code file="netlify.toml" nocode="true" >}}
{{< readfile file="netlify.toml" highlight="toml" >}}
{{< /code >}}
## Build and Deploy Site

2
content/en/templates/404.md
View File

@ -26,7 +26,7 @@ In addition to the standard page variables, the 404 page has access to all site
This is a basic example of a 404.html template:
{{< code file="layouts/404.html" download="404.html" >}}
{{< code file="layouts/404.html" >}}
{{ define "main" }}
<main id="main">
<div>

6
content/en/templates/base.md
View File

@ -26,7 +26,7 @@ See [Template Lookup Order](/templates/lookup-order/) for details and examples.
The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order.
{{< code file="layouts/_default/baseof.html" download="baseof.html" >}}
{{< code file="layouts/_default/baseof.html" >}}
<!DOCTYPE html>
<html>
<head>
@ -52,7 +52,7 @@ The following defines a simple base template at `_default/baseof.html`. As a def
From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from:
{{< code file="layouts/_default/list.html" download="list.html" >}}
{{< code file="layouts/_default/list.html" >}}
{{ define "main" }}
<h1>Posts</h1>
{{ range .Pages }}
@ -80,7 +80,7 @@ Code that you put outside the block definitions *can* break your layout. This ev
The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]:
{{< code file="layouts/_default/single.html" download="single.html" >}}
{{< code file="layouts/_default/single.html" >}}
{{ define "title" }}
<!-- This will override the default value set in baseof.html; i.e., "{{ .Site.Title }}" in the original example-->
{{ .Title }} &ndash; {{ .Site.Title }}

2
content/en/templates/homepage.md
View File

@ -35,7 +35,7 @@ See the homepage template below or [Content Organization][contentorg] for more i
The following is an example of a homepage template that uses [partial][partials], [base] templates, and a content file at `content/_index.md` to populate the `{{ .Title }}` and `{{ .Content }}` [page variables][pagevars].
{{< code file="layouts/index.html" download="index.html" >}}
{{< code file="layouts/index.html" >}}
{{ define "main" }}
<main aria-role="main">
<header class="homepage-header">

2
content/en/templates/internal.md
View File

@ -90,7 +90,7 @@ Users have noticed that enabling Disqus comments when running the Hugo web serve
You can create the following `layouts/partials/disqus.html`:
{{< code file="layouts/partials/disqus.html" download="disqus.html" >}}
{{< code file="layouts/partials/disqus.html" >}}
<div id="disqus_thread"></div>
<script type="text/javascript">

2
content/en/templates/introduction.md
View File

@ -540,7 +540,7 @@ notoc: true
Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]:
{{< code file="layouts/partials/toc.html" download="toc.html" >}}
{{< code file="layouts/partials/toc.html" >}}
{{ if not .Params.notoc }}
<aside>
<header>

8
content/en/templates/lists/index.md
View File

@ -84,7 +84,7 @@ Follow my journey through this new blog.
You can now access this `_index.md`'s' content in your list template:
{{< code file="layouts/_default/list.html" download="list.html" >}}
{{< code file="layouts/_default/list.html" >}}
{{ define "main" }}
<main>
<article>
@ -108,7 +108,7 @@ You can now access this `_index.md`'s' content in your list template:
This above will output the following HTML:
{{< code file="example.com/posts/index.html" copy="false" >}}
{{< code file="example.com/posts/index.html" copy=false >}}
<!--top of your baseof code-->
<main>
<article>
@ -132,7 +132,7 @@ You do *not* have to create an `_index.md` file for every list page (i.e. sectio
Using this same `layouts/_default/list.html` template and applying it to the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from:
{{< code file="example.com/quote/index.html" copy="false" >}}
{{< code file="example.com/quote/index.html" copy=false >}}
<!--baseof-->
<main>
<article>
@ -178,7 +178,7 @@ This list template has been modified slightly from a template originally used in
### Taxonomy Template
{{< code file="layouts/_default/taxonomy.html" download="taxonomy.html" >}}
{{< code file="layouts/_default/taxonomy.html" >}}
{{ define "main" }}
<main>
<div>

4
content/en/templates/partials.md
View File

@ -154,7 +154,7 @@ Note that the variant parameters are not made available to the underlying partia
The following `header.html` partial template is used for [spf13.com](https://spf13.com/):
{{< code file="layouts/partials/header.html" download="header.html" >}}
{{< code file="layouts/partials/header.html" >}}
<!DOCTYPE html>
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
<head>
@ -179,7 +179,7 @@ The `header.html` example partial was built before the introduction of block tem
The following `footer.html` partial template is used for [spf13.com](https://spf13.com/):
{{< code file="layouts/partials/footer.html" download="footer.html" >}}
{{< code file="layouts/partials/footer.html" >}}
<footer>
<div>
<p>

2
content/en/templates/robots.md
View File

@ -35,7 +35,7 @@ You may overwrite the internal template with a custom template. Hugo selects the
## Robots.txt Template Example
{{< code file="layouts/robots.txt" download="robots.txt" >}}
{{< code file="layouts/robots.txt" >}}
User-agent: *
{{ range .Pages }}
Disallow: {{ .RelPermalink }}

2
content/en/templates/section-templates.md
View File

@ -43,7 +43,7 @@ Examples:
## Example: Creating a Default Section Template
{{< code file="layouts/_default/section.html" download="section.html" >}}
{{< code file="layouts/_default/section.html" >}}
{{ define "main" }}
<main>
{{ .Content }}

8
content/en/templates/shortcode-templates.md
View File

@ -187,7 +187,7 @@ Would load the template at `/layouts/shortcodes/youtube.html`:
</div>
{{< /code >}}
{{< code file="youtube-embed.html" copy="false" >}}
{{< code file="youtube-embed.html" copy=false >}}
<div class="embed video-player">
<iframe class="youtube-player" type="text/html"
width="640" height="385"
@ -230,7 +230,7 @@ You have created the shortcode at `/layouts/shortcodes/img.html`, which loads th
Would be rendered as:
{{< code file="img-output.html" copy="false" >}}
{{< code file="img-output.html" copy=false >}}
<figure>
<img src="/media/spf13.jpg" />
<figcaption>
@ -262,7 +262,7 @@ Would load the template found at `/layouts/shortcodes/vimeo.html`:
Would be rendered as:
{{< code file="vimeo-iframes.html" copy="false" >}}
{{< code file="vimeo-iframes.html" copy=false >}}
<div class="vimeo-container">
<iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
</div>
@ -291,7 +291,7 @@ The template for the `highlight` shortcode uses the following code, which is alr
The rendered output of the HTML example code block will be as follows:
{{< code file="syntax-highlighted.html" copy="false" >}}
{{< code file="syntax-highlighted.html" copy=false >}}
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672">&lt;html&gt;</span>
<span style="color: #f92672">&lt;body&gt;</span> This HTML <span style="color: #f92672">&lt;/body&gt;</span>
<span style="color: #f92672">&lt;/html&gt;</span>

2
content/en/templates/single-page-templates.md
View File

@ -24,7 +24,7 @@ Content pages are of the type `page` and will therefore have all the [page varia
This single page template makes use of Hugo [base templates], the [`.Format` function] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`] is also used to check whether the taxonomies are set in the front matter.
{{< code file="layouts/posts/single.html" download="single.html" >}}
{{< code file="layouts/posts/single.html" >}}
{{ define "main" }}
<section id="main">

2
content/en/templates/taxonomy-templates.md
View File

@ -280,7 +280,7 @@ The following example displays all terms in a site's tags taxonomy:
This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms.
{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}}
{{< code file="layouts/partials/all-taxonomies.html" >}}
<section>
<ul id="all-taxonomies">
{{ range $taxonomy_term, $taxonomy := .Site.Taxonomies }}

6
content/en/templates/views.md
View File

@ -62,7 +62,7 @@ The following example demonstrates how to use content views inside your [list te
In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows:
{{< code file="layouts/_default/list.html" download="list.html" >}}
{{< code file="layouts/_default/list.html" >}}
<main id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
@ -77,7 +77,7 @@ In this example, `.Render` is passed into the template to call the [render funct
Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.)
{{< code file="layouts/_default/summary.html" download="summary.html" >}}
{{< code file="layouts/_default/summary.html" >}}
<article class="post">
<header>
<h2><a href='{{ .Permalink }}'> {{ .Title }}</a> </h2>
@ -94,7 +94,7 @@ Hugo will pass the entire page object to the following `summary.html` view templ
Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`).
{{< code file="layouts/_default/li.html" download="li.html" >}}
{{< code file="layouts/_default/li.html" >}}
<li>
<a href="{{ .Permalink }}">{{ .Title }}</a>
<div class="meta">{{ .Date.Format "Mon, Jan 2, 2006" }}</div>

61
layouts/shortcodes/code.html
View File

@ -1,26 +1,39 @@
{{ $file := .Get "file" }}
{{ $codeLang := "" }}
{{ $suffix := findRE "(\\.[^.]+)$" $file 1 }}
{{ with $suffix }}
{{ $codeLang = (index . 0 | strings.TrimPrefix ".") }}
{{ end }}
{{ with .Get "codeLang" }}{{ $codeLang = . }}{{ end }}
{{ if eq $codeLang "html" }}
{{ $codeLang = "go-html-template" }}
{{ end }}
{{- /*
Renders syntax highlighted code.
@param {bool} [copy=true] If true, display a copy to clipboard button.
@param {string} [file] The file name to display above the rendered code.
@param {string} [lang] The code language of the inner content.
@returns {template.HTML}
*/}}
{{- /* Initialize. */}}
{{- $copy := true }}
{{- $file := "&nbsp;" }}
{{- $lang := "" }}
{{- /* Get parameters. */}}
{{- $file = .Get "file" }}
{{- $lang = or (.Get "lang") (path.Ext $file | strings.TrimPrefix ".") "text" }}
{{- if in (slice "false" false 0) (.Get "copy") }}
{{- $copy = false }}
{{- else if in (slice "true" true 1) (.Get "copy")}}
{{- $copy = true }}
{{- end }}
{{- /* Use the go-html-template Chroma lexer for HTML. */}}
{{- if eq $lang "html" }}
{{- $lang = "go-html-template" }}
{{- end }}
{{- /* Render. */}}
<div class="code relative" id="{{ $file | urlize }}">
{{- with $file -}}
<div class="filename san-serif f6 dib lh-solid pl2 pv2">{{ . }}</div>
{{- end -}}
{{ if ne (.Get "copy") "false" }}
<button class="needs-js copy bg-accent-color-dark f6 absolute top-0 right-0 lh-solid hover-bg-primary-color-dark bn white ph3 pv2" title="Copy this code to your clipboard." data-clipboard-action="copy" aria-label="copy button">
</button>
{{/* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}}
{{ end }}
<div class="code-copy-content nt3" {{ with .Get "download" }}id="{{ . }}"{{ end }}>
{{ $inner := trim .Inner "\n" | safeHTML }}
{{ if .Get "nocode" }}{{ $inner }}{{ else }}{{ with $codeLang }}{{ highlight $inner . "" }}{{ else }}<pre><code>{{ $inner }}</code></pre>{{ end }}{{ end }}
</div>
<div class="f6 dib lh-solid pl2 pv2">{{ or $file "nbsp;" }}</div>
{{- if $copy }}
<button class="needs-js copy bg-accent-color-dark f6 absolute top-0 right-0 lh-solid hover-bg-primary-color-dark bn white ph3 pv2" title="Copy this code to your clipboard." data-clipboard-action="copy" aria-label="copy button"></button>
{{- end }}
<div class="code-copy-content nt3">
{{- highlight (trim .Inner "\n\r") $lang }}
</div>
</div>