mirror of
https://github.com/gohugoio/hugo.git
synced 2026-09-02 03:32:38 +00:00
Update with download button and new see-source icons in code blocks
This commit is contained in:
Ryan Watters
@@ -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.
|
||||
|
||||
{{% input file="apache-notice.txt" %}}
|
||||
{{% code file="apache-notice.txt" %}}
|
||||
```
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
@@ -160,4 +160,4 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
@@ -26,11 +26,11 @@ hugo new [content-section/file-name.md]
|
||||
|
||||
We can use this pattern to create a new `.md` file in the `posts` section of the [example site][]:
|
||||
|
||||
{{% input file="archetype-example.sh" %}}
|
||||
{{% code file="archetype-example.sh" %}}
|
||||
```bash
|
||||
hugo new posts/my-first-post.md
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% note "Override Content Type in a New File" %}}
|
||||
To override the content type Hugo infers from `[content-section]`, add the `--kind` flag to the end of the `hugo new` command.
|
||||
@@ -82,14 +82,14 @@ Default archetypes are convenient if your content's front matter stays consisten
|
||||
|
||||
The [example site][] includes `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category.
|
||||
|
||||
{{% input file="archetypes/default.md" %}}
|
||||
{{% code file="archetypes/default.md" %}}
|
||||
```toml
|
||||
+++
|
||||
tags = ["golang", "hugo"]
|
||||
categories = ["web development"]
|
||||
+++
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% warning "EOL Characters in Text Editors"%}}
|
||||
If you get an `EOF error` when using `hugo new`, add a carriage return after the closing `+++` or `---` for your TOML or YAML front matter, respectively. (See [troubleshooting](/troubleshooting/eof-error/).)
|
||||
@@ -99,11 +99,11 @@ If you get an `EOF error` when using `hugo new`, add a carriage return after the
|
||||
|
||||
With an `archetypes/default.md` in place, we can use the CLI to create a new post in the `posts` content section:
|
||||
|
||||
{{% input file="new-post-from-default.sh" %}}
|
||||
{{% code file="new-post-from-default.sh" %}}
|
||||
```bash
|
||||
$ hugo new posts/my-new-post.md
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Hugo then creates a new markdown file with the following front matter:
|
||||
|
||||
@@ -136,7 +136,7 @@ Suppose the example site's `posts` section requires more sophisticated front mat
|
||||
|
||||
### Creating a Custom Archetype
|
||||
|
||||
{{% input file="archetypes/posts.md"%}}
|
||||
{{% code file="archetypes/posts.md"%}}
|
||||
```toml
|
||||
+++
|
||||
description = ""
|
||||
@@ -144,17 +144,17 @@ tags = ""
|
||||
categories = ""
|
||||
+++
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### Using a Custom Archetype
|
||||
|
||||
With an `archetypes/posts.md` in place, we can use the CLI to create a new posts with custom `posts` metadata in the `posts` content section:
|
||||
|
||||
{{% input file="new-post-from-custom.sh" %}}
|
||||
{{% code file="new-post-from-custom.sh" %}}
|
||||
```bash
|
||||
$ hugo new posts/post-from-custom.md
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`.
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@ You also have the option to set the following in the front matter for a given pi
|
||||
|
||||
Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account. In order to prevent this, a slightly tweaked partial template is required. So, rather than using the built-in `"_internal/disqus.html"` template referenced above, create a template in `layouts/partials` that looks like the following:
|
||||
|
||||
{{% input file="layouts/partials/disqus.html" %}}
|
||||
{{% code file="layouts/partials/disqus.html" %}}
|
||||
```html
|
||||
<div id="disqus_thread"></div>
|
||||
<script type="text/javascript">
|
||||
@@ -76,17 +76,17 @@ Users have noticed that enabling Disqus comments when running the Hugo web serve
|
||||
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
|
||||
<a href="http://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`.
|
||||
|
||||
You can then reference the partial template:
|
||||
|
||||
{{% input file="disqus-reference.html" %}}
|
||||
{{% code file="disqus-reference.html" %}}
|
||||
```golang
|
||||
{{ partial "disqus.html" . }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
## Alternatives
|
||||
|
||||
|
||||
@@ -50,7 +50,7 @@ Be careful to enter <code><!--more--></code> exactly
|
||||
|
||||
You can show content summaries with the following code. You could use the following snipper, for example, in a [section template][].
|
||||
|
||||
{{% input file="page-list-with-summaries.html" %}}
|
||||
{{% code file="page-list-with-summaries.html" %}}
|
||||
```html
|
||||
{{ range first 10 .Data.Pages }}
|
||||
<article>
|
||||
@@ -66,7 +66,7 @@ You can show content summaries with the following code. You could use the follow
|
||||
</article>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Note how the `.Truncated` boolean valuable may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article.
|
||||
|
||||
|
||||
@@ -105,7 +105,7 @@ By having the same _base file name_, the content pieces are linked together as t
|
||||
|
||||
To create a list of links to translated content, use a template similar to this:
|
||||
|
||||
{{% input file="layouts/partials/i18nlist.html" %}}
|
||||
{{% code file="layouts/partials/i18nlist.html" %}}
|
||||
```html
|
||||
{{ if .IsTranslated }}
|
||||
<h4>{{ i18n "translations" }}</h4>
|
||||
@@ -118,7 +118,7 @@ To create a list of links to translated content, use a template similar to this:
|
||||
</ul>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
The above can be put in a `partial` (`./layouts/partials/`) and included in any template, be it for a [content page][contenttemplate] or the [home page][homepagetemplte]. It will not print anything if there are no translations for a given page, or if it is---in the case of the home page, section listing, etc.---a site with only one language.
|
||||
|
||||
|
||||
@@ -79,11 +79,11 @@ The `figure` shortcode can use the following named parameters:
|
||||
|
||||
#### Example `figure` Input
|
||||
|
||||
{{% input file="figure-input-example.md" %}}
|
||||
{{% code file="figure-input-example.md" %}}
|
||||
```markdown
|
||||
{{</* figure src="/media/spf13.jpg" title="Steve Francia" */>}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
#### Example `figure` Output
|
||||
|
||||
@@ -128,7 +128,7 @@ This shortcode will convert the source code provided into syntax-highlighted HTM
|
||||
|
||||
#### Example `highlight` Input
|
||||
|
||||
{{% input file="highlight-shortcode.md" %}}
|
||||
{{% code file="highlight-shortcode.md" %}}
|
||||
```golang
|
||||
{{</* highlight html */>}}
|
||||
<section id="main">
|
||||
@@ -141,7 +141,7 @@ This shortcode will convert the source code provided into syntax-highlighted HTM
|
||||
</section>
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
#### Example `highlight` Output
|
||||
|
||||
@@ -216,11 +216,11 @@ To embed slides from [Speaker Deck][], click on "< /> Embed" (u
|
||||
|
||||
Extract the value from the field `data-id` and pass it to the shortcode:
|
||||
|
||||
{{% input file="speakerdeck-example-input.md" %}}
|
||||
{{% code file="speakerdeck-example-input.md" %}}
|
||||
```golang
|
||||
{{</* speakerdeck 4e8126e72d853c0060001f97 */>}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### `tweet`
|
||||
|
||||
|
||||
@@ -125,21 +125,21 @@ taxonomies:
|
||||
|
||||
If you do not specify any taxonomies in your [site configuration][] file *and* your content already includes front matter with `tags:` or `categories`, Hugo will automatically create taxonomy pages. To override this behavior, set the key-value pairs for both of the default taxonomies to empty strings in your `config` file.
|
||||
|
||||
{{% input file="remove-default-taxonomies-config.toml" %}}
|
||||
{{% code file="remove-default-taxonomies-config.toml" %}}
|
||||
```toml
|
||||
[taxonomies]
|
||||
tag = ""
|
||||
category = ""
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% input file="remove-default-taxonomies-config.yml" %}}
|
||||
{{% code file="remove-default-taxonomies-config.yml" %}}
|
||||
```yaml
|
||||
taxonomies:
|
||||
tag: ""
|
||||
category: ""
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### Preserving Taxonomy Values
|
||||
|
||||
|
||||
@@ -77,11 +77,11 @@ hugo server
|
||||
|
||||
If everything looks fine, we are ready to commit your additions. For the sake of best practices, please make sure that your commit follows our [code contribution guideline][].
|
||||
|
||||
{{% input file="commit-site.sh" %}}
|
||||
{{% code file="commit-site.sh" %}}
|
||||
```git
|
||||
git commit -m "docs: Add example.com to the showcase"
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Last but not least, we're ready to create a [pull request].
|
||||
|
||||
|
||||
@@ -76,13 +76,13 @@ Use the `note` shortcode when you want to draw attention to information subtly.
|
||||
|
||||
#### `note` Admonition Shortcode Input
|
||||
|
||||
{{% input file="note-with-heading.md" %}}
|
||||
{{% code file="note-with-heading.md" %}}
|
||||
```golang
|
||||
{{%/* note "Example Note Admonition" */%}}
|
||||
Here is a piece of information I would like to draw your **attention** to.
|
||||
{{%/* /note */%}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
#### `note` Admonition Shortcode Output (Code)
|
||||
|
||||
@@ -106,13 +106,13 @@ Use the `warning` shortcode when you want to draw the user's attention to someth
|
||||
|
||||
#### `warning` Admonition Shortcode Input
|
||||
|
||||
{{% input file="warning-admonition-input.md" %}}
|
||||
{{% code file="warning-admonition-input.md" %}}
|
||||
```golang
|
||||
{{%/* warning "Example Warning" */%}}
|
||||
This is a warning, which should be reserved for *important* information like breaking changes.
|
||||
{{%/* /warning */%}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
#### `warning` Admonition Shortcode Output
|
||||
|
||||
|
||||
@@ -45,7 +45,7 @@ Highlighting is carried out via the [built-in shortcode](/content-management/sho
|
||||
|
||||
### Example `highlight` Shortcode Input
|
||||
|
||||
{{% input file="example-highlight-shortcode-input.md" %}}
|
||||
{{% code file="example-highlight-shortcode-input.md" %}}
|
||||
```html
|
||||
{{</* highlight html */>}}
|
||||
<section id="main">
|
||||
@@ -58,7 +58,7 @@ Highlighting is carried out via the [built-in shortcode](/content-management/sho
|
||||
</section>
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### Example `highlight` Shortcode Output
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@ Checks whether a given value is set and returns a default value if it is not. *S
|
||||
|
||||
`default` function examples reference the following content page:
|
||||
|
||||
{{% input file="content/posts/default-function-example.md" %}}
|
||||
{{% code file="content/posts/default-function-example.md" %}}
|
||||
```yaml
|
||||
---
|
||||
title: Sane Defaults
|
||||
@@ -39,7 +39,7 @@ oldparam: The default function helps make your templating DRYer.
|
||||
newparam:
|
||||
---
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
`default` can be written in more than one way:
|
||||
|
||||
@@ -52,12 +52,12 @@ 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:
|
||||
|
||||
{{% input file="variable-as-default-value.html" nocopy="true" %}}
|
||||
{{% code file="variable-as-default-value.html" nocopy="true" %}}
|
||||
```golang
|
||||
{{$old := .Params.oldparam }}
|
||||
<p>{{ .Params.newparam | default $old }}</p>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Which would return:
|
||||
|
||||
@@ -67,11 +67,11 @@ Which would return:
|
||||
|
||||
And then using dot notation
|
||||
|
||||
{{% input file="dot-notation-default-value.html" %}}
|
||||
{{% code file="dot-notation-default-value.html" %}}
|
||||
```golang
|
||||
<title>{{ .Params.seo_title | default .Title }}</title>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Which would return
|
||||
|
||||
@@ -85,21 +85,21 @@ The following have equivalent return values but are far less terse. This demonst
|
||||
|
||||
Using `if`:
|
||||
|
||||
{{% input file="if-instead-of-default.html" nocopy="true" %}}
|
||||
{{% code file="if-instead-of-default.html" nocopy="true" %}}
|
||||
```golang
|
||||
<title>{{if .Params.seo_title}}{{.Params.seo_title}}{{else}}{{.Title}}{{end}}</title>
|
||||
=> Sane Defaults
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Using `with`:
|
||||
|
||||
{{% input file="with-instead-of-default.html" nocopy="true" %}}
|
||||
{{% code file="with-instead-of-default.html" nocopy="true" %}}
|
||||
```golang
|
||||
<title>{{with .Params.seo_title}}{{.}}{{else}}{{.Title}}{{end}}</title>
|
||||
=> Sane Defaults
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -26,14 +26,14 @@ To maintain a consistent output order, maps will be sorted by keys and only a sl
|
||||
|
||||
Examples of `delimit` use the following front matter:
|
||||
|
||||
{{% input file="delimit-example-front-matter.toml" nocopy="true" %}}
|
||||
{{% code file="delimit-example-front-matter.toml" nocopy="true" %}}
|
||||
```toml
|
||||
+++
|
||||
title: I love Delimit
|
||||
tags: [ "tag1", "tag2", "tag3" ]
|
||||
+++
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
`delimit` called in your template takes the form of
|
||||
|
||||
@@ -41,11 +41,11 @@ tags: [ "tag1", "tag2", "tag3" ]
|
||||
{{ delimit array/slice/map delimiter optionallastdelimiter}}
|
||||
```
|
||||
|
||||
{{% input file="delimit-pages-tags.html" %}}
|
||||
{{% code file="delimit-pages-tags.html" %}}
|
||||
```html
|
||||
<p>Tags: {{ delimit .Params.tags ", " }}</p>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% output "delimit-pages-tags-output.html" %}}
|
||||
```html
|
||||
@@ -55,11 +55,11 @@ tags: [ "tag1", "tag2", "tag3" ]
|
||||
|
||||
Here is the same example but with the optional "last" delimiter:
|
||||
|
||||
{{% input file="delimit-page-tags-final-and.html" %}}
|
||||
{{% code file="delimit-page-tags-final-and.html" %}}
|
||||
```golang
|
||||
Tags: {{ delimit .Params.tags ", " ", and " }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% output "delimit-page-tags-final-and-output.html" %}}
|
||||
```html
|
||||
|
||||
@@ -234,14 +234,14 @@ No other web server software (e.g., Apache, nginx, IIS) is necessary.
|
||||
|
||||
Here is the command:
|
||||
|
||||
{{% input file="hugo-production-server.sh" %}}
|
||||
{{% code file="hugo-production-server.sh" %}}
|
||||
```bash
|
||||
hugo server --baseURL=http://yoursite.org/ \
|
||||
--port=80 \
|
||||
--appendPort=false \
|
||||
--bind=87.245.198.50
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Note the `bind` option, which is the interface to which the server will bind (defaults to `127.0.0.1`: fine for most development use cases). Some hosts, such as Amazon Web Services, run NAT (network address translation); sometimes it can be hard to figure out the actual IP address. Using `--bind=0.0.0.0` will bind to all interfaces.
|
||||
|
||||
|
||||
@@ -28,7 +28,7 @@ In this `config` file, you can direct to Hugo as to how it should render your we
|
||||
|
||||
The following is a typical example of a YAML configuration file. Note the document opens with 3 hyphens and closes with 3 periods. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
|
||||
|
||||
{{% input file="config.yml" %}}
|
||||
{{% code file="config.yml"%}}
|
||||
```yaml
|
||||
---
|
||||
baseURL: "https://yoursite.example.com/"
|
||||
@@ -46,13 +46,13 @@ params:
|
||||
SidebarRecentLimit: 5
|
||||
...
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### All Variables, YAML
|
||||
|
||||
The following is the full list of Hugo-defined variables in an example YAML file. The values provided in this example represent the default values used by Hugo.
|
||||
|
||||
{{% input file="config.yml" %}}
|
||||
{{% code file="config.yml" download="config.yml" %}}
|
||||
```yaml
|
||||
---
|
||||
archetypeDir: "archetypes"
|
||||
@@ -163,7 +163,7 @@ taxonomies:
|
||||
- tag: "tags"
|
||||
---
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
## TOML Configuration
|
||||
|
||||
@@ -191,7 +191,7 @@ title = "My Hugo Site"
|
||||
|
||||
The following is the full list of Hugo-defined variables in an example TOML file. The values provided in this example represent the default values used by Hugo.
|
||||
|
||||
{{% input file="config.toml" %}}
|
||||
{{% code file="config.toml" download="config.toml"%}}
|
||||
```toml
|
||||
+++
|
||||
archetypeDir = "archetypes"
|
||||
@@ -304,7 +304,7 @@ watch = true
|
||||
tag = "tags"
|
||||
+++
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
## Configuration Through Environmental Variables
|
||||
|
||||
@@ -346,7 +346,7 @@ However, if you have specific needs with respect to Markdown, Hugo exposes some
|
||||
2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override the site setting there. See [site configuration for more information](/content-management/front-matter/#override-global-blackfriday-configuration).
|
||||
{{% /note %}}
|
||||
|
||||
{{% input file="bf-config.toml" %}}
|
||||
{{% code file="bf-config.toml" %}}
|
||||
```toml
|
||||
[blackfriday]
|
||||
angledQuotes = true
|
||||
@@ -354,9 +354,9 @@ However, if you have specific needs with respect to Markdown, Hugo exposes some
|
||||
plainIDAnchors = true
|
||||
extensions = ["hardLineBreak"]
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% input file="bf-config.yml" %}}
|
||||
{{% code file="bf-config.yml" %}}
|
||||
```yaml
|
||||
blackfriday:
|
||||
angledQuotes: true
|
||||
@@ -365,7 +365,7 @@ blackfriday:
|
||||
extensions:
|
||||
- hardLineBreak
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
|
||||
## Specs for Configuration Formats
|
||||
|
||||
@@ -39,11 +39,11 @@ Ideally, you should install it somewhere in your `PATH` for easy use. `/usr/loca
|
||||
|
||||
If you are on OS X and using [Homebrew][brew], you can install Hugo with the following one-liner:
|
||||
|
||||
{{% input file="install-with-homebrew.sh" %}}
|
||||
{{% code file="install-with-homebrew.sh" %}}
|
||||
```bash
|
||||
brew update && brew install hugo
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
For more detailed explanations, read the installation guides that follow for [Windows](#installing-hugo-on-windows) and [Mac OS X](#installing-hugo-on-mac-osx).
|
||||
|
||||
@@ -110,29 +110,29 @@ Since building from source is appealing to more seasoned command line users, thi
|
||||
|
||||
Go to the `brew` website, <http://brew.sh/>, and follow the directions there. The most important step is the installation from the command line:
|
||||
|
||||
{{% input file="install-brew.sh" %}}
|
||||
{{% code file="install-brew.sh" %}}
|
||||
```bash
|
||||
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
#### Step 2: Run the `brew` Command to Install `hugo`
|
||||
|
||||
Whenever installing with Homebrew, it's a good idea to update the formulae and Homebrew itself by running the update command:
|
||||
|
||||
{{% input file="update-brew.sh" %}}
|
||||
{{% code file="update-brew.sh" %}}
|
||||
```bash
|
||||
$ brew update
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
You can then install Hugo using `brew`:
|
||||
|
||||
{{% input file="install-brew.sh" %}}
|
||||
{{% code file="install-brew.sh" %}}
|
||||
```bash
|
||||
$ brew install hugo
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
If Homebrew is working properly, you should see something similar to the following:
|
||||
|
||||
|
||||
@@ -91,11 +91,11 @@ You'll see the `bookshelf` directory has 6 subdirectories and 1 file. Let's look
|
||||
|
||||
Let's now add a post to our "bookshelf." We will use the `hugo new` command to add a post. This first post will be on the book [*Good To Great*][bookurl]. Make sure you are inside the `bookshelf` directory.
|
||||
|
||||
{{% input file="create-new-book-review-post.sh" %}}
|
||||
{{% code file="create-new-book-review-post.sh" %}}
|
||||
```bash
|
||||
hugo new post/good-to-great.md
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
You should then see the following output:
|
||||
|
||||
@@ -137,7 +137,7 @@ The text bracketed by `+++` is the TOML [front matter][frontmatter] for the cont
|
||||
|
||||
Let's update `good-to-great.md` with a short review of *Good to Great*:
|
||||
|
||||
{{% input file="good-to-great-start.md" %}}
|
||||
{{% code file="good-to-great-start.md" %}}
|
||||
```markdown
|
||||
+++
|
||||
date = "2016-02-14T16:11:58+05:30"
|
||||
@@ -147,7 +147,7 @@ title = "Good to Great Book Review"
|
||||
|
||||
I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great. Although this book is about how companies became great but we could apply a lot of the learnings on ourselves. Concepts like level 5 leader, hedgehog concept, the stockdale paradox are equally applicable to individuals.
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
## Step 4. Serve Content
|
||||
|
||||
@@ -230,19 +230,19 @@ You can clone one or more themes from within the `themes` directory. We will use
|
||||
|
||||
Once inside the `themes` directory, you can use the following one-liner to clone Robust, check out the specific commit, and then return to your project's root directory:
|
||||
|
||||
{{% input file="clone-robust-theme" %}}
|
||||
{{% code file="clone-robust-theme" %}}
|
||||
```bash
|
||||
git clone https://github.com/dim0627/hugo_theme_robust.git && cd hugo_theme_robust && git checkout 3baae29 && cd ../..
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Now let's start Hugo's server again but with the addition of the `-theme` flag for Robust:
|
||||
|
||||
{{% input file="hugo-server-with-theme.sh" %}}
|
||||
{{% code file="hugo-server-with-theme.sh" %}}
|
||||
```bash
|
||||
hugo server --theme=hugo_theme_robust --buildDrafts
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
You should see an output to the console similar to the following:
|
||||
|
||||
@@ -306,19 +306,19 @@ You can very easily switch between different themes in Hugo. Let's suppose we wa
|
||||
|
||||
From your project root, you can use this one-liner to change into `themes`, clone Bleak, and go back to your project's root directory:
|
||||
|
||||
{{% input file="clone-bleak-theme.sh" %}}
|
||||
{{% code file="clone-bleak-theme.sh" %}}
|
||||
```bash
|
||||
cd themes && git clone https://github.com/Zenithar/hugo-theme-bleak.git && cd ..
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Now restart the server with our new theme flag:
|
||||
|
||||
{{% input file="run-server-with-bleak.sh" %}}
|
||||
{{% code file="run-server-with-bleak.sh" %}}
|
||||
```bash
|
||||
hugo server --theme=hugo-theme-bleak --buildDrafts
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Our website is now using the `bleak` theme at <http://localhost:1313>, which should look similar to the following screenshot:
|
||||
|
||||
@@ -328,17 +328,17 @@ Our website is now using the `bleak` theme at <http://localhost:1313>, which sho
|
||||
|
||||
Kill the Hugo server if you are still running it with the Bleak theme, and then restart the server with the `robust` theme. We will use Robust for the duration of this Quick Start:
|
||||
|
||||
{{% input file="restart-with-robust-sh" %}}
|
||||
{{% code file="restart-with-robust-sh" %}}
|
||||
```bash
|
||||
hugo server --theme=hugo_theme_robust --buildDrafts
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### Updating Our `config.toml`
|
||||
|
||||
Our website is currently using the dummy values specified in `bookshelf/config.toml`, which were auto-generated with `hugo new site bookshelf`. Let's update the configuration:
|
||||
|
||||
{{% input file="updated-config.toml" %}}
|
||||
{{% code file="updated-config.toml" %}}
|
||||
```toml
|
||||
baseURL = "http://example.org/"
|
||||
languageCode = "en-us"
|
||||
@@ -347,7 +347,7 @@ title = "Shekhar Gulati Book Reviews"
|
||||
[Params]
|
||||
Author = "Shekhar Gulati"
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### Watch Your Site Reload Instantly
|
||||
|
||||
@@ -404,15 +404,15 @@ Now we need to change the layout of the index page so that only images are shown
|
||||
|
||||
Create a new file for `li.html` inside the `bookshelf/layouts/_default` directory. If you are in your project root, you can use the following one-liner to both create the file and return to the project root:
|
||||
|
||||
{{% input file="create-new-li-html.sh" %}}
|
||||
{{% code file="create-new-li-html.sh" %}}
|
||||
```bash
|
||||
cd layouts && mkdir _default && cd _default && touch li.html && cd ../..
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Copy the content shown below into the new `li.html`. When contrasting this with the `li.html` that ships with the Robust theme, you'll notice we have removed details of the book so that only the image is shown:
|
||||
|
||||
{{% input file="layouts/_default/li.html" %}}
|
||||
{{% code file="layouts/_default/li.html" %}}
|
||||
```html
|
||||
<article class="li">
|
||||
<a href="{{ .Permalink }}" class="clearfix">
|
||||
@@ -420,7 +420,7 @@ Copy the content shown below into the new `li.html`. When contrasting this with
|
||||
</a>
|
||||
</article>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Now, the website should render similar to the following screenshot:
|
||||
|
||||
@@ -430,26 +430,26 @@ Next, we want to remove information related to the theme from the footer. Let's
|
||||
|
||||
This is a new [partial template][partialtemplates]. If you are still in the project's root directory, you can use the following one-liner to create the partial before returning to the project root:
|
||||
|
||||
{{% input file="create-new-default-foot.sh" %}}
|
||||
{{% code file="create-new-default-foot.sh" %}}
|
||||
```bash
|
||||
cd layouts && mkdir partials && cd partials && touch default_foot.html && cd ../..
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Now add the following to our new `default_foot.html` partial template:
|
||||
|
||||
{{% input file="layouts/partials/default_foot.html" %}}
|
||||
{{% code file="layouts/partials/default_foot.html" %}}
|
||||
```html
|
||||
<footer class="site">
|
||||
<p>{{ with .Site.Copyright | safeHTML }}{{ . }}{{ else }}© {{ $.Site.LastChange.Year }} {{ if isset $.Site.Params "Author" }}{{ $.Site.Params.Author }}{{ else }}{{ .Site.Title }}{{ end }}{{ end }}</p>
|
||||
<p>Powered by <a href="http://gohugo.io" target="_blank">Hugo</a>,</p>
|
||||
</footer>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
So far we are using the default image, but we would like to use the book image so that we can relate to the book. Every book review will define a configuration setting in its front matter. Update the content and front matter of `good-to-great.md` as shown below.
|
||||
|
||||
{{% input file="content/post/good-to-great.md" %}}
|
||||
{{% code file="content/post/good-to-great.md" %}}
|
||||
```markdown
|
||||
+++
|
||||
date = "2017-02-19T21:09:05-06:00"
|
||||
@@ -460,7 +460,7 @@ image = "good-to-great.jpg"
|
||||
|
||||
I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great. Although this book is about how companies became great but we could apply a lot of the learnings on ourselves. Concepts like level 5 leader, hedgehog concept, the stockdale paradox are equally applicable to individuals.
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Grab a (legal) image from somewhere, name it `good-to-great.jpg`, and place it in the `bookshelf/static/images` directory.
|
||||
|
||||
@@ -547,11 +547,11 @@ There is more than one way to host your site on GitHub. Be sure to check out [Ho
|
||||
|
||||
First, let's set up Git version control for your bookshelf website and include a `.gitignore` file to prevent tracking of the `public` and `themes` directories. From within your root project directory, you can use the following one-liner:
|
||||
|
||||
{{% input file="set-up-git.sh" %}}
|
||||
{{% code file="set-up-git.sh" %}}
|
||||
```bash
|
||||
git init && echo "/public/" >> .gitignore && echo "/themes/" >> .gitignore && git add . && git commit -m "Initial commit"
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Now the Git repositories under `bookshelf/themes` won't conflict with your `bookshelf` repository, and neither will a Git repository in `bookshelf/public`.
|
||||
|
||||
|
||||
@@ -35,11 +35,11 @@ If it is not done yet, we will make an automated way to SSH to your server. If y
|
||||
|
||||
First, install the ssh client. On Debian/Ubuntu/derivates, use the following command:
|
||||
|
||||
{{% input file="install-openssh.sh" %}}
|
||||
{{% code file="install-openssh.sh" %}}
|
||||
```bash
|
||||
sudo apt-get install openssh-client
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Then generate your ssh key by entering the following commands:
|
||||
|
||||
|
||||
@@ -42,29 +42,29 @@ All the work for setting up a Hugo project and using this guide is done via the
|
||||
|
||||
First, create your new Hugo website using the [`hugo new site` command][basicusage] and change into the newly created directory for the project. In this guide, we are calling our new project `hugo-wercker-example`:
|
||||
|
||||
{{% input file="hugo-new-site.sh" %}}
|
||||
{{% code file="hugo-new-site.sh" %}}
|
||||
```bash
|
||||
hugo new site hugo-wercker-example
|
||||
cd hugo-wercker-example
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
We will use the [Herring Cove theme][] by first cloning the theme into the `themes` directory.
|
||||
|
||||
{{% input file="clone-herring-cove-theme.sh" %}}
|
||||
{{% code file="clone-herring-cove-theme.sh" %}}
|
||||
```bash
|
||||
cd themes
|
||||
git clone https://github.com/spf13/herring-cove.git
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Cloning the project from the command line will conflict with our own version control. So, we need to remove the external git configuration that came with the clone of Herring Cove:
|
||||
|
||||
{{% input file="remove-herring-cove-git.sh" %}}
|
||||
{{% code file="remove-herring-cove-git.sh" %}}
|
||||
```bash
|
||||
rm -rf herring-cove/.git
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
We need content for Hugo to build. Let's add a quick `/about` page:
|
||||
|
||||
@@ -78,11 +78,11 @@ The preceding example for the about page leverages archetypes to scaffold a new
|
||||
|
||||
Now you can edit `contents/about.md` in your text editor of choice, but this is not necessary for the purposes of this guide. Running the following command will build your Hugo site into the `public` directory. We have added `undraft` to ensure that the example page is no longer in draft mode:
|
||||
|
||||
{{% input file="hugo-build-undraft.sh" %}}
|
||||
{{% code file="hugo-build-undraft.sh" %}}
|
||||
```bash
|
||||
hugo undraft content/about.md
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Once the website is build, t's a good idea to run the following command to start a local server and ensure you're changes have been implemented:
|
||||
|
||||
@@ -104,19 +104,19 @@ git init
|
||||
|
||||
Running `git status` at this point will show you the following entries: the `config.toml` file, the `themes` directory, the `contents` directory, and the `public` directory. However, we don't want the `public` directory version controlled because Wercker is responsible for generating the finished website later on. Therefore, we'll add a `.gitignore` file to our project that will exclude the `/public` directory from being tracked by Git:
|
||||
|
||||
{{% input file="gitignore.sh" %}}
|
||||
{{% code file="gitignore.sh" %}}
|
||||
```bash
|
||||
echo "/public" >> .gitignore
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Wercker might complain when we try to build the site later on because we currently do not have any static files outside of the `themes` directory. We simply have to add *any* file to the static folder to prevent Wercker from complaining. To keep this guide simple, let's add a `robots.txt`. The following command creates the file in `/static`. The contents of the `robots.txt` lets search engines know they have full access to crawl the published website:
|
||||
|
||||
{{% input file="addrobotstxt.sh" %}}
|
||||
{{% code file="addrobotstxt.sh" %}}
|
||||
```bash
|
||||
echo "User-agent: *\nDisallow:" > static/robots.txt
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Now we need to add (i.e., [stage [see Git documentation]][gitbasics]) and commit all of our changes in the repository into Git:
|
||||
|
||||
@@ -130,12 +130,12 @@ Now we need to create a new repository on GitHub. Once you are signed in to GitH
|
||||
|
||||
We then choose a name for the project (`hugo-wercker-example`). When clicking on create repository GitHub displays the commands for adding an existing project to the site. The commands shown below are the ones used for this site, if you're following along you will need to use the ones shown by GitHub. Once we've run those commands the project is in GitHub and we can move on to setting up the Wercker configuration. Be sure to replace `YourUserName` with your GitHub account/username:
|
||||
|
||||
{{% input file="setup-gh-repo.sh" %}}
|
||||
{{% code file="setup-gh-repo.sh" %}}
|
||||
```bash
|
||||
git remote add origin git@github.com:YourUsername/hugo-wercker-example.git
|
||||
git push -u origin master
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
![][2]
|
||||
|
||||
@@ -225,7 +225,7 @@ We're not going to use any of the advanced features of Hugo-Build in this guide.
|
||||
The docs are a work in progress. As such, the `version` represented in this guide may not represent the version you've been using for local development. Be sure to use the appropriate Hugo version for your build step.
|
||||
{{% /warning %}}
|
||||
|
||||
{{% input file="wercker-build-step.yml" %}}
|
||||
{{% code file="wercker-build-step.yml" %}}
|
||||
```yaml
|
||||
box: debian
|
||||
build:
|
||||
@@ -235,16 +235,16 @@ build:
|
||||
theme: herring-cove
|
||||
flags: --buildDrafts=true
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
We can conclude this first step by pushing our `wercker.yml` to our GitHub repository and then seeing the magic at work within Wercker's interface.
|
||||
|
||||
{{% input file="push-wecker-to-gh.sh" %}}
|
||||
{{% code file="push-wecker-to-gh.sh" %}}
|
||||
```bash
|
||||
git commit -a -m "Add wercker.yml"
|
||||
git push origin master
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
If completed and successful, a green check mark should appear in the commit column of your first build. However, this is only the build step. We still need to deploy the website to our free hosting on GitHub Pages. If you would like more details about the build, you can click the commit hash.
|
||||
|
||||
@@ -254,7 +254,7 @@ If completed and successful, a green check mark should appear in the commit colu
|
||||
|
||||
In order to deploy to GitHub Pages, we need to add a deploy step to our `wercker.yml`. We are going to add `lukevevier/gh-pages`, the most popular GitHub Pages step in the Wercker Steps repository. Additionally, we need to ensure the box Wercker uses for our deployments has git and ssh installed. We can do this using the `install-packages` command. Here is our *final* `wercker.yml` file:
|
||||
|
||||
{{% input file="wercker.yml" %}}
|
||||
{{% code file="wercker.yml" %}}
|
||||
```yaml
|
||||
box: debian
|
||||
build:
|
||||
@@ -272,7 +272,7 @@ deploy:
|
||||
domain: hugo-wercker.ig.nore.me
|
||||
basedir: public
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### How does the GitHub Pages Configuration Work?
|
||||
|
||||
|
||||
@@ -94,7 +94,7 @@ After a short while you'll see the updated contents on your GitHub Pages site.
|
||||
|
||||
To automate these steps, you can create a script with the following contents:
|
||||
|
||||
{{% input file="publish_to_ghpages.sh" %}}
|
||||
{{% code file="publish_to_ghpages.sh" %}}
|
||||
```sh
|
||||
#!/bin/sh
|
||||
|
||||
@@ -126,7 +126,7 @@ hugo
|
||||
echo "Updating gh-pages branch"
|
||||
cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)"
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing. Or adding `echo yourdomainname.com >> CNAME` if you set up for your gh-pages to use customize domain.
|
||||
|
||||
|
||||
@@ -32,7 +32,7 @@ cd your-hugo-site
|
||||
|
||||
In the root directory of your Hugo site, create a `.gitlab-ci.yml` file. The `.gitlab-ci.yml` configures the GitLab CI on how to build your page. Simply add the content below.
|
||||
|
||||
{{% input file="gitlab-ci.yml" %}}
|
||||
{{% code file="gitlab-ci.yml" %}}
|
||||
```yml
|
||||
image: publysher/hugo
|
||||
|
||||
@@ -45,7 +45,7 @@ pages:
|
||||
only:
|
||||
- master
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
## Push Your Hugo Website to GitLab
|
||||
|
||||
|
||||
@@ -29,7 +29,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:
|
||||
|
||||
{{% input file="404.html"%}}
|
||||
{{% code file="404.html"%}}
|
||||
```html
|
||||
{{ partial "header.html" . }}
|
||||
{{ partial "subheader.html" . }}
|
||||
@@ -42,7 +42,7 @@ This is a basic example of a 404.html template:
|
||||
|
||||
{{ partial "footer.html" . }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
## Automatic Loading
|
||||
|
||||
|
||||
@@ -274,7 +274,7 @@ The most easily overlooked concept to understand about Go templates is that `{{
|
||||
|
||||
The following shows how to define a variable independent of the context.
|
||||
|
||||
{{% input file="range-through-tags-w-variable.html" %}}
|
||||
{{% code file="range-through-tags-w-variable.html" %}}
|
||||
```html
|
||||
{{ $title := .Site.Title }}
|
||||
{{ $base := .Site.BaseURL }}
|
||||
@@ -287,7 +287,7 @@ The following shows how to define a variable independent of the context.
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% note %}}
|
||||
Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well.
|
||||
@@ -297,7 +297,7 @@ Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}`
|
||||
|
||||
`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block where we defined `$title` and `$base` for the same desired output, but now using `$`:
|
||||
|
||||
{{% input file="range-through-tags-w-global.html" %}}
|
||||
{{% code file="range-through-tags-w-global.html" %}}
|
||||
```html
|
||||
{{ $base := .Site.BaseURL }}
|
||||
<ul class="tags">
|
||||
@@ -309,7 +309,7 @@ Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}`
|
||||
{{ end }}
|
||||
</ul>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% warning "Don't Redefine the Dot" %}}
|
||||
The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. ***Don't do it.*** You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value.
|
||||
@@ -321,13 +321,13 @@ Go 1.6 includes the ability to trim the whitespace from either side of a Go tag
|
||||
|
||||
For instance, the following Go template will include the newlines and horizontal tab in its HTML output:
|
||||
|
||||
{{% input file="with-whitespace.html" %}}
|
||||
{{% code file="with-whitespace.html" %}}
|
||||
```html
|
||||
<div>
|
||||
{{ .Title }}
|
||||
</div>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% output "with-whitespace-output.html" %}}
|
||||
```html
|
||||
@@ -339,13 +339,13 @@ For instance, the following Go template will include the newlines and horizontal
|
||||
|
||||
Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline:
|
||||
|
||||
{{% input file="without-whitespace-input.html" %}}
|
||||
{{% code file="without-whitespace-input.html" %}}
|
||||
```html
|
||||
<div>
|
||||
{{- .Title -}}
|
||||
</div>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% output "without-whitespace-input.html" %}}
|
||||
```html
|
||||
@@ -383,7 +383,7 @@ toc: true
|
||||
|
||||
Here is the corresponding code inside the `table-of-contents.html` [partial template][partials]:
|
||||
|
||||
{{% input file="table-of-contents.html" %}}
|
||||
{{% code file="table-of-contents.html" %}}
|
||||
```html
|
||||
{{if ne .Params.toc false}}
|
||||
<aside id="toc">
|
||||
@@ -397,7 +397,7 @@ Here is the corresponding code inside the `table-of-contents.html` [partial temp
|
||||
<a href="#" id="toc-toggle"></a>
|
||||
{{end}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `toc:` field in this page's front matter does not equal (i.e. `ne`) `false`.
|
||||
|
||||
@@ -407,28 +407,28 @@ In your [site's configuration file][hugoconfig] (e.g., `config.yaml`), you can d
|
||||
|
||||
For instance, you might declare:
|
||||
|
||||
{{% input file="config.yaml" %}}
|
||||
{{% code file="config.yaml" %}}
|
||||
```yaml
|
||||
params:
|
||||
CopyrightHTML: "Copyright © 2013 John Doe. All Rights Reserved."
|
||||
TwitterUser: "spf13"
|
||||
SidebarRecentLimit: 5
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Within a footer layout, you might then declare a `<footer>` which is only provided if the `CopyrightHTML` parameter is provided, and if it is given, you would declare it to be HTML-safe, so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates.
|
||||
|
||||
{{% input file="layouts/partials/sample-footer.html" %}}
|
||||
{{% code file="layouts/partials/sample-footer.html" %}}
|
||||
```html
|
||||
{{if .Site.Params.CopyrightHTML}}<footer>
|
||||
<div class="text-center">{{.Site.Params.CopyrightHTML | safeHTML}}</div>
|
||||
</footer>{{end}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
An alternative way of writing the "`if`" and then referencing the same value is to use [`with`](/functions/with/) instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent:
|
||||
|
||||
{{% input file="layouts/partials/twitter.html" %}}
|
||||
{{% code file="layouts/partials/twitter.html" %}}
|
||||
```html
|
||||
{{with .Site.Params.TwitterUser}}<span class="twitter">
|
||||
<a href="https://twitter.com/{{.}}" rel="author">
|
||||
@@ -436,7 +436,7 @@ An alternative way of writing the "`if`" and then referencing the same value is
|
||||
alt="Twitter"></a>
|
||||
</span>{{end}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`](/functions/first/) and [`.RelPermalink`](/functions/relpermalink/) functions as well as the [`.Site.Pages` variable](/variables-and-params/site-variables/).
|
||||
|
||||
@@ -453,7 +453,7 @@ Finally, you can pull "magic constants" out of your layouts as well. The followi
|
||||
|
||||
Go allows you to do more than what's shown here. Using Hugo's [`where` function](/functions/where/) and Go built-ins, we can list only the items from `content/events/` whose date (set in the [front matter][]) is in the future:
|
||||
|
||||
{{% input file="show-upcoming-dates.html" %}}
|
||||
{{% code file="show-upcoming-dates.html" %}}
|
||||
```golang
|
||||
<h4>Upcoming Events</h4>
|
||||
<ul class="upcoming-events">
|
||||
@@ -468,7 +468,7 @@ Go allows you to do more than what's shown here. Using Hugo's [`where` function]
|
||||
{{ end }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
|
||||
[`where` function]: /functions/where/
|
||||
|
||||
@@ -32,7 +32,7 @@ Whether the path is absolute or relative does not matter because---at least for
|
||||
|
||||
So, let's create a new shortcode using `readDir`:
|
||||
|
||||
{{% input file="layouts/shortcodes/directoryindex.html" %}}<pre><code>{{< readfile "layouts/shortcodes/directoryindex.html" >}}</code></pre>{{% /input %}}
|
||||
{{% code file="layouts/shortcodes/directoryindex.html" %}}<pre><code>{{< readfile "layouts/shortcodes/directoryindex.html" >}}</code></pre>{{% /code %}}
|
||||
|
||||
For the files in any given directory, this shortcode usefully lists the files' basenames and sizes and also creates a link to each of them.
|
||||
|
||||
|
||||
@@ -56,7 +56,7 @@ When using Hugo v0.12 and above, please use the `partial` call (and leave out th
|
||||
|
||||
This header template is used for [spf13.com](http://spf13.com/):
|
||||
|
||||
{{% input file="layouts/partials/header.html" %}}
|
||||
{{% code file="layouts/partials/header.html" %}}
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
|
||||
@@ -74,13 +74,13 @@ This header template is used for [spf13.com](http://spf13.com/):
|
||||
</head>
|
||||
<body lang="en">
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
## Example footer.html
|
||||
|
||||
This footer template is used for [spf13.com](http://spf13.com/):
|
||||
|
||||
{{% input file="layouts/partials/footer.html" %}}
|
||||
{{% code file="layouts/partials/footer.html" %}}
|
||||
```html
|
||||
<footer>
|
||||
<div>
|
||||
@@ -109,7 +109,7 @@ This footer template is used for [spf13.com](http://spf13.com/):
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
To reference a partial template stored in a subfolder, e.g. `/layouts/partials/post/tag/list.html`, call it this way:
|
||||
|
||||
@@ -171,19 +171,19 @@ Provide your tracking id in your configuration file, e.g. config.yaml.
|
||||
|
||||
Include the internal template in your templates like so:
|
||||
|
||||
{{% input file="call-ga.md" %}}
|
||||
{{% code file="call-ga.md" %}}
|
||||
```golang
|
||||
{{ template "_internal/google_analytics.html" . }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
For asynchronous loading of Google analytics, include the async template:
|
||||
|
||||
{{% input file="call-ga-async.md" %}}
|
||||
{{% code file="call-ga-async.md" %}}
|
||||
```golang
|
||||
{{ template "_internal/google_analytics_async.html" . }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
<!-- pulled from extras/comments -->
|
||||
|
||||
@@ -227,7 +227,7 @@ You also have the option to set the following in the front matter for a given pi
|
||||
|
||||
Users have noticed that enabling Disqus comments when running the Hugo web server on `localhost` (i.e. via `hugo server`) causes the creation of unwanted discussions on the associated Disqus account. In order to prevent this, a slightly tweaked partial template is required. So, rather than using the built-in `"_internal/disqus.html"` template referenced above, create a template in `layouts/partials` that looks like the following:
|
||||
|
||||
{{% input file="layouts/partials/disqus.html" %}}
|
||||
{{% code file="layouts/partials/disqus.html" %}}
|
||||
```html
|
||||
<div id="disqus_thread"></div>
|
||||
<script type="text/javascript">
|
||||
@@ -247,17 +247,17 @@ Users have noticed that enabling Disqus comments when running the Hugo web serve
|
||||
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
|
||||
<a href="http://disqus.com/" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`.
|
||||
|
||||
You can then reference the partial template:
|
||||
|
||||
{{% input file="disqus-reference.html" %}}
|
||||
{{% code file="disqus-reference.html" %}}
|
||||
```golang
|
||||
{{ partial "disqus.html" . }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
## Alternatives
|
||||
|
||||
|
||||
@@ -85,7 +85,7 @@ It makes use of [partial templates][partials]. All examples use a
|
||||
[view](/templates/views/) called either "li" or "summary" which this example site
|
||||
defined.
|
||||
|
||||
{{% input file="layouts/section/post.html" %}}
|
||||
{{% code file="layouts/section/post.html" %}}
|
||||
```html
|
||||
{{ partial "header.html" . }}
|
||||
{{ partial "subheader.html" . }}
|
||||
@@ -102,7 +102,7 @@ defined.
|
||||
</section>
|
||||
{{ partial "footer.html" . }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### Example taxonomy template (tag.html)
|
||||
This content template is used for [spf13.com](http://spf13.com/).
|
||||
@@ -400,13 +400,13 @@ you can do just that.
|
||||
1. `array` or `slice of maps or structs`
|
||||
2. `number of elements`
|
||||
|
||||
{{% input file="layout/_default/section.html" %}}
|
||||
{{% code file="layout/_default/section.html" %}}
|
||||
```golang
|
||||
{{ range first 10 .Data.Pages }}
|
||||
{{ .Render "summary" }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### `where`
|
||||
|
||||
@@ -416,25 +416,25 @@ you can do just that.
|
||||
2. `key` or `field name'
|
||||
3. `match value`
|
||||
|
||||
{{% input file="layouts/_default/.html" %}}
|
||||
{{% code file="layouts/_default/.html" %}}
|
||||
```html
|
||||
{{ range where .Data.Pages "Section" "post" }}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### `first` and `where` Together
|
||||
|
||||
Using `first` and `where` together can be very powerful:
|
||||
|
||||
{{% input file="first-and-where-together.html" %}}
|
||||
{{% code file="first-and-where-together.html" %}}
|
||||
```golang
|
||||
{{ range first 5 (where .Data.Pages "Section" "post") }}
|
||||
{{ .Content }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
{{% note %}}
|
||||
If `where` or `first` receives invalid input or a field name that doesn’t exist, it will return an error and stop site generation. `where` and `first` also work on taxonomy list templates *and* taxonomy terms templates. (See [Taxonomy Templates](/templates/taxonomy-templates/).)
|
||||
@@ -459,9 +459,9 @@ The valid values for 'kind' are as follows:
|
||||
|
||||
The `.Site.GetPage` example assumes the following project directory structure:
|
||||
|
||||
{{% input file="grab-blog-section-index-page-title.html" %}}
|
||||
{{% code file="grab-blog-section-index-page-title.html" %}}
|
||||
{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
`.Site.GetPage` will return `nil` if no `_index.md` page is found. If `content/blog/_index.md` does not exist, the template will output a blank section where `{{.Title}}` should have been in the preceding example.
|
||||
|
||||
|
||||
@@ -15,11 +15,11 @@ toc: true
|
||||
|
||||
## Creating Custom Shortcodes
|
||||
|
||||
Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templatessection] and [basic content files][].
|
||||
Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files][].
|
||||
|
||||
### File Placement
|
||||
|
||||
To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][directorystructurepage]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose.
|
||||
To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{</* myshortcode /*/>}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose.
|
||||
|
||||
### Deciding on Shortcode and Parameter Type
|
||||
|
||||
@@ -76,9 +76,9 @@ A shortcode with `.Inner` content can be used without the inline content, and wi
|
||||
|
||||
The variable `.Params` contains the list of parameters in case you need to do more complicated things than `.Get`. It is sometimes useful to provide a flexible shortcode that can take named or positional parameters. To meet this need, Hugo shortcodes have `.IsNamedParams`, a boolean available that can be used such as `{{ if .IsNamedParams }}...{{ else }}...{{ end }}`. See the [example Vimeo shortcode][vimeoexample] below for an example.
|
||||
|
||||
You can also use the variable `.Page` to access all the normal [page variables][pagevariablespage].
|
||||
You can also use the variable `.Page` to access all the normal [page variables][pagevars].
|
||||
|
||||
A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvariablespage]. This can be very useful for inheritance of common shortcode parameters from the root.
|
||||
A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root.
|
||||
|
||||
## Custom Shortcode Examples
|
||||
|
||||
@@ -92,11 +92,11 @@ Let's assume you would like to keep mentions of your copyright year current in y
|
||||
{{</* year */>}}
|
||||
```
|
||||
|
||||
{{% input file="/layouts/shortcodes/year.html" %}}
|
||||
{{% code file="/layouts/shortcodes/year.html" %}}
|
||||
```golang
|
||||
{{ .Page.Now.Year }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### Single Positional Example: `youtube`
|
||||
|
||||
@@ -108,14 +108,14 @@ Embedded videos are a common addition to markdown content that can quickly becom
|
||||
|
||||
Would load the template at `/layouts/shortcodes/youtube.html`:
|
||||
|
||||
{{% input file="/layouts/shortcodes/youtube.html" %}}
|
||||
{{% code file="/layouts/shortcodes/youtube.html" %}}
|
||||
```html
|
||||
<div class="embed video-player">
|
||||
<iframe class="youtube-player" type="text/html" width="640" height="385" src="http://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0">
|
||||
</iframe>
|
||||
</div>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
|
||||
|
||||
@@ -133,17 +133,17 @@ Would load the template at `/layouts/shortcodes/youtube.html`:
|
||||
|
||||
### Single Named Example: `image`
|
||||
|
||||
Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][]. Your goal is to be able to call the shortcode as follows in your content files:
|
||||
Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files:
|
||||
|
||||
{{% input file="content-image.md" %}}
|
||||
{{% code file="content-image.md" %}}
|
||||
```golang
|
||||
{{</* img src="/media/spf13.jpg" title="Steve Francia" */>}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template:
|
||||
|
||||
{{% input file="/layouts/shortcodes/img.html" %}}
|
||||
{{% code file="/layouts/shortcodes/img.html" %}}
|
||||
```html
|
||||
<!-- image -->
|
||||
<figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
|
||||
@@ -164,7 +164,7 @@ You have created the shortcode at `/layouts/shortcodes/img.html`, which loads th
|
||||
</figure>
|
||||
<!-- image -->
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Would be rendered as:
|
||||
|
||||
@@ -188,7 +188,7 @@ Would be rendered as:
|
||||
|
||||
Would load the template found at `/layouts/shortcodes/vimeo.html`:
|
||||
|
||||
{{% input file="/layouts/shortcodes/vimeo.html" %}}
|
||||
{{% code file="/layouts/shortcodes/vimeo.html" %}}
|
||||
```html
|
||||
{{ if .IsNamedParams }}
|
||||
<div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}">
|
||||
@@ -200,7 +200,7 @@ Would load the template found at `/layouts/shortcodes/vimeo.html`:
|
||||
</div>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Would be rendered as:
|
||||
|
||||
@@ -219,7 +219,7 @@ Would be rendered as:
|
||||
|
||||
The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo.
|
||||
|
||||
{{% input file="highlight-example.md" %}}
|
||||
{{% code file="highlight-example.md" %}}
|
||||
```markdown
|
||||
{{</* highlight html */>}}
|
||||
<html>
|
||||
@@ -227,7 +227,7 @@ The following is taken from `highlight`, which is a [built-in shortcode][] that
|
||||
</html>
|
||||
{{</* /highlight */>}}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
The template for the `highlight` shortcode uses the following code, which is already included in Hugo:
|
||||
|
||||
@@ -252,15 +252,16 @@ The preceding shortcode makes use of a Hugo-specific template function called `h
|
||||
|
||||
## More Shortcode Examples
|
||||
|
||||
More shortcode examples can be found in the [shortcodes directory for spf13.com][spf13shortcodesdirectory] and the [shortcodes directory for the Hugo docs][docsshortcodesdirectory].
|
||||
More shortcode examples can be found in the [shortcodes directory for spf13.com][spf13shortcodes] and the [shortcodes directory for the Hugo docs][docsshortcodes].
|
||||
|
||||
[built-in shortcode]: /content-management/shortcodes/
|
||||
[directorystructurepage]: /getting-started/directory-structure/ "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories."
|
||||
[docsshortcodesdirectory]: https://github.com/spf13/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading."
|
||||
[basic content files]: /content-management/supported-content-formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website."
|
||||
[pagevariablespage]: /variables-and-params/page-variables/ "See which variables you can leverage in your templating for page vs list templates."
|
||||
[shortcodesvariablespage]: /variables-and-params/shortcode-variables/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template."
|
||||
[spf13shortcodesdirectory]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia."
|
||||
[templatessection]: /templates/ "The templates section of the Hugo docs."
|
||||
[built-in shortcode]: /content-management/shortcodes/
|
||||
[source organization]: /getting-started/directory-structure/ "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories."
|
||||
[docsshortcodes]: https://github.com/spf13/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading."
|
||||
[figure]: /content-management/shortcodes/#figure
|
||||
[pagevars]: /variables-and-params/page-variables/ "See which variables you can leverage in your templating for page vs list templates."
|
||||
[shortcodesvars]: /variables-and-params/shortcode-variables/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template."
|
||||
[spf13shortcodes]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia."
|
||||
[templates]: /templates/ "The templates section of the Hugo docs."
|
||||
[vimeoexample]: #single-flexible-example-vimeo
|
||||
[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode."
|
||||
@@ -79,7 +79,7 @@ Now we can look at the front matter for the three single-page content (i.e.`.md`
|
||||
|
||||
### `my-first-post.md`
|
||||
|
||||
{{% input file="content/posts/my-first-post.md" %}}
|
||||
{{% code file="content/posts/my-first-post.md" %}}
|
||||
```yaml
|
||||
---
|
||||
title: My First Post
|
||||
@@ -87,7 +87,7 @@ date: 2017-02-19
|
||||
description: This is my first post.
|
||||
---
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
When it comes time for Hugo to render the content to the page, it will go through the single page template lookup order until it finds what it needs for `my-first-post.md`:
|
||||
|
||||
@@ -109,7 +109,7 @@ Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo th
|
||||
|
||||
### `my-second-post.md`
|
||||
|
||||
{{% input file="content/posts/my-second-post.md" %}}
|
||||
{{% code file="content/posts/my-second-post.md" %}}
|
||||
```yaml
|
||||
---
|
||||
title: My Second Post
|
||||
@@ -119,7 +119,7 @@ type: review
|
||||
layout: reviewarticle
|
||||
---
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Here is the way Hugo's traverses the single-page lookup order for `my-second-post.md`:
|
||||
|
||||
@@ -143,7 +143,7 @@ Notice that the directory for the template for `my-second-post.md` is `review` a
|
||||
|
||||
### `my-first-event.md`
|
||||
|
||||
{{% input file="content/events/my-first-event.md" %}}
|
||||
{{% code file="content/events/my-first-event.md" %}}
|
||||
```yaml
|
||||
---
|
||||
title: My First
|
||||
@@ -151,7 +151,7 @@ date: 2017-02-21
|
||||
description: This is an upcoming event..
|
||||
---
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Here is the way Hugo's traverses the single-page lookup order for `my-first-event.md`:
|
||||
|
||||
@@ -179,7 +179,7 @@ Content pages are of the type `page` and will therefore have all the [page varia
|
||||
|
||||
This content template is used for [spf13.com][spf13]. It makes use of [partial templates][partials]:
|
||||
|
||||
{{% input file="layouts/post/single.html" %}}
|
||||
{{% code file="layouts/post/single.html" %}}
|
||||
```html
|
||||
{{ partial "header.html" . }}
|
||||
{{ partial "subheader.html" . }}
|
||||
@@ -222,13 +222,13 @@ This content template is used for [spf13.com][spf13]. It makes use of [partial t
|
||||
{{ partial "disqus.html" . }}
|
||||
{{ partial "footer.html" . }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
### `project/single.html`
|
||||
|
||||
This content template is also used for [spf13.com][spf13] and makes use of [partial templates][partials]:
|
||||
|
||||
{{% input file="project/single.html" %}}
|
||||
{{% code file="project/single.html" %}}
|
||||
```html
|
||||
{{ partial "header.html" . }}
|
||||
{{ partial "subheader.html" . }}
|
||||
@@ -270,7 +270,7 @@ This content template is also used for [spf13.com][spf13] and makes use of [part
|
||||
|
||||
{{ partial "footer.html" . }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Notice how `project/single.html` uses an additional parameter unique to this template. This doesn't need to be defined ahead of time. The key can wait to be used in the template if present in the content file's front matter.
|
||||
|
||||
|
||||
@@ -23,28 +23,28 @@ These snippets use the `printf` function available in all Go templates. This fu
|
||||
|
||||
You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`.
|
||||
|
||||
{{% input file="get-top-level-syntax.sh" %}}
|
||||
{{% code file="get-top-level-syntax.sh" %}}
|
||||
```golang
|
||||
{{ printf "%#v" $.Site }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
This will print out the value of `.Permalink`:
|
||||
|
||||
{{% input file="get-permalink.sh" %}}
|
||||
{{% code file="get-permalink.sh" %}}
|
||||
```golang
|
||||
{{ printf "%#v" .Permalink }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
This will print out a list of all the variables scoped to the current context
|
||||
(aka [The dot, "`.`"][thedot]).
|
||||
|
||||
{{% input file="get-all-vars-current-context.sh" %}}
|
||||
{{% code file="get-all-vars-current-context.sh" %}}
|
||||
```golang
|
||||
{{ printf "%#v" . }}
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
When writing a [Homepage][hometemplate], what does one of the pages you're looping through look like?
|
||||
|
||||
|
||||
@@ -47,12 +47,12 @@ git clone URL_TO_THEME
|
||||
|
||||
The following example shows how to use the "Hyde" theme, which has its source hosted at <https://github.com/spf13/hyde>:
|
||||
|
||||
{{% input file="clone-theme.sh" %}}
|
||||
{{% code file="clone-theme.sh" %}}
|
||||
```bash
|
||||
cd themes
|
||||
git clone https://github.com/spf13/hyde
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
Alternatively, you can download the theme as a `.zip` file, unzip the theme contents, and then move the unzipped source into your `themes` directory.
|
||||
|
||||
|
||||
@@ -80,7 +80,7 @@ The `.Hugo` variable provides easy access to Hugo-related data and contains the
|
||||
: The compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`<br>
|
||||
|
||||
{{% note "Use the Hugo Generator Tag" %}}
|
||||
We highly recommend using `.Hugo.Generator` in your website. It is already included in all theme headers. The generator tag is significant in that it allows the Hugo team to track the usage and popularity of Hugo.
|
||||
We highly recommend using `.Hugo.Generator` in your website's `<head>`. `.Hugo.Generator` is included by default in all themes hosted on [themes.gohugo.io](http://themes.gohugo.io). The generator tag allows the Hugo team to track the usage and popularity of Hugo.
|
||||
{{% /note %}}
|
||||
|
||||
## Menu Variables
|
||||
|
||||
@@ -190,12 +190,12 @@ These fields would then be accessible to the `/themes/yourtheme/layouts/review/s
|
||||
|
||||
Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors.
|
||||
|
||||
{{% input file="/themes/yourtheme/layouts/review/single.html" %}}
|
||||
{{% code file="/themes/yourtheme/layouts/review/single.html" %}}
|
||||
```html
|
||||
<h3><a href={{ printf "%s" $.Params.affiliatelink }}>Buy this book</a></h3>
|
||||
<p>It was recommended by {{ .Params.recommendedby }}.</p>
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
|
||||
This template would render as follows, assuming you've set [`uglyURLs`](/content-management/url-management/) to `false` in your [site `config`](/getting-started/configuration/):
|
||||
|
||||
|
||||
@@ -114,8 +114,8 @@ baseURL = "http://yoursite.example.com/"
|
||||
|
||||
You can use `.Site.Params` in a [partial template](/templates/partial-templates/) to call the default site description:
|
||||
|
||||
{{% input file="layouts/partials/head.html" %}}
|
||||
{{% code file="layouts/partials/head.html" %}}
|
||||
```html
|
||||
<meta name="description" content="{{if .IsHome}}{{ $.Site.Params.description }}{{else}}{{.Description}}{{end}}" />
|
||||
```
|
||||
{{% /input %}}
|
||||
{{% /code %}}
|
||||
@@ -0,0 +1,20 @@
|
||||
{{$icon := index (split (.Get "file") ".") 1 }}
|
||||
<div class="code-copy input" id="{{.Get "file" | urlize}}">
|
||||
{{- with .Get "file" -}}<div class="code-copy-header"><div class="action-buttons"></div><span title="{{.}}" class="filename">{{- . -}}</span><i class="icon-{{$icon}} input"></i></div>{{- end -}}
|
||||
{{with .Get "source"}}
|
||||
<a href="{{.}}" class="see-code-source" role="button" target="_blank" title="See source for this snippet">See Source</a>
|
||||
{{end}}
|
||||
{{with .Get "download"}}
|
||||
<button class="download-button" title="Download a copy of {{.}}">
|
||||
<i class="icon-download"></i>
|
||||
</button>
|
||||
{{end}}
|
||||
{{ if ne (.Get "copy") "false" }}
|
||||
<button class="copy-button" title="Copy to clipboard" data-clipboard-snippet>
|
||||
<i class="icon-clipboard"></i><!-- <div class="copy-text"> COPY</div> -->
|
||||
</button>
|
||||
{{end}}
|
||||
<div class="code-copy-content" {{with .Get "download"}}id="{{.}}"{{end}}>
|
||||
{{- .Inner -}}
|
||||
</div>
|
||||
</div>
|
||||
@@ -1,20 +0,0 @@
|
||||
{{- if .IsNamedParams -}}
|
||||
{{$filenameclass := index (split (.Get "filename") ".") 1 }}
|
||||
<div class="code-copy input" id="{{.Get "filename" | urlize}}">
|
||||
{{- with .Get "filename" -}}<div class="code-copy-header"><div class="action-buttons"></div><span title="{{.}}" class="filename">{{- . -}}</span><i class="icon-{{$filenameclass}} input"></i></div>{{- end -}}
|
||||
<button class="copy-button" title="Copy to clipboard" data-clipboard-snippet>
|
||||
<div class="copy-text"><i class="icon-clipboard"></i> COPY</div>
|
||||
</button>
|
||||
{{- .Inner -}}
|
||||
</div>
|
||||
{{- else -}}
|
||||
{{$filenameclass := index (split (.Get 0) ".") 1 }}
|
||||
<div class="code-copy input" id="{{.Get 0|urlize}}">
|
||||
<div class="code-copy-header"><div class="action-buttons"></div>{{if ne $filenameclass "sh"}}<span class="filename" title="{{.Get 0}}">{{.Get 0}}</span>{{end}}<i class="icon-{{$filenameclass}} input"></i></div>{{- if ne (index .Params 1) "nocopy" -}}
|
||||
<button class="copy-button" title="Copy to clipboard" data-clipboard-snippet>
|
||||
<div class="copy-text"><i class="icon-clipboard"></i> COPY</div>
|
||||
</button>
|
||||
{{- end -}}
|
||||
{{- .Inner -}}
|
||||
</div>
|
||||
{{end}}
|
||||
Vendored
+1
-1
File diff suppressed because one or more lines are too long
Executable → Regular
BIN
Binary file not shown.
Executable → Regular
BIN
Binary file not shown.
Executable → Regular
+2668
-652
File diff suppressed because it is too large
Load Diff
|
Before Width: | Height: | Size: 357 KiB After Width: | Height: | Size: 434 KiB |
Executable → Regular
BIN
Binary file not shown.
Executable → Regular
BIN
Binary file not shown.
Executable → Regular
BIN
Binary file not shown.
Vendored
+4
-4
File diff suppressed because one or more lines are too long
@@ -16,7 +16,7 @@
|
||||
<i class="fa fa-chevron-left"></i>
|
||||
<div class="page-info">
|
||||
<span>Previous</span>
|
||||
<h5 class="{{$section}}">{{.Title}}{{if ne .Section "functions"}} of {{.Section | humanize | title}}{{end}}</h5>
|
||||
<h5 class="{{$section}}">{{.Title}}{{if and (ne .Section "functions") (ne .Section "hosting-and-deployment")}} of {{.Section | humanize | title}}{{end}}</h5>
|
||||
</div>
|
||||
</a>
|
||||
{{ end }}
|
||||
|
||||
@@ -11,5 +11,13 @@
|
||||
<li><a href="{{.Site.Params.gitter}}" target="_blank"><i class="icon-gitter"></i> Gitter (Dev Chat Only)</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div>
|
||||
<ul class="footer-list">
|
||||
<li><a href="https://twitter.com/spf13" target="_blank"><i class="icon-twitter"></i> @spf13</a></li>
|
||||
<li><a href="https://twitter.com/gohugoio" target="_blank"><i class="icon-twitter"></i> @GoHugoIO</a></li>
|
||||
<li><a href="https://twitter.com/bepsays" target="_blank"><i class="icon-twitter"></i> @bepsays</a></li>
|
||||
<li><a href="https://"></a></li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
@@ -62,7 +62,7 @@ gulp.task("image-resize", () => {
|
||||
|
||||
gulp.task('scripts', function(cb) {
|
||||
pump([
|
||||
gulp.src(['js/_clipboard.js', 'js/_velocity.min.js', 'js/_velocity.ui.min.js', 'js/scripts/*.js']),
|
||||
gulp.src(['js/_clipboard.js','js/_filesaver.js', 'js/_velocity.min.js', 'js/_velocity.ui.min.js', 'js/scripts/*.js']),
|
||||
// sourcemaps.init(),
|
||||
babel({
|
||||
presets: ['es2015']
|
||||
|
||||
@@ -0,0 +1,188 @@
|
||||
/* FileSaver.js
|
||||
* A saveAs() FileSaver implementation.
|
||||
* 1.3.2
|
||||
* 2016-06-16 18:25:19
|
||||
*
|
||||
* By Eli Grey, http://eligrey.com
|
||||
* License: MIT
|
||||
* See https://github.com/eligrey/FileSaver.js/blob/master/LICENSE.md
|
||||
*/
|
||||
|
||||
/*global self */
|
||||
/*jslint bitwise: true, indent: 4, laxbreak: true, laxcomma: true, smarttabs: true, plusplus: true */
|
||||
|
||||
/*! @source http://purl.eligrey.com/github/FileSaver.js/blob/master/FileSaver.js */
|
||||
|
||||
var saveAs = saveAs || (function(view) {
|
||||
"use strict";
|
||||
// IE <10 is explicitly unsupported
|
||||
if (typeof view === "undefined" || typeof navigator !== "undefined" && /MSIE [1-9]\./.test(navigator.userAgent)) {
|
||||
return;
|
||||
}
|
||||
var
|
||||
doc = view.document
|
||||
// only get URL when necessary in case Blob.js hasn't overridden it yet
|
||||
, get_URL = function() {
|
||||
return view.URL || view.webkitURL || view;
|
||||
}
|
||||
, save_link = doc.createElementNS("http://www.w3.org/1999/xhtml", "a")
|
||||
, can_use_save_link = "download" in save_link
|
||||
, click = function(node) {
|
||||
var event = new MouseEvent("click");
|
||||
node.dispatchEvent(event);
|
||||
}
|
||||
, is_safari = /constructor/i.test(view.HTMLElement)
|
||||
, is_chrome_ios =/CriOS\/[\d]+/.test(navigator.userAgent)
|
||||
, throw_outside = function(ex) {
|
||||
(view.setImmediate || view.setTimeout)(function() {
|
||||
throw ex;
|
||||
}, 0);
|
||||
}
|
||||
, force_saveable_type = "application/octet-stream"
|
||||
// the Blob API is fundamentally broken as there is no "downloadfinished" event to subscribe to
|
||||
, arbitrary_revoke_timeout = 1000 * 40 // in ms
|
||||
, revoke = function(file) {
|
||||
var revoker = function() {
|
||||
if (typeof file === "string") { // file is an object URL
|
||||
get_URL().revokeObjectURL(file);
|
||||
} else { // file is a File
|
||||
file.remove();
|
||||
}
|
||||
};
|
||||
setTimeout(revoker, arbitrary_revoke_timeout);
|
||||
}
|
||||
, dispatch = function(filesaver, event_types, event) {
|
||||
event_types = [].concat(event_types);
|
||||
var i = event_types.length;
|
||||
while (i--) {
|
||||
var listener = filesaver["on" + event_types[i]];
|
||||
if (typeof listener === "function") {
|
||||
try {
|
||||
listener.call(filesaver, event || filesaver);
|
||||
} catch (ex) {
|
||||
throw_outside(ex);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
, auto_bom = function(blob) {
|
||||
// prepend BOM for UTF-8 XML and text/* types (including HTML)
|
||||
// note: your browser will automatically convert UTF-16 U+FEFF to EF BB BF
|
||||
if (/^\s*(?:text\/\S*|application\/xml|\S*\/\S*\+xml)\s*;.*charset\s*=\s*utf-8/i.test(blob.type)) {
|
||||
return new Blob([String.fromCharCode(0xFEFF), blob], {type: blob.type});
|
||||
}
|
||||
return blob;
|
||||
}
|
||||
, FileSaver = function(blob, name, no_auto_bom) {
|
||||
if (!no_auto_bom) {
|
||||
blob = auto_bom(blob);
|
||||
}
|
||||
// First try a.download, then web filesystem, then object URLs
|
||||
var
|
||||
filesaver = this
|
||||
, type = blob.type
|
||||
, force = type === force_saveable_type
|
||||
, object_url
|
||||
, dispatch_all = function() {
|
||||
dispatch(filesaver, "writestart progress write writeend".split(" "));
|
||||
}
|
||||
// on any filesys errors revert to saving with object URLs
|
||||
, fs_error = function() {
|
||||
if ((is_chrome_ios || (force && is_safari)) && view.FileReader) {
|
||||
// Safari doesn't allow downloading of blob urls
|
||||
var reader = new FileReader();
|
||||
reader.onloadend = function() {
|
||||
var url = is_chrome_ios ? reader.result : reader.result.replace(/^data:[^;]*;/, 'data:attachment/file;');
|
||||
var popup = view.open(url, '_blank');
|
||||
if(!popup) view.location.href = url;
|
||||
url=undefined; // release reference before dispatching
|
||||
filesaver.readyState = filesaver.DONE;
|
||||
dispatch_all();
|
||||
};
|
||||
reader.readAsDataURL(blob);
|
||||
filesaver.readyState = filesaver.INIT;
|
||||
return;
|
||||
}
|
||||
// don't create more object URLs than needed
|
||||
if (!object_url) {
|
||||
object_url = get_URL().createObjectURL(blob);
|
||||
}
|
||||
if (force) {
|
||||
view.location.href = object_url;
|
||||
} else {
|
||||
var opened = view.open(object_url, "_blank");
|
||||
if (!opened) {
|
||||
// Apple does not allow window.open, see https://developer.apple.com/library/safari/documentation/Tools/Conceptual/SafariExtensionGuide/WorkingwithWindowsandTabs/WorkingwithWindowsandTabs.html
|
||||
view.location.href = object_url;
|
||||
}
|
||||
}
|
||||
filesaver.readyState = filesaver.DONE;
|
||||
dispatch_all();
|
||||
revoke(object_url);
|
||||
}
|
||||
;
|
||||
filesaver.readyState = filesaver.INIT;
|
||||
|
||||
if (can_use_save_link) {
|
||||
object_url = get_URL().createObjectURL(blob);
|
||||
setTimeout(function() {
|
||||
save_link.href = object_url;
|
||||
save_link.download = name;
|
||||
click(save_link);
|
||||
dispatch_all();
|
||||
revoke(object_url);
|
||||
filesaver.readyState = filesaver.DONE;
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
fs_error();
|
||||
}
|
||||
, FS_proto = FileSaver.prototype
|
||||
, saveAs = function(blob, name, no_auto_bom) {
|
||||
return new FileSaver(blob, name || blob.name || "download", no_auto_bom);
|
||||
}
|
||||
;
|
||||
// IE 10+ (native saveAs)
|
||||
if (typeof navigator !== "undefined" && navigator.msSaveOrOpenBlob) {
|
||||
return function(blob, name, no_auto_bom) {
|
||||
name = name || blob.name || "download";
|
||||
|
||||
if (!no_auto_bom) {
|
||||
blob = auto_bom(blob);
|
||||
}
|
||||
return navigator.msSaveOrOpenBlob(blob, name);
|
||||
};
|
||||
}
|
||||
|
||||
FS_proto.abort = function(){};
|
||||
FS_proto.readyState = FS_proto.INIT = 0;
|
||||
FS_proto.WRITING = 1;
|
||||
FS_proto.DONE = 2;
|
||||
|
||||
FS_proto.error =
|
||||
FS_proto.onwritestart =
|
||||
FS_proto.onprogress =
|
||||
FS_proto.onwrite =
|
||||
FS_proto.onabort =
|
||||
FS_proto.onerror =
|
||||
FS_proto.onwriteend =
|
||||
null;
|
||||
|
||||
return saveAs;
|
||||
}(
|
||||
typeof self !== "undefined" && self
|
||||
|| typeof window !== "undefined" && window
|
||||
|| this.content
|
||||
));
|
||||
// `self` is undefined in Firefox for Android content script context
|
||||
// while `this` is nsIContentFrameMessageManager
|
||||
// with an attribute `content` that corresponds to the window
|
||||
|
||||
if (typeof module !== "undefined" && module.exports) {
|
||||
module.exports.saveAs = saveAs;
|
||||
} else if ((typeof define !== "undefined" && define !== null) && (define.amd !== null)) {
|
||||
define("FileSaver.js", function() {
|
||||
return saveAs;
|
||||
});
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
$('.download-button').on('click', function() {
|
||||
var codeblock = $(this).siblings('.code-copy-content'),
|
||||
codeText = codeblock.text(),
|
||||
fileName = codeblock.attr('id');
|
||||
var downloadFile = new Blob([codeText], { type: 'text/plain;charset=utf-8' });
|
||||
saveAs(downloadFile, fileName);
|
||||
});
|
||||
|
||||
@@ -98,7 +98,7 @@ p + .code-copy {
|
||||
}
|
||||
|
||||
button.copy-button,
|
||||
a[role="button"].see-on-github {
|
||||
button.download-button {
|
||||
display: block;
|
||||
box-shadow: none;
|
||||
padding: 0px;
|
||||
@@ -139,10 +139,43 @@ a[role="button"].see-on-github {
|
||||
}
|
||||
}
|
||||
|
||||
a[role="button"].see-on-github {
|
||||
left: 0px;
|
||||
a[role="button"].see-code-source {
|
||||
position: absolute;
|
||||
top: 1.75em;
|
||||
right: 0px;
|
||||
border-radius: 0px;
|
||||
background: transparent;
|
||||
text-transform: uppercase;
|
||||
color: darken($hugo-white, 5%);
|
||||
font-size: 14px;
|
||||
}
|
||||
|
||||
a[href*="bitbucket"].see-code-source:after {
|
||||
content: '\f171';
|
||||
font-family: 'FontAwesome';
|
||||
display: inline-block;
|
||||
font-size: 1.3em;
|
||||
color: inherit;
|
||||
margin-left:.2em;
|
||||
}
|
||||
a[href*="github"].see-code-source:after {
|
||||
content: '\f09b';
|
||||
font-family: 'FontAwesome';
|
||||
display: inline-block;
|
||||
font-size: 1.3em;
|
||||
color: inherit;
|
||||
margin-left:.2em;
|
||||
}
|
||||
a[href*="gitlab"].see-code-source:after {
|
||||
content: '\f296';
|
||||
font-family: 'FontAwesome';
|
||||
display: inline-block;
|
||||
font-size: 1.3em;
|
||||
color: inherit;
|
||||
margin-left:.2em;
|
||||
}
|
||||
|
||||
|
||||
button.copy-button {
|
||||
display: none;
|
||||
@include MQ(M) {
|
||||
|
||||
@@ -54,6 +54,7 @@ ul.footer-list {
|
||||
margin-left: 0px;
|
||||
padding-left: 0px;
|
||||
margin: 0px;
|
||||
flex-wrap: wrap;
|
||||
li a {
|
||||
color: $hugo-white;
|
||||
display: flex;
|
||||
|
||||
Reference in New Issue
Block a user