diff --git a/docs/content/content/types.md b/docs/content/content/types.md index 0011a577a..adc7919f4 100644 --- a/docs/content/content/types.md +++ b/docs/content/content/types.md @@ -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 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*. -### Step 2: +### Step 2: Create template 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*. -### Step 4: +### Step 4: Create views 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 of contents on a single page. Hugo makes no assumptions here about how you want diff --git a/docs/content/extras/shortcodes.md b/docs/content/extras/shortcodes.md index ed7384d9f..dee8d12da 100644 --- a/docs/content/extras/shortcodes.md +++ b/docs/content/extras/shortcodes.md @@ -6,53 +6,118 @@ groups: ["extras"] groups_weight: 10 --- -Because Hugo uses markdown for its simple content format, however there's a lot of things that -markdown doesn't support well. +Because Hugo uses markdown for its simple content format, however there's a lot +of things that markdown doesn't support well. -We are unwilling to accept being constrained by our simple format. Also unacceptable is writing raw -html in our markdown every time we want to include unsupported content such as a video. To do -so is in complete opposition to the intent of using a bare bones format for our content and -utilizing templates to apply styling for display. +We are unwilling to accept being constrained by our simple format. Also +unacceptable is writing raw html in our markdown every time we want to include +unsupported content such as a video. To do so is in complete opposition to the +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. -## What is a shortcode? -A shortcode is a simple snippet inside a markdown file that Hugo will render using a predefined template. +A shortcode is a simple snippet inside a markdown file that Hugo will render +using a predefined template. -An example of a shortcode would be `{{% video http://urlToVideo %}}` - -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). +## Using a shortcode In your content files a shortcode can be called by using '{{% name parameters %}}' 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 name are the parameters. +The first word is always the name of the shortcode. Parameters follow the name. +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 -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 +Some shortcodes use or require closing shortcodes. Like HTML, the opening and closing +shortcodes match (name only), the closing being prepended with a slash. + +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 %}} +
+
+

{{ .Title }}

+ {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
+
+ {{% /highlight %}} +{{% /highlight %}} + + +#### Example Output + +{{% highlight html %}} + <section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} + </div> + </section> +{{% /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 %}} + {{% 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. -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** 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 }} -For paired shortcodes the variable .Inner is available which contains all of -the content between the opening and closing shortcodes. **Simply using this -variable is the only difference between single and paired shortcodes.** +If a closing shortcode is used, the variable .Inner will be populated with all +of the content between the opening and closing shortcodes. If a closing +shortcode is required, you can check the length of .Inner and provide a warning +to the user. ## Single Positional Example: youtube @@ -110,7 +176,7 @@ Would load the template /layouts/shortcodes/img.html {{ if isset .Params "attrlink"}} {{ end }} {{ index .Params "attr" }} {{ if isset .Params "attrlink"}} {{ end }} -

{{ end }} +

{{ end }} {{ end }} diff --git a/docs/content/layout/templates.md b/docs/content/layout/templates.md index 400e429b9..1c563e486 100644 --- a/docs/content/layout/templates.md +++ b/docs/content/layout/templates.md @@ -1,5 +1,5 @@ --- -title: "Templates" +title: "Hugo Templates" date: "2013-07-01" aliases: ["/doc/templates/"] linktitle: "Overview"