mirror of
https://github.com/gohugoio/hugo.git
synced 2026-08-26 16:28:52 +00:00
Update rss vars page
This commit is contained in:
Ryan Watters
+8
-10
@@ -1,18 +1,16 @@
|
||||
---
|
||||
title: Create a Multilingual Site
|
||||
linktitle: Create a Multilingual Site
|
||||
description:
|
||||
godocref:
|
||||
author: ""
|
||||
authorurl: ""
|
||||
originalurl: ""
|
||||
linktitle: ""
|
||||
description: ""
|
||||
godocref: ""
|
||||
publishdate: ""
|
||||
lastmod: ""
|
||||
categories: [tutorials]
|
||||
tags: [tutorials]
|
||||
weight:
|
||||
tags: []
|
||||
author: ""
|
||||
authorurl: ""
|
||||
originalurl: ""
|
||||
draft: false
|
||||
aliases: []
|
||||
z_notesforauthors: "Go to gohugo.io/docscontrib for info on req fields"
|
||||
z_notesforauthors: "Go to gohugo.io/docscontrib for info on required fields"
|
||||
---
|
||||
|
||||
|
||||
+29
-11
@@ -133,11 +133,15 @@ The following are high-level requirements for the documentation site.
|
||||
- [X] New site architecture and content groupings
|
||||
- [ ] Single sample website (include in docs source, [`/static/example`](https://github.com/rdwatters/hugo-docs-concept/tree/master/static/example)) for consistent code samples or in-page tutorials
|
||||
|
||||
#### [Content Strategy Statement](http://contentmarketinginstitute.com/2016/01/content-on-strategy-templates/)
|
||||
#### Content Strategy Statement
|
||||
|
||||
[What is this?](http://contentmarketinginstitute.com/2016/01/content-on-strategy-templates/)
|
||||
|
||||
> The Hugo documentation increases the Hugo user base and strengthens the Hugo community by providing intuitive, beginner-friendly, regularly updated usage guides. Hugo documentation makes visitors feel excited and confident that Hugo is the ideal choice for static website development.
|
||||
|
||||
#### [Editorial Mission](http://contentmarketinginstitute.com/2015/10/statement-content-marketing/)
|
||||
#### Editorial Mission
|
||||
|
||||
[What is this?](http://contentmarketinginstitute.com/2015/10/statement-content-marketing/)
|
||||
|
||||
> The Hugo documentation is a joint effort between the Hugo maintainers and the open-source community. Hugo documentation is designed to promote Hugo, the world's fastest, friendliest, and most extensible static site generator. Hugo documentation is the primary vehicle by which the Hugo team reaches its target audiences. When visitors comes to the Hugo documentation, we want them to install Hugo, develop a new static website with our tool, and share their progress and insights with the Hugo community at large.
|
||||
|
||||
@@ -160,7 +164,9 @@ The following are high-level requirements for the documentation site.
|
||||
- [ ] Content groupings (GA) to measure usage, behavior flow, and define content gaps
|
||||
- [ ] Automated reports (GA)
|
||||
|
||||
> **Note:** These are separate from usage statics re: Hugo downloads, `.Hugo.Generator`, etc.
|
||||
{{% note %}}
|
||||
These are separate from usage statics re: Hugo downloads, `.Hugo.Generator`, etc.
|
||||
{{% /note %}}
|
||||
|
||||
## Visual Design
|
||||
|
||||
@@ -181,23 +187,28 @@ The following are high-level requirements for the documentation site.
|
||||
|
||||
## Content Changes
|
||||
|
||||
The following is an *abbreviated* listing of *substantive* changes to content organization. Everything is ordered according to [existing site structure and site navigation](http://gohugo.io/overview/introduction/). These changes do not include copy edits for consistent or preferred usage, improvements in semantics, etc, all of which easily numbers in the thousands, if not more.
|
||||
The following is an *abbreviated* listing of *substantive* changes to content organization. Everything is ordered according to the current docs site navigation. The changes I delimit here do not include copy edits for consistent or preferred usage, improvements in semantics, etc, all of which easily numbers in the thousands, likely more.
|
||||
|
||||
### Download Hugo
|
||||
|
||||
This is no longer a site navigation link and is instead a button along with "File and Issue" and "Discuss Hugo".
|
||||
This is no longer a site navigation link and is instead a button along with "File an Issue" and "Discuss Hugo" at the bottom of the sidebar.
|
||||
|
||||
### Site Showcase
|
||||
|
||||
* Site showcase has stayed more or less as is, including styling, etc. However, I did clean up the templating and all currently submitted showcase files. (E.g., changing "thumbnail" to "image" and not requiring a full path.) This will also be updated in the ["docs" page of the contribute section](/contribute/contribute-to-the-hugo-docs/)
|
||||
|
||||
### Press & Articles
|
||||
|
||||
* The press and article pages has been moved under "News" along with "Release Notes". Also, this whole section is lower on the navigation because it's less frequently visited---I'm assuming---than just about everything on the site.
|
||||
* Like everything else, I've kept up with changes to the docs upstream on GitHub, but in this case, I also includes a [half dozen *new* articles as well](/news/press-and-articles/).
|
||||
|
||||
### About Hugo
|
||||
|
||||
### Getting Started
|
||||
|
||||
* The [Quick Start][] has been completely updated for more consistent heading structure, etc. Also, **I may delete the "deployment" section of the Quick Start** since this a) adds unnecessary length, making the guide less "quick" and b) detracts from the new "hosting and deployment" section, which offers better advice, and c) is redundant with [Hosting on Github](https://hugodocsconcept.netlify.com/hosting-and-deployment/hosting-on-github/). For example, the Quick Start didn't mention that files already written to public are not necessarily erased at build time. This can cause problems with drafts. I think the other options—e.g. Arjen's Wercker tutorial—are more viable and represent better practices for newcomers to Hugo. If future versions of Hugo include baked-in deployment features, I think it's worth reconsidering adding the deployment step back to the Quick Start.
|
||||
|
||||
### [Content](http://gohugo.io/content)
|
||||
### Content
|
||||
|
||||
* This section has been renamed "Content Management" to facilitate elimination of the ["extras"](http://gohugo.io) section. **Note**: this section does *not* include any templating. The convention is `content-management/shortcodes.md` (for explanation and usage) and then `content-management/shortcode-templates.md`
|
||||
|
||||
@@ -205,22 +216,29 @@ This is no longer a site navigation link and is instead a button along with "Fil
|
||||
|
||||
### Templates
|
||||
|
||||
* Reworked considerably. Page titles have all been changed to reflect their obvious connection to *templating*.
|
||||
* "Lookup order" page added. The order of the template pages in the main navigation is now such that it could be seen as a sequence of pages showing how to learn templating. Hence the primer, lookup order, and base templates as the first three pages in this section.
|
||||
|
||||
### Taxonomies
|
||||
|
||||
|
||||
### [Extras](http://gohugo.io/extras)
|
||||
### Extras
|
||||
|
||||
* This section no longer exists in the new documentation site
|
||||
* *Extras*, in the content world, is the equivalent of *miscellaneous* or *additional resources*. It's an area that's been tacked onto site navigation to accommodate a *seemingly* disparate set of new features. In other words, READ: "We don't have any idea of where to put this"
|
||||
* *Extras* pages:
|
||||
* **Aliases** Incorporated into [`/content-management/url-management/`]
|
||||
* **Analytics** Incorporated into [/templates/partial-templates/#built-in]
|
||||
* **Aliases** Incorporated into [URL Management](/content-management/url-management/)
|
||||
* **Analytics** Incorporated into [built-in partials](/templates/partials/#using-hugos-built-in-partials)
|
||||
* **Builders** This has been removed completely since it has no real added value. The three "builders" mentioned (`new site`, `new theme`, and `new <content>`) are all well-delimited in their respective pages, which is where end users expect to find this type of information in the first place.
|
||||
* **Comments** Incorporated into [content management](/content-management/comments/) for content-related pieces and mentioned in [partials](/templates/partials/) for implementation.
|
||||
* **Cross-References** Added as its own page under Content Management (`/content-management/cross-references/`)
|
||||
|
||||
### Community
|
||||
|
||||
### [Tutorials](http://gohugo.io/tutorials)
|
||||
### Tutorials
|
||||
|
||||
* All installation guides have been consilidated under [/getting-started/install-hugo/]
|
||||
* Original page: <http://gohugo.io/tutorials>
|
||||
* All installation guides have been consolidated under [/getting-started/installing/]
|
||||
* Installing Hugo shouldn't be considered a separate tutorial
|
||||
* "Tutorials" is not an intuitive place for end-users to look for this kind of documentation
|
||||
* All content moved from `/tutorials` edited to reflect a less tutorial-ish style of language (e.g., remove of lines starting with "In this tutorial...")
|
||||
|
||||
@@ -14,81 +14,39 @@ toc: true
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
<!-- pulled from extras/comments -->
|
||||
As Hugo is a static site generator, the content produced is static and doesn't allow for a high degree of interaction with the website's end users. The most common interaction people ask for in static websites is the ability to add comments.
|
||||
|
||||
As Hugo is a static site generator, the content produced is static and doesn’t interact with the users. The most common interaction people ask for is comment capability.
|
||||
|
||||
Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to website via JavaScript.
|
||||
Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript.
|
||||
|
||||
Your theme may already support Disqus, but even it if doesn’t, it is easy to add.
|
||||
|
||||
## Disqus
|
||||
|
||||
### Adding Disqus to a Template
|
||||
|
||||
Hugo comes with all the code you would need to include load Disqus. Simply include the following line where you want your comments to appear:
|
||||
|
||||
```golang
|
||||
{{ template "_internal/disqus.html" . }}
|
||||
```
|
||||
Hugo comes with all the code you need to include load [Disqus][], a popular commenting service for both static and dynamic websites.
|
||||
|
||||
### Configuring Disqus
|
||||
|
||||
That template requires you to set a single value in your site `config`:
|
||||
Disqus comments require you set a single value in your [site's configuration file][configuration]. The following show the configuration variable in TOML and YAML, respectively:
|
||||
|
||||
```toml
|
||||
disqusShortname = "yourdiscussshortname"
|
||||
```
|
||||
|
||||
Or with a `config.yml`:
|
||||
|
||||
```yaml
|
||||
disqusShortname: "yourdiscussshortname"
|
||||
```
|
||||
|
||||
You also have the option to set the following in the front matter for a given piece of content:
|
||||
For many website, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file:
|
||||
|
||||
* `disqus_identifier`
|
||||
* `disqus_title`
|
||||
* `disqus_url`
|
||||
|
||||
### Conditional Loading of Disqus Comments
|
||||
### Rendering Hugo's Built-in Disqus Partial Template
|
||||
|
||||
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:
|
||||
See [Partial Templates][partials] to learn how to add the Disqus partial to your Hugo website's templates.
|
||||
|
||||
{{% code file="layouts/partials/disqus.html" %}}
|
||||
```html
|
||||
<div id="disqus_thread"></div>
|
||||
<script type="text/javascript">
|
||||
|
||||
(function() {
|
||||
// Don't ever inject Disqus on localhost--it creates unwanted
|
||||
// discussions from 'localhost:1313' on your Disqus account...
|
||||
if (window.location.hostname == "localhost")
|
||||
return;
|
||||
|
||||
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
|
||||
var disqus_shortname = '{{ .Site.DisqusShortname }}';
|
||||
dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
|
||||
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
|
||||
})();
|
||||
</script>
|
||||
<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>
|
||||
```
|
||||
{{% /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:
|
||||
|
||||
{{% code file="disqus-reference.html" %}}
|
||||
```golang
|
||||
{{ partial "disqus.html" . }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
## Alternatives
|
||||
## Commenting Alternatives
|
||||
|
||||
There are a few alternatives to commenting on static sites for those who do not want to use Hugo's built-in Disqus support:
|
||||
|
||||
@@ -98,16 +56,22 @@ There are a few alternatives to commenting on static sites for those who do not
|
||||
* [Muut](http://muut.com/)
|
||||
* [多说](http://duoshuo.com/) ([Duoshuo](http://duoshuo.com/), popular in China)
|
||||
* [isso](http://posativ.org/isso/) (Self-hosted, Python)
|
||||
* [Tutorial on Implementing Isso with Hugo][issotutorial]
|
||||
* [Kaiju](https://github.com/spf13/kaiju)
|
||||
|
||||
## Kaiju
|
||||
|
||||
[Kaiju](https://github.com/spf13/kaiju) is an open-source project started by [spf13](http://spf13.com/) (Hugo’s author) to bring easy and fast real time discussions to the web.
|
||||
|
||||
Written using Go, Socket.io and MongoDB, it is very fast and easy to deploy.
|
||||
Written using Go, Socket.io, and [MongoDB][], Kaiju is very fast and easy to deploy.
|
||||
|
||||
It is in early development but shows promise. If you have interest, please help by contributing whether via a pull request, an issue or even just a tweet. Everything helps.
|
||||
It is in early development but shows promise. If you have interest, please help by contributing via pull request, [opening an issue in the Kaiju GitHub repository][kaijuissue], or [Tweeting about it][tweet]. Every bit helps.
|
||||
|
||||
## Discourse
|
||||
|
||||
Additionally, you may recognize [Discourse](http://www.discourse.org) as the system that powers the [Hugo Discussion Forum](http://discuss.gohugo.io).
|
||||
[configuration]: /getting-started/configuration/
|
||||
[forum]: https://discuss.gohugo.io
|
||||
[front matter]: /content-management/front-matter/
|
||||
[kaijuissue]: https://github.com/spf13/kaiju/issues/new
|
||||
[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/
|
||||
[partials]: /templates/partials/
|
||||
[MongoDB]: https://www.mongodb.com/
|
||||
[tweet]: https://twitter.com/spf13
|
||||
@@ -177,7 +177,7 @@ This shortcode will convert the source code provided into syntax-highlighted HTM
|
||||
{{% /output %}}
|
||||
|
||||
{{% note "Syntax Highlighting" %}}
|
||||
For more information on your options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting](/developer-tools/syntax-highlighting/.
|
||||
For more information on your options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting](/developer-tools/syntax-highlighting/).
|
||||
{{% /note %}}
|
||||
|
||||
### `instagram`
|
||||
|
||||
@@ -8,7 +8,7 @@ lastmod: 2017-02-01
|
||||
categories: [contribute to hugo]
|
||||
tags: [dev,showcase]
|
||||
weight: 30
|
||||
draft: false
|
||||
draft: true
|
||||
aliases: []
|
||||
toc: true
|
||||
notesforauthors:
|
||||
@@ -17,13 +17,7 @@ notesforauthors:
|
||||
|
||||
If you've built a site with Hugo and would like to have it featured on the official Hugo site, you can add your website with a few steps to the [Site Showcase][].
|
||||
|
||||
## 1. Create Your Fork
|
||||
|
||||
First, make sure that you created a [fork](https://help.github.com/articles/fork-a-repo/) of Hugo on Github and cloned your fork on your local computer. Next, create a separate branch for your additions. Note that you can choose a different descriptive branch name if you like:
|
||||
|
||||
```git
|
||||
git checkout -b showcase-addition
|
||||
```
|
||||
|
||||
## 2. Add Your Showcase File via the `showcase` Archetype
|
||||
|
||||
@@ -53,43 +47,4 @@ notesforauthors: "For the image, only include the file name *without* a director
|
||||
---
|
||||
```
|
||||
|
||||
Add at least values for `sitelink`, `title`, `description`, and a path for `thumbnail`.
|
||||
|
||||
{{% note "Notes for Authors" %}}
|
||||
You may notice a `notesforauthors` key-value in your new content file for the showcase. These notes are not required, but rather have been added to make it easier to fill out the required metadata without needing to refer to the Hugo docs website. You can delete this metadata before submitting a pull request.
|
||||
{{% /note %}}
|
||||
|
||||
## 3. Add an Image
|
||||
|
||||
We need to create the thumbnail of your website. Give your thumbnail a name like `my-hugo-site-name.png`. Save it under [`docs/static/images/showcase/`][].
|
||||
|
||||
{{% warning "Thumbnail Size" %}}
|
||||
It's important that the thumbnail has the required dimensions of 600px by 400px or the site will not render appropriately. Be sure to optimize your image as a matter of best practice.
|
||||
{{% /warning %}}
|
||||
|
||||
Check one last time that everything looks complete. Start Hugo's built-in server in order to inspect your local copy of the showcase in the browser.
|
||||
|
||||
```bash
|
||||
hugo server
|
||||
```
|
||||
|
||||
## 4. Commit and Submit a Pull Request
|
||||
|
||||
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][].
|
||||
|
||||
{{% code file="commit-site.sh" %}}
|
||||
```git
|
||||
git commit -m "docs: Add example.com to the showcase"
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Last but not least, we're ready to create a [pull request].
|
||||
|
||||
### Contributor License Agreement
|
||||
|
||||
Don't forget to accept the contributor license agreement. Click on the yellow badge in the automatically added comment in the pull request to accept.
|
||||
|
||||
[code contribution guideline]: https://github.com/spf13/hugo#code-contribution-guideline
|
||||
[pull request]: https://github.com/spf13/hugo/compare
|
||||
[Site Showcase]: /showcase/
|
||||
[`docs/static/images/showcase/`]: https://github.com/spf13/hugo/tree/master/docs/static/images/showcase/
|
||||
@@ -17,46 +17,204 @@ needsreview: true
|
||||
|
||||
Documentation is a critical component of any open-source project. The Hugo docs were completely reworked in anticipation of the release of v0.19, but there is always room for improvement.
|
||||
|
||||
<!-- ## Edit Locally and Submit a Pull Request
|
||||
## Create Your Fork
|
||||
|
||||
**IN DEVELOPMENT**
|
||||
First, make sure that you created a [fork](https://help.github.com/articles/fork-a-repo/) of Hugo on Github and cloned the fork locally on your computer. Next, create a separate branch for your additions. Note that you can choose a different descriptive branch name that best fits the type of content you're trying to submit:
|
||||
|
||||
## How Content is Ordered in the Hugo Docs
|
||||
```git
|
||||
git checkout -b showcase-addition
|
||||
```
|
||||
|
||||
**IN DEVELOPMENT** -->
|
||||
## Adding a New Content Page
|
||||
|
||||
## Adding a New Content Pages
|
||||
|
||||
The Hugo docs are built using Hugo and therefore make heavy use of Hugo's [archetype][] feature to easily scaffold new instances of content types. All [content sections][] in Hugo documentation have an assigned archetypes ([see source][archsource])
|
||||
The Hugo docs are built using Hugo and therefore make heavy use of Hugo's [archetype][] feature to easily scaffold new instances of content types. All [content sections][] in Hugo documentation have an assigned archetypes ([see source][archsource]).
|
||||
|
||||
|
||||
### Adding a New Function
|
||||
|
||||
### Adding a New Tutorial
|
||||
|
||||
Once you have cloned the Hugo repository, you can create a new function via the following command. For functions, title the new function in lowercase.
|
||||
|
||||
```
|
||||
hugo new tutorials/newfunction.md
|
||||
```
|
||||
|
||||
The archetype for the `functions` content type is as follows:
|
||||
|
||||
{{% code file="archetypes/functions.md" %}}
|
||||
```yaml
|
||||
{{< readfile file="archetypes/functions.md">}}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
|
||||
### Adding a New Showcase
|
||||
|
||||
**IN DEVELOPMENT**
|
||||
Once you have cloned the Hugo repository, you can create add your site as a new showcase content file via the following command. Name the markdown file accordingly:
|
||||
|
||||
```
|
||||
hugo new tutorials/my-showcase-addition.md
|
||||
```
|
||||
|
||||
The archetype for the `showcase` content type is as follows:
|
||||
|
||||
{{% code file="archetypes/showcase.md" %}}
|
||||
```yaml
|
||||
{{< readfile file="archetypes/showcase.md">}}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Add at least values for `sitelink`, `title`, `description`, and a path for `image`.
|
||||
|
||||
#### Add an Image for the Showcase
|
||||
|
||||
We need to create the thumbnail of your website. Give your thumbnail a name like `my-hugo-site-name.png`. Save it under [`docs/static/images/showcase/`][].
|
||||
|
||||
{{% warning "Showcase Image Size" %}}
|
||||
It's important that the image you use for your showcase submission has the required dimensions of 600px × 400px or the site will not render appropriately. Be sure to optimize your image as a matter of best practice. If you're looking for a quick online optimization tool, check out [Compressor](https://compressor.io/).
|
||||
{{% /warning %}}
|
||||
|
||||
### Adding a New Tutorial
|
||||
|
||||
**IN DEVELOPMENT**
|
||||
Once you have cloned the Hugo repository, you can create a new tutorial via the following command. Name the markdown file accordingly:
|
||||
|
||||
```
|
||||
hugo new tutorials/my-new-tutorial.md
|
||||
```
|
||||
|
||||
The archetype for the `tutorials` content type is as follows:
|
||||
|
||||
{{% code file="archetypes/tutorials.md" %}}
|
||||
```yaml
|
||||
{{< readfile file="archetypes/tutorials.md">}}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
## Adding Code Blocks to Hugo Docs
|
||||
|
||||
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 Code Block Syntax
|
||||
|
||||
Across all 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. The Hugo docs use a version of [highlight.js](https://highlightjs.org/) that's been modified for specific Hugo keywords.
|
||||
|
||||
Your options for languages are `xml`/`html`, `go`/`golang`, `md`/`markdown`/`mkd`, `handlebars`, `apache`, `toml`, `yaml`, `json`, `css`, `asciidoc`, `ruby`, `powershell`/`ps`, `scss`, `sh`/`zsh`/`bash`/`git`, `http`/`https`, and `javascript`/`js`.
|
||||
|
||||
````html
|
||||
```html
|
||||
<h1>Hello world!</h1>
|
||||
```
|
||||
````
|
||||
|
||||
### Code Block Shortcodes
|
||||
|
||||
**IN DEVELOPMENT**
|
||||
The Hugo documentation comes with very robust shortcodes to help you add interactive code snippets.
|
||||
|
||||
### Code Block
|
||||
{{% note %}}
|
||||
With both the `code` and the `output` shortcodes, *you still need to include the triple back ticks and 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 docs. We assume that the triple-back-tick syntax will live longer than the shortcode.
|
||||
{{% /note %}}
|
||||
|
||||
**IN DEVELOPMENT**
|
||||
#### Input Code Block
|
||||
|
||||
### Output Code Block
|
||||
The first shortcode is the one you'll use most often, `code`. `code`, like all code block shortcodes, requires at least a single `file` named parameter. Here is the signature:
|
||||
|
||||
**IN DEVELOPMENT**
|
||||
````golang
|
||||
{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}}
|
||||
```language
|
||||
A whole bunch of coding going on up in here! Boo-yah!
|
||||
```
|
||||
{{%/* /code */%}}
|
||||
````
|
||||
|
||||
Let's go through each of the three arguments passed into `code`:
|
||||
|
||||
1. `file`. This is the only ***required*** argument for this shortcode. `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 bar of the text-editor design you've seen throughout the docs. Note that you always want to end the file with an extension, but never use more than a single period in the filename. For example, instead of `./archetypes/default`, use `archetypes/default.md`. The file extension is important for displaying the correct icon.
|
||||
2. `download`. If omitted entirely, 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.
|
||||
3. `copy`. All `code` instances add a copy button to the bottom right automatically. However, there are times where you may not want to encourage your end user to copy a code block but still want to keep consistent styling for the filename (e.g., if you adding a "Do not do" code in a tutorial). If you want to turn off the copy functionality of `code`, you can add `copy="false"`.
|
||||
|
||||
##### Example of `Code`
|
||||
|
||||
Here is an HTML code block we want to tell the user lives in the `layouts/_default` directory. We are going to also make the block downloadable because it works as a standalone file:
|
||||
|
||||
````html
|
||||
{{%/* code file="layouts/_default/single.html" download="single.html" */%}}
|
||||
```html
|
||||
{{ define "main" }}
|
||||
<main class="main">
|
||||
<article class="content">
|
||||
<header>
|
||||
<h1>{{.Title}}</h1>
|
||||
{{with .Params.subtitle}}
|
||||
<span class="subtitle">{{.}}</span>
|
||||
</header>
|
||||
<div class="body-copy">
|
||||
{{.Content}}
|
||||
</div>
|
||||
<aside class="toc">
|
||||
{{.TableOfContents}}
|
||||
</aside>
|
||||
</article>
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{%/* /code */%}}
|
||||
````
|
||||
|
||||
The output of this example will render to the Hugo docs as follows:
|
||||
|
||||
{{% code file="layouts/_default/single.html" download="single.html" %}}
|
||||
```html
|
||||
{{ define "main" }}
|
||||
<main class="main">
|
||||
<article class="content">
|
||||
<header>
|
||||
<h1>{{.Title}}</h1>
|
||||
{{with .Params.subtitle}}
|
||||
<span class="subtitle">{{.}}</span>
|
||||
</header>
|
||||
<div class="body-copy">
|
||||
{{.Content}}
|
||||
</div>
|
||||
<aside class="toc">
|
||||
{{.TableOfContents}}
|
||||
</aside>
|
||||
</article>
|
||||
</main>
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
#### Output Code Block
|
||||
|
||||
The `output` shortcode is almost identical to the `code` shortcode but doesn't take any more arguments than the required `file`. The purpose is to demonstrate what the output, or *rendered*, HTML will look after Hugo builds its templates:
|
||||
|
||||
````html
|
||||
{{%/* output file="post/my-first-post/index.html" */%}}
|
||||
```html
|
||||
<h1>This is my First Hugo Blog Post</h1>
|
||||
<p>I am excited to be using Hugo.</p>
|
||||
```
|
||||
{{%/* /output */%}}
|
||||
````
|
||||
|
||||
The preceding `output` example will render as follows to the Hugo docs:
|
||||
|
||||
{{% output file="post/my-first-post/index.html" %}}
|
||||
```html
|
||||
<h1>This is my First Hugo Blog Post</h1>
|
||||
<p>I am excited to be using Hugo.</p>
|
||||
```
|
||||
{{% /output %}}
|
||||
|
||||
## Blockquotes
|
||||
|
||||
Blockquotes can be
|
||||
|
||||
|
||||
{{% note "Blockquotes `!=` Admonitions" %}}
|
||||
Previous versions of the Hugo documentation used [Markdown `<blockquote>` syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes) to draw attention to content. This is [*not* the intended semantic use of the `<blockquote>` element](http://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting actual text. To note or warn your user of specific information, use the admonition shortcodes that follow.
|
||||
{{% /note %}}
|
||||
|
||||
## Admonition Short Codes
|
||||
|
||||
@@ -64,12 +222,7 @@ The Hugo docs are built using Hugo and therefore make heavy use of Hugo's [arche
|
||||
|
||||
> 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]
|
||||
|
||||
|
||||
Both `note` and `warning` with a single, *optional* argument for the admonition title. If the title, a [positional parameter][shortcodeparams]
|
||||
|
||||
{{% note "Admonitions are **NOT** Blockquotes" %}}
|
||||
Previous versions of the Hugo documentation used [Markdown `<blockquote>` syntax](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes) to draw attention to content. This is not the [intended semantic use of the `<blockquote>` element](http://html5doctor.com/cite-and-blockquote-reloaded/).
|
||||
{{% /note %}}
|
||||
Both `note` and `warning` use a single, *optional* argument for the admonition title, which accepts markdown syntax as well. If the title, a [positional parameter][shortcodeparams] in quotes is missing, the default behavior of the `note` and `warning` shortcodes will be to display the text "Note" and "Warning", respectively.
|
||||
|
||||
### Note Admonition Shortcode
|
||||
|
||||
@@ -109,7 +262,7 @@ Use the `warning` shortcode when you want to draw the user's attention to someth
|
||||
|
||||
{{% code file="warning-admonition-input.md" %}}
|
||||
```golang
|
||||
{{%/* warning "Example Warning" */%}}
|
||||
{{%/* warning "Example Warning Admonition" */%}}
|
||||
This is a warning, which should be reserved for *important* information like breaking changes.
|
||||
{{%/* /warning */%}}
|
||||
```
|
||||
@@ -119,7 +272,7 @@ This is a warning, which should be reserved for *important* information like bre
|
||||
|
||||
{{% output file="warning-admonition-output.html" %}}
|
||||
```html
|
||||
{{% warning "Example Warning" %}}
|
||||
{{% warning "Example Warning Admonition" %}}
|
||||
This is a warning, which should be reserved for *important* information like breaking changes.
|
||||
{{% /warning %}}
|
||||
```
|
||||
@@ -127,7 +280,7 @@ This is a warning, which should be reserved for *important* information like bre
|
||||
|
||||
#### `warning` Admonition Shortcode Display
|
||||
|
||||
{{% warning "Example Warning" %}}
|
||||
{{% warning "Example Warning Admonition" %}}
|
||||
This is a warning, which should be reserved for *important* information like breaking changes.
|
||||
{{% /warning %}}
|
||||
|
||||
|
||||
@@ -116,5 +116,5 @@ Now in the complete version, you can sort the tags, convert the tags to links wi
|
||||
[chome]: /functions/chomp/
|
||||
[delimit]: /functions/delimit/
|
||||
[functions]: /functions/
|
||||
[partials]: /templates/partial-templates/
|
||||
[partials]: /templates/partials/
|
||||
[range]: /functions/range/
|
||||
@@ -15,8 +15,7 @@ toc: false
|
||||
notesforauthors:
|
||||
---
|
||||
|
||||
The Hugo docs were completely reworked from the ground up in anticipation of v0.19. Included in the reboot was the concept of leveraging a [single example site][] from which to pull code blocks and demo content in the documentation. Once you finish the [quick start][], be sure to look into how [the Hugo docs have been optimized for rapid learning][].
|
||||
The Hugo docs were completely reworked from the ground up in anticipation of v0.19. There are extensive code block examples throughout the documentation. If this is your first time using Hugo and you [already have Hugo installed on your machine][install], we recommend the [quick start][].
|
||||
|
||||
[quick start]: /getting-started/quick-start/
|
||||
[single example site]: /getting-started/using-the-hugo-docs/
|
||||
[the Hugo docs have been optimized for rapid learning]: /getting-started/using-the-hugo-docs/
|
||||
[install]: /getting-started/installing/
|
||||
[quick start]: /getting-started/quick-start/
|
||||
@@ -262,5 +262,5 @@ Interested? Here are some great tutorials contributed by Hugo users:
|
||||
[GoDaddy]: https://www.godaddy.com/
|
||||
[Heroku]: https://www.heroku.com/
|
||||
[IIS]: http://www.iis.net/
|
||||
[install]: /getting-started/install-hugo/
|
||||
[install]: /getting-started/installing/
|
||||
[nginx]: http://nginx.org/
|
||||
@@ -330,7 +330,7 @@ ignoreFiles = [ "\\.foo$", "\\.boo$" ]
|
||||
```
|
||||
The above is a list of regular expressions. Note that the backslash (`\`) character is escaped in this example to keep TOML happy.
|
||||
|
||||
## Configure Blackfriday Rendering
|
||||
## Configuring Blackfriday Rendering
|
||||
|
||||
[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in
|
||||
[Markdown](http://daringfireball.net/projects/markdown/) rendering engine.
|
||||
|
||||
@@ -44,9 +44,9 @@ Learn more about the different directories and what their purpose is:
|
||||
* [themes](/themes/)
|
||||
|
||||
|
||||
## Example
|
||||
## Example Hugo Project Directory
|
||||
|
||||
An example directory may look like:
|
||||
An example directory may look like the following
|
||||
|
||||
```bash
|
||||
.
|
||||
@@ -93,6 +93,7 @@ An example directory may look like:
|
||||
| └── doc
|
||||
└── static
|
||||
├── css
|
||||
├── images
|
||||
└── js
|
||||
```
|
||||
|
||||
@@ -102,7 +103,7 @@ This directory structure tells us a lot about this website:
|
||||
2. It will also apply two different taxonomies to that content: *categories* and *tags*.
|
||||
3. It will be displaying content in 3 different views: a list, a summary, and a full-page view.
|
||||
|
||||
## Content for Home Page and Other List Pages
|
||||
## Content for Homepage and Other List Pages
|
||||
|
||||
Since Hugo 0.18, "everything" is a `Page` that can have content and metadata, like `.Params`, attached to it -- and share the same set of [page variables](/variables/page-variables/).
|
||||
|
||||
@@ -112,7 +113,9 @@ For the default Markdown content, the filename will be `_index.md`.
|
||||
|
||||
Se the example directory tree below.
|
||||
|
||||
**Note that you don't have to create `_index` file for every section, taxonomy and similar, a default page will be created if not present, but with no content and default values for `.Title` etc.**
|
||||
{{% note "You Don't Have to Create `_index.md`"%}}
|
||||
You don't have to create an `_index` file for every list page (i.e. section, taxonomy, taxonomy terms, etc). If Hugo does not find an `_index.md` on a list page, a default page will be created if not present but with no `{{.Content}}` and only the default values for `.Title` etc.
|
||||
{{% /note %}}
|
||||
|
||||
```bash
|
||||
└── content
|
||||
|
||||
@@ -51,8 +51,8 @@ For more detailed explanations, read the installation guides that follow for [Wi
|
||||
|
||||
#### Prerequisite tools for downloading and building source code
|
||||
|
||||
* [Git](http://git-scm.com/)
|
||||
* [Go][] 1.5+
|
||||
* [Git][installgit]
|
||||
* [Go 1.5+][installgo]
|
||||
|
||||
#### Get directly from GitHub
|
||||
|
||||
@@ -366,7 +366,7 @@ built with love by spf13 and friends in Go.
|
||||
Complete documentation is available at http://gohugo.io/.
|
||||
```
|
||||
|
||||
If you do, then the installation is complete. If you don't, double-check the path that you placed the `hugo.exe` file in and that you typed that path correctly when you added it to your `PATH` variable. If you're still not getting the output, search the [Hugo discussion forum][hugodiscussion] to see if others have already figured out our problem. If not, add a note---in the "Support" category---and be sure to include your command and the output.
|
||||
If you do, then the installation is complete. If you don't, double-check the path that you placed the `hugo.exe` file in and that you typed that path correctly when you added it to your `PATH` variable. If you're still not getting the output, search the [Hugo discussion forum][forum] to see if others have already figured out our problem. If not, add a note---in the "Support" category---and be sure to include your command and the output.
|
||||
|
||||
At the prompt, change your directory to the `Sites` directory.
|
||||
|
||||
@@ -432,13 +432,15 @@ you need to install the Python-based Pygments program. The procedure is outlined
|
||||
|
||||
## Next Steps
|
||||
|
||||
Now that you've installed Hugo, read the [Quick Start guide](/getting-started/quick-start/) and explore the rest of the documentation, starting with an [explanation of how to best use the Hugo docs][usingthehugodocs]. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][hugodiscussion].
|
||||
Now that you've installed Hugo, read the [Quick Start guide][quickstart] and explore the rest of the documentation. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][forum].
|
||||
|
||||
[brew]: https://brew.sh/
|
||||
[highlight shortcode]: /content-management/shortcodes/#highlight
|
||||
[hugodiscussion]: https://discuss.gohugo.io
|
||||
[forum]: https://discuss.gohugo.io
|
||||
[installgit]: (http://git-scm.com/)
|
||||
[installgo]: https://golang.org/dl/
|
||||
[Path Editor]: https://patheditor2.codeplex.com/
|
||||
[pygments]: http://pygments.org
|
||||
[quickstart]: /getting-started/quick-start/
|
||||
[releases]: https://github.com/spf13/hugo/releases
|
||||
[usingthehugodocs]: /getting-started/using-the-hugo-docs/
|
||||
[Windows Environment Variables Editor]: http://eveditor.com/
|
||||
@@ -430,7 +430,7 @@ Now, the website should render similar to the following screenshot:
|
||||
|
||||
Next, we want to remove information related to the theme from the footer. Let's create a new directory at `bookshelf/layouts/partials`. This will hold our new file called `default_foot.html`.
|
||||
|
||||
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:
|
||||
This is a new [partial template][partials]. 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:
|
||||
|
||||
{{% code file="create-new-default-foot.sh" %}}
|
||||
```bash
|
||||
@@ -565,10 +565,10 @@ Here's what you should look into next:
|
||||
[frontmatter]: /content-management/front-matter/
|
||||
[hostinganddeploy]: /hosting-and-deployment/
|
||||
[hugodirectories]: /getting-started/directory-structure/
|
||||
[install]: /getting-started/install-hugo/
|
||||
[install]: /getting-started/installing/
|
||||
[lists]: /templating/lists/
|
||||
[partialtemplates]: /templates/partial-templates/
|
||||
[quickinstall]: /getting-started/install-hugo/#quick-install
|
||||
[partials]: /templates/partials/
|
||||
[quickinstall]: /getting-started/installing/#quick-install
|
||||
[releases]: https://github.com/spf13/hugo/releases
|
||||
[robusttheme]: https://github.com/dim0627/hugo_theme_robust
|
||||
[section]: /content-management/sections/
|
||||
|
||||
@@ -9,7 +9,7 @@ categories: [getting started]
|
||||
tags: [usage,docs,fundamentals]
|
||||
tags_weight: 01
|
||||
weight: 20
|
||||
draft: false
|
||||
draft: true
|
||||
aliases: [/getting-started/using-the-docs/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
|
||||
@@ -16,21 +16,22 @@ needsreview: true
|
||||
|
||||
<!-- begin data files -->
|
||||
|
||||
In addition to the [built-in variables](/templates/variables/) available from Hugo, you can specify your own custom data that can be accessed via templates or shortcodes.
|
||||
In addition to the [built-in variables][vars] available from Hugo, you can specify your own custom data that can be accessed via templates or shortcodes.
|
||||
|
||||
Hugo supports loading data from YAML(http://yaml.org/), [JSON](http://www.json.org/), and [TOML](https://github.com/toml-lang/toml) files located in the `data` directory.
|
||||
Hugo supports loading data from YAML, JSON, and TOML files located in the `data` directory in the root of your Hugo project.
|
||||
|
||||
{{% note %}}
|
||||
Templates using `.Site.Data` even work with LiveReload!
|
||||
{{% /note %}}
|
||||
|
||||
Data Files can also be used in [Hugo themes][themes], but note: If the same `key` is used in both the root data folder (i.e. `data/`) and in the theme's data folder (i.e., `themes/<THEME>/data/), the main one will win. So, for theme authors, for theme specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace, e.g. `mytheme/data/<THEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag; e.g., `hugo -v`.
|
||||
|
||||
## The Data Folder
|
||||
|
||||
The `data` folder is where you can store additional data for Hugo to use when generating your site. Data files aren't used to generate standalone pages - rather they're meant supplemental to the content files. This feature can extend the content in case your frontmatter would grow immensely. Or perhaps your want to show a larger dataset in a template (see example below). In both cases it's a good idea to outsource the data in their own file.
|
||||
|
||||
These files must be YAML, JSON or TOML files (using either the `.yml`, `.yaml`, `.json` or `toml` extension) and the data will be accessible as a `map` in `.Site.Data`.
|
||||
These files must be YAML, JSON or TOML files (using either the `.yml`, `.yaml`, `.json` or `toml` extension). The data will be accessible as a `map` in the `.Site.Data` variable.
|
||||
|
||||
## Data Files in Themes
|
||||
|
||||
Data Files can also be used in [Hugo themes][themes] but note that theme data files follow the same logic as other template files in the [Hugo lookup order][lookup] (i.e., give two files with the same name and relative path, the file in the root project `data` directory will override the file in the `themes/<THEME>/data` directory).
|
||||
|
||||
Therefore, theme authors should take care to not include data files that could be easily overwritten by a user who decides to [customize a theme][customize]. for theme specific data items that shouldn't be overridden, it can be wise to prefix the folder structure with a namespace, e.g. `mytheme/data/<THEME>/somekey/...`. To check if any such duplicate exists, run hugo with the `-v` flag.
|
||||
|
||||
**The keys in this map will be a dot chained set of _path_, _filename_ and _key_ in file (if applicable).**
|
||||
|
||||
@@ -114,6 +115,8 @@ Note the use of the `markdownify` template function. This will send the descript
|
||||
|
||||
<!-- begin "Data-drive Content" page -->
|
||||
|
||||
## Data-Driven Content
|
||||
|
||||
Data-driven content with a static site generator? Yes, it is possible!
|
||||
|
||||
In addition to the [data files](/extras/datafiles/) feature, we have also
|
||||
@@ -127,15 +130,17 @@ and `getCSV`, which are available in **all template files**.
|
||||
|
||||
## Implementation details
|
||||
|
||||
### Calling the functions with an URL
|
||||
### Calling the Functions with a URL
|
||||
|
||||
In any HTML template or Markdown document, call the functions like this:
|
||||
|
||||
{{ $dataJ := getJSON "url" }}
|
||||
{{ $dataC := getCSV "separator" "url" }}
|
||||
```golang
|
||||
{{ $dataJ := getJSON "url" }}
|
||||
{{ $dataC := getCSV "separator" "url" }}
|
||||
```
|
||||
|
||||
or, if you use a prefix or postfix for the URL, the functions
|
||||
accept [variadic arguments](http://en.wikipedia.org/wiki/Variadic_function):
|
||||
If you use a prefix or postfix for the URL, the functions
|
||||
accept [variadic arguments][variadic]:
|
||||
|
||||
{{ $dataJ := getJSON "url prefix" "arg1" "arg2" "arg n" }}
|
||||
{{ $dataC := getCSV "separator" "url prefix" "arg1" "arg2" "arg n" }}
|
||||
@@ -165,32 +170,35 @@ first 5 gists for a GitHub user:
|
||||
{{ end }}
|
||||
</ul>
|
||||
|
||||
|
||||
### Example for CSV files
|
||||
|
||||
For `getCSV`, the one-character long separator must be placed in the
|
||||
first position followed by the URL.
|
||||
For `getCSV`, the one-character-long separator must be placed in the
|
||||
first position followed by the URL. The following is an example of creating an HTML table in a [partial template][partials] from a published CSV:
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
<th>Position</th>
|
||||
<th>Salary</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }}
|
||||
{{ $sep := "," }}
|
||||
{{ range $i, $r := getCSV $sep $url }}
|
||||
<tr>
|
||||
<td>{{ index $r 0 }}</td>
|
||||
<td>{{ index $r 1 }}</td>
|
||||
<td>{{ index $r 2 }}</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
{{% code file="layouts/partials/get-csv.html" %}}
|
||||
```html
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Name</th>
|
||||
<th>Position</th>
|
||||
<th>Salary</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
{{ $url := "http://a-big-corp.com/finance/employee-salaries.csv" }}
|
||||
{{ $sep := "," }}
|
||||
{{ range $i, $r := getCSV $sep $url }}
|
||||
<tr>
|
||||
<td>{{ index $r 0 }}</td>
|
||||
<td>{{ index $r 1 }}</td>
|
||||
<td>{{ index $r 2 }}</td>
|
||||
</tr>
|
||||
{{ end }}
|
||||
</tbody>
|
||||
</table>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
The expression `{{index $r number}}` must be used to output the nth-column from
|
||||
the current row.
|
||||
@@ -205,26 +213,23 @@ You can also set `cacheDir` in the main configuration file.
|
||||
|
||||
If you don't like caching at all, you can fully disable caching with the command line flag `--ignoreCache`.
|
||||
|
||||
### Authentication when using REST URLs
|
||||
### Authentication When Using REST URLs
|
||||
|
||||
Currently, you can only use those authentication methods that can be put into an URL. [OAuth](http://en.wikipedia.org/wiki/OAuth) or other authentication methods are not implemented.
|
||||
Currently, you can only use those authentication methods that can be put into an URL. [OAuth][] and other authentication methods are not implemented.
|
||||
|
||||
### Loading local files
|
||||
### Loading Local files
|
||||
|
||||
To load local files with the two functions `getJSON` and `getCSV`, the source files must reside within Hugo's working directory. The file extension does not matter but the content does.
|
||||
To load local files with `getJSON` and `getCSV`, the source files must reside within Hugo's working directory. The file extension does not matter, but the content does.
|
||||
|
||||
It applies the same output logic as in the topic: *Calling the functions with an URL*.
|
||||
It applies the same output logic as above in [Calling the Functions with a URL](#calling-the-functions-with-a-url).
|
||||
|
||||
## LiveReload
|
||||
## LiveReload with Data Files
|
||||
|
||||
There is no chance to trigger a [LiveReload](/extras/livereload/) when the content of an URL changes. However, when a local JSON/CSV file changes, then a LiveReload will be triggered of course. Symlinks are not supported.
|
||||
There is no chance to trigger a [LiveReload][] when the content of a URL changes. However, when a *local* file changes (i.e., `data/*` and `themes/<THEME>/data/*`), a LiveReload will be triggered. Symlinks are not supported. Note too that because downloading of data takes a while, Hugo stops processing your Markdown files until the data download has completed.
|
||||
|
||||
{{% note "URLs and LiveReload" %}}
|
||||
If you change any local file and the LiveReload is triggered, Hugo will either read the URL content from the cache or, if you have disabled the cache, Hugo will re-download the content. This can create huge traffic and you may also reach API limits quickly.
|
||||
{{% /note %}}
|
||||
|
||||
As downloading of content takes a while, Hugo stops processing
|
||||
your Markdown files until the content has been downloaded.
|
||||
{{% warning "URL Data and LiveReload" %}}
|
||||
If you change any local file and the LiveReload is triggered, Hugo will read the data-driven (URL) content from the cache. If you have disabled the cache (i.e., by running the server with `hugo server --ignoreCache`), Hugo will re-download the content every time LiveReload triggers. This can create *huge* traffic. You may reach API limits quickly.
|
||||
{{% /warning %}}
|
||||
|
||||
## Examples
|
||||
|
||||
@@ -232,13 +237,22 @@ your Markdown files until the content has been downloaded.
|
||||
- GitHub Starred Repositories [in a posts](https://github.com/SchumacherFM/blog-cs/blob/master/content%2Fposts%2Fgithub-starred.md) with the related [short code](https://github.com/SchumacherFM/blog-cs/blob/master/layouts%2Fshortcodes%2FghStarred.html).
|
||||
- More? Please tell us!
|
||||
|
||||
## Specs for Configuration Formats
|
||||
## Specs for Data Formats
|
||||
|
||||
* [TOML Spec][toml]
|
||||
* [YAML Spec][yaml]
|
||||
* [JSON Spec][json]
|
||||
* [CSV Spec][csv]
|
||||
|
||||
[csv]: https://tools.ietf.org/html/rfc4180
|
||||
[customize]: /themes/customizing/
|
||||
[lookup]: /templates/lookup-order/
|
||||
[json]: /documents/ecma-404-json-spec.pdf
|
||||
[LiveReload]: /getting-started/basic-usage/#livereload
|
||||
[OAuth]: http://en.wikipedia.org/wiki/OAuth
|
||||
[partials]: /templates/partials/
|
||||
[themes]: /themes/
|
||||
[toml]: https://github.com/toml-lang/toml
|
||||
[yaml]: http://yaml.org/spec/
|
||||
[variadic]: http://en.wikipedia.org/wiki/Variadic_function
|
||||
[vars]: /variables/
|
||||
@@ -451,7 +451,7 @@ Finally, you can pull "magic constants" out of your layouts as well. The followi
|
||||
</nav>
|
||||
```
|
||||
|
||||
## Go Templating Example: Show Only Upcoming Events
|
||||
## Example: Show Only Upcoming Events
|
||||
|
||||
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 a content file's [front matter][]) is in the future. The following is an example [partial template][partials]:
|
||||
|
||||
|
||||
@@ -14,59 +14,59 @@ toc: false
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
The home page of a website is often formatted differently than the other pages. In Hugo you can define your own homepage template.
|
||||
The homepage of a website is often formatted differently than the other pages. In Hugo you can define your own homepage template.
|
||||
|
||||
Homepage is a `Page` and has all the [page variables](/templates/variables/) and [site variables](/templates/variables/) available to use in the templates.
|
||||
Homepage is a `Page` and therefore has all the [page variables][pagevars] and [site variables][sitevars] available for use.
|
||||
|
||||
*This is the only required template for building a site and useful when bootstrapping a new site and template. It is also the only required template when using a single page site.*
|
||||
{{% note "The Only Required Template" %}}
|
||||
The homepage template is the *only* required template for building a site and useful when bootstrapping a new site and template. It is also the only required template if you are developing a single page site.
|
||||
{{% /note %}}
|
||||
|
||||
In addition to the standard page variables, the homepage has access to all site content accessible from `.Data.Pages`. Details on how to use the list of pages can be found in the [Lists Template](/templates/list/).
|
||||
## Homepage Template Lookup Order
|
||||
|
||||
Note that a home page can also have a content file with frontmatter, see [Source Organization](/overview/source-directory/).
|
||||
The [lookup order][lookup] for the homepage template is as follows:
|
||||
|
||||
## Which Template will be rendered?
|
||||
* `/layouts/index.html`
|
||||
* `/layouts/\_default/list.html`
|
||||
* `/layouts/\_default/single.html`
|
||||
* `/themes/<THEME>/layouts/index.html`
|
||||
* `/themes/<THEME>/layouts/_default/list.html`
|
||||
* `/themes/<THEME>/layouts/_default/single.html`
|
||||
|
||||
Hugo uses a set of rules to figure out which template to use when rendering a specific page.
|
||||
## `.Data.Pages` on the Homepage
|
||||
|
||||
Hugo will use the following prioritized list. If a file isn’t present, then the next one in the list will be used. This enables you to craft specific layouts when you want to without creating more templates than necessary. For most sites, only the \_default file at the end of
|
||||
the list will be needed.
|
||||
In addition to the standard [page variables][pagevars], the homepage template has access to *all* site content via `.Data.Pages`.
|
||||
|
||||
* /layouts/index.html
|
||||
* /layouts/\_default/list.html
|
||||
* /layouts/\_default/single.html
|
||||
* /themes/`THEME`/layouts/index.html
|
||||
* /themes/`THEME`/layouts/\_default/list.html
|
||||
* /themes/`THEME`/layouts/\_default/single.html
|
||||
`.Data.Pages` usually refers to the list of pages available within a given section or taxonomy. However, since `index.html` is the homepage of your Hugo project (i.e., in essence, the top of the master section), `Data.Pages` for `layouts/index.html` is interchangeable with `.Site.Pages` when written on the homepage template.
|
||||
|
||||
## Example index.html
|
||||
This content template is used for [spf13.com](http://spf13.com/).
|
||||
Note that a homepage can also have a content file with front matter. This content file lives at `content/_index.md`. See [Content Organization][contentorg] for more information.
|
||||
|
||||
It makes use of [partial templates](/templates/partials/) and uses a similar approach as a [List](/templates/list/).
|
||||
## Example Homepage Template
|
||||
|
||||
<!DOCTYPE html>
|
||||
<html class="no-js" lang="en-US" prefix="og: http://ogp.me/ns# fb: http://ogp.me/ns/fb#">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
The following is an example of a homepage template.
|
||||
|
||||
{{ partial "meta.html" . }}
|
||||
It makes use of [partial templates][partials] and uses a similar approach as a [Hugo list template][lists].
|
||||
|
||||
<base href="{{ .Site.BaseURL }}">
|
||||
<title>{{ .Site.Title }}</title>
|
||||
<link rel="canonical" href="{{ .Permalink }}">
|
||||
<link href="{{ .RSSLink }}" rel="alternate" type="application/rss+xml" title="{{ .Site.Title }}" />
|
||||
|
||||
{{ partial "head_includes.html" . }}
|
||||
</head>
|
||||
<body lang="en">
|
||||
|
||||
{{ partial "subheader.html" . }}
|
||||
|
||||
<section id="main">
|
||||
{{% code file="layouts/index.html" download="index.html" %}}
|
||||
```html
|
||||
{{ define "main" }}
|
||||
{{ partial "content-header.html" . }}
|
||||
<main aria-role="main">
|
||||
<div>
|
||||
<!-- Note that .Data.Pages is the equivalent of .Site.Pages on the homepage template. -->
|
||||
{{ range first 10 .Data.Pages }}
|
||||
{{ .Render "summary"}}
|
||||
{{ end }}
|
||||
</div>
|
||||
</section>
|
||||
</main>
|
||||
{{ partial "content-footer.html" . }}
|
||||
{{ end }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
{{ partial "footer.html" . }}
|
||||
[contentorg]: /content-management/content-organization/
|
||||
[lists]: /templates/lists/
|
||||
[lookup]: /templates/lookup-order/
|
||||
[pagevars]: /variables/page-variables/
|
||||
[partials]: /templates/partials/
|
||||
[sitevars]: /variables/site-variables/
|
||||
@@ -118,7 +118,7 @@ If `where` or `first` receives invalid input or a field name that doesn’t exis
|
||||
[homepage]: /templates/homepage-template/
|
||||
[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php
|
||||
[mentalmodel]: http://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html
|
||||
[partials]: /templates/partial-templates/
|
||||
[partials]: /templates/partials/
|
||||
[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification"
|
||||
[RSS]: /templates/rss-templates/
|
||||
[sections]: /content-management/sections/
|
||||
|
||||
@@ -28,16 +28,18 @@ Most Hugo websites will only need the default template files at the end of the l
|
||||
|
||||
See examples of the lookup order for each of the Hugo template types:
|
||||
|
||||
* [Base Templates][]
|
||||
* [Homepage Template][home]
|
||||
* [Base Templates][base]
|
||||
* [Section Page Templates][sectionlookup]
|
||||
* [Taxonomy List Templates][taxonomylookup]
|
||||
* [Taxonomy Terms Templates][termslookup]
|
||||
* [Single Page Templates][singlelookup]
|
||||
* [RSS Templates][rsslookup]
|
||||
|
||||
[Base Templates]: /templates/base-templates-and-blocks/#base-template-lookup-order
|
||||
[base]: /templates/base-templates-and-blocks/#base-template-lookup-order
|
||||
[directory structure]: /getting-started/directory-structure/
|
||||
[DRY]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
|
||||
[home]: /templates/homepage-template/#homepage-template-lookup-order
|
||||
[rsslookup]: /templates/rss-templates/#rss-template-lookup-order
|
||||
[sectionlookup]: /templates/section-templates/#section-template-lookup-order
|
||||
[singlelookup]: templates/single-page-templates/#single-page-template-lookup-order
|
||||
|
||||
@@ -18,11 +18,10 @@ notesforauthors:
|
||||
|
||||
In practice, it's very convenient to split out common template portions into a
|
||||
partial template that can be included anywhere. As you create the rest of your
|
||||
templates, you will include templates from the ``/layouts/partials` directory
|
||||
or from arbitrary subdirectories like `/layouts/partials/post/tag`.
|
||||
templates, you will include templates from the `/layouts/partials/` directory
|
||||
or from arbitrary partial subdirectories like `/layouts/partials/post/tag/`.
|
||||
|
||||
Partials are especially important for themes as it gives users an opportunity
|
||||
to overwrite just a small part of your theme, while maintaining future compatibility.
|
||||
Partials are especially important for [themes][] because they give theme users an opportunity to [overwrite just a small portion of a theme][customize] while maintaining compatibility with the theme's upstream.
|
||||
|
||||
Theme developers may want to include a few partials with empty HTML
|
||||
files in the theme just so end users have an easy place to inject their
|
||||
@@ -161,40 +160,36 @@ Hugo ships with prebuilt internal partial templates for Google Analytics trackin
|
||||
|
||||
<!-- pulled from extras/analytics -->
|
||||
|
||||
### Configuring Google Analytics
|
||||
#### Configuring Google Analytics
|
||||
|
||||
Provide your tracking id in your configuration file, e.g. config.yaml.
|
||||
|
||||
googleAnalytics = "UA-123-45"
|
||||
```toml
|
||||
googleAnalytics = "UA-123-45"
|
||||
```
|
||||
|
||||
### Google Analytics Example
|
||||
#### Google Analytics Example
|
||||
|
||||
Include the internal template in your templates like so:
|
||||
|
||||
{{% code file="call-ga.md" %}}
|
||||
{{% code file="call-ga.html" %}}
|
||||
```golang
|
||||
{{ template "_internal/google_analytics.html" . }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
For asynchronous loading of Google analytics, include the async template:
|
||||
|
||||
{{% code file="call-ga-async.md" %}}
|
||||
{{% code file="call-ga-async.html" %}}
|
||||
```golang
|
||||
{{ template "_internal/google_analytics_async.html" . }}
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
<!-- pulled from extras/comments -->
|
||||
|
||||
As Hugo is a static site generator, the content produced is static and doesn’t interact with the users. The most common interaction people ask for is comment capability.
|
||||
|
||||
Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to website via JavaScript.
|
||||
|
||||
Your theme may already support Disqus, but even it if doesn’t, it is easy to add.
|
||||
|
||||
### Disqus
|
||||
|
||||
Hugo also ships with a built-in partial for [Disqus comments][disqus], a popular commenting system for both static and dynamic websites.
|
||||
|
||||
#### Adding Disqus to a Template
|
||||
|
||||
Hugo comes with all the code you would need to include load Disqus. Simply include the following line where you want your comments to appear:
|
||||
@@ -259,26 +254,6 @@ You can then reference the partial template:
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
## Alternatives
|
||||
|
||||
A few alternatives exist to [Disqus](https://disqus.com/):
|
||||
|
||||
* [Discourse](http://www.discourse.org)
|
||||
* [IntenseDebate](http://intensedebate.com/)
|
||||
* [Livefyre](http://livefyre.com/)
|
||||
* [Muut](http://muut.com/)
|
||||
* [多说](http://duoshuo.com/) ([Duoshuo](http://duoshuo.com/), popular in China)
|
||||
* [isso](http://posativ.org/isso/) (Self-hosted, Python)
|
||||
* [Kaiju](https://github.com/spf13/kaiju)
|
||||
|
||||
## Kaiju
|
||||
|
||||
[Kaiju](https://github.com/spf13/kaiju) is an open-source project started by [spf13](http://spf13.com/) (Hugo’s author) to bring easy and fast real time discussions to the web.
|
||||
|
||||
Written using Go, Socket.io and MongoDB, it is very fast and easy to deploy.
|
||||
|
||||
It is in early development but shows promise. If you have interest, please help by contributing whether via a pull request, an issue or even just a tweet. Everything helps.
|
||||
|
||||
## Discourse
|
||||
|
||||
Additionally, you may recognize [Discourse](http://www.discourse.org) as the system that powers the [Hugo Discussion Forum](http://discuss.gohugo.io).
|
||||
[themes]: /themes/
|
||||
[customize]: /themes/customizing/
|
||||
[disqus]: https://disqus.com
|
||||
@@ -86,7 +86,7 @@ your list templates:
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
### Order by Weight -> Date
|
||||
### Ordering a list by Weight -> Date
|
||||
|
||||
```html
|
||||
{{ range .Data.Pages.ByWeight }}
|
||||
@@ -97,7 +97,7 @@ your list templates:
|
||||
{{ end }}
|
||||
```
|
||||
|
||||
### Order by Date
|
||||
### Ordering a List by Date
|
||||
|
||||
{{ range .Data.Pages.ByDate }}
|
||||
<li>
|
||||
@@ -106,7 +106,7 @@ your list templates:
|
||||
</li>
|
||||
{{ end }}
|
||||
|
||||
### Order by PublishDate
|
||||
### Ordering a List by PublishDate
|
||||
|
||||
{{ range .Data.Pages.ByPublishDate }}
|
||||
<li>
|
||||
@@ -115,7 +115,7 @@ your list templates:
|
||||
</li>
|
||||
{{ end }}
|
||||
|
||||
### Order by ExpiryDate
|
||||
### Ordering a list by ExpiryDate
|
||||
|
||||
{{ range .Data.Pages.ByExpiryDate }}
|
||||
<li>
|
||||
@@ -124,7 +124,7 @@ your list templates:
|
||||
</li>
|
||||
{{ end }}
|
||||
|
||||
### Order by Lastmod
|
||||
### Ordering a List by Lastmod
|
||||
|
||||
{{ range .Data.Pages.ByLastmod }}
|
||||
<li>
|
||||
@@ -133,7 +133,7 @@ your list templates:
|
||||
</li>
|
||||
{{ end }}
|
||||
|
||||
### Order by Length
|
||||
### Ordering a List by Length
|
||||
|
||||
{{ range .Data.Pages.ByLength }}
|
||||
<li>
|
||||
@@ -143,7 +143,7 @@ your list templates:
|
||||
{{ end }}
|
||||
|
||||
|
||||
### Order by Title
|
||||
### Ordering a List by Title
|
||||
|
||||
{{ range .Data.Pages.ByTitle }}
|
||||
<li>
|
||||
@@ -152,7 +152,7 @@ your list templates:
|
||||
</li>
|
||||
{{ end }}
|
||||
|
||||
### Order by LinkTitle
|
||||
### Ordering a List by LinkTitle
|
||||
|
||||
{{ range .Data.Pages.ByLinkTitle }}
|
||||
<li>
|
||||
@@ -161,7 +161,7 @@ your list templates:
|
||||
</li>
|
||||
{{ end }}
|
||||
|
||||
### Order by Parameter
|
||||
### Order List by Parameter
|
||||
|
||||
Order based on the specified front matter parameter. Pages without that
|
||||
parameter will use the site's `.Site.Params` default. If the parameter is not
|
||||
@@ -317,7 +317,7 @@ it’s really just a matter of preference.
|
||||
|
||||
Because Grouping returns a key and a slice of pages, all of the ordering methods listed above are available.
|
||||
|
||||
In this example, I’ve ordered the groups in chronological order and the content
|
||||
In this example, I’ve ordered the groups in chronological ordering and the content
|
||||
within each group in alphabetical order by title.
|
||||
|
||||
```html
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: Robots.txt File
|
||||
linktitle: Robots.txt
|
||||
description:
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [templates]
|
||||
tags: [robots,search engines]
|
||||
weight: 165
|
||||
draft: false
|
||||
aliases: [/extras/robots-txt/]
|
||||
toc: false
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
Hugo can generated a customized [robots.txt](http://www.robotstxt.org/) in the
|
||||
[same way as any other templates]({{< ref "templates/go-templates.md" >}}).
|
||||
|
||||
To enable it, just set `enableRobotsTXT` option to `true` in the [configuration file]({{< ref "overview/configuration.md" >}}). By default, it generates a robots.txt, which allows everything, with the following content:
|
||||
|
||||
```http
|
||||
User-agent: *
|
||||
```
|
||||
|
||||
## Robots.txt Template Lookup Order
|
||||
|
||||
The [lookup order][lookup] for the `robots.txt` template is as follows:
|
||||
|
||||
* `/layouts/robots.txt`
|
||||
* `/themes/<THEME>/layout/robots.txt`
|
||||
|
||||
An example of a `robots.txt` layout is:
|
||||
|
||||
```http
|
||||
User-agent: *
|
||||
|
||||
{{range .Data.Pages}}
|
||||
Disallow: {{.RelPermalink}}{{end}}
|
||||
```
|
||||
|
||||
This template disallows all the pages of the site creating one `Disallow` entry for each one.
|
||||
|
||||
[lookup]: /layouts/lookup-order
|
||||
@@ -70,7 +70,7 @@ The following examples assume two things:
|
||||
Now we can look at the front matter for the three single-page content (i.e.`.md`) files.
|
||||
|
||||
{{% note "Three Content Pages but *Four* Markdown Files?" %}}
|
||||
`_index.md` may seem like a single page of content but is actually a specific `kind` in Hugo. Whereas `my-first-post.md`, `my-second-post.md`, and `my-first-event.md` are all of kind `page`, all `_index.md` files in a Hugo project are of kind `section` and therefore do not submit themselves to the *single* page template lookup. Instead, `events/_index.md` will render according to its [section template](templates/section-templates/) and respective lookup order.
|
||||
`_index.md` may seem like a single page of content but is actually a specific `kind` in Hugo. Whereas `my-first-post.md`, `my-second-post.md`, and `my-first-event.md` are all of kind `page`, all `_index.md` files in a Hugo project are of kind `section` and therefore do not submit themselves to the *single* page template lookup. Instead, `events/_index.md` will render according to its [section template](/templates/section-templates/) and respective lookup order.
|
||||
{{% /note %}}
|
||||
|
||||
### `my-first-post.md`
|
||||
@@ -279,7 +279,7 @@ To easily generate new instances of this content type (e.g., new `.md` files in
|
||||
[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
|
||||
[front matter]: /content-management/front-matter/
|
||||
[page variables]: /variables-and-parms/page-variables/
|
||||
[partials]: /templates/partial-templates/
|
||||
[partials]: /templates/partials/
|
||||
[section]: /content-management/sections/
|
||||
[site variables]: /variables/site-variables/
|
||||
[spf13]: http://spf13.com/
|
||||
@@ -18,7 +18,7 @@ A single Sitemap template is used to generate the `sitemap.xml` file.
|
||||
Hugo automatically comes with this template file. **No work is needed on
|
||||
the users' part unless they want to customize `sitemap.xml`.**
|
||||
|
||||
A sitemap is a `Page` and have all the [page variables](/layout/variables/) available to use in this template along with Sitemap-specific ones:
|
||||
A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use in this template along with Sitemap-specific ones:
|
||||
|
||||
`.Sitemap.ChangeFreq`
|
||||
: The page change frequency
|
||||
@@ -29,7 +29,7 @@ A sitemap is a `Page` and have all the [page variables](/layout/variables/) avai
|
||||
`.Sitemap.Filename`
|
||||
: The sitemap filename
|
||||
|
||||
If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal one.
|
||||
If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo..
|
||||
|
||||
## Hugo’s sitemap.xml
|
||||
|
||||
@@ -66,4 +66,6 @@ Defaults for `<changefreq>`, `<priority>` and `filename` values can be set in th
|
||||
filename = "sitemap.xml"
|
||||
```
|
||||
|
||||
The same fields can be specified in an individual page's front matter in order to override the value for that page.
|
||||
The same fields can be specified in an individual content file's front matter in order to override the value assigned to that piece of content at render time.
|
||||
|
||||
[pagevars]: /variables/page-variables/
|
||||
@@ -9,23 +9,19 @@ categories: [themes]
|
||||
tags: [themes, source, organization, directories]
|
||||
weight: 20
|
||||
draft: false
|
||||
aliases: [/themes/customizing/,/themes/customize/]
|
||||
aliases: [/themes/customize/]
|
||||
toc: true
|
||||
needsreview: true
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
The following are key concepts for Hugo site customization. Hugo permits you to supplement *or* override any theme template or static file, with files in your working directory.
|
||||
The following are key concepts for Hugo site customization with themes. Hugo permits you to supplement *or* override any theme template or static file with files in your working directory.
|
||||
|
||||
{{% note %}}
|
||||
When you use a theme cloned from its git repository, do not edit the theme's files directly. Instead, theme customization in Hugo is a matter of *overriding* the templates made available to you in a theme. This provides the added flexibility of tweaking a theme to meet your needs while staying current with a theme's upstream.
|
||||
{{% /note %}}
|
||||
|
||||
## Understanding the Theme Lookup Order
|
||||
|
||||
{{< readfile file="readfile-content/lookupexplanation.md" markdown="true" >}}
|
||||
|
||||
## Replacing Static Files
|
||||
|
||||
There are times where you want to include static assets that differ from versions of the same asset that ships with a theme. For example, if you would like to use a more recent version of jQuery than what the theme happens to include, simply place an identically-named file in the same relative location but in your working directory.
|
||||
@@ -19,13 +19,13 @@ needsreview: true
|
||||
[Shortcodes][shortcodes] have access to parameters delimited in the shortcode declaration via [`.Get`][getfunction], page- and site-level variables, and also the following shortcode-specific fields:
|
||||
|
||||
`.Parent`
|
||||
: Provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root.
|
||||
: provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root.
|
||||
|
||||
`.IsNamedParams`
|
||||
: Boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes]
|
||||
: boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes]
|
||||
|
||||
`.Inner`
|
||||
: Represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used
|
||||
: represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used
|
||||
|
||||
## Git Variables
|
||||
|
||||
@@ -46,19 +46,19 @@ Hugo's Git integrations should be fairly performant but *can* increase your buil
|
||||
The `GitInfo` object contains the following fields:
|
||||
|
||||
`.AbbreviatedHash`
|
||||
: The abbreviated commit hash (e.g., `866cbcc`)
|
||||
: the abbreviated commit hash (e.g., `866cbcc`)
|
||||
|
||||
`.AuthorName`
|
||||
: The author's name, respecting `.mailmap`
|
||||
: the author's name, respecting `.mailmap`
|
||||
|
||||
`.AuthorEmail`
|
||||
: The author's email address, respecting `.mailmap`
|
||||
: the author's email address, respecting `.mailmap`
|
||||
|
||||
`.AuthorDate`
|
||||
: The author date
|
||||
: the author date
|
||||
|
||||
`.Hash`
|
||||
: The commit hash (e.g., `866cbccdab588b9908887ffd3b4f2667e94090c3`)
|
||||
: the commit hash (e.g., `866cbccdab588b9908887ffd3b4f2667e94090c3`)
|
||||
|
||||
`.Subject`
|
||||
: commit message subject (e.g., `tpl: Add custom index function`)
|
||||
@@ -68,16 +68,16 @@ The `GitInfo` object contains the following fields:
|
||||
The `.Hugo` variable provides easy access to Hugo-related data and contains the following fields:
|
||||
|
||||
`.Hugo.Generator`
|
||||
: Meta tag for the version of Hugo that generated the site. `.Hugo.Generator` outputs a *complete* HTML tag; e.g. `<meta name="generator" content="Hugo 0.18" />`
|
||||
: `<meta>`` tag for the version of Hugo that generated the site. `.Hugo.Generator` outputs a *complete* HTML tag; e.g. `<meta name="generator" content="Hugo 0.18" />`
|
||||
|
||||
`.Hugo.Version`
|
||||
: The current version of the Hugo binary you are using e.g. `0.13-DEV`<br>
|
||||
: the current version of the Hugo binary you are using e.g. `0.13-DEV`<br>
|
||||
|
||||
`.Hugo.CommitHash`
|
||||
: The git commit hash of the current Hugo binary e.g. `0e8bed9ccffba0df554728b46c5bbf6d78ae5247`<br>
|
||||
: the git commit hash of the current Hugo binary e.g. `0e8bed9ccffba0df554728b46c5bbf6d78ae5247`
|
||||
|
||||
`.Hugo.BuildDate`
|
||||
: The compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`<br>
|
||||
: 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'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.
|
||||
@@ -114,6 +114,19 @@ A menu entry in a [menu template][] has the following properties:
|
||||
`.Children`
|
||||
: Menu
|
||||
|
||||
## Sitemap Variable
|
||||
|
||||
A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use sitemap templates. They also have the following sitemap-specific variables available to them:
|
||||
|
||||
`.Sitemap.ChangeFreq`
|
||||
: the page change frequency
|
||||
|
||||
`.Sitemap.Priority`
|
||||
: the priority of the page
|
||||
|
||||
`.Sitemap.Filename`
|
||||
: the sitemap filename
|
||||
|
||||
|
||||
[configuration]: /getting-started/configuration/
|
||||
[getfunction]: /functions/get/
|
||||
|
||||
@@ -112,7 +112,7 @@ baseURL = "http://yoursite.example.com/"
|
||||
author = "Nikola Tesla"
|
||||
```
|
||||
|
||||
You can use `.Site.Params` in a [partial template](/templates/partial-templates/) to call the default site description:
|
||||
You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description:
|
||||
|
||||
{{% code file="layouts/partials/head.html" %}}
|
||||
```html
|
||||
|
||||
Vendored
+1
-1
File diff suppressed because one or more lines are too long
@@ -0,0 +1,11 @@
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
|
||||
<svg width="100%" height="100%" viewBox="0 0 400 400" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:1.41421;">
|
||||
<g transform="matrix(1.90897,0,0,1.90897,-27.8648,-56.0002)">
|
||||
<path d="M119.631,36.154L203.822,85.066L203.822,181.395L119.631,229.184L35.578,181.395L35.578,85.066L119.631,36.154Z" style="fill:rgb(255,64,136);"/>
|
||||
<path d="M207.664,81.239L209.061,83.666L209.061,182.809L207.638,185.253L121.013,234.423L118.245,234.422L31.761,185.251L30.34,182.808L30.34,83.667L31.735,81.242L118.217,30.916L121.041,30.915L207.664,81.239ZM40.817,88.078L40.817,178.348L119.633,223.159L198.584,178.345L198.584,88.081L119.633,42.214L40.817,88.078Z" style="fill:rgb(201,23,126);"/>
|
||||
</g>
|
||||
<g transform="matrix(1.78981,0,0,2.02809,-42.2616,88.7603)">
|
||||
<path d="M179.238,106.552L154.758,106.552L154.758,62.2L112.134,62.2L112.134,106.552L87.654,106.552L87.654,1.648L112.134,1.648L112.134,45.496L154.758,45.496L154.758,1.648L179.238,1.648L179.238,106.552Z" style="fill:white;fill-rule:nonzero;"/>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 1.3 KiB |
Vendored
+1
-1
File diff suppressed because one or more lines are too long
@@ -6,7 +6,7 @@
|
||||
<span>Home</span>
|
||||
</a>
|
||||
</li>
|
||||
{{if ne .Kind "section"}}
|
||||
{{if and (ne .Kind "section") (ne .Section "")}}
|
||||
<li>
|
||||
<a class="crumb" href="{{.Site.BaseURL}}{{.Section | urlize}}">
|
||||
<img src="{{.Site.BaseURL}}images/hugo-icons/{{.Section | urlize}}.svg" alt="">
|
||||
|
||||
@@ -32,6 +32,7 @@
|
||||
<div class="nav-buttons">
|
||||
<a role="button" href="https://github.com/spf13/hugo/releases"><i class="icon-download"></i>Download Hugo</a>
|
||||
<a role="button" href="{{.Site.Params.discuss}}" target="_blank"><i class="icon-forum"></i> Discuss Hugo</a><br>
|
||||
<a role="button" href="https://github.com/spf13/hugo/issues/new" target="_blank"><i class="icon-github"></i> File an Issue</a><br>
|
||||
<!-- <a role="button" href="{{.Site.BaseURL}}mailing-list/"><i class="icon-mail"></i>Join the Mailing List</a> -->
|
||||
</div>
|
||||
</nav>
|
||||
@@ -1,4 +1,6 @@
|
||||
// Keywords and other highlight in this script have been modified for better selection of Hugo-specific keywords
|
||||
// 1. "code", "output", "note", and "warning" added as keywords to go/golang for Hugo for shortcodes used in documentation site
|
||||
// 2. "file", "download", and "copy" added to literals for Hugo-doc-specific shortcodes
|
||||
/*! highlight.js v9.9.0 | BSD3 License | git.io/hljslicense */
|
||||
! function(e) {
|
||||
var n = "object" == typeof window && window || "object" == typeof self && self;
|
||||
@@ -269,8 +271,9 @@ hljs.registerLanguage("xml", function(s) {
|
||||
t = { eW: !0, i: /</, r: 0, c: [{ cN: "attr", b: e, r: 0 }, { b: /=\s*/, r: 0, c: [{ cN: "string", endsParent: !0, v: [{ b: /"/, e: /"/ }, { b: /'/, e: /'/ }, { b: /[^\s"'=<>`]+/ }] }] }] };
|
||||
return { aliases: ["html", "xhtml", "rss", "atom", "xjb", "xsd", "xsl", "plist"], cI: !0, c: [{ cN: "meta", b: "<!DOCTYPE", e: ">", r: 10, c: [{ b: "\\[", e: "\\]" }] }, s.C("<!--", "-->", { r: 10 }), { b: "<\\!\\[CDATA\\[", e: "\\]\\]>", r: 10 }, { b: /<\?(php)?/, e: /\?>/, sL: "php", c: [{ b: "/\\*", e: "\\*/", skip: !0 }] }, { cN: "tag", b: "<style(?=\\s|>|$)", e: ">", k: { name: "style" }, c: [t], starts: { e: "</style>", rE: !0, sL: ["css", "xml"] } }, { cN: "tag", b: "<script(?=\\s|>|$)", e: ">", k: { name: "script" }, c: [t], starts: { e: "</script>", rE: !0, sL: ["actionscript", "javascript", "handlebars", "xml"] } }, { cN: "meta", v: [{ b: /<\?xml/, e: /\?>/, r: 10 }, { b: /<\?\w+/, e: /\?>/ }] }, { cN: "tag", b: "</?", e: "/?>", c: [{ cN: "name", b: /[^\/><\s]+/, r: 0 }, t] }] }
|
||||
});
|
||||
|
||||
hljs.registerLanguage("go", function(e) {
|
||||
var t = { keyword: "break default func interface select case map struct chan else goto package switch const fallthrough if range end type continue for import return var go defer bool byte complex64 complex128 float32 float64 int8 int16 int32 int64 string uint8 uint16 uint32 uint64 int uint uintptr rune id autoplay Get", literal: "true false iota nil Pages with", built_in: "append cap close complex highlight copy imag len make new panic print println real recover delete Site Data tweet speakerdeck youtube ref relref vimeo instagram gist figure innershortcode" };
|
||||
var t = { keyword: "code output note warning break default func interface select case map struct chan else goto package switch const fallthrough if range end type continue for import return var go defer bool byte complex64 complex128 float32 float64 int8 int16 int32 int64 string uint8 uint16 uint32 uint64 int uint uintptr rune id autoplay Get", literal: "file download copy true false iota nil Pages with", built_in: "append cap close complex highlight copy imag len make new panic print println real recover delete Site Data tweet speakerdeck youtube ref relref vimeo instagram gist figure innershortcode" };
|
||||
return { aliases: ["golang"], k: t, i: "</", c: [e.CLCM, e.CBCM, { cN: "string", v: [e.QSM, { b: "'", e: "[^\\\\]'" }, { b: "`", e: "`" }] }, { cN: "number", v: [{ b: e.CNR + "[dflsi]", r: 1 }, e.CNM] }, { b: /:=/ }, { cN: "function", bK: "func", e: /\s*\{/, eE: !0, c: [e.TM, { cN: "params", b: /\(/, e: /\)/, k: t, i: /["']/ }] }] }
|
||||
});
|
||||
hljs.registerLanguage("markdown", function(e) {
|
||||
|
||||
@@ -65,6 +65,13 @@ h4 {
|
||||
// text-transform: uppercase;
|
||||
}
|
||||
|
||||
h5 {
|
||||
font-size: 1em;
|
||||
font-weight: bold;
|
||||
margin-bottom: 1em;
|
||||
color:$base-font-color;
|
||||
}
|
||||
|
||||
//used throughout the "functions" section to render titles in the base code font family
|
||||
.functions {
|
||||
font-family: $code-font-family;
|
||||
|
||||
@@ -28,6 +28,7 @@ a {
|
||||
a.tooltip {
|
||||
position: relative;
|
||||
overflow: visible;
|
||||
font-family:$base-font-family;
|
||||
&:hover::before {
|
||||
display: inline-block;
|
||||
position: absolute;
|
||||
@@ -35,7 +36,6 @@ a.tooltip {
|
||||
bottom: -1.4em;
|
||||
font-size: 12px;
|
||||
color: white;
|
||||
font-family: 'fontello';
|
||||
min-width: 80px;
|
||||
padding: .25em .33em;
|
||||
background-color: $base-font-color;
|
||||
@@ -71,6 +71,7 @@ a.tooltip {
|
||||
}
|
||||
&::before {
|
||||
padding-right: 1.5em;
|
||||
font-family:$base-font-family;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user