From c0a626b6851f1f0cb231874977be132f0250e354 Mon Sep 17 00:00:00 2001 From: Ryan Watters Date: Sat, 25 Feb 2017 21:40:13 -0600 Subject: [PATCH] Add first round of functions --- .gitignore | 1 + README.md | 2 +- content/about-hugo/roadmap.md | 6 +- content/concept.md | 41 +++-- .../content-organization.md | 114 +++++++++++- .../content-management/content-summaries.md | 2 +- .../content-management/cross-references.md | 91 ++++++---- content/content-management/sections.md | 2 +- content/content-management/shortcodes.md | 5 +- content/content-management/url-management.md | 102 +++++------ .../_index.md | 0 .../add-your-site-to-the-showcase.md | 2 +- .../contribute-to-hugo-development.md | 12 +- .../contribute-to-the-hugo-docs.md | 2 + content/functions/GetPage.md | 14 +- content/functions/absURL.md | 24 --- .../functions/abslangurl-and-rellangurl.md | 27 +++ content/functions/absurl-and-relurl.md | 53 ++++++ content/functions/apply.md | 107 ++++++++++- content/functions/base64.md | 53 ++++++ content/functions/base64Decode.md | 24 --- content/functions/base64Encode.md | 24 --- .../functions/countrunes-and-countwords.md | 34 ++++ content/functions/countrunes.md | 23 --- content/functions/dateformat.md | 10 +- content/functions/i18n.md | 15 +- content/functions/{absLangURL.md => now.md} | 14 +- content/functions/partialCached.md | 23 ++- content/functions/querify.md | 25 ++- content/functions/readFile.md | 24 --- .../{readDir.md => readdir-and-readfile.md} | 10 +- content/functions/ref-and-relref.md | 27 +++ content/functions/relLangURL.md | 24 --- content/functions/relURL.md | 24 --- content/functions/relref.md | 24 --- content/functions/render.md | 11 +- content/functions/safeURL.md | 69 +++++++- content/functions/scratch.md | 3 +- content/functions/sha.md | 31 ++++ content/functions/sha1.md | 25 --- content/functions/sha256.md | 24 --- content/functions/time.md | 15 +- content/functions/urlize.md | 65 +++++-- content/getting-started/configuration.md | 15 +- content/getting-started/quick-start.md | 49 +---- .../getting-started/using-the-hugo-docs.md | 2 +- content/showcase/_index.md | 2 +- .../templates/base-templates-and-blocks.md | 54 +++--- content/templates/content-view-templates.md | 167 ++++++++++-------- content/templates/data-templates.md | 21 ++- content/templates/go-template-primer.md | 24 +-- ...d-grouping-lists.md => lists-rendering.md} | 2 +- content/templates/lists.md | 130 ++------------ content/templates/local-file-templates.md | 15 +- content/templates/lookup-order.md | 46 +++++ content/templates/rss-templates.md | 10 +- content/templates/section-templates.md | 22 +-- content/templates/single-page-templates.md | 38 ++-- content/templates/taxonomy-templates.md | 22 ++- content/themes/customizing-a-theme.md | 4 +- content/themes/installing-and-using-themes.md | 2 +- .../_index.md | 4 +- .../file-variables.md | 0 .../other-variables.md | 0 .../page-variables.md | 0 .../site-variables.md | 0 .../taxonomy-variables.md | 0 data/sitenavigation.yml | 4 +- ...and-params.afdesign => variables.afdesign} | Bin layouts/shortcodes/code.html | 4 +- layouts/shortcodes/readfile.html | 2 +- readfile-content/lookupexplanation.md | 2 +- static/css/style.min.css | 2 +- .../accept-cla.png | Bin .../ci-errors.png | Bin .../copy-remote-url.png | Bin .../forking-a-repository.png | Bin .../open-pull-request.png | Bin ...{contribute-to-hugo.svg => contribute.svg} | 0 ...variables-and-params.svg => variables.svg} | 0 themes/hugodocs/layouts/_default/single.html | 7 +- .../hugodocs/layouts/_default/taxonomy.html | 12 +- themes/hugodocs/layouts/_default/terms.html | 48 ++--- .../layouts/partials/content-footer.html | 6 +- .../partials/head/metadata-standard.html | 7 +- .../layouts/partials/site-footer.html | 45 +++-- .../layouts/partials/table-of-contents.html | 3 +- .../hugodocs/layouts/section/functions.html | 2 + .../pipeline/scss/base/_typography.scss | 30 +++- .../scss/components/_content-footer.scss | 2 +- .../pipeline/scss/layout/_site-content.scss | 11 ++ .../scss/layout/_site-navigation.scss | 7 + 92 files changed, 1207 insertions(+), 844 deletions(-) rename content/{contribute-to-hugo => contribute}/_index.md (100%) rename content/{contribute-to-hugo => contribute}/add-your-site-to-the-showcase.md (93%) rename content/{contribute-to-hugo => contribute}/contribute-to-hugo-development.md (96%) rename content/{contribute-to-hugo => contribute}/contribute-to-the-hugo-docs.md (99%) delete mode 100644 content/functions/absURL.md create mode 100644 content/functions/abslangurl-and-rellangurl.md create mode 100644 content/functions/absurl-and-relurl.md create mode 100644 content/functions/base64.md delete mode 100644 content/functions/base64Decode.md delete mode 100644 content/functions/base64Encode.md create mode 100644 content/functions/countrunes-and-countwords.md delete mode 100644 content/functions/countrunes.md rename content/functions/{absLangURL.md => now.md} (55%) delete mode 100644 content/functions/readFile.md rename content/functions/{readDir.md => readdir-and-readfile.md} (72%) create mode 100644 content/functions/ref-and-relref.md delete mode 100644 content/functions/relLangURL.md delete mode 100644 content/functions/relURL.md delete mode 100644 content/functions/relref.md create mode 100644 content/functions/sha.md delete mode 100644 content/functions/sha1.md delete mode 100644 content/functions/sha256.md rename content/templates/{ordering-and-grouping-lists.md => lists-rendering.md} (99%) create mode 100644 content/templates/lookup-order.md rename content/{variables-and-params => variables}/_index.md (92%) rename content/{variables-and-params => variables}/file-variables.md (100%) rename content/{variables-and-params => variables}/other-variables.md (100%) rename content/{variables-and-params => variables}/page-variables.md (100%) rename content/{variables-and-params => variables}/site-variables.md (100%) rename content/{variables-and-params => variables}/taxonomy-variables.md (100%) rename dev-and-design-resources/{variables-and-params.afdesign => variables.afdesign} (100%) rename static/images/{contribute-to-hugo => contribute}/contribute-to-hugo-development/accept-cla.png (100%) rename static/images/{contribute-to-hugo => contribute}/contribute-to-hugo-development/ci-errors.png (100%) rename static/images/{contribute-to-hugo => contribute}/contribute-to-hugo-development/copy-remote-url.png (100%) rename static/images/{contribute-to-hugo => contribute}/contribute-to-hugo-development/forking-a-repository.png (100%) rename static/images/{contribute-to-hugo => contribute}/contribute-to-hugo-development/open-pull-request.png (100%) rename static/images/hugo-icons/{contribute-to-hugo.svg => contribute.svg} (100%) rename static/images/hugo-icons/{variables-and-params.svg => variables.svg} (100%) diff --git a/.gitignore b/.gitignore index 707e6858d..b31591375 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ themes/hugodocs/pipeline/node_modules ryans-notes.md notes-for-reviewers.md functions-page.md +specific-reviewers.md diff --git a/README.md b/README.md index b44570d66..f459b3b49 100644 --- a/README.md +++ b/README.md @@ -8,4 +8,4 @@ ## Contributing to the Docs -(WIP) See the guide at for instructions on how to contribute to the documentation. \ No newline at end of file +(WIP) See the guide at for instructions on how to contribute to the documentation. \ No newline at end of file diff --git a/content/about-hugo/roadmap.md b/content/about-hugo/roadmap.md index 3bac4e491..f2f889fb8 100644 --- a/content/about-hugo/roadmap.md +++ b/content/about-hugo/roadmap.md @@ -33,12 +33,12 @@ Feel free to [contribute to Hugo's development][devcontribute], [improve Hugo's [#1014]: https://github.com/spf13/hugo/issues/1014 [#1435]: https://github.com/spf13/hugo/issues/1435 [#1436]: https://github.com/spf13/hugo/issues/1436 -[devcontribute]: /contribute-to-hugo/contribute-to-hugo-development/ -[doccontribute]: /contribute-to-hugo/contribute-to-the-hugo-docs/ +[devcontribute]: /contribute/contribute-to-hugo-development/ +[doccontribute]: /contribute/contribute-to-the-hugo-docs/ [hosting and deployment]: /hosting-and-deployment/ [migrate]: /developer-tools/migrate-to-hugo/ [newissue]: https://github.com/spf13/hugo/issues/ [related Discuss thread]: https://discuss.gohugo.io/t/web-based-editor/155 [themes]: /themes/ [tutorials]: /tutorials -[***your*** best ideas!]: /contribute-to-hugo/ \ No newline at end of file +[***your*** best ideas!]: /contribute/ \ No newline at end of file diff --git a/content/concept.md b/content/concept.md index 5d2235de0..685c80e2f 100644 --- a/content/concept.md +++ b/content/concept.md @@ -16,7 +16,7 @@ toc: true ## Strategy, Tactics, and Requirements {{% warning "Disclaimer" %}} -WIP. Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *very schlocky* version of the content strategy document. +WIP. Before any of my fellow content strategists banish me to content strategy hell, know that I *know* this is a *schlocky* version of a true strategic document. {{% /warning %}} ### Introduction @@ -115,12 +115,18 @@ The following are high-level requirements for the documentation site. - [X] Semantic HTML5 elements (e.g., `article`, `main`, `aside`, `dl`) - [X] SSL - [ ] AMP? +- [ ] 301s [^1] + +#### Accessibility + +- [ ] Aria roles +- [ ] Alt text for all images #### Editorial and Content - [ ] Basic style guide - The style guide should facilitate a more consistent UX for the site but not be so complex as to deter documentation contributors -- [X] Contribution guidelines (see [WIP on live site](https://hugodocsconcept.netlify.com/contribute-to-hugo/contribute-to-the-hugo-docs/)) +- [X] Contribution guidelines (see [WIP on live site](https://hugodocsconcept.netlify.com/contribute/contribute-to-the-hugo-docs/)) - [X] Standardized content types (see [WIP archetypes in source](https://github.com/rdwatters/hugo-docs-concept/tree/master/themes/hugodocs/archetypes) - [X] New content model, including taxonomies ([see tags page][tagspage]) - [ ] DRY. New shortcodes for repeat content (e.g., lists of aliases, page variables, site variables, and others) @@ -140,7 +146,7 @@ The following are high-level requirements for the documentation site. - [X] Copyable code blocks (via highlight.js, extended for hugo-specific keywords) - [X] Dual in-page navigation (i.e. site nav *and* in-page TOC) - [X] Smooth scrolling -- [X] [RTD-style admonitions][admonitions] (see [example admonition shortcode](https://github.com/rdwatters/hugo-docs-concept/blob/master/layouts/shortcodes/note.html) and [examples on published site](http://localhost:1313/contribute-to-hugo/contribute-to-the-hugo-docs/#admonition-short-codes)) +- [X] [RTD-style admonitions][admonitions] (see [example admonition shortcode](https://github.com/rdwatters/hugo-docs-concept/blob/master/layouts/shortcodes/note.html) and [examples on published site](/contribute/contribute-to-the-hugo-docs/#admonition-short-codes)) - [ ] Share buttons: Reddit, Twitter, LinkedIn, and "Copy Page Url"; the last of these provides the strongest utility for docs references in the Hugo forums ## Author Experience (AX) @@ -171,14 +177,7 @@ The following are high-level requirements for the documentation site. - [X] Abstracted color palette - [X] Abstracted typefaces (multiple open-source fonts available) -[admonitions]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions -[designresources]: https://github.com/rdwatters/hugo-docs-concept/tree/master/dev-and-design-resources -[forum]: https://discuss.gohugo.io -[ex1]: https://discuss.gohugo.io/t/frustrated-with-documentation/2810 -[ex2]: https://discuss.gohugo.io/t/documentation-restructure-and-design/1891 -[forum]: -[functionarchetype]: https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugodocs/archetypes/functions.md -[tagspage]: https://hugodocsconcept.netlify.com/tags/ + ## Content Changes @@ -344,11 +343,27 @@ Apache License - 60 **Ordered by title** -[Quick Start]: https://hugodocsconcept.netlify.com/getting-started/quick-start/ - ## Current Content (Source) ```markdown {{< readfile file="content/tree.txt" >}} ``` +## Proposed Schedule for Hugo Docs Release + + +1. **2017-02-26** Release to Gitter Channel for Review +2. **2017-03-01** Post in Discussion Forum for Feedback +3. **2017-??-??** Add to Hugo repo for release with v19 + +[^1]: As this point, the URL structure has changed considerably. I've been fastidious about adding aliases wherever possible, but I'm not sure what negative effect this approach is going to take with our current search relevancy. The [current list of aliases is quite large](/contribute/contribute-to-the-hugo-docs/#be-mindful-of-aliases). + + +[admonitions]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions +[designresources]: https://github.com/rdwatters/hugo-docs-concept/tree/master/dev-and-design-resources +[forum]: https://discuss.gohugo.io +[ex1]: https://discuss.gohugo.io/t/frustrated-with-documentation/2810 +[ex2]: https://discuss.gohugo.io/t/documentation-restructure-and-design/1891 +[functionarchetype]: https://github.com/rdwatters/hugo-docs-concept/blob/master/themes/hugodocs/archetypes/functions.md +[tagspage]: https://hugodocsconcept.netlify.com/tags/ +[Quick Start]: https://hugodocsconcept.netlify.com/getting-started/quick-start/ \ No newline at end of file diff --git a/content/content-management/content-organization.md b/content/content-management/content-organization.md index d278b4d6a..290aa9b15 100644 --- a/content/content-management/content-organization.md +++ b/content/content-management/content-organization.md @@ -16,11 +16,11 @@ needsreview: true ## Introduction -Hugo uses files (see [supported content formats][]) with headers called [front matter][]. By default, Hugo assumes the same structure that works to organize your content should be used to organize your rendered website. This is done in an effort to reduce configuration. However, this convention can be overridden through additional configuration in the front matter, as well as through Hugo's extensive features related to [URL management][]. +Hugo uses files (see [Supported Content Formats][]) with headers called [front matter][]. By default, Hugo assumes the same structure that works to organize your content should be used to organize your rendered website. This is done in an effort to reduce configuration. However, this convention can be overridden through additional configuration in the front matter, as well as through Hugo's extensive features related to [URL management][]. ## Organizing Source Content -In Hugo, the content should be organized in a manner that reflects the rendered website. Without any additional configuration, the following will just work. Hugo supports content nested at any level, but the top level (i.e. `content/*``) is special in Hugo and is considered the content [section](/content-management/sections/). +In Hugo, the content should be organized in a manner that reflects the rendered website. Without any additional configuration, the following will just work. Hugo supports content nested at any level, but the top level (i.e. `content/*``) is special in Hugo and is considered the content [section][]. ## Destinations @@ -141,6 +141,116 @@ http://spf13.com/extras/indexes/example * defined in front matter * overrides all the above +## \_index.md and 'Everything is a Page' + +As of version v0.18 Hugo now treats '[everything as a page](http://bepsays.com/en/2016/12/19/hugo-018/)'. This allows you to add content and front matter to any page, including list pages like [sections][sectiontemplates], [taxonomies][taxonomytemplates], [Taxonomy Terms pages](/templates/terms/) and even to potential 'special case' pages like the [Homepage](/templates/homepage/). + +In order to take advantage of this behaviour you need to do a few things. + +1. Create an \_index.md file that contains the front matter and content you would like to apply. + +2. Place the \_index.md file in the correct place in the [directory structure][]. + +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` Works + +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. + +If this is confusing or you are unfamiliar with Hugo's template hierarchy, visit the various template pages listed below. You may need to find the 'active' template responsible for any particular page on your own site by going through the template hierarchy and matching it to your particular setup/theme you are using. + +- [Homepage template](/templates/homepage/) +- [Content List templates](/templates/list/) +- [Single Content templates](/templates/content/) +- [Taxonomy Terms templates](/templates/terms/) + +Now that you've got a handle on templates lets recap some Hugo basics to understand how to use an \_index.md file with a List page. + +1. Sections and Taxonomies are 'List' pages, NOT single pages. +2. List pages are rendered using the template heirarchy found in the [Content - List Template](http://localhost:1313/templates/list/) docs. +3. The Homepage, though technically a List page, can have [it's own template](/templates/homepage/) at layouts/index.html rather than \_default/list.html. Many themes exploit this behaviour so you are likely to encounter this specific use case. +4. Taxonomy terms pages are 'lists of metadata' not lists of content, so [have their own templates](/templates/terms/). + +Let's put all this information together: + +> **\_index.md files used in List pages, Terms pages or the Homepage are NOT rendered as single pages or with Single Content templates.** + +> **All pages, including List pages, can have front matter and front matter can have markdown content - meaning \_index.md files are the way to _provide_ front matter and content to the respective List/Terms/Homepage.** + +Here are a couple of examples to make it clearer... + +``` +| \_index.md location | Page affected | Rendered by | +| ------------------- | ------------ | ----------- | +| /content/post/\_index.md | site.com/post/ | /layouts/section/post.html | +| /content/categories/hugo/\_index.md | site.com/categories/hugo/ | /layouts/taxonomy/hugo.html | +``` + +## Why `_index.md files are used` + +With a Single page such as a post it's possible to add the front matter and content directly into the .md page itself. With List/Terms/Homepages this is not possible so \_index.md files can be used to provide that front matter/content to them. + +## How to display content from \_index.md files + +From the information above it should follow that content within an \_index.md file won't be rendered in its own Single Page, instead it'll be made available to the respective list, terms, Homepage. + +To **_actually render that content_** you need to ensure that the relevant template responsible for rendering the List/Terms/Homepage contains (at least) `{{ .Content }}`. + +This is the way to actually display the content within the \_index.md file on the List/Terms/Homepage. + +A very simple example is shown in the following default section list page: + +{{% code file="layouts/_default/section.html" download="section.html" %}} +```html +{{ define "main" }} +
+ {{ .Content }} +
    + {{ range .Paginator.Pages }} +
  • {{.Title}} +
    + {{ partial "summary.html" . }} +
    +
    • + {{ end }} +
