Fix spacing on section list pages

content/contribute-to-hugo/contribute-to-the-hugo-docs.md

@@ -15,7 +15,7 @@ toc: true
 needsreview: true
 ---
 
-Documentation is an integral part 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.
+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
 
@@ -25,9 +25,9 @@ Documentation is an integral part of any open source project. The Hugo docs were
 
 **IN DEVELOPMENT** -->
 
-## Creating New Content for the Hugo Docs
+## Adding a New Content Pages
 
-**IN DEVELOPMENT**
+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
@@ -41,11 +41,13 @@ Documentation is an integral part of any open source project. The Hugo docs were
 
 **IN DEVELOPMENT**
 
-## Code Block Shortcode Examples
+## Adding Code Blocks to Hugo Docs
+
+### Code Block Shortcodes
 
 **IN DEVELOPMENT**
 
-### Input Code Block
+### Code Block
 
 **IN DEVELOPMENT**
 
@@ -56,7 +58,6 @@ Documentation is an integral part of any open source project. The Hugo docs were
 ## Blockquotes
 
 
-
 ## Admonition Short Codes
 
 **Admonitions** are common directives in technical documentation. The most popular is that seen in [reStructuredTex Directives][sourceforge]. From the SourceForge documentation:
@@ -148,6 +149,10 @@ The Hugo docs are not especially prescriptive in terms of grammar and usage. We
 2. *Homepage* is one word.
 3. Be sure to add a `godocref` whenever possible to a new content file's front matter. We want to promote Hugo *and* Golang by demonstrating the inseparable wedding of the two.
 
+## Pages Needing Code Examples
+
+{{< needsexamples >}}
+
 ## How Content is Ordered in the Docs
 
 **IN DEVELOPMENT**
@@ -158,5 +163,7 @@ Use aliases sparingly. The following table shows a list of all the aliases used
 
 {{< allaliases >}}
 
