Minor Docs Tweaks - hugo - [fork] hugo port for 9front
HTML git clone git@git.drkhsh.at/hugo.git
DIR Log
DIR Files
DIR Refs
DIR Submodules
DIR README
DIR LICENSE
---
DIR commit bf6407759b68490ffaa29c59e71ce17f031faaec
DIR parent 8008675983a8fc592a4994de09552edcb3a53252
HTML Author: spf13 <steve.francia@gmail.com>
Date: Tue, 18 Feb 2014 18:35:03 -0500
Minor Docs Tweaks
Diffstat:
M docs/content/content/types.md | 8 ++++----
M docs/content/extras/shortcodes.md | 132 +++++++++++++++++++++++--------
M docs/content/layout/templates.md | 2 +-
3 files changed, 104 insertions(+), 38 deletions(-)
---
DIR diff --git 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
DIR diff --git a/docs/content/extras/shortcodes.md b/docs/content/extras/shortcodes.md
@@ -6,52 +6,117 @@ 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
-parameters named parameters work best.
+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.
-The format for named parameters models that of html with the format name="value"
+### highlight
-Lastly like HTML, shortcodes can be singular or paired. An example of a paired
-shortcode would be:
+This shortcode will convert the source code provided into syntax highlighted
+html. Read more on [highlighting](/extras/highlighting).
- {{% code_highlight %}} A bunch of code here {{% /code_highlight %}}
+#### Usage
+Highlight takes exactly one required parameter of language and requires a
+closing shortcode.
-Shortcodes are paired with an opening shortcode identical to a single shortcode
-and 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>
+ {{% /highlight %}}
+{{% /highlight %}}
+
+
+#### Example Output
+
+{{% highlight html %}}
+ <span style="color: #f92672"><section</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"main"</span><span style="color: #f92672">></span>
+ <span style="color: #f92672"><div></span>
+ <span style="color: #f92672"><h1</span> <span style="color: #a6e22e">id=</span><span style="color: #e6db74">"title"</span><span style="color: #f92672">></span>{{ .Title }}<span style="color: #f92672"></h1></span>
+ {{ range .Data.Pages }}
+ {{ .Render "summary"}}
+ {{ end }}
+ <span style="color: #f92672"></div></span>
+ <span style="color: #f92672"></section></span>
+{{% /highlight %}}
-## Creating a shortcode
+### 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.
-All that you need to do to create a shortcode is place a template in the layouts/shortcodes directory.
+#### Usage
-The template name will be the name of the shortcode.
+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.
**Inside the template**
@@ -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"}}<a href="{{ index .Params "attrlink"}}"> {{ end }}
{{ index .Params "attr" }}
{{ if isset .Params "attrlink"}}</a> {{ end }}
- </p> {{ end }}
+ </p> {{ end }}
</figcaption>
{{ end }}
</figure>
DIR diff --git 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"