Minor Docs Tweaks

This commit is contained in:
spf13 2014-02-18 18:35:03 -05:00
parent 8008675983
commit bf6407759b
3 changed files with 110 additions and 44 deletions

View file

@ -20,16 +20,16 @@ templates that the new type will use.
It is essential to provide the single render view template as well as a It is essential to provide the single render view template as well as a
list view template. list view template.
### Step 1: ### Step 1: Create Type Directory
Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*. Create a directory with the name of the type in layouts.Type is always singular. *Eg /layouts/post*.
### Step 2: ### Step 2: Create template
Create a file called single.html inside your directory. *Eg /layouts/post/single.html*. Create a file called single.html inside your directory. *Eg /layouts/post/single.html*.
### Step 3: ### Step 3: Create list template
Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/indexes/post.html*. Create a file with the same name as your directory in /layouts/indexes/. *Eg /layouts/indexes/post.html*.
### Step 4: ### Step 4: Create views
Many sites support rendering content in a few different ways, for Many sites support rendering content in a few different ways, for
instance a single page view and a summary view to be used when displaying a list instance a single page view and a summary view to be used when displaying a list
of contents on a single page. Hugo makes no assumptions here about how you want of contents on a single page. Hugo makes no assumptions here about how you want

View file

@ -6,53 +6,118 @@ groups: ["extras"]
groups_weight: 10 groups_weight: 10
--- ---
Because Hugo uses markdown for its simple content format, however there's a lot of things that Because Hugo uses markdown for its simple content format, however there's a lot
markdown doesn't support well. of things that markdown doesn't support well.
We are unwilling to accept being constrained by our simple format. Also unacceptable is writing raw We are unwilling to accept being constrained by our simple format. Also
html in our markdown every time we want to include unsupported content such as a video. To do unacceptable is writing raw html in our markdown every time we want to include
so is in complete opposition to the intent of using a bare bones format for our content and unsupported content such as a video. To do so is in complete opposition to the
utilizing templates to apply styling for display. intent of using a bare bones format for our content and utilizing templates to
apply styling for display.
To avoid both of these limitations Hugo created shortcodes. To avoid both of these limitations Hugo created shortcodes.
## What is a shortcode? A shortcode is a simple snippet inside a markdown file that Hugo will render
A shortcode is a simple snippet inside a markdown file that Hugo will render using a predefined template. using a predefined template.
An example of a shortcode would be `{{% video http://urlToVideo %}}` ## Using a shortcode
Shortcodes are created by placing a template file in `layouts/shortcodes/`. The
name of the file becomes the name of the shortcode (without the extension).
In your content files a shortcode can be called by using '{{% name parameters In your content files a shortcode can be called by using '{{% name parameters
%}}' respectively. Shortcodes are space delimited (parameters with spaces %}}' respectively. Shortcodes are space delimited (parameters with spaces
can be quoted). can be quoted).
The first word is always the name of the shortcode. Following The first word is always the name of the shortcode. Parameters follow the name.
the name are the parameters. The format for named parameters models that of html with the format
name="value". The current implementation only supports this exact format. Extra
spaces or different quote marks will not parse properly.
The author of the shortcode can choose if the short code will use positional Some shortcodes use or require closing shortcodes. Like HTML, the opening and closing
parameters or named parameters (but not both). A good rule of thumb is that if shortcodes match (name only), the closing being prepended with a slash.
a short code has a single required value in the case of the youtube example
below then positional works very well. For more complex layouts with optional Example of a paired shortcode:
{{% highlight go %}} A bunch of code here {{% /highlight %}}
## Hugo Shortcodes
Hugo ships with a set of predefined shortcodes.
### highlight
This shortcode will convert the source code provided into syntax highlighted
html. Read more on [highlighting](/extras/highlighting).
#### Usage
Highlight takes exactly one required parameter of language and requires a
closing shortcode.
#### Example
{{% highlight html %}}
{{% highlight html %}}
<section id="main">
<div>
<h1 id="title">{{ .Title }}</h1>
{{ range .Data.Pages }}
{{ .Render "summary"}}
{{ end }}
</div>
</section>
{{&#37; /highlight %}}
{{% /highlight %}}
#### Example Output
{{% highlight html %}}
<span style="color: #f92672">&lt;section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;main&quot;</span><span style="color: #f92672">&gt;</span>
<span style="color: #f92672">&lt;div&gt;</span>
<span style="color: #f92672">&lt;h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">&quot;title&quot;</span><span style="color: #f92672">&gt;</span>{{ .Title }}<span style="color: #f92672">&lt;/h1&gt;</span>
{{ range .Data.Pages }}
{{ .Render &quot;summary&quot;}}
{{ end }}
<span style="color: #f92672">&lt;/div&gt;</span>
<span style="color: #f92672">&lt;/section&gt;</span>
{{% /highlight %}}
### figure
Figure is simply an extension of the image capabilities present with Markdown.
figure provides the ability to add captions, css classes, alt text, links etc.
#### Usage
figure can use the following parameters
* src
* link
* title
* caption
* attr (attribution)
* attrlink
* alt
#### Example
{{% highlight html %}}
{{&#37; figure src="/media/spf13.jpg" title="Steve Francia" %}}
{{% /highlight %}}
#### Example output
{{% highlight html %}}
{{% /highlight %}}
## Creating your own shortcodes
To create a shortcode, place a template in the layouts/shortcodes directory. The
template name will be the name of the shortcode.
In creating a shortcode you can choose if the short code will use positional
parameters or named parameters (but not both). A good rule of thumb is that if a
short code has a single required value in the case of the youtube example below
then positional works very well. For more complex layouts with optional
parameters named parameters work best. parameters named parameters work best.
The format for named parameters models that of html with the format name="value"
Lastly like HTML, shortcodes can be singular or paired. An example of a paired
shortcode would be:
{{% code_highlight %}} A bunch of code here {{% /code_highlight %}}
Shortcodes are paired with an opening shortcode identical to a single shortcode
and a closing shortcode.
## Creating a shortcode
All that you need to do to create a shortcode is place a template in the layouts/shortcodes directory.
The template name will be the name of the shortcode.
**Inside the template** **Inside the template**
To access a parameter by either position or name the index method can be used. To access a parameter by either position or name the index method can be used.
@ -65,9 +130,10 @@ To check if a parameter has been provided use the isset method provided by Hugo.
{{ if isset .Params "class"}} class="{{ index .Params "class"}}" {{ end }} {{ if isset .Params "class"}} class="{{ index .Params "class"}}" {{ end }}
For paired shortcodes the variable .Inner is available which contains all of If a closing shortcode is used, the variable .Inner will be populated with all
the content between the opening and closing shortcodes. **Simply using this of the content between the opening and closing shortcodes. If a closing
variable is the only difference between single and paired shortcodes.** shortcode is required, you can check the length of .Inner and provide a warning
to the user.
## Single Positional Example: youtube ## Single Positional Example: youtube
@ -110,7 +176,7 @@ Would load the template /layouts/shortcodes/img.html
{{ if isset .Params "attrlink"}}<a href="{{ index .Params "attrlink"}}"> {{ end }} {{ if isset .Params "attrlink"}}<a href="{{ index .Params "attrlink"}}"> {{ end }}
{{ index .Params "attr" }} {{ index .Params "attr" }}
{{ if isset .Params "attrlink"}}</a> {{ end }} {{ if isset .Params "attrlink"}}</a> {{ end }}
</p> {{ end }} </p> {{ end }}
</figcaption> </figcaption>
{{ end }} {{ end }}
</figure> </figure>

View file

@ -1,5 +1,5 @@
--- ---
title: "Templates" title: "Hugo Templates"
date: "2013-07-01" date: "2013-07-01"
aliases: ["/doc/templates/"] aliases: ["/doc/templates/"]
linktitle: "Overview" linktitle: "Overview"