+[archsource]: https://github.com/spf13/hugo/tree/master/docs/archetypes
+[archetype]: /content-management/archetypes/
 [shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown
 [sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions

content/functions/absLangURL.md

@@ -16,6 +16,7 @@ relatedfuncs: []
 deprecated: false
 draft: false
 aliases: []
+needsexamples: true
 ---
 
 ## Example

content/functions/default.md

@@ -17,6 +17,7 @@ relatedfuncs: []
 deprecated: false
 draft: false
 aliases: [/functions/default/]
+needsexamples: false
 ---
 
 Checks whether a given value is set and returns a default value if it is not. *Set* in this context means different things depending on date type:

content/functions/dict.md

@@ -17,5 +17,37 @@ relatedfuncs: []
 deprecated: false
 draft: false
 aliases: []
+needsexamples: true
 ---
 
+Creates a dictionary `(map[string, interface{})`, expects parameters added in value:object fasion.
+Invalid combinations like keys that are not strings or uneven number of parameters, will result in an exception thrown.
+Useful for passing maps to partials when adding to a template.
+
+e.g. Pass into "foo.html" a map with the keys "important, content"
+
+{{% code file="dict-example.html" %}}
+```html
+{{$important := .Site.Params.SomethingImportant }}
+{{range .Site.Params.Bar}}
+    {{partial "foo" (dict "content" . "important" $important)}}
+{{end}}
+```
+{{% /code %}}
+
+And then in `foo.html`:
+
+```golang
+Important {{.important}}
+{{.content}}
+```
+
+`dict` also allows you to create a map on the fly to pass into
+
+{{% code file="dict-create-map.html" %}}
+```golang
+{{partial "foo" (dict "important" "Smiles" "content" "You should do more")}}
+```
+{{% /code %}}
+
+

content/functions/shuffle.md

@@ -17,9 +17,27 @@ relatedfuncs: []
 deprecated: false
 draft: false
 aliases: []
+needsexamples: true
 ---
 
-## Example
+### shuffle
 
-## Advanced Example
+`shuffle` returns a random permutation of a given array or slice:
 
+{{% code file="shuffle-input.html" %}}
+```html
+<div class="shuffle-sequence">{{ shuffle (seq 1 5) }}</div>
+<div class="shuffle-slice">{{ shuffle (slice "foo" "bar" "buzz") }}</div>
+```
+{{% /code %}}
+
+This example would return the following:
+
+{{% output file="shuffle-output.html" %}}
+```html
+<div class="shuffle-seq">2 5 3 1 4</div>
+<div class="shuffle-slice">buzz foo bar</div>
+```
+{{% /output %}}
+
+This example also makes use of the [slice](/functions/slice/) and [seq](/functions/seq/) functions.

content/functions/slice.md

@@ -6,9 +6,8 @@ godocref:
 date: 2017-02-01
 publishdate: 2017-02-01
 lastmod: 2017-02-01
-tags: []
 categories: [functions]
-toc:
+tags: [slice, array, interface]
 signature:
 workson: []
 hugoversion:
@@ -16,9 +15,20 @@ relatedfuncs: []
 deprecated: false
 draft: false
 aliases: []
+toc: false
+needsexamples: true
 ---
 
-## Example
+`slice` allows you to create an array (`[]interface{}`) of all arguments that you pass to this function.
 
-## Advanced Example
+One use case is the concatenation of elements in combination with the [`delimit` function][]:
 
+{{% code "slice.html" %}}
+```html
+{{ delimit (slice "foo" "bar" "buzz") ", " }}
+<!-- returns the string "foo, bar, buzz" -->
+```
+{{% /code %}}
+
+
+[`delimit` function]: /functions/delimit/

content/templates/lists.md

@@ -1,6 +1,6 @@
 ---
 title: Introduction to Lists in Hugo
-linktitle: Hugo Lists Introduction
+linktitle: Hugo Lists
 description: Lists have a specific meaning and usage in Hugo. If you want to know how to render your site homepage, section homepage, taxonomy list, or taxonomy terms list, start here.
 date: 2017-02-01
 publishdate: 2017-02-01
@@ -50,7 +50,7 @@ In order to take advantage of this behaviour you need to do a few things.
 
 3. Ensure that the respective template is configured to display `{{ .Content }}` if you wish for the content of the \_index.md file to be rendered on the respective page.
 
-### How \_index.md pages work
+### How \_index.md Pages Work
 
 Before continuing it's important to know that this page must reference certain templates to describe how the \_index.md page will be rendered. Hugo has a multitude of possible templates that can be used and placed in various places (think theme templates for instance). For simplicity/brevity the default/top level template location will be used to refer to the entire range of places the template can be placed.
 

content/templates/ordering-and-grouping-lists.md

@@ -1,6 +1,6 @@
 ---
 title: Ordering and Grouping Lists
-linktitle: Rendering Lists
+linktitle: Rendering Hugo Lists
 description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site, but
 date: 2017-02-01
 publishdate: 2017-02-01
@@ -334,7 +334,7 @@ within each group in alphabetical order by title.
 {{ end }}
 ```
 
-## Filtering & Limiting Content
+## Filtering and Limiting Content
 
 Sometimes you only want to list a subset of the available content. A common
 request is to only display “Posts” on the homepage. Using the `where` function,

layouts/shortcodes/needsexamples.html

@@ -0,0 +1,7 @@
+<ul class="utils-list">
+	{{range where .Site.Pages "Section" "functions"}}
+	{{ if .Params.needsexamples }}
+	<li><a href="{{.Permalink}}">{{.Title}}</a></li>
+	{{ end }}
+	{{ end }}
+</ul>

themes/hugodocs/layouts/_default/section.html

@@ -1,17 +1,19 @@
 {{ define "main" }}
 {{$title := .Title}}
 <main class="main">
-	<header class="content-header">
-		{{partial "breadcrumb.html" . }}
-		<h1 class="page-title {{if eq .Kind "page"}}{{.Section}}{{end}}" id="{{ .Title | urlize }}">
-		{{- partial "list-icon.html" . -}}
-		{{- .Title | markdownify -}}</h1>
-		{{partial "content-header-links.html" . }}
-		{{partial "tags.html" . }}
-	</header>
-	<div class="body-copy">
-	{{.Content}}
-	{{partial "contents-list.html" .}}
+	<div class="content">
+		<header class="content-header">
+			{{partial "breadcrumb.html" . }}
+			<h1 class="page-title {{if eq .Kind "page"}}{{.Section}}{{end}}" id="{{ .Title | urlize }}">
+			{{- partial "list-icon.html" . -}}
+			{{- .Title | markdownify -}}</h1>
+			{{partial "content-header-links.html" . }}
+			{{partial "tags.html" . }}
+		</header>
+		<div class="body-copy">
+		{{.Content}}
+		{{partial "contents-list.html" .}}
+		</div>
 	</div>
 	{{partial "content-footer.html" . }}
 	{{partial "table-of-contents.html" . }}

themes/hugodocs/layouts/partials/contents-list.html

@@ -4,13 +4,13 @@
 <h2 id="contents" class="contents-list-heading section-heading">Contents:</h2>
 {{end}}
 {{range .Data.Pages}}
-<!-- if statement checks for sitelink, which includes the Hugo themes site link in the nav and *every* showcase site (ie, /content/showcase/*.md) -->
+<!-- if statement checks for sitelink. sitelink: is a field in front matter of /content/showcase/*.md) -->
 <a {{with .Params.sitelink }}href="{{.}} "target="_blank"{{else}}href="{{.Permalink}}"{{end}}>
-<article class="contents-list {{$kind}}">
-	<header>
-		<h3 class="list-icon {{.Section}}">{{- partial "list-icon.html" . -}}{{with .LinkTitle}}{{. | markdownify}}{{else}}{{.Title | markdownify}}{{end}}{{with .Params.sitelink }}&nbsp;<i class="fa fa-external-link" aria-hidden="true"></i>{{end}}</h3>
-	</header>
-	<p>{{.Description | markdownify }}</p>
-</article>
+	<section class="contents-list {{$kind}}">
+		<header>
+			<h3 class="list-icon {{.Section}}">{{- partial "list-icon.html" . -}}{{with .LinkTitle}}{{. | markdownify}}{{else}}{{.Title | markdownify}}{{end}}{{with .Params.sitelink }}&nbsp;<i class="fa fa-external-link" aria-hidden="true"></i>{{end}}</h3>
+		</header>
+		<p>{{.Description | markdownify }}</p>
+	</section>
 </a>
 {{end}}

themes/hugodocs/pipeline/scss/components/_lists.scss

@@ -71,7 +71,7 @@ aside {
     margin-bottom: 1em;
     font-size: 1em;
     clear: both;
-    line-height:1.6;
+    line-height: 1.6;
     padding: {
       top: .5em;
       bottom: .5em;
@@ -89,7 +89,7 @@ aside {
       margin: .5em 0em 0em 0em;
       text-indent: 0px;
       height: auto;
-      font-size:.9em;
+      font-size: .9em;
       padding: {
         top: .25em;
         bottom: 0em;
@@ -99,3 +99,18 @@ aside {
     }
   }
 }
+
+//For example, used in the "Pages Needing Code Examples" section of "Contribute to the Hugo docs"
+.body-copy {
+  .utils-list {
+    list-style: none;
+    margin-left: 0px;
+    padding-left: 0px;
+    li {
+      list-style: none;
+      display: inline;
+      margin-left: 0px;
+      padding-left: 0px;
+    }
+  }
+}

themes/hugodocs/pipeline/scss/layout/_site-content.scss

@@ -37,7 +37,7 @@ main.main {
   }
 }
 
-article.content {
+.content {
   width: 90%;
   margin-left: auto;
   margin-right: auto;