+ {{ partial "pagination.html" . }} +
+{{ end }} +``` +{{% /code %}} + +You can see `{{ .Content }}` just after the `
` element. For this particular example, the content of the \_index.md file will show before the main list of summaries. + +## Where to Organize `_index.md` Files + +To add content and front matter to the homepage, a section, a taxonomy or a taxonomy terms listing, add a markdown file with the base name \_index on the relevant place on the file system. + +```bash +└── content + ├── _index.md + ├── categories + │ ├── _index.md + │ └── photo + │ └── _index.md + ├── post + │ ├── _index.md + │ └── firstpost.md + └── tags + ├── _index.md + └── hugo + └── _index.md +``` + +In the above example, `_index.md, pages have been added to each section and taxonomy. + +An `_index.md` file has also been added in the top level 'content' directory. + +### Where to place `_index.md` for the Homepage Template + +Hugo themes are designed to use the 'content' directory as the root of the website, so adding an \_index.md file here (like has been done in the example above) is how you would add front matter/content to the homepage. + [front matter]: /content-management/front-matter/ +[section]: /content-management/section/ [supported content formats]: /content-management/supported-content-formats/ [URL management]: /content-management/url-management/ diff --git a/content/content-management/content-summaries.md b/content/content-management/content-summaries.md index 66160b747..098665a99 100644 --- a/content/content-management/content-summaries.md +++ b/content/content-management/content-summaries.md @@ -9,7 +9,7 @@ categories: [content management] tags: [summaries,abstracts,read more] weight: 90 draft: false -aliases: [/content/summaries/] +aliases: [/content/summaries/,/content-management/summaries] toc: true --- diff --git a/content/content-management/cross-references.md b/content/content-management/cross-references.md index 210b977fd..6c5dfe05c 100644 --- a/content/content-management/cross-references.md +++ b/content/content-management/cross-references.md @@ -1,7 +1,7 @@ --- title: Cross References linktitle: -description: +description: Hugo makes it easy to link documents together with the ref and relref shortcodes, which safely provide links to headings inside of your content, whether across documents or within a document. date: 2017-02-01 publishdate: 2017-02-01 lastmod: 2017-01-09 @@ -9,12 +9,11 @@ categories: [content management] tags: ["cross references","references", "anchors", "urls"] weight: 100 draft: false -aliases: [] +aliases: [/extras/crossreferences/] toc: true -needsreview: true --- -Hugo makes it easy to link documents together with `ref` and `relref`, both of which are [built-in Hugo shortcodes][]. These shortcodes are also used to safely provide links to headings inside of your content, whether across documents or within a document. The only difference between `ref` and `relref` is whether the resulting URL is absolute (`http://1.com/about/`) or relative (`/about/`). +Hugo makes it easy to link documents together with `ref` and `relref`, both of which are [built-in Hugo shortcodes][]. These shortcodes are also used to safely provide links to headings inside of your content, whether across documents or within a document. The only difference between `ref` and `relref` is whether the resulting URL is absolute (`http://1.com/about/`) or relative (`/about/`), respectively. ## Using `ref` and `relref` @@ -27,35 +26,59 @@ Hugo makes it easy to link documents together with `ref` and `relref`, both of w {{}} ``` -The single parameter to `ref` is a string with a content _document name_ (`about.md`), an in-document _anchor_ (`#who`), or both (`about.md#who`). +The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces. ### Document Names -The _document name_ is the name of a document including the format extension; this may be just the filename, or the relative path from the `content/` directory. With a document `content/blog/post.md`, either format will produce the same result. +The `documentname` is the name of a document, including the format extension; this may be just the filename, or the relative path from the `content/` directory. With a document `content/blog/post.md`, either format will produce the same result: ```golang {{}} ⇒ `/blog/post/` {{}} ⇒ `/blog/post/` ``` -If you have multiple sections with the same filename, you should only use the relative path format, because the behaviour is _undefined_. So, if I also have a document `link/post.md`, the output of `ref` is unknown for `post.md`. +If you have the same filename used across multiple sections, you should only use the relative path format; otherwise, the behavior will be `undefined`. This is best illustrated with an example `content` directory: -```golang -{{}} ⇒ `/blog/post/` -{{}} ⇒ `/blog/post/` (maybe) -{{}} ⇒ `/link/post/` (maybe) -{{}} ⇒ `/link/post/` +```bash +. +└── content + ├── events + │   └── my-birthday.md + ├── galleries + │   └── my-birthday.md + ├── meta + │   └── my-article.md + └── posts + └── my-birthday.md ``` -A relative document name must *not* begin with a slash (`/`). +The potential for conflicting `documentname` is more likely in larger sites. Using the example of multiple `my-birthday.md` files, the following shows how these cross references may or may not render when called from within `content/meta/my-article.md`: +{{% code file="content/meta/my-article.md" copy="false" %}} ```golang -{{}} ⇒ `""` +{{}} ⇒ `/events/my-birthday/` (maybe) +{{}} ⇒ `/posts/my-birthday/` (maybe) +{{}} ⇒ `/galleries/my-birthday/` (maybe) +{{}} ⇒ `/events/my-birthday/` +{{}} ⇒ `/galleries/my-birthday/` +``` +{{% /code %}} + +A relative document name must *not* begin with a slash (`/`). +```golang +{{}} ⇒ `""` ``` ### Anchors -When an _anchor_ is provided by itself, the current page’s unique identifier will be appended; when an _anchor_ is provided with a document name, the found page's unique identifier will be appended. +When an `anchor` is provided by itself, the current page’s unique identifier will be appended; when an `anchor` is provided appended to `documentname`, the found page's unique identifier will be appended: + +```golang +{{}} ⇒ `#anchors:9decaf7` +{{}} ⇒ `/blog/post/#who:badcafe` +``` + +The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite ```golang {{}} ⇒ `#who:9decaf7` @@ -66,8 +89,8 @@ More information about document unique identifiers and headings can be found [be ### Examples -* `{{}}` ⇒ `http://1.com/blog/post/` -* `{{}}` ⇒ `http://1.com/blog/post/#tldr:caffebad` +* `{{}}` ⇒ `http://yoursite.com/blog/post/` +* `{{}}` ⇒ `http://yoursite.com/blog/post/#tldr:caffebad` * `{{}}` ⇒ `/blog/post/` * `{{}}` ⇒ `/blog/post/#tldr:caffebad` * `{{}}` ⇒ `#tldr:badcaffe` @@ -82,8 +105,8 @@ Ensuring heading uniqueness across the site is accomplished with a unique identi `ref` and `relref` were added so you can make these reference links without having to know the document’s unique identifier. (The links in document tables of contents are automatically up-to-date with this value.) ```golang -{{}} -/content-management/crossreferences/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242 +{{}} +/content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242 ``` What follows is a deeper discussion of *why* and *how* Hugo generates heading anchors. It is not necessary to know this to use `ref` and `relref`, but it may be useful in understanding how some anchors may not match your expectations. @@ -142,27 +165,27 @@ This can even affect specified heading anchors that come after a generated headi * `# My Heading` ⇒ `my-heading` * `# My Heading {#my-heading}` ⇒ `my-heading-1` -> This particular collision and override is unfortunate, but unavoidable because Hugo processes each heading for collision detection as it sees it during conversion. +{{% note %}} +This particular collision and override both unfortunate and unavoidable because Hugo processes each heading for collision detection as it sees it during conversion. +{{% /note %}} -This technique works well for documents rendered on individual pages, like blog posts. What about on Hugo list pages? +This technique works well for documents rendered on individual pages (e.g., blog posts), but what about [Hugo list pages][lists]? ### Unique Heading Anchors in Lists Hugo converts each document from Markdown independently. It doesn’t know that `blog/post.md` has an "Example" heading that will collide with the "Example" heading in `blog/post2.md`. Even if it did know this, the addition of `blog/post3.md` should not cause the anchors for the headings in the other blog posts to change. -Enter the document’s unique identifier. To prevent this sort of collision on -list pages, Hugo always appends the document's to a generated heading anchor. -So, the "Example" heading in `blog/post.md` actually turns into -`#example:81df004…`, and the "Example" heading in `blog/post2.md` actually -turns into `#example:8cf1599…`. All you have to know is the heading anchor that -was generated, not the document identifier; `ref` and `relref` take care of the -rest for you. +Enter the document’s unique identifier. To prevent this sort of collision on list pages, Hugo always appends the document's to a generated heading anchor. So, the "Example" heading in `blog/post.md` actually turns into `#example:81df004…`, and the "Example" heading in `blog/post2.md` actually turns into `#example:8cf1599…`. All you have to know is the heading anchor that was generated, not the document identifier; `ref` and `relref` take care of the rest for you. - Post Example - Post Example +```html +Post Example +Post Example +``` - [Post Two Example]({{}}) - Post Two Example +``` +[Post Two Example]({{}}) +Post Two Example +``` - -[built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes \ No newline at end of file +[built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes +[lists]: /templates/lists/ \ No newline at end of file diff --git a/content/content-management/sections.md b/content/content-management/sections.md index 07cf7eb4e..e7ed2d1fb 100644 --- a/content/content-management/sections.md +++ b/content/content-management/sections.md @@ -49,7 +49,7 @@ Hugo will automatically create pages for each section root that list all of the As of Hugo v0.18, section pages can also have a content file and front matter. These section content files must be placed in their corresponding section folder and named `_index.md` in order for Hugo to correctly render the front matter and content. {{% warning "`index.md` vs `_index.md`" %}} -Hugo themes developed before v0.18 often used an `index.md` in a content section as a hack to emulate the behavior of `_index.md`. The hack may work...*sometimes*; however, the order of page rendering can be unpredictable in Hugo. What works now may fail to render appropriately as your site grows. It is **strongly advised** to use `_index.md` as the *preferred* content section index page. **Note:** `_index.md`'s layout, as representative of a section, is a [list template](/templates/section-templates/) and *not* a [single template](/templates/single-page-templates/). +Hugo themes developed before v0.18 often used an `index.md`(i.e., without the leading underscore) in a content section as a hack to emulate the behavior of `_index.md`. The hack may work...*sometimes*; however, the order of page rendering can be unpredictable in Hugo. What works now may fail to render appropriately as your site grows. It is **strongly advised** to use `_index.md` as content for your section index pages. **Note:** `_index.md`'s layout, as representative of a section, is a [list page template](/templates/section-templates/) and *not* a [single page template](/templates/single-page-templates/). {{% /warning %}} ## Content *Section* vs Content *Type* diff --git a/content/content-management/shortcodes.md b/content/content-management/shortcodes.md index 38c3696ce..794c0e633 100644 --- a/content/content-management/shortcodes.md +++ b/content/content-management/shortcodes.md @@ -1,7 +1,7 @@ --- title: Shortcodes linktitle: -description: +description: Shortcodes are simple snippets inside your content files that Hugo renders renders so as not to mess with the clean and simple syntax of your preferred content format. godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -389,7 +389,7 @@ Using the preceding `youtube` example, the following HTML will be added to your #### Example `youtube` Display -Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. +Using the preceding `youtube` example (without `autoplay="true"`), the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. The video is also include in the [Quick Start of the Hugo documentation][quickstart]. {{< youtube w7Ft2ymGmfc >}} @@ -406,6 +406,7 @@ To learn more about creating your own shortcode templates, see the [shortcode te [partials]: /templates/partials-templates/ [Pygments]: http://pygments.org/ [projectorganizationsection]: /project-organization/directory-structure/ +[quickstart]: /getting-started/quick-start/ [shortcode template documentation]: /templates/shortcode-templates/ [Speaker Deck]: https://speakerdeck.com/ [templatessection]: /templates/ diff --git a/content/content-management/url-management.md b/content/content-management/url-management.md index fece48ddb..946485cbc 100644 --- a/content/content-management/url-management.md +++ b/content/content-management/url-management.md @@ -1,7 +1,7 @@ --- title: URL Management linktitle: URL Management -description: +description: Hugo provides native support for permalinks, aliases, link canonicalization, and multiple options for handling relative vs absolute URLs. date: 2017-02-01 publishdate: 2017-02-01 lastmod: 2017-02-01 @@ -16,7 +16,7 @@ needsreview: true ## Permalinks -By default, a Hugo-built site is laid out into the target `publishdir` specified in your [site configuration][configuration]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder. namespace matching its layout within the `contentdir` hierarchy. The `permalinks` option in your [site configuration][] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option. +By default, a Hugo-built site is laid out into the target `publishdir` specified in your [site configuration][configuration]. The directories created at build time for a section reflect the position of the content's directory within the `content` folder. namespace matching its layout within the `contentdir` hierarchy. The `permalinks` option in your [site configuration][] allows you to adjust the directory paths (i.e., the URLs) on a per-section basis. This will change where the files are written to and will change the page's internal "canonical" location, such that template references to `.RelPermalink` will honor the adjustments made as a result of the mappings in this option. {{% note "Default Publish and Content Folders" %}} These examples use the default values for `publishDir` and `contentDir`; i.e., `publish` and `content`, respectively. You can override the default values in your [site's `config` file](/getting-started/configuration/). @@ -26,19 +26,23 @@ For example, if one of your [sections][] is called `post` and you want to adjust ### YAML Permalinks Configuration Example +{{% code file="config.yml" copy="false" %}} ```yaml permalinks: post: /:year/:month/:title/ ``` +{{% /code %}} ### TOML Permalinks Configuration Example +{{% code file="config.toml" copy="false" %}} ```toml [permalinks] post = "/:year/:month/:title/" ``` +{{% /code %}} -Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry` with `date: 2013-11-18T19:20:00-05:00` in its front matter will render to `public/2013/11/sample-entry/index.html` at build time and therefore be reachable at `http://yoursite.example.com/2013/11/sample-entry/`. +Only the content under `post/` will have the new URL structure. For example, the file `content/post/sample-entry` with `date: 2013-11-18T19:20:00-05:00` in its front matter will render to `public/2013/11/sample-entry/index.html` at build time and therefore be reachable at `http://yoursite.com/2013/11/sample-entry/`. ### Permalink Configuration Values @@ -58,51 +62,38 @@ The following is a list of values that can be used in a `permalink` definition i ## Example -Given a post on your current Hugo site, with a path of: +Let's assume you create a new piece of content at `content/posts/my-awesome-blog-post.md`. The content is a revision of your previous post at `content/posts/my-original-url.md`. You can create an `aliases` field in the front matter of your new `my-awesome-blog-post.md` where you can add previous paths. The following show examples of creating this filed in TOML and YAML front matter, respectively. -``content/posts/my-awesome-blog-post.md`` - -... you create an "aliases" section in the frontmatter of your post, and add previous paths to that. - -### TOML frontmatter +### TOML Front Matter +{{% code file="content/posts/my-awesome-post.md" copy="false" %}} ```toml +++ - ... aliases = [ "/posts/my-original-url/", "/2010/01/01/even-earlier-url.html" ] - ... +++ ``` +{{% /code %}} -### YAML frontmatter +### YAML Front Matter +{{% code file="content/posts/my-awesome-post.md" copy="false" %}} ```yaml --- - ... aliases: - /posts/my-original-url/ - /2010/01/01/even-earlier-url.html - ... --- ``` +{{% /code %}} -Now when you visit any of the locations specified in aliases, _assuming the same site domain_, you'll be redirected to the page they are specified on. - -## Important Behaviors - -1. *Hugo makes no assumptions about aliases. They also don't change based -on your UglyURLs setting. You need to provide absolute path to your webroot -and the complete filename or directory.* - -2. *Aliases are rendered prior to any content and will be overwritten by -any content with the same location.* +Now when you visit any of the locations specified in aliases---i.e., *assuming the same site domain*---you'll be redirected to the page they are specified on. For example, a visitor to `yoursite.com/posts/my-original-url/` will be immediately redirected to `yoursite.com/posts/my-awesome-blog-post`. ## Multilingual example -On [multilingual sites](/content-management/multilingual/), each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code. +On [multilingual sites][multilingual], each translation of a post can have unique aliases. To use the same alias across multiple languages, prefix it with the language code. In `/posts/my-new-post.es.md`: @@ -117,22 +108,22 @@ aliases: For people migrating existing published content to Hugo, there's a good chance you need a mechanism to handle redirecting old URLs. -Luckily, redirects can be handled easily with _aliases_ in Hugo. +Luckily, redirects can be handled easily with **aliases** in Hugo. ### How Hugo Aliases Work -When aliases are specified, Hugo creates a physical folder structure to match the alias entry, and, an html file specifying the canonical URL for the page, and a redirect target. +When aliases are specified, Hugo creates a directory to match the alias entry. Inside the directory, Hugo creates an `.html` file specifying the canonical URL for the page and the new redirect target. -Assuming a baseURL of `mysite.tld`, the contents of the html file will look something like: +Assuming a baseURL of `yoursite.com`, the contents of the html file will look something like: ```html - http://mysite.tld/posts/my-original-url - + http://yoursite.com/posts/my-original-url + - + ``` @@ -142,7 +133,7 @@ The `http-equiv="refresh"` line is what performs the redirect, in 0 seconds in t ### Customizing You may customize this alias page by creating an alias.html template in the -layouts folder of your site. In this case, the data passed to the template is +layouts folder of your site (i.e., `layouts/alias.html`). In this case, the data passed to the template is `Permalink` : the link to the page being aliased @@ -150,6 +141,15 @@ layouts folder of your site. In this case, the data passed to the template is `Page` : the Page data for the page being aliased +### Important Behaviors of Aliases + +1. Hugo makes no assumptions about aliases. They also do not change based +on your UglyURLs setting. You need to provide absolute paths to your web root +and the complete filename or directory. + +2. Aliases are rendered *before* to any content and will be overwritten by +any content with the same location. + ## Pretty URLs Hugo's default behavior is to render your content with "pretty" URLs. No non-standard server-side configuration is required for these pretty URLs to work. @@ -175,15 +175,15 @@ If you want a specific piece of content to have an exact URL, you can specify th . └── content └── about - | └── _index.md // <- http://1.com/about/ + | └── _index.md // <- http://yoursite.com/about/ ├── post - | ├── firstpost.md // <- http://1.com/post/firstpost/ + | ├── firstpost.md // <- http://yoursite.com/post/firstpost/ | ├── happy - | | └── ness.md // <- http://1.com/post/happy/ness/ - | └── secondpost.md // <- http://1.com/post/secondpost/ + | | └── ness.md // <- http://yoursite.com/post/happy/ness/ + | └── secondpost.md // <- http://yoursite.com/post/secondpost/ └── quote - ├── first.md // <- http://1.com/quote/first/ - └── second.md // <- http://1.com/quote/second/ + ├── first.md // <- http://yoursite.com/quote/first/ + └── second.md // <- http://yoursite.com/quote/second/ ``` Here's the same organization run with `hugo --uglyURLs`: @@ -192,15 +192,15 @@ Here's the same organization run with `hugo --uglyURLs`: . └── content └── about - | └── _index.md // <- http://1.com/about/ + | └── _index.md // <- http://yoursite.com/about/ ├── post - | ├── firstpost.md // <- http://1.com/post/firstpost.html + | ├── firstpost.md // <- http://yoursite.com/post/firstpost.html | ├── happy - | | └── ness.md // <- http://1.com/post/happy/ness.html - | └── secondpost.md // <- http://1.com/post/secondpost.html + | | └── ness.md // <- http://yoursite.com/post/happy/ness.html + | └── secondpost.md // <- http://yoursite.com/post/secondpost.html └── quote - ├── first.md // <- http://1.com/quote/first.html - └── second.md // <- http://1.com/quote/second.html + ├── first.md // <- http://yoursite.com/quote/first.html + └── second.md // <- http://yoursite.com/quote/second.html ``` @@ -208,14 +208,14 @@ Here's the same organization run with `hugo --uglyURLs`: By default, all relative URLs encountered in the input are left unmodified, e.g. `/css/foo.css` would stay as `/css/foo.css`, i.e. `canonifyURLs` defaults to `false`. -By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = http://yoursite.example.com/` defined in the site-wide `config.toml`, the relative URL `/css/foo.css` would be turned into the absolute URL `http://yoursite.example.com/css/foo.css`. +By setting `canonifyURLs` to `true`, all relative URLs would instead be *canonicalized* using `baseURL`. For example, assuming you have `baseURL = http://yoursite.com/` defined in the site-wide `config.toml`, the relative URL `/css/foo.css` would be turned into the absolute URL `http://yoursite.com/css/foo.css`. -Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note though that all real browsers handle this client-side without issues. +Benefits of canonicalization include fixing all URLs to be absolute, which may aid with some parsing tasks. Note, however, that all modern browsers handle this on the client without issues. -Benefits of non-canonicalization include being able to have resource inclusion be scheme-relative, so that http vs https can be decided based on how this page was retrieved. +Benefits of non-canonicalization include being able to have scheme-relative resource inclusion; e.g., so that `http` vs `https` can be decided according to how the page was retrieved. {{% note "`canonifyURLs` default change" %}} -In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. So, please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions. +In the May 2014 release of Hugo v0.11, the default value of `canonifyURLs` was switched from `true` to `false`, which we think is the better default and should continue to be the case going forward. Please verify and adjust your website accordingly if you are upgrading from v0.10 or older versions. {{% /note %}} To find out the current value of `canonifyURLs` for your website, you may use the handy `hugo config` command added in v0.13. @@ -234,12 +234,14 @@ hugo config | FINDSTR /I canon By default, all relative URLs are left unchanged by Hugo, which can be problematic when you want to make your site browsable from a local file system. -Setting `relativeURLs` to `true` in the site configuration will cause Hugo to rewrite all relative URLs to be relative to the current content. +Setting `relativeURLs` to `true` in your [site configuration][configuration] will cause Hugo to rewrite all relative URLs to be relative to the current content. -For example, if the `/post/first/` page contained a link with a relative URL of `/about/`, Hugo would rewrite that URL to `../../about/`. +For example, if the `/post/first/` page contained a link to `/about/`, Hugo would rewrite that URL to `../../about/`. +[configuration]: /getting-started/configuration/ [Content Organization]: /content-management/content-organization/ [flag from the command line]: /getting-started/basic-usage/ [front matter]: /content-management/front-matter/ +[multilingual]: /content-management/multilingual-mode/ [sections]: /content-management/sections/ [site configuration]: /project-organization/configuration/ \ No newline at end of file diff --git a/content/contribute-to-hugo/_index.md b/content/contribute/_index.md similarity index 100% rename from content/contribute-to-hugo/_index.md rename to content/contribute/_index.md diff --git a/content/contribute-to-hugo/add-your-site-to-the-showcase.md b/content/contribute/add-your-site-to-the-showcase.md similarity index 93% rename from content/contribute-to-hugo/add-your-site-to-the-showcase.md rename to content/contribute/add-your-site-to-the-showcase.md index 718503882..8a08428f6 100644 --- a/content/contribute-to-hugo/add-your-site-to-the-showcase.md +++ b/content/contribute/add-your-site-to-the-showcase.md @@ -49,7 +49,7 @@ tags: [] image: "yourimage.jpg" toc: false title: my hugo site name -notesforauthors: "For the image, only include the file name *without* a directory/path, which is taken care of in the templating. See the showcase contribution page at gohugo.io/contribute-to-hugo/add-your-site-to-the-showcase/ for more details. As always, feel free to delete `notesforauthors` or modify for anyone in the future who may edit the content in this file." +notesforauthors: "For the image, only include the file name *without* a directory/path, which is taken care of in the templating. See the showcase contribution page at gohugo.io/contribute/add-your-site-to-the-showcase/ for more details. As always, feel free to delete `notesforauthors` or modify for anyone in the future who may edit the content in this file." --- ``` diff --git a/content/contribute-to-hugo/contribute-to-hugo-development.md b/content/contribute/contribute-to-hugo-development.md similarity index 96% rename from content/contribute-to-hugo/contribute-to-hugo-development.md rename to content/contribute/contribute-to-hugo-development.md index c8d20e620..f06611621 100644 --- a/content/contribute-to-hugo/contribute-to-hugo-development.md +++ b/content/contribute/contribute-to-hugo-development.md @@ -10,7 +10,7 @@ tags: [dev,open source] authors: [digitalcraftsman] weight: 10 draft: false -aliases: [/contribute-to-hugo/contribute-to-hugo-development/] +aliases: [/contribute/contribute-to-hugo-development/] toc: true needsreview: true notesforauthors: @@ -141,11 +141,11 @@ If you're not fimiliar with this term, GitHub's [help pages](https://help.github Open the [Hugo repository](https://github.com/spf13/hugo) on Github and click on the "Fork" button in the top right. -![Fork button](/images/contribute-to-hugo/contribute-to-hugo-development/forking-a-repository.png) +![Fork button](/images/contribute/contribute-to-hugo-development/forking-a-repository.png) Now open your fork repository on GitHub and copy the remote url of your fork. You can choose between HTTPS and SSH as protocol that Git should use for the following operations. HTTPS works always [if you're not sure](https://help.github.com/articles/which-remote-url-should-i-use/). -![Copy remote url](/images/contribute-to-hugo/contribute-to-hugo-development/copy-remote-url.png) +![Copy remote url](/images/contribute/contribute-to-hugo-development/copy-remote-url.png) Switch back to the terminal and move into the directory of the cloned master repository from the last step. @@ -350,7 +350,7 @@ We made a lot of progress. Good work. In this step we finally open a pull reques You should find a green button labeld with "New pull request". But GitHub is clever and probably suggests you a pull request like in the beige box below: -![Open a pull request](/images/contribute-to-hugo/contribute-to-hugo-development/open-pull-request.png) +![Open a pull request](/images/contribute/contribute-to-hugo-development/open-pull-request.png) The new page summaries the most important information of your pull request. Scroll down and you find the additions of all your commits. Make sure everything looks as expected and click on "Create pull request". @@ -358,13 +358,13 @@ The new page summaries the most important information of your pull request. Scro Last but not least you should accept the contributor license agreement (CLA). A new comment should be added automatically to your pull request. Click on the yellow badge, accept the agreement and authenticate yourself with your GitHub account. It just takes a few clicks and only needs to be done once. -![Accept the CLA](/images/contribute-to-hugo/contribute-to-hugo-development/accept-cla.png) +![Accept the CLA](/images/contribute/contribute-to-hugo-development/accept-cla.png) ### Automatic builds We use the [Travis CI loop](https://travis-ci.org/spf13/hugo) (Linux and OS X) and [AppVeyor](https://ci.appveyor.com/project/spf13/hugo/branch/master) (Windows) to compile Hugo with your additions. This should ensure that everything works as expected before merging your pull request. This in most cases only relevant if you made changes to the codebase of Hugo. -![Automic builds and their status](/images/contribute-to-hugo/contribute-to-hugo-development/ci-errors.png) +![Automic builds and their status](/images/contribute/contribute-to-hugo-development/ci-errors.png) Above you can see that Travis wasn't able to compile the changes in this pull request. Click on "Details" and try to investigate why the build failed. But it doesn't have to be your fault. Mostly, the `master` branch that we used as foundation for your pull request should build without problems. diff --git a/content/contribute-to-hugo/contribute-to-the-hugo-docs.md b/content/contribute/contribute-to-the-hugo-docs.md similarity index 99% rename from content/contribute-to-hugo/contribute-to-the-hugo-docs.md rename to content/contribute/contribute-to-the-hugo-docs.md index 756d0fff9..3ba62ca6b 100644 --- a/content/contribute-to-hugo/contribute-to-the-hugo-docs.md +++ b/content/contribute/contribute-to-the-hugo-docs.md @@ -151,6 +151,8 @@ The Hugo docs are not especially prescriptive in terms of grammar and usage. We ## Pages Needing Code Examples +Examples + {{< needsexamples >}} ## How Content is Ordered in the Docs diff --git a/content/functions/GetPage.md b/content/functions/GetPage.md index 6fdfd20f8..ade14872c 100644 --- a/content/functions/GetPage.md +++ b/content/functions/GetPage.md @@ -18,7 +18,17 @@ draft: false aliases: [] --- -## Example +Every `Page` has a `Kind` attribute that shows what kind of page it is. While this attribute can be used to list pages of a certain `kind` using `where`, often it can be useful to fetch a single page by its path. -## Advanced Example +`GetPage` looks up an index page of a given `Kind` and `path`. This method may support regular pages in the future, but currently it is a convenient way of getting the index pages, such as the home page or a section, from a template: + + {{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }} + +This method wil return `nil` when no page could be found, so the above will not print anything if the blog section isn't found. + +The valid page kinds are: *home, section, taxonomy and taxonomyTerm.* + +**The following is a good example of `.GetPage`**: + + +{ + "@context" : "http://schema.org", + "@type" : "BlogPosting", + "image" : {{ apply .Params.images "absURL" "." }} +} + +``` +{{% /code %}} + +The above uses the [apply function][] and also exploits the fact that the Go template parser JSON-encodes objects inside `