diff --git a/content/content-management/formats.md b/content/content-management/formats.md index b876ccf6d..0e05c4495 100644 --- a/content/content-management/formats.md +++ b/content/content-management/formats.md @@ -17,9 +17,9 @@ aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-f toc: true --- -**Markdown is the main content format** and comes in two flavours: The excellent [Blackfriday project][blackfriday] (name your files `*.md` or set `markup = "markdown"` in frontmatter) or its fork [Mmark][mmark] (name your files `*.mmark` or set `markup = "mmark"` in frontmatter), both very fast markdown engines written in Golang. +**Markdown is the main content format** and comes in two flavours: The excellent [Blackfriday project][blackfriday] (name your files `*.md` or set `markup = "markdown"` in front matter) or its fork [Mmark][mmark] (name your files `*.mmark` or set `markup = "mmark"` in front matter), both very fast markdown engines written in Go. -For Emacs users, [goorgeous](https://github.com/chaseadamsio/goorgeous) provides built-in native support for Org mode (name your files `*.org` or set `markup = "org"` in frontmatter) +For Emacs users, [goorgeous](https://github.com/chaseadamsio/goorgeous) provides built-in native support for Org-mode (name your files `*.org` or set `markup = "org"` in front matter) {{% note "Deeply Nested Lists" %}} Before you begin writing your content in markdown, Blackfriday has a known issue [(#329)](https://github.com/russross/blackfriday/issues/329) with handling deeply nested lists. Luckily, there is an easy workaround. Use 4-spaces (i.e., tab) rather than 2-space indentations. @@ -234,7 +234,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are [helperssource]: https://github.com/spf13/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65 [hl]: /tools/syntax-highlighting/ [hlsc]: /content-management/shortcodes/#highlight -[hugocss]: /css/style.min.css +[hugocss]: /css/style.css [ietf]: https://tools.ietf.org/html/ [mathjaxdocs]: https://docs.mathjax.org/en/latest/ [mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet diff --git a/content/functions/scratch.md b/content/functions/scratch.md index 4480cf7cc..e06f627fa 100644 --- a/content/functions/scratch.md +++ b/content/functions/scratch.md @@ -1,7 +1,6 @@ --- -title: scratch -# linktitle: Scratch -description: Acts as a "scratchpad" to allow for writable page-scoped variables. +title: Scratch +description: Acts as a "scratchpad" to allow for writable page- or shortcode-scoped variables. godocref: date: 2017-02-01 publishdate: 2017-02-01 @@ -22,7 +21,7 @@ draft: false aliases: [/extras/scratch/,/doc/scratch/] --- -`Scratch` is a "scratchpad" for your [page-scoped variables][pagevars]. In most cases you can do well without `Scratch`, but there are some use cases that aren't solvable with Go's templates without `Scratch`'s help, due to scoping issues. +In most cases you can do well without `Scratch`, but there are some use cases that aren't solvable with Go's templates without `Scratch`'s help, due to scoping issues. `Scratch` is added to both `Page` and `Shortcode` -- with following methods: diff --git a/content/getting-started/quick-start.md b/content/getting-started/quick-start.md index 07b9b2963..038c1e330 100644 --- a/content/getting-started/quick-start.md +++ b/content/getting-started/quick-start.md @@ -1,7 +1,7 @@ --- title: Quick Start linktitle: Quick Start -description: Build an online bookshelf that taps into HUGO's CLI, directory structure, configuration, and theming. +description: Build an online bookshelf that taps into Hugo's CLI, directory structure, configuration, and theming. date: 2013-07-01 publishdate: 2013-07-01 lastmod: 2017-06-22 @@ -26,10 +26,6 @@ This Quick Start was originally written by [Shekhar Gulati](https://twitter.com/ In this Quick Start, we will build an online bookshelf that lists books and their reviews. -## Assumptions - -This quick start assumes you are using Hugo v0.15 or greater. - ## Step 1. Install Hugo [Install Hugo][install]. If installing from [Hugo releases][releases], you'll need to save the main executable as `hugo` (or `hugo.exe` on Windows) somewhere in your `PATH`. You will need the `hugo` command in the following steps. diff --git a/content/templates/introduction.md b/content/templates/introduction.md index ce3b025eb..bcb525020 100644 --- a/content/templates/introduction.md +++ b/content/templates/introduction.md @@ -1,7 +1,7 @@ --- title: Introduction to Hugo Templating linktitle: Introduction -description: Hugo uses Go's html/template library, an extremely lightweight and performant engine, as the basis for all Hugo templating. +description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. godocref: https://golang.org/pkg/html/template/ date: 2017-02-01 publishdate: 2017-02-01 @@ -19,21 +19,15 @@ aliases: [/templates/introduction/,/layouts/introduction/,/layout/introduction/, toc: true --- -Hugo uses the excellent [Go html/template][gohtmltemplate] library, an extremely lightweight engine that provides just the right amount of logic to be able to create any style of static website. If you have used other template systems from different languages or frameworks, you will find a lot of similarities in Go templates. - {{% note %}} The following is only a primer on Go templates. For an in-depth look into Go templates, check the official [Go docs](http://golang.org/pkg/html/template/). {{% /note %}} -## Introduction to Go Templates - -Go templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. As a positive consequence of this simplicity, Go templates parse very quickly. - -A unique characteristic of Go templates is that they are *content aware*. Variables and content will be sanitized depending on the context of where they are used. +Go templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. ## Basic Syntax -Golang templates are HTML files with the addition of [variables][variables] and [functions][hugofunctions]. Golang template variables and functions are accessible within `{{ }}`. +Golang templates are HTML files with the addition of [variables][variables] and [functions][functions]. Golang template variables and functions are accessible within `{{ }}`. ### Accessing a Predefined Variable @@ -63,21 +57,28 @@ Accessing the Page Parameter `bar` defined in a piece of content's [front matter ## Variables -Each Go template has a struct (object) made available to it. In Hugo, each template is passed a page's struct. More details on the structs passed to specific page kinds are in the [variables][] section. +Each Go template gets a data object. In Hugo, each template is passed a `Page`. See [variables][] for more information. -A variable is accessed by referencing the variable name inside of a template: +This is how you access a `Page` variable from a template: ```golang {{ .Title }} ``` -Variables can also be defined and referenced: +Values can also be stored in custom variables and referenced later: ```golang {{ $address := "123 Main St."}} {{ $address }} ``` +{{% warning %}} +Variables defined inside `if` conditionals and similar are not visible on the outside. See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). + +Hugo has created a workaround for this issue in [Scratch](/functions/scratch). + +{{% /warning %}} + ## Functions Go templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. diff --git a/content/templates/pagination.md b/content/templates/pagination.md index e81ce08f4..f46a0295e 100644 --- a/content/templates/pagination.md +++ b/content/templates/pagination.md @@ -37,7 +37,7 @@ Setting `Paginate` to a positive value will split the list pages for the homepag ## Listing Paginator Pages {{% warning %}} -`.Paginator` is provided to help you build a pager menu. This features is currently only supported on homepage and list pages (i.e., taxonomies and section lists). +`.Paginator` is provided to help you build a pager menu. This feature is currently only supported on homepage and list pages (i.e., taxonomies and section lists). {{% /warning %}} There are two ways to configure and use a `.Paginator`: