diff options
34 files changed, 517 insertions, 32 deletions
diff --git a/docs/content/en/content-management/comments.md b/docs/content/en/content-management/comments.md index 20932a825..1152c843c 100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@ -48,7 +48,8 @@ See [Partial Templates][partials] to learn how to add the Disqus partial to your There are a few alternatives to commenting on static sites for those who do not want to use Disqus: * [Static Man](https://staticman.net/) -* [txtpen](https://txtpen.com) +* [Talkyard](https://www.talkyard.io/blog-comments) (Open source, & serverless hosting) +* [txtpen](https://txtpen.github.io/hn/) * [IntenseDebate](http://intensedebate.com/) * [Graph Comment][] * [Muut](http://muut.com/) diff --git a/docs/content/en/content-management/formats.md b/docs/content/en/content-management/formats.md index 6c53ab467..ab9fdd781 100644 --- a/docs/content/en/content-management/formats.md +++ b/docs/content/en/content-management/formats.md @@ -219,6 +219,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are * [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball] * [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet] * [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial] +* [The Markdown Guide, Matt Cone][mdguide] [`emojify` function]: /functions/emojify/ [ascii]: http://asciidoctor.org/ @@ -237,6 +238,7 @@ Markdown syntax is simple enough to learn in a single sitting. The following are [ietf]: https://tools.ietf.org/html/ [mathjaxdocs]: https://docs.mathjax.org/en/latest/ [mdcheatsheet]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet +[mdguide]: https://www.markdownguide.org/ [mdtutorial]: http://www.markdowntutorial.com/ [Miek Gieben's website]: https://miek.nl/2016/March/05/mmark-syntax-document/ [mmark]: https://github.com/miekg/mmark diff --git a/docs/content/en/content-management/front-matter.md b/docs/content/en/content-management/front-matter.md index bf067797c..9ad1d3804 100644 --- a/docs/content/en/content-management/front-matter.md +++ b/docs/content/en/content-management/front-matter.md @@ -115,7 +115,7 @@ url the multilingual feature. weight -: used for [ordering your content in lists][ordering]. +: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. \<taxonomies\> : field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. _Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables._ diff --git a/docs/content/en/content-management/image-processing/index.md b/docs/content/en/content-management/image-processing/index.md index ecc85bb51..954ff7395 100644 --- a/docs/content/en/content-management/image-processing/index.md +++ b/docs/content/en/content-management/image-processing/index.md @@ -166,7 +166,7 @@ All of the above settings can also be set per image procecssing. ## Smart Cropping of Images -By default, Hugo will use the [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the libray author to improve this in the future. +By default, Hugo will use the [Smartcrop](https://github.com/muesli/smartcrop), a library created by [muesli](https://github.com/muesli), when cropping images with `.Fill`. You can set the anchor point manually, but in most cases the smart option will make a good choice. And we will work with the library author to improve this in the future. An example using the sunset image from above: diff --git a/docs/content/en/content-management/page-resources.md b/docs/content/en/content-management/page-resources.md index cefb1cd47..f45cf4b01 100644 --- a/docs/content/en/content-management/page-resources.md +++ b/docs/content/en/content-management/page-resources.md @@ -116,7 +116,7 @@ From the example above: - `documents/photo_specs.pdf` will get the `photo` icon. - `documents/checklist.pdf`, `documents/guide.pdf` and `documents/payment.docx` will get `Title` as set by `title`. - Every `PDF` in the bundle except `documents/photo_specs.pdf` will get the `pdf` icon. -- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#counter), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`. +- All `PDF` files will get a new `Name`. The `name` parameter contains a special placeholder [`:counter`](#the-counter-placeholder-in-name-and-title), so the `Name` will be `pdf-file-1`, `pdf-file-2`, `pdf-file-3`. - Every docx in the bundle will receive the `word` icon. {{% warning %}} diff --git a/docs/content/en/content-management/related.md b/docs/content/en/content-management/related.md index 6f66e4468..5755676c3 100644 --- a/docs/content/en/content-management/related.md +++ b/docs/content/en/content-management/related.md @@ -36,7 +36,7 @@ To list up to 5 related pages is as simple as including something similar to thi {{% note %}} -Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation more advanced usage of this feature. +Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. {{% /note %}} The full set of methods available on the page lists can bee seen in this Go interface: diff --git a/docs/content/en/content-management/syntax-highlighting.md b/docs/content/en/content-management/syntax-highlighting.md index b2d7a4552..517968e3c 100644 --- a/docs/content/en/content-management/syntax-highlighting.md +++ b/docs/content/en/content-management/syntax-highlighting.md @@ -18,7 +18,7 @@ toc: true From Hugo 0.28, the default syntax hightlighter in Hugo is [Chroma](https://github.com/alecthomas/chroma); it is built in Go and is really, really fast -- and for the most important parts compatible with Pygments. -If you want to continue to use Pygments (see below), set `pygmentsUseClasses=true` in your site config. +If you want to continue to use Pygments (see below), set `pygmentsUseClassic=true` in your site config. The example below shows a simple code snippet from the Hugo source highlighted with the `highlight` shortcode. Note that the gohugo.io site is generated with `pygmentsUseClasses=true` (see [Generate Syntax Highlighter CSS](#generate-syntax-highlighter-css)). @@ -94,7 +94,7 @@ linenos : For Chroma, any value in this setting will print line numbers. Pygments has some more fine grained control. linenostart -: Start the line numbers from this value (default is 1). +: Start the line numbers from this value (default is 1). hl_lines @@ -143,7 +143,7 @@ Highlighting is carried out via the [built-in shortcode](/content-management/sho See [Highlight](/functions/highlight/). ## Highlight in Code Fences - + It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `pygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/); ```` diff --git a/docs/content/en/content-management/taxonomies.md b/docs/content/en/content-management/taxonomies.md index 287c6f899..629fab94d 100644 --- a/docs/content/en/content-management/taxonomies.md +++ b/docs/content/en/content-management/taxonomies.md @@ -82,15 +82,23 @@ Moonrise Kingdom <- Value ... ``` -## Hugo Taxonomy Defaults +## Hugo Taxonomy Defaults {#default-taxonomies} Hugo natively supports taxonomies. -Without adding a single line to your site's configuration file, Hugo will automatically create taxonomies for `tags` and `categories`. If you do not want Hugo to create any taxonomies, set `disableKinds` in your site's configuration to the following: +Without adding a single line to your [site config][config] file, Hugo will automatically create taxonomies for `tags` and `categories`. That would be same as manually [configuring your taxonomies](#configuring-taxonomies) as below: -``` +{{< code-toggle copy="false" >}} +[taxonomies] + tag = "tags" + category = "categories" +{{</ code-toggle >}} + +If you do not want Hugo to create any taxonomies, set `disableKinds` in your [site config][config] to the following: + +{{< code-toggle copy="false" >}} disableKinds = ["taxonomy","taxonomyTerm"] -``` +{{</ code-toggle >}} ### Default Destinations @@ -99,11 +107,15 @@ When taxonomies are used---and [taxonomy templates][] are provided---Hugo will a * A single page at `example.com/categories/` that lists all the [terms within the taxonomy][] * [Individual taxonomy list pages][taxonomy templates] (e.g., `/categories/development/`) for each of the terms that shows a listing of all pages marked as part of that taxonomy within any content file's [front matter][] -## Configure Taxonomies +## Configure Taxonomies {#configuring-taxonomies} -Taxonomies must be defined in your [website configuration][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML. +Custom taxonomies other than the [defaults](#default-taxonomies) must be defined in your [site config][config] before they can be used throughout the site. You need to provide both the plural and singular labels for each taxonomy. For example, `singular key = "plural value"` for TOML and `singular key: "plural value"` for YAML. -### Example: Taxonomy Configuration +### Example: Adding a custom taxonomy named "series" + +{{% note %}} +While adding custom taxonomies, you need to put in the default taxonomies too, _if you want to keep them_. +{{% /note %}} {{< code-toggle copy="false" >}} [taxonomies] @@ -112,11 +124,22 @@ Taxonomies must be defined in your [website configuration][config] before they c series = "series" {{</ code-toggle >}} +### Example: Removing default taxonomies + +If you want to have just the default `tags` taxonomy, and remove the `categories` taxonomy for your site, you can do so by modifying the `taxonomies` value in your [site config][config]. + +{{< code-toggle copy="false" >}} +[taxonomies] + tag = "tags" +{{</ code-toggle >}} + +If you want to disable all taxonomies altogether, see the use of `disableKinds` in [Hugo Taxonomy Defaults](#default-taxonomies). + ### Preserve Taxonomy Values By default, taxonomy names are normalized. -Therefore, if you want to have a taxonomy term with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, set the value for `preserveTaxonomyNames` to `true` in your [site configuration][config]. Hugo will then preserve special characters in taxonomy values but will still title-ize the values for titles and normalize them in URLs. +Therefore, if you want to have a taxonomy term with special characters such as `Gérard Depardieu` instead of `Gerard Depardieu`, set the value for `preserveTaxonomyNames` to `true` in your [site config][config]. Hugo will then preserve special characters in taxonomy values but will still title-ize the values for titles and normalize them in URLs. Note that if you use `preserveTaxonomyNames` and intend to manually construct URLs to the archive pages, you will need to pass the taxonomy values through the [`urlize` template function][]. diff --git a/docs/content/en/contribute/development.md b/docs/content/en/contribute/development.md index 67bc6c2b6..aafec4110 100644 --- a/docs/content/en/contribute/development.md +++ b/docs/content/en/contribute/development.md @@ -38,7 +38,7 @@ If you're struggling at any point in this contribution guide, reach out to the H The installation of Go should take only a few minutes. You have more than one option to get Go up and running on your machine. -If you are having trouble following the installation guides for go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums]. +If you are having trouble following the installation guides for Go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums]. ### Install Go From Source @@ -58,7 +58,7 @@ go version go1.8 darwin/amd64 Next, make sure that you set up your `GOPATH` [as described in the installation guide][setupgopath]. -You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace; .e.g.: +You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace; for example: ``` /Users/<yourusername>/Code/go @@ -66,7 +66,7 @@ You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty strin ### Install Go with Homebrew -If you are a macOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command: +If you are a MacOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command: {{< code file="install-go.sh" >}} brew install go @@ -84,7 +84,7 @@ If you're going to contribute code, you'll need to have an account on GitHub. Go ## Install Git on Your System -You will need to have Git installed on your computer to contribute to Hugo development. Teaching git is outside the scope of the Hugo docs, but if you're looking for an excellent reference to learn the basics of Git, we recommend the [Git book][gitbook] if you are not sure where to begin. The used terminology will be explained with annotations. +You will need to have Git installed on your computer to contribute to Hugo development. Teaching Git is outside the scope of the Hugo docs, but if you're looking for an excellent reference to learn the basics of Git, we recommend the [Git book][gitbook] if you are not sure where to begin. We will include short explainations of the Git commands in this document. Git is a [version control system](https://en.wikipedia.org/wiki/Version_control) to track the changes of source code. Hugo depends on smaller third-party packages that are used to extend the functionality. We use them because we don't want to reinvent the wheel. @@ -96,7 +96,7 @@ Finally, check again with `git version` if Git was installed successfully. ### Git Graphical Front Ends -There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Thus, so we will use the command line since the commands are everywhere the same. +There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Because of this we will document how to use the command line, since the commands are the same everywhere. ### Install Hub on Your System (Optional) @@ -123,7 +123,7 @@ hub version 2.2.2 ## Set up your working copy -The working copy is set up locally on your computer. It's what you'll edit, compile, and end up pushing back to GitHub. The main steps are cloning the repository and creating your fork as a remote. +You set up the working copy of the repository locally on your computer. Your local copy of the files is what you'll edit, compile, and end up pushing back to GitHub. The main steps are cloning the repository and creating your fork as a remote. ### Clone the repository diff --git a/docs/content/en/functions/cond.md b/docs/content/en/functions/cond.md index 16c1f105f..72a9c0a9a 100644 --- a/docs/content/en/functions/cond.md +++ b/docs/content/en/functions/cond.md @@ -24,3 +24,9 @@ Example: ``` Would emit "goose" if the `$geese` array has exactly 1 item, or "geese" otherwise. + +{{% warning %}} +Whenever you use a `cond` function, *both* variable expressions are *always* evaluated. This means that a usage like `cond false (div 1 0) 27` will throw an error because `div 1 0` will be evaluated *even though the condition is false*. + +In other words, the `cond` function does *not* provide [short-circuit evaluation](https://en.wikipedia.org/wiki/Short-circuit_evaluation) and does *not* work like a normal [ternary operator](https://en.wikipedia.org/wiki/%3F:) that will pass over the first expression if the condition returns `false`. +{{% /warning %}}
\ No newline at end of file diff --git a/docs/content/en/getting-started/installing.md b/docs/content/en/getting-started/installing.md index bf0bde50d..7a81d097c 100644 --- a/docs/content/en/getting-started/installing.md +++ b/docs/content/en/getting-started/installing.md @@ -443,7 +443,7 @@ sudo apt-get install hugo * Might not be the latest version, especially if you are using an older, stable version (e.g., Ubuntu 16.04 LTS). Until backports and PPA are available, you may consider installing the Hugo snap package to get the latest version of Hugo. {{% note %}} -Hugo-as-a-snap can write only inside the user’s `$HOME` directory---and gvfs-mounted directories owned by the user---because of Snaps’ confinement and security model. More information is also available [in this related GitHub issue](https://github.com/gohugoio/hugo/issues/3143). Use ```sudo apt-get install hugo --classic``` to disable the default security model if you want hugo to be able to have write access in other paths besides the user’s `$HOME` directory. +Hugo-as-a-snap can write only inside the user’s `$HOME` directory---and gvfs-mounted directories owned by the user---because of Snaps’ confinement and security model. More information is also available [in this related GitHub issue](https://github.com/gohugoio/hugo/issues/3143). Use ```sudo snap install hugo --classic``` to disable the default security model if you want hugo to be able to have write access in other paths besides the user’s `$HOME` directory. {{% /note %}} ### Arch Linux diff --git a/docs/content/en/news/0.10-relnotes/index.md b/docs/content/en/news/0.10-relnotes/index.md new file mode 100644 index 000000000..060998ba0 --- /dev/null +++ b/docs/content/en/news/0.10-relnotes/index.md @@ -0,0 +1,21 @@ +--- +date: 2014-03-01T17:21:33Z +description: "Hugo 0.10 brings syntax highlighting (powered by Pygments), automatic table of contents generation, support for Unicode, and a lot more!" +title: "Hugo 0.10" +categories: ["Releases"] +--- + +- [Syntax highlighting](http://hugo.spf13.com/extras/highlighting) powered by pygments (**slow**) +- Ability to [sort content](http://hugo.spf13.com/content/ordering) many more ways +- Automatic [table of contents](http://hugo.spf13.com/extras/toc) generation +- Support for unicode URLs, aliases and indexes +- Configurable per-section [permalink](http://hugo.spf13.com/extras/permalinks) pattern support +- Support for [paired shortcodes](http://hugo.spf13.com/extras/shortcodes) +- Shipping with some [shortcodes](http://hugo.spf13.com/extras/shortcodes) (highlight & figure) +- Adding [canonify](http://hugo.spf13.com/extras/urls) option to keep URLs relative +- A bunch of [additional template functions](http://hugo.spf13.com/layouts/templatefunctions) +- Watching very large sites now works on mac +- RSS generation improved. Limited to 50 items by default, can limit further in [template](http://hugo.spf13.com/layout/rss) +- Boolean params now supported in [frontmatter](http://hugo.spf13.com/content/front-matter) +- Launched website [showcase](http://hugo.spf13.com/showcase). Show off your own hugo site! +- A bunch of [bug fixes](https://github.com/spf13/hugo/commits/master) diff --git a/docs/content/en/news/0.11-relnotes/index.md b/docs/content/en/news/0.11-relnotes/index.md new file mode 100644 index 000000000..dc4115fe0 --- /dev/null +++ b/docs/content/en/news/0.11-relnotes/index.md @@ -0,0 +1,23 @@ +--- +date: 2014-05-29T22:53:22Z +description: "Now 3–4 times faster, Hugo 0.11 brings live reload, theme engine, menu system, XML sitemap, and more!" +title: "Hugo 0.11" +categories: ["Releases"] +--- + +- Considerably faster... about 3 - 4x faster on average +- [Live Reload](/getting-started/usage/#livereload). Hugo will automatically reload the browser when the build is complete +- Theme engine w/[Theme Repository](http://github.com/spf13/hugoThemes) +- [Menu system](/content-management/menus/) with support for active page +- [Builders](/extras/builders) to quickly create a new site, content or theme +- [XML sitemap](/templates/sitemap) generation +- [Integrated Disqus](/extras/comments) support +- Streamlined [template organization](/templates/overview) +- Brand new docs site +- Support for publishDate which allows for posts to be dated in the future +- More [sort](/functions/sort/#readout) options +- Logging support +- Much better error handling +- More informative verbose output +- Renamed Indexes > [Taxonomies](/taxonomies/overview) +- Renamed Chrome > [Partials](/templates/partials) diff --git a/docs/content/en/news/0.12-relnotes/index.md b/docs/content/en/news/0.12-relnotes/index.md new file mode 100644 index 000000000..4401b5efc --- /dev/null +++ b/docs/content/en/news/0.12-relnotes/index.md @@ -0,0 +1,29 @@ +--- +date: 2015-01-21T20:35:00Z +description: "Hugo 0.12 focused on polishing the theme engine and adding critical functionality to the templates." +title: "Hugo 0.12" +categories: ["Releases"] +--- + +A lot has happened since Hugo v0.11.0 was released. Most of the work has been +focused on polishing the theme engine and adding critical functionality to the +templates. + +This release represents over 90 code commits from 28 different contributors. + +- 10 [new themes](https://github.com/spf13/hugoThemes) created by the community +- fully themable [partials](/templates/partials/) +- [404 template](/templates/404/) support in themes +- [shortcode](/extras/shortcodes/) support in themes +- [views](/templates/views/) support in themes +- inner [shortcode](/extras/shortcodes/) content now treated as markdown +- support for header ids in markdown (# header {#myid}) +- [where](/templates/lists/#where) template function to filter lists of content, taxonomies, etc +- [groupby](/templates/list) & [groupbydate](/templates/list) methods to group pages +- taxonomy [pages list](/taxonomies/methods/) now sortable, filterable, limitable & groupable +- general cleanup to taxonomies & documentation to make it more clear and consistent +- [showcase](/showcase/) returned and has been expanded +- pretty links now always have trailing slashes +- [baseurl](/overview/configuration/) can now include a subdirectory +- better feedback about draft & future post rendering +- a variety of improvements to [the website](/) diff --git a/docs/content/en/news/0.13-relnotes/index.md b/docs/content/en/news/0.13-relnotes/index.md new file mode 100644 index 000000000..198f5fe7b --- /dev/null +++ b/docs/content/en/news/0.13-relnotes/index.md @@ -0,0 +1,95 @@ +--- +date: 2015-02-22T04:10:06Z +description: "Hugo 0.13 is the largest Hugo release to date. The release introduced some long sought after features (pagination, sequencing, data loading, tons of template improvements) as well as major internal improvements. In addition to the code changes, the Hugo community has grown significantly and now has over 3000 stars on GitHub, 134 contributors, 24 themes and 1000s of happy users." +title: "Hugo 0.13" +categories: ["Releases"] +--- + +The v0.13.0 release is the largest Hugo release to date. The release introduced +some long sought after features (pagination, sequencing, data loading, tons of +template improvements) as well as major internal improvements. In addition to +the code changes, the Hugo community has grown significantly and now has over +3000 stars on GitHub, 134 contributors, 24 themes and 1000s of happy users. + +This release represents **448 contributions by 65 contributors** + +A special shout out to [@bep](https://github.com/bep) and +[@anthonyfok](https://github.com/anthonyfok) for their new role as Hugo +maintainers and their tremendous contributions this release. + +### New major features +- Support for [data files](http://gohugo.io/extras/datafiles/) in [YAML](http://yaml.org/), + [JSON](http://www.json.org/), or [TOML](https://github.com/toml-lang/toml) + located in the `data` directory ([#885 |