From 2c0d1ccdcd95de0bddeb39dca2e4d08f0d8056d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Fri, 21 Jul 2017 11:00:08 +0200 Subject: [PATCH] Squashed 'docs/' changes from b0470688..73f355ce 73f355ce Update theme 83ff50c2 Use example.com in examples 71292134 Add alias news > release-notes 2e15f642 Update theme 8eef09d2 Add Pygments configuration 572b9e75 Clean up the code shortcode use a1b2fd3b Remove the code fence language codes 1473b1d9 Remove redundant text b92c2042 Update theme 8f439c28 Edit contributing section in README 8bcf8a19 Add contributing section to README 4c44ee1c Fix broken content file 2bdc7710 Clarify .Data.Pages sorting in lists.md 092271c2 Use infinitive mood for main titles b9b8abef Update theme to reflect change to home page content b897b71b Change copy to use sentence case fd675ee5 Enable RSS feed for sections 060a5e27 Correct movie title in taxonomies.md 6a5ca96a Update displayed site name for Hub 22f4b7a4 Add example of starting up the local server d9612cb3 Update theme a8c3988a Update theme 4198189d Update theme 12d6b016 Update theme 2b1c4197 Update theme b6d90a1e Fix News release titles cfe751db Add some build info to README git-subtree-dir: docs git-subtree-split: 73f355ce0dd88d032062ea70067431ab980cdd8d --- README.md | 39 +++- config.toml | 9 + content/_index.md | 2 +- content/about/license.md | 6 +- content/content-management/archetypes.md | 44 ++--- content/content-management/authors.md | 32 ++- content/content-management/comments.md | 4 +- .../content-management/cross-references.md | 24 ++- content/content-management/formats.md | 28 +-- content/content-management/front-matter.md | 8 +- content/content-management/menus.md | 18 +- content/content-management/multilingual.md | 26 +-- content/content-management/organization.md | 56 +++--- content/content-management/sections.md | 28 +-- content/content-management/shortcodes.md | 102 ++++------ content/content-management/summaries.md | 6 +- content/content-management/taxonomies.md | 20 +- content/content-management/toc.md | 14 +- content/content-management/types.md | 6 +- content/content-management/urls.md | 84 ++++---- content/contribute/_index.md | 4 +- content/contribute/development.md | 60 +++--- content/contribute/documentation.md | 74 +++---- content/contribute/themes.md | 16 +- content/functions/GetPage.md | 6 +- content/functions/abslangurl.md | 6 +- content/functions/absurl.md | 12 +- content/functions/adddate.md | 8 +- content/functions/after.md | 10 +- content/functions/apply.md | 26 +-- content/functions/base64.md | 10 +- content/functions/chomp.md | 2 +- content/functions/countrunes.md | 2 +- content/functions/countwords.md | 2 +- content/functions/default.md | 34 ++-- content/functions/delimit.md | 22 +-- content/functions/dict.md | 12 +- content/functions/findRe.md | 2 +- content/functions/first.md | 2 +- content/functions/format.md | 2 +- content/functions/i18n.md | 2 +- content/functions/imageConfig.md | 2 +- content/functions/index-function.md | 8 +- content/functions/intersect.md | 8 +- content/functions/len.md | 12 +- content/functions/math.md | 12 +- content/functions/md5.md | 4 +- content/functions/now.md | 4 +- content/functions/partialCached.md | 8 +- content/functions/printf.md | 2 +- content/functions/querify.md | 4 +- content/functions/readfile.md | 2 +- content/functions/ref.md | 2 +- content/functions/relLangURL.md | 6 +- content/functions/relref.md | 2 +- content/functions/relurl.md | 12 +- content/functions/render.md | 2 +- content/functions/replacere.md | 2 +- content/functions/safeHTML.md | 6 +- content/functions/safeHTMLAttr.md | 2 +- content/functions/safeURL.md | 22 +-- content/functions/seq.md | 4 +- content/functions/sha.md | 4 +- content/functions/shuffle.md | 8 +- content/functions/slice.md | 6 +- content/functions/sort.md | 2 +- content/functions/time.md | 6 +- content/functions/union.md | 4 +- content/functions/uniq.md | 2 +- content/functions/unix.md | 6 +- content/functions/urlize.md | 14 +- content/functions/where.md | 26 ++- content/functions/with.md | 6 +- content/getting-started/_index.md | 4 +- content/getting-started/configuration.md | 40 ++-- .../getting-started/directory-structure.md | 2 +- content/getting-started/installing.md | 66 +++---- content/getting-started/quick-start.md | 124 +++++------- content/getting-started/usage.md | 20 +- .../deployment-with-rsync.md | 16 +- .../deployment-with-wercker.md | 68 +++---- .../hosting-on-bitbucket.md | 16 +- .../hosting-on-firebase.md | 16 +- .../hosting-on-github.md | 30 ++- .../hosting-on-gitlab.md | 14 +- .../hosting-on-netlify.md | 8 +- content/news/0-16.md | 2 +- content/news/0-17.md | 2 +- content/news/0-18.md | 2 +- content/news/0-19.md | 2 +- content/news/0-20-1.md | 2 +- content/news/0-20-2.md | 2 +- content/news/0-20-3.md | 2 +- content/news/0-20-4.md | 2 +- content/news/0-20-5.md | 2 +- content/news/0-20-6.md | 2 +- content/news/0-20-7.md | 2 +- content/news/0-20.md | 2 +- content/news/0-21.md | 2 +- content/news/0-22-1.md | 6 +- content/news/0-22.md | 4 +- content/news/0-23.md | 2 +- content/news/0-24-1.md | 2 +- content/news/0-24.md | 6 +- content/news/0-25-1.md | 2 +- content/news/0-25.md | 4 +- content/news/_index.md | 1 + content/news/release-notes.md | 8 +- content/readfiles/bfconfig.md | 4 +- content/templates/404.md | 8 +- content/templates/alternatives.md | 2 +- content/templates/base.md | 20 +- content/templates/data-templates.md | 16 +- content/templates/files.md | 20 +- content/templates/homepage.md | 6 +- content/templates/internal.md | 22 +-- content/templates/introduction.md | 98 ++++----- content/templates/lists.md | 186 ++++++------------ content/templates/lookup-order.md | 20 +- content/templates/menu-templates.md | 12 +- content/templates/ordering-and-grouping.md | 148 +++++--------- content/templates/output-formats.md | 10 +- content/templates/pagination.md | 6 +- content/templates/partials.md | 14 +- content/templates/robots.md | 8 +- content/templates/rss.md | 10 +- content/templates/section-templates.md | 16 +- content/templates/shortcode-templates.md | 100 ++++------ content/templates/single-page-templates.md | 6 +- content/templates/sitemap-template.md | 4 +- content/templates/taxonomy-templates.md | 34 ++-- content/templates/template-debugging.md | 12 +- content/templates/views.md | 22 +-- content/themes/creating.md | 6 +- content/themes/customizing.md | 12 +- content/themes/installing-and-using-themes.md | 20 +- content/tools/syntax-highlighting.md | 22 +-- content/troubleshooting/_index.md | 4 +- .../accented-characters-in-urls.md | 2 +- content/troubleshooting/eof-error.md | 2 +- content/variables/page.md | 18 +- content/variables/site.md | 8 +- content/variables/taxonomy.md | 6 +- layouts/shortcodes/code.html | 8 +- requirements.txt | 1 + themes/gohugoioTheme | 2 +- 146 files changed, 1037 insertions(+), 1443 deletions(-) create mode 100644 requirements.txt diff --git a/README.md b/README.md index 60a554e54..eba081c96 100644 --- a/README.md +++ b/README.md @@ -2,12 +2,37 @@ Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in GoLang. -## Branches +## Contributing -* The `master` branch is the **current Hugo version** and will be auto-deployed to [gohugo.io/](https://gohugo.io/). -* Anything not relevant to the current Hugo version goes into the `dev` branch. -* Changes in [hugo/docs](https://github.com/gohugoio/hugo/tree/master/docs) will, in general, be merged once every release, but can be manually merged/cherry picked if needed. This goes both ways. -* All contributions that is not tightly coupled with code changes, should be made directly to `hugoDocs`. -* But we also merge PRs into [hugo/docs](https://github.com/gohugoio/hugo/tree/master/docs), but preferably changes that is related to the code in the PR itself +We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you. -To summarize, we have two branches in this repository: `master` (current Hugo) and `dev` (next Hugo). +Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository. + +*Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.* + + +## Build + +To view the documentation site locally, you need to clone this repository with submodules: + +```bash +git clone --recursive https://github.com/gohugoio/hugoDocs.git +``` + +Or if you already have a clone locally: + +```bash +git submodule update --init +``` +Also note that the documentation version for a given version of Hugo can also be found in the `/docs` sub-folder of the [Hugo source repository](https://github.com/gohugoio/hugo). + +Then to view the docs in your browser, run Hugo and open up the link: +```bash +hugo serve +Started building sites ... +. +. +Serving pages from memory +Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) +Press Ctrl+C to stop +``` diff --git a/config.toml b/config.toml index aafb6aa00..08c72176f 100644 --- a/config.toml +++ b/config.toml @@ -16,8 +16,17 @@ pluralizeListTitles = false # We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below). disableAliases = true + +# Highlighting config (Pygments) +# It is (currently) not in use, but you can do ```go in a content file if you want to. +pygmentsCodeFences = true + +# See https://help.farbox.com/pygments.html +pygmentsStyle = "friendly" + [outputs] home = [ "HTML", "RSS", "REDIR" ] +section = [ "HTML", "RSS"] [mediaTypes] [mediaTypes."text/netlify"] diff --git a/content/_index.md b/content/_index.md index f23aa99e9..3f9ad64a4 100644 --- a/content/_index.md +++ b/content/_index.md @@ -29,7 +29,7 @@ features: - heading: Custom Outputs image_path: /images/icon-custom-outputs.svg - tagline: HTML not Enough? + tagline: HTML not enough? copy: Hugo allows you to output your content in multiple formats, including JSON or AMP, and makes it easy to create your own. sections: - heading: "100s of Themes" diff --git a/content/about/license.md b/content/about/license.md index 037e62e9b..7575b79c8 100644 --- a/content/about/license.md +++ b/content/about/license.md @@ -148,8 +148,7 @@ _END OF TERMS AND CONDITIONS_ To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives. -{{% code file="apache-notice.txt" download="apache-notice.txt" %}} -``` +{{< code file="apache-notice.txt" download="apache-notice.txt" >}} Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); @@ -163,5 +162,4 @@ distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -``` -{{% /code %}} +{{< /code >}} diff --git a/content/content-management/archetypes.md b/content/content-management/archetypes.md index d6d30b3f3..9fc58139b 100644 --- a/content/content-management/archetypes.md +++ b/content/content-management/archetypes.md @@ -31,17 +31,15 @@ See above The `hugo new` generator for archetypes assumes your working directory is the content folder at the root of your project. Hugo is able to infer the appropriate archetype by assuming the content type from the content section passed to the CLI command: -```bash +``` hugo new / ``` We can use this pattern to create a new `.md` file in the `posts` section: -{{% code file="archetype-example.sh" %}} -```bash +{{< code file="archetype-example.sh" >}} hugo new posts/my-first-post.md -``` -{{% /code %}} +{{< /code >}} {{% note "Override Content Type in a New File" %}} To override the content type Hugo infers from `[content-section]`, add the `--kind` flag to the end of the `hugo new` command. @@ -50,7 +48,7 @@ To override the content type Hugo infers from `[content-section]`, add the `--ki Running this command in a new site that does not have default or custom archetypes will create the following file: {{% output file="content/posts/my-first-post.md" %}} -```toml +``` +++ date = "2017-02-01T19:20:04-07:00" title = "my first post" @@ -100,14 +98,12 @@ When you create a new Hugo project using `hugo new site`, you'll notice that Hug The following examples are from a site that's using `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category. -{{% code file="archetypes/default.md" %}} -```toml +{{< code file="archetypes/default.md" >}} +++ tags = ["golang", "hugo"] categories = ["web development"] +++ -``` -{{% /code %}} +{{< /code >}} {{% warning "EOL Characters in Text Editors"%}} If you get an `EOF error` when using `hugo new`, add a carriage return after the closing `+++` or `---` for your TOML or YAML front matter, respectively. (See the [troubleshooting article on EOF errors](/troubleshooting/eof-error/) for more information.) @@ -117,16 +113,14 @@ If you get an `EOF error` when using `hugo new`, add a carriage return after the With an `archetypes/default.md` in place, we can use the CLI to create a new post in the `posts` content section: -{{% code file="new-post-from-default.sh" %}} -```bash +{{< code file="new-post-from-default.sh" >}} $ hugo new posts/my-new-post.md -``` -{{% /code %}} +{{< /code >}} Hugo then creates a new markdown file with the following front matter: {{% output file="content/posts/my-new-post.md" %}} -```toml +``` +++ categories = ["web development"] date = "2017-02-01T19:20:04-07:00" @@ -148,30 +142,26 @@ Suppose your site's `posts` section requires more sophisticated front matter tha ### Create a Custom Archetype -{{% code file="archetypes/posts.md"%}} -```toml +{{< code file="archetypes/posts.md">}} +++ description = "" tags = "" categories = "" +++ -``` -{{% /code %}} +{{< /code >}} ### Use a Custom Archetype With an `archetypes/posts.md` in place, you can use the Hugo CLI to create a new post with your preconfigured front matter in the `posts` content section: -{{% code file="new-post-from-custom.sh" %}} -```bash +{{< code file="new-post-from-custom.sh" >}} $ hugo new posts/post-from-custom.md -``` -{{% /code %}} +{{< /code >}} This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`: {{% output file="content/posts/post-from-custom-archetype.md" %}} -```toml +``` +++ categories = "" date = 2017-02-13T17:24:43-08:00 @@ -186,11 +176,9 @@ title = "post from custom archetype" As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs: -{{% code file="archetypes/functions.md" %}} -```yaml +{{< code file="archetypes/functions.md" >}} {{< readfile file="/themes/gohugoioTheme/archetypes/functions.md" >}} -``` -{{% /code %}} +{{< /code >}} {{% note %}} The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/files/). diff --git a/content/content-management/authors.md b/content/content-management/authors.md index 80a783912..0a0d1799d 100644 --- a/content/content-management/authors.md +++ b/content/content-management/authors.md @@ -30,8 +30,7 @@ You can create a profile containing metadata for each author on your website. Th Let's suppose Alice Allison is a blogger. A simple unique identifier would be `alice`. Now, we have to create a file called `alice.toml` in the `data/_authors/` directory. The following example is the standardized template written in TOML: -{{% code file="data/_authors/alice.toml" %}} -```toml +{{< code file="data/_authors/alice.toml" >}} givenName = "Alice" # or firstName as alias familyName = "Allison" # or lastName as alias displayName = "Alice Allison" @@ -50,8 +49,7 @@ weight = 10 [params] random = "whatever you want" -``` -{{% /code %}} +{{< /code >}} All variables are optional but it's advised to fill all important ones (e.g. names and biography) because themes can vary in their usage. @@ -67,7 +65,7 @@ The `params` section can contain arbitrary data much like the same-named section Earlier it was mentioned that content can be associated with an author through their corresponding identifier. In our case, blogger Alice has the identifier `alice`. In the front matter of a content file, you can create a list of identifiers and assign it to the `authors` variable. Here are examples for `alice` using YAML and TOML, respectively. -```yaml +``` --- title: Why Hugo is so Awesome date: 2016-08-22T14:27:502:00 @@ -77,7 +75,7 @@ authors: ["alice"] Nothing to read here. Move along... ``` -```toml +``` +++ title = Why Hugo is so Awesome date = "2016-08-22T14:27:502:00" @@ -116,8 +114,7 @@ This is can be done with the `.Social.URL` function. Its only parameter is the n Most articles feature a small section with information about the author at the end. Let's create one containing the author's name, a thumbnail, a (summarized) biography and links to all social networks: -{{% code file="layouts/partials/author-info.html" download="author-info.html" %}} -```html +{{< code file="layouts/partials/author-info.html" download="author-info.html" >}} {{ with .Author }}

{{ .DisplayName }}

{{ .DisplayName }} @@ -128,8 +125,7 @@ Most articles feature a small section with information about the author at the e {{ end }} {{ end }} -``` -{{% /code %}} +{{< /code >}} ## Who Published What? @@ -137,12 +133,12 @@ That question can be answered with a list of all authors and another list contai In order to let Hugo know that we want to group content based on their author, we have to create a new taxonomy called `author` (the name corresponds to the variable in the front matter). Here is the snippet in a `config.yaml` and `config.toml`, respectively: -```yaml +``` taxonomies: author: authors ``` -```toml +``` [taxonomies] author = "authors" ``` @@ -152,8 +148,7 @@ taxonomies: In the next step we can create a template to list all authors of your website. Later, the list can be accessed at `www.example.com/authors/`. Create a new template in the `layouts/taxonomy/` directory called `authors.term.html`. This template will be exclusively used for this taxonomy. -{{% code file="layouts/taxonomy/author.term.html" download="author.term.html" %}} -```html +{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}}
    {{ range $author, $v := .Data.Terms }} {{ $profile := $.Authors.Get $author }} @@ -164,8 +159,7 @@ In the next step we can create a template to list all authors of your website. L {{ end }}
-``` -{{% /code %}} +{{< /code >}} `.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically). @@ -175,15 +169,13 @@ Last but not least, we have to create the second list that contains all publicat The layout for this page can be defined in the template `layouts/taxonomy/author.html`. -{{% code file="layouts/taxonomy/author.html" download="author.html" %}} -```html +{{< code file="layouts/taxonomy/author.html" download="author.html" >}} {{ range .Data.Pages }}

{{ .Title }}

written by {{ .Author.DisplayName }} {{ .Summary }} {{ end }} -``` -{{% /code %}} +{{< /code >}} The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags. diff --git a/content/content-management/comments.md b/content/content-management/comments.md index 33387e570..2db449738 100644 --- a/content/content-management/comments.md +++ b/content/content-management/comments.md @@ -29,11 +29,11 @@ Hugo comes with all the code you need to load Disqus into your templates. Before Disqus comments require you set a single value in your [site's configuration file][configuration]. The following show the configuration variable in a `config.toml` and `config.yml`, respectively: -```toml +``` disqusShortname = "yourdiscussshortname" ``` -```yaml +``` disqusShortname: "yourdiscussshortname" ``` diff --git a/content/content-management/cross-references.md b/content/content-management/cross-references.md index 9a2795330..7ee81f3db 100644 --- a/content/content-management/cross-references.md +++ b/content/content-management/cross-references.md @@ -20,7 +20,7 @@ toc: true ## Use `ref` and `relref` -```md +``` {{}} {{}} {{}} @@ -35,14 +35,14 @@ The single parameter to `ref` is a string with a content `documentname` (e.g., ` 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: -```md +``` {{}} => `/blog/post/` {{}} => `/blog/post/` ``` 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: -```bash +``` . └── content ├── events @@ -57,16 +57,14 @@ If you have the same filename used across multiple sections, you should only use To be sure to get the correct reference in this case, use the full path: -{{% code file="content/meta/my-article.md" copy="false" %}} -```md +{{< code file="content/meta/my-article.md" copy="false" >}} {{}} => /events/my-birthday/ -``` -{{% /code %}} +{{< /code >}} {{< todo >}}Remove this warning when https://github.com/gohugoio/hugo/issues/3703 is released.{{< /todo >}} A relative document name must *not* begin with a slash (`/`). -```md +``` {{}} => "" ``` @@ -82,14 +80,14 @@ If the page exists in multiple [output formats][], `ref` or `relref` can be used 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: -```md +``` {{}} => #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 -```md +``` {{}} => #who:9decaf7 {{}} => /blog/post/#who:badcafe ``` @@ -98,8 +96,8 @@ More information about document unique identifiers and headings can be found [be ### Examples -* `{{}}` => `http://yoursite.com/blog/post/` -* `{{}}` => `http://yoursite.com/blog/post/#tldr:caffebad` +* `{{}}` => `http://example.com/blog/post/` +* `{{}}` => `http://example.com/blog/post/#tldr:caffebad` * `{{}}` => `/blog/post/` * `{{}}` => `/blog/post/#tldr:caffebad` * `{{}}` => `#tldr:badcaffe` @@ -113,7 +111,7 @@ 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.) -```md +``` {{}} /content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242 ``` diff --git a/content/content-management/formats.md b/content/content-management/formats.md index ae6276db3..be84e7cf4 100644 --- a/content/content-management/formats.md +++ b/content/content-management/formats.md @@ -41,20 +41,18 @@ Hugo supports [GitHub-styled task lists (i.e., TODO lists)][gfmtasks] for the Bl #### Example Task List Input -{{% code file="content/my-to-do-list.md" %}} -```markdown +{{< code file="content/my-to-do-list.md" >}} - [ ] a task list item - [ ] list syntax required - [ ] incomplete - [x] completed -``` -{{% /code %}} +{{< /code >}} #### Example Task List Output The preceding markdown produces the following HTML in your rendered website: -```html +```
  • a task list item
  • list syntax required
    • @@ -98,7 +96,7 @@ As Hugo ships with Mmark, using the syntax is as easy as changing the extension In the event that you want to only use Mmark in specific files, you can also define the Mmark syntax in your content's front matter: -```yaml +``` --- title: My Post date: 2017-04-01 @@ -120,12 +118,10 @@ This is not an introduction into actually using MathJax to render typeset mathem The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventurous readers can consult the [Loading and Configuring](http://docs.mathjax.org/en/latest/configuration.html) section of the MathJax documentation for additional methods of including MathJax), but the easiest way is to use the secure MathJax CDN by include a ` -``` -{{% /code %}} +{{< /code >}} One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/partials/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website. @@ -149,8 +145,7 @@ There are multiple ways to remedy this problem. One solution is to simply escape Another option is to tell Markdown to treat the MathJax code as verbatim code and not process it. One way to do this is to wrap the math expression inside a `
    ` `
    ` block. Markdown would ignore these sections and they would get passed directly on to MathJax and processed correctly. This works great for display style mathematics, but for inline math expressions the line break induced by the `
    ` is not acceptable. The syntax for instructing Markdown to treat inline text as verbatim is by wrapping it in backticks (`` ` ``). You might have noticed, however, that the text included in between backticks is rendered differently than standard text (on this site these are items highlighted in red). To get around this problem, we could create a new CSS entry that would apply standard styling to all inline verbatim text that includes MathJax code. Below I will show the HTML and CSS source that would accomplish this (note this solution was adapted from [this blog post](http://doswa.com/2011/07/20/mathjax-in-markdown.html)---all credit goes to the original author). -{{% code file="mathjax-markdown-solution.html" %}} -```js +{{< code file="mathjax-markdown-solution.html" >}} -``` -{{% /code %}} +{{< /code >}} As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page. -{{% code file="mathjax-style.css" %}} -```css +{{< code file="mathjax-style.css" >}} code.has-jax { font: inherit; font-size: 100%; @@ -192,8 +185,7 @@ code.has-jax { border: inherit; color: #515151; } -``` -{{% /code %}} +{{< /code >}} In the CSS snippet, notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my CSS. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body. diff --git a/content/content-management/front-matter.md b/content/content-management/front-matter.md index 104050cf3..070328670 100644 --- a/content/content-management/front-matter.md +++ b/content/content-management/front-matter.md @@ -34,7 +34,7 @@ JSON ### TOML Example -```toml +``` +++ title = "spf13-vim 3.0 release and new website" description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." @@ -50,7 +50,7 @@ slug = "spf13-vim-3-0-release-and-new-website" ### YAML Example -```yaml +``` --- title: "spf13-vim 3.0 release and new website" description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." @@ -66,7 +66,7 @@ slug: "spf13-vim-3-0-release-and-new-website" ### JSON Example -```json +``` { "title": "spf13-vim 3.0 release and new website", "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.", @@ -154,7 +154,7 @@ You can add fields to your front matter arbitrarily to meet your needs. These us The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates. -```yaml +``` include_toc: true show_comments: false ``` diff --git a/content/content-management/menus.md b/content/content-management/menus.md index ddcf3002e..7c877afc8 100644 --- a/content/content-management/menus.md +++ b/content/content-management/menus.md @@ -88,7 +88,7 @@ If all you need to do is add an entry to a menu, the simple form works well. #### A Single Menu -```yaml +``` --- menu: "main" --- @@ -96,7 +96,7 @@ menu: "main" #### Multiple Menus -```yaml +``` --- menu: ["main", "footer"] --- @@ -105,7 +105,7 @@ menu: ["main", "footer"] #### Advanced -```yaml +``` --- menu: docs: @@ -120,8 +120,7 @@ You can also add entries to menus that aren’t attached to a piece of content. Here’s an example snippet pulled from a `config.toml`: -{{% code file="config.toml" %}} -```toml +{{< code file="config.toml" >}} [[menu.main]] name = "about hugo" pre = "" @@ -133,13 +132,11 @@ Here’s an example snippet pulled from a `config.toml`: pre = "" weight = -100 url = "/getting-started/" -``` -{{% /code %}} +{{< /code >}} Here's the equivalent snippet in a `config.yaml`: -{{% code file="config.yml" %}} -```yaml +{{< code file="config.yml" >}} --- menu: docs: @@ -153,8 +150,7 @@ menu: Weight: -100 URL: "/getting-started/" --- -``` -{{% /code %}} +{{< /code >}} {{% note %}} The URLs must be relative to the context root. If the `baseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the value used for `URL` in the above example is `http://subdomain.example.com/`, the output will be `http://subdomain.example.com`. diff --git a/content/content-management/multilingual.md b/content/content-management/multilingual.md index 58644640d..e3c65a26d 100644 --- a/content/content-management/multilingual.md +++ b/content/content-management/multilingual.md @@ -23,8 +23,7 @@ You should define the available languages in a `Languages` section in your site The following is an example of a TOML site configuration for a multilingual Hugo project: -{{% code file="config.toml" download="config.toml" %}} -```toml +{{< code file="config.toml" download="config.toml" >}} DefaultContentLanguage = "en" copyright = "Everything is mine" @@ -46,8 +45,7 @@ weight = 2 linkedin = "lien-francais" [Languages.fr.navigation] help = "Aide" -``` -{{% /code %}} +{{< /code >}} Anything not defined in a `[Languages]` block will fall back to the global value for that key (e.g., `copyright` for the English [`en`] language). @@ -66,8 +64,7 @@ Only the obvious non-global options can be overridden per language. Examples of Taxonomies and [Blackfriday configuration][config] can also be set per language: -{{% code file="bf-config.toml" %}} -```toml +{{< code file="bf-config.toml" >}} [Taxonomies] tag = "tags" @@ -87,8 +84,7 @@ weight = 2 title = "Français" [Languages.fr.Taxonomies] plaque = "plaques" -``` -{{% /code %}} +{{< /code >}} ## Translate Your Content @@ -110,7 +106,7 @@ By having the same *base filename*, the content pieces are linked together as tr If you need distinct URLs per language, you can set the slug in the non-default language file. For example, you can define a custom slug for a French translation in the front matter of `content/about.fr.md` as follows: -```yaml +``` slug: "a-propos" ``` @@ -127,8 +123,7 @@ We will fix this in https://github.com/gohugoio/hugo/issues/2699 To create a list of links to translated content, use a template similar to the following: -{{% code file="layouts/partials/i18nlist.html" %}} -```html +{{< code file="layouts/partials/i18nlist.html" >}} {{ if .IsTranslated }}

    {{ i18n "translations" }}

      @@ -139,8 +134,7 @@ To create a list of links to translated content, use a template similar to the f {{ end}}
    {{ end }} -``` -{{% /code %}} +{{< /code >}} The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page, or if there are translations---in the case of the homepage, section listing, etc.---a site with only render one language. @@ -191,7 +185,7 @@ And then in the template: ``` To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: -```bash +``` hugo --i18n-warnings | grep i18n i18n|MISSING_TRANSLATION|en|wordCount ``` @@ -229,7 +223,7 @@ This technique extracts the day, month and year by specifying ``.Date.Day``, ``. You can define your menus for each language independently. The [creation of a menu][menus] works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file: -```toml +``` defaultContentLanguage = "en" [languages.en] @@ -254,7 +248,7 @@ weight = 0 The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version as the default content language that resides in the root directory. -```html +```
      {{- $currentPage := . -}} {{ range .Site.Menus.main -}} diff --git a/content/content-management/organization.md b/content/content-management/organization.md index 2f6e20740..33780c0eb 100644 --- a/content/content-management/organization.md +++ b/content/content-management/organization.md @@ -34,20 +34,20 @@ While Hugo supports content nested at any level, the top levels (i.e. `content/< . └── content └── about - | └── _index.md // <- http://yoursite.com/about/ + | └── _index.md // <- http://example.com/about/ ├── post - | ├── firstpost.md // <- http://yoursite.com/post/firstpost/ + | ├── firstpost.md // <- http://example.com/post/firstpost/ | ├── happy - | | └── ness.md // <- http://yoursite.com/post/happy/ness/ - | └── secondpost.md // <- http://yoursite.com/post/secondpost/ + | | └── ness.md // <- http://example.com/post/happy/ness/ + | └── secondpost.md // <- http://example.com/post/secondpost/ └── quote - ├── first.md // <- http://yoursite.com/quote/first/ - └── second.md // <- http://yoursite.com/quote/second/ + ├── first.md // <- http://example.com/quote/first/ + └── second.md // <- http://example.com/quote/second/ ``` ## Path Breakdown in Hugo -The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "http://yoursite.com"` in your [site's configuration file][config]. +The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "http://example.com"` in your [site's configuration file][config]. ### Index Pages: `_index.md` @@ -56,7 +56,7 @@ The following demonstrates the relationships between your content organization a You can keep one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website: -```bash +``` . url . ⊢--^-⊣ . path slug @@ -68,7 +68,7 @@ content/posts/_index.md At build, this will output to the following destination with the associated values: -```bash +``` url ("/posts/") ⊢-^-⊣ @@ -76,7 +76,7 @@ At build, this will output to the following destination with the associated valu ⊢--------^---------⊣⊢-^-⊣ permalink ⊢----------^-------------⊣ -http://yoursite.com/posts/index.html +http://example.com/posts/index.html ``` ### Single Pages in Sections @@ -84,7 +84,7 @@ http://yoursite.com/posts/index.html Single content files in each of your sections are going to be rendered as [single page templates][singles]. Here is an example of a single `post` within `posts`: -```bash +``` path ("posts/my-first-hugo-post.md") . ⊢-----------^------------⊣ . section slug @@ -94,7 +94,7 @@ content/posts/my-first-hugo-post.md At the time Hugo builds your site, the content will be output to the following destination: -```bash +``` url ("/posts/my-first-hugo-post/") ⊢------------^----------⊣ @@ -102,7 +102,7 @@ At the time Hugo builds your site, the content will be output to the following d ⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣ permalink ⊢--------------------^---------------------⊣ -http://yoursite.com/posts/my-first-hugo-post/index.html +http://example.com/posts/my-first-hugo-post/index.html ``` ### Section with Nested Directories @@ -110,7 +110,7 @@ http://yoursite.com/posts/my-first-hugo-post/index.html To continue the example, the following demonstrates destination paths for a file located at `content/events/chicago/lollapalooza.md` in the same site: -```bash +``` section ⊢--^--⊣ url @@ -120,7 +120,7 @@ To continue the example, the following demonstrates destination paths for a file ⊢--------^--------⊣ ⊢------^-----⊣⊢----^------⊣ permalink ⊢----------------------^-----------------------⊣ -http://yoursite.com/events/chicago/lollapalooza/ +http://example.com/events/chicago/lollapalooza/ ``` {{% note %}} @@ -166,25 +166,23 @@ The following items are defined in this order for a specific reason: items expla ### `filename` -This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `yoursite.com/posts/my-post/`). +This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `example.com/posts/my-post/`). ### `slug` When defined in the front matter, the `slug` can take the place of the filename for the destination. -{{% code file="content/posts/old-post.md" %}} -```yaml +{{< code file="content/posts/old-post.md" >}} --- title: New Post slug: "new-post" --- -``` -{{% /code %}} +{{< /code >}} This will render to the following destination according to Hugo's default behavior: ``` -yoursite.com/posts/new-post/ +example.com/posts/new-post/ ``` ### `section` @@ -195,15 +193,13 @@ yoursite.com/posts/new-post/ A content's `type` is also determined by its location on disk but, unlike `section`, it *can* be specified in the front matter. See [types][]. This can come in especially handy when you want a piece of content to render using a different layout. In the following example, you can create a layout at `layouts/new/mylayout.html` that Hugo will use to render this piece of content, even in the midst of many other posts. -{{% code file="content/posts/my-post.md" %}} -```yaml +{{< code file="content/posts/my-post.md" >}} --- title: My Post type: new layout: mylayout --- -``` -{{% /code %}} +{{< /code >}} @@ -73,8 +72,7 @@ You can show content summaries with the following code. You could use the follow {{ end }} {{ end }} -``` -{{% /code %}} +{{< /code >}} Note how the `.Truncated` boolean valuable may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article. diff --git a/content/content-management/taxonomies.md b/content/content-management/taxonomies.md index 78317d9f2..fcefa5c80 100644 --- a/content/content-management/taxonomies.md +++ b/content/content-management/taxonomies.md @@ -52,7 +52,7 @@ To continue with the example of a movie site, the following demonstrates content ``` Actor <- Taxonomy Bruce Willis <- Term - The Six Sense <- Content + The Sixth Sense <- Content Unbreakable <- Content Moonrise Kingdom <- Content Samuel L. Jackson <- Term @@ -86,7 +86,7 @@ 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: -```toml +``` disableKinds = ["taxonomy","taxonomyTerm"] ``` @@ -94,7 +94,7 @@ disableKinds = ["taxonomy","taxonomyTerm"] When taxonomies are used---and [taxonomy templates][] are provided---Hugo will automatically create both a page listing all the taxonomy's terms and individual pages with lists of content associated with each term. For example, a `categories` taxonomy declared in your your configuration and used in your content front matter will create the following pages: -* A single page at `yoursite.com/categories/` that lists all the [terms within the taxonomy][] +* 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 @@ -103,7 +103,7 @@ Taxonomies must be defined in your [website configuration][config] before they c ### Example: TOML Taxonomy Configuration -```toml +``` [taxonomies] tag = "tags" category = "categories" @@ -112,7 +112,7 @@ Taxonomies must be defined in your [website configuration][config] before they c ### Example: YAML Taxonomy Configuration -```yaml +``` taxonomies: tag: "tags" category: "categories" @@ -145,7 +145,7 @@ If you would like the ability to quickly generate content files with preconfigur ### Example: TOML Front Matter with Taxonomies -```toml +``` +++ title = "Hugo: A fast and flexible static site generator" tags = [ "Development", "Go", "fast", "Blogging" ] @@ -158,7 +158,7 @@ project_url = "https://github.com/gohugoio/hugo" ### Example: YAML Front Matter with Taxonomies -```yaml +``` --- title: "Hugo: A fast and flexible static site generator" #tags: ["Development", "Go", "fast", "Blogging"] @@ -171,7 +171,7 @@ project_url: "https://github.com/gohugoio/hugo" ### Example: JSON Front Matter with Taxonomies -```json +``` { "title": "Hugo: A fast and flexible static site generator", "tags": [ @@ -199,7 +199,7 @@ The following TOML and YAML examples show a piece of content that has a weight o ### Example: TOML Taxonomic `weight` -```toml +``` +++ title = "foo" tags = [ "a", "b", "c" ] @@ -211,7 +211,7 @@ categories_weight = 44 ### Example: YAML Taxonomic `weight` -```yaml +``` --- title: foo #tags: [ "a", "b", "c" ] diff --git a/content/content-management/toc.md b/content/content-management/toc.md index de4d9266a..13da764dc 100644 --- a/content/content-management/toc.md +++ b/content/content-management/toc.md @@ -25,7 +25,7 @@ Currently, the `{{.TableOfContents}}` [page variable](/variables/page/) does not Create your markdown the way you normally would with the appropriate headings. Here is some example content: -```md +``` ## Introduction @@ -49,8 +49,7 @@ The built-in `.TableOfContents` variables outputs a `
    -``` -{{% /code %}} +{{< /code >}} ### List Pages Without `_index.md` @@ -147,8 +141,7 @@ You do *not* have to create an `_index.md` file for every list page (i.e. sectio Using this same `layouts/_default/list.html` template and applying it to the the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from: -{{% code file="yoursite.com/quote/index.html" copy="false" %}} -```html +{{< code file="example.com/quote/index.html" copy="false" >}}
    @@ -158,13 +151,12 @@ Using this same `layouts/_default/list.html` template and applying it to the the
    -``` -{{% /code %}} +{{< /code >}} {{% note %}} The default behavior of Hugo is to pluralize list titles; hence the inflection of the `quote` section to "Quotes" when called with the `.Title` [page variable](/variables/page/). You can change this via the `pluralizeListTitles` directive in your [site configuration](/getting-started/configuration/). @@ -176,8 +168,7 @@ The default behavior of Hugo is to pluralize list titles; hence the inflection o This list template has been modified slightly from a template originally used in [spf13.com](http://spf13.com/). It makes use of [partial templates][partials] for the chrome of the rendered page rather than using a [base template][base] The examples that follow also use the [content view templates][views] `li.html` or `summary.html`. -{{% code file="layouts/section/post.html" %}} -```html +{{< code file="layouts/section/post.html" >}} {{ partial "header.html" . }} {{ partial "subheader.html" . }}
    @@ -192,13 +183,11 @@ This list template has been modified slightly from a template originally used in
    {{ partial "footer.html" . }} -``` -{{% /code %}} +{{< /code >}} ### Taxonomy Template -{{% code file="layouts/_default/taxonomies.html" download="taxonomies.html" %}} -```html +{{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}} {{ define "main" }}
    @@ -210,17 +199,15 @@ This list template has been modified slightly from a template originally used in
    {{ end }} -``` -{{% /code %}} +{{< /code >}} ## Order Content Hugo lists render the content based on metadata you provide in [front matter][]. In addition to sane defaults, Hugo also ships with multiple methods to make quick work of ordering content inside list templates: -### Default List Ordering: Weight > Date +### Default: Weight > Date > LinkTitle > FilePath -{{% code file="layouts/partials/default-order.html" %}} -```html +{{< code file="layouts/partials/default-order.html" >}}
      {{ range .Data.Pages }}
    • @@ -229,13 +216,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
      • {{ end }}
    -``` -{{% /code %}} +{{< /code >}} ### By Weight -{{% code file="layouts/partials/by-weight.html" %}} -```html +{{< code file="layouts/partials/by-weight.html" >}}
      {{ range .Data.Pages.ByWeight }}
    • @@ -244,13 +229,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
      • {{ end }}
    -``` -{{% /code %}} +{{< /code >}} ### By Date -{{% code file="layouts/partials/by-date.html" %}} -```html +{{< code file="layouts/partials/by-date.html" >}}
      {{ range .Data.Pages.ByDate }} @@ -260,13 +243,11 @@ Hugo lists render the content based on metadata you provide in [front matter][]. {{ end }}
    -``` -{{% /code %}} +{{< /code >}} ### By Publish Date -{{% code file="layouts/partials/by-publish-date.html" %}} -```html +{{< code file="layouts/partials/by-publish-date.html" >}}
      {{ range .Data.Pages.ByPublishDate }} @@ -276,13 +257,11 @@ Hugo lists render the content based on metadata you provide in [front matter][]. {{ end }}
    -``` -{{% /code %}} +{{< /code >}} ### By Expiration Date -{{% code file="layouts/partials/by-expiry-date.html" %}} -```html +{{< code file="layouts/partials/by-expiry-date.html" >}}
      {{ range .Data.Pages.ByExpiryDate }}
    • @@ -291,13 +270,11 @@ Hugo lists render the content based on metadata you provide in [front matter][].
      • {{ end }}
    -``` -{{% /code %}} +{{< /code >}} ### By Last Modified Date -{{% code file="layouts/partials/by-last-mod.html" %}} -```html +{{< code file="layouts/partials/by-last-mod.html" >}}
      {{ range .Data.Pages.ByLastmod }} @@ -307,13 +284,11 @@ Hugo lists render the content based on metadata you provide in [front matter][]. {{ end }}
    -``` -{{% /code %}} +{{< /code >}} ### By Length -{{% code file="layouts/partials/by-length.html" %}} -```html +{{< code file="layouts/partials/by-length.html" >}}
      {{ range .Data.Pages.ByLength }} @@ -323,13 +298,11 @@ Hugo lists render the content based on metadata you provide in [front matter][]. {{ end }}
    -``` -{{% /code %}} +{{< /code >}} ### By Title -{{% code file="layouts/partials/by-title.html" %}} -```html +{{< code file="layouts/partials/by-title.html" >}}
      {{ range .Data.Pages.ByTitle }} @@ -339,13 +312,11 @@ Hugo lists render the content based on metadata you provide in [front matter][]. {{ end }}
    -``` -{{% /code %}} +{{< /code >}} ### By Link Title -{{% code file="layouts/partials/by-link-title.html" %}} -```html +{{< code file="layouts/partials/by-link-title.html" >}}
      {{ range .Data.Pages.ByLinkTitle }} @@ -355,38 +326,32 @@ Hugo lists render the content based on metadata you provide in [front matter][]. {{ end }}
    -``` -{{% /code %}} +{{< /code >}} ### By Parameter Order based on the specified front matter parameter. Content that does not have the specified front matter field will use the site's `.Site.Params` default. If the parameter is not found at all in some entries, those entries will appear together at the end of the ordering. -{{% code file="layouts/partials/by-rating.html" %}} -```html +{{< code file="layouts/partials/by-rating.html" >}} {{ range (.Data.Pages.ByParam "rating") }} {{ end }} -``` -{{% /code %}} +{{< /code >}} If the targeted front matter field is nested beneath another field, you can access the field using dot notation. -{{% code file="layouts/partials/by-nested-param.html" %}} -```html +{{< code file="layouts/partials/by-nested-param.html" >}} {{ range (.Data.Pages.ByParam "author.last_name") }} {{ end }} -``` -{{% /code %}} +{{< /code >}} ### Reverse Order Reversing order can be applied to any of the above methods. The following uses `ByDate` as an example: -{{% code file="layouts/partials/by-date-reverse.html" %}} -```html +{{< code file="layouts/partials/by-date-reverse.html" >}}
      {{ range .Data.Pages.ByDate.Reverse }}
    • @@ -395,8 +360,7 @@ Reversing order can be applied to any of the above methods. The following uses `
      • {{ end }}
    -``` -{{% /code %}} +{{< /code >}} ## Group Content @@ -404,8 +368,7 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc. ### By Page Field -{{% code file="layouts/partials/by-page-field.html" %}} -```html +{{< code file="layouts/partials/by-page-field.html" >}} {{ range .Data.Pages.GroupBy "Section" }}

    {{ .Key }}

    @@ -418,13 +381,11 @@ Hugo provides some functions for grouping pages by Section, Type, Date, etc. {{ end }}
{{ end }} -``` -{{% /code %}} +{{< /code >}} In the above example, you may want `{{.Title}}` to point the `title` field you have added to your `_index.md` file instead. You can access this value using the [`.GetPage` function][getpage]: -{{% code file="layouts/partials/by-page-field.html" %}} -```html +{{< code file="layouts/partials/by-page-field.html" >}} {{ range .Data.Pages.GroupBy "Section" }} @@ -443,13 +404,11 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h {{ end }} {{ end }} -``` -{{% /code %}} +{{< /code >}} ### By Date -{{% code file="layouts/partials/by-page-date.html" %}} -```html +{{< code file="layouts/partials/by-page-date.html" >}} {{ range .Data.Pages.GroupByDate "2006-01" }}

{{ .Key }}

@@ -462,13 +421,11 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h {{ end }} {{ end }} -``` -{{% /code %}} +{{< /code >}} ### By Publish Date -{{% code file="layouts/partials/by-page-publish-date.html" %}} -```html +{{< code file="layouts/partials/by-page-publish-date.html" >}} {{ range .Data.Pages.GroupByPublishDate "2006-01" }}

{{ .Key }}

@@ -481,13 +438,11 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h {{ end }} {{ end }} -``` -{{% /code %}} +{{< /code >}} ### By Page Parameter -{{% code file="layouts/partials/by-page-param.html" %}} -```html +{{< code file="layouts/partials/by-page-param.html" >}} {{ range .Data.Pages.GroupByParam "param_key" }}

{{ .Key }}

@@ -500,15 +455,13 @@ In the above example, you may want `{{.Title}}` to point the `title` field you h {{ end }} {{ end }} -``` -{{% /code %}} +{{< /code >}} ### By Page Parameter in Date Format The following template takes grouping by `date` a step further and uses Golang's layout string. See the [`Format` function][] for more examples of how to use Golang's layout string to format dates in Hugo. -{{% code file="layouts/partials/by-page-param-as-date.html" %}} -```html +{{< code file="layouts/partials/by-page-param-as-date.html" >}} {{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }}

{{ .Key }}

@@ -521,8 +474,7 @@ The following template takes grouping by `date` a step further and uses Golang's {{ end }} {{ end }} -``` -{{% /code %}} +{{< /code >}} ### Reverse Key Order @@ -532,21 +484,21 @@ While these are logical defaults, they are not always the desired order. There a #### 1. Adding the Reverse Method -```html +``` {{ range (.Data.Pages.GroupBy "Section").Reverse }} ``` -```html +``` {{ range (.Data.Pages.GroupByDate "2006-01").Reverse }} ``` #### 2. Providing the Alternate Direction -```html +``` {{ range .Data.Pages.GroupByDate "2006-01" "asc" }} ``` -```html +``` {{ range .Data.Pages.GroupBy "Section" "desc" }} ``` @@ -560,8 +512,7 @@ Here is the ordering for the example that follows: 2. Groups are listed in ascending order (i.e., the oldest groups first) 3. Pages within each respective group are ordered alphabetically according to the `title`. -{{% code file="layouts/partials/by-group-by-page.html" %}} -```html +{{< code file="layouts/partials/by-group-by-page.html" >}} {{ range .Data.Pages.GroupByDate "2006-01" "asc" }}

{{ .Key }}

    @@ -573,8 +524,7 @@ Here is the ordering for the example that follows: {{ end }}
{{ end }} -``` -{{% /code %}} +{{< /code >}} ## Filter and Limiting Lists @@ -588,13 +538,11 @@ Sometimes you only want to list a subset of the available content. A common is t 2. `key` *or* `field name` 3. `match value` -{{% code file="layouts/_default/.html" %}} -```html +{{< code file="layouts/_default/.html" >}} {{ range where .Data.Pages "Section" "post" }} {{ .Content }} {{ end }} -``` -{{% /code %}} +{{< /code >}} You can see more examples in the [functions documentation for `where`][wherefunction]. @@ -605,26 +553,22 @@ You can see more examples in the [functions documentation for `where`][wherefunc 1. `array` *or* `slice of maps or structs` 2. `number of elements` -{{% code file="layout/_default/section.html" %}} -```html +{{< code file="layout/_default/section.html" >}} {{ range first 10 .Data.Pages }} {{ .Render "summary" }} {{ end }} -``` -{{% /code %}} +{{< /code >}} ### `first` and `where` Together Using `first` and `where` together can be very powerful: -{{% code file="first-and-where-together.html" %}} -```html +{{< code file="first-and-where-together.html" >}} {{ range first 5 (where .Data.Pages "Section" "post").ByTitle }} {{ .Content }} {{ end }} -``` -{{% /code %}} +{{< /code >}} [base]: /templates/base/ [bepsays]: http://bepsays.com/en/2016/12/19/hugo-018/ @@ -648,4 +592,4 @@ Using `first` and `where` together can be very powerful: [taxvars]: /variables/taxonomy/ [views]: /templates/views/ [wherefunction]: /functions/where/ -[wherekeyword]: https://www.techonthenet.com/sql/where.php \ No newline at end of file +[wherekeyword]: https://www.techonthenet.com/sql/where.php diff --git a/content/templates/lookup-order.md b/content/templates/lookup-order.md index 37d994eed..3f4ff79a0 100644 --- a/content/templates/lookup-order.md +++ b/content/templates/lookup-order.md @@ -52,7 +52,7 @@ The lookup order is best illustrated through examples. The following shows you t 1. The project is using the theme `mytheme` (specified in the project's [configuration][config]). 2. The layouts and content directories for the project are as follows: -```bash +``` . ├── content │ ├── events @@ -88,15 +88,13 @@ Only three of the four markdown files in the above project are subject to the *s ### Example: `my-first-post.md` -{{% code file="content/posts/my-first-post.md" copy="false" %}} -```yaml +{{< code file="content/posts/my-first-post.md" copy="false" >}} --- title: My First Post date: 2017-02-19 description: This is my first post. --- -``` -{{% /code %}} +{{< /code >}} When building your site, Hugo will go through the lookup order until it finds what it needs for `my-first-post.md`: @@ -118,8 +116,7 @@ Notice the term `UNSPECIFIED` rather than `UNDEFINED`. If you don't tell Hugo th ### Example: `my-second-post.md` -{{% code file="content/posts/my-second-post.md" copy="false" %}} -```yaml +{{< code file="content/posts/my-second-post.md" copy="false" >}} --- title: My Second Post date: 2017-02-21 @@ -127,8 +124,7 @@ description: This is my second post. type: review layout: reviewarticle --- -``` -{{% /code %}} +{{< /code >}} Here is the way Hugo traverses the single-page lookup order for `my-second-post.md`: @@ -152,15 +148,13 @@ Notice that the directory for the template for `my-second-post.md` is `review` a ### Example: `my-first-event.md` -{{% code file="content/events/my-first-event.md" copy="false" %}} -```yaml +{{< code file="content/events/my-first-event.md" copy="false" >}} --- title: My First date: 2017-02-21 description: This is an upcoming event.. --- -``` -{{% /code %}} +{{< /code >}} Here is the way Hugo traverses the single-page lookup order for `my-first-event.md`: diff --git a/content/templates/menu-templates.md b/content/templates/menu-templates.md index 791825d16..eb300afe7 100644 --- a/content/templates/menu-templates.md +++ b/content/templates/menu-templates.md @@ -24,8 +24,7 @@ able to build your menu however you want. The following is an example: -{{% code file="layouts/partials/sidebar.html" download="sidebar.html" %}} -```html +{{< code file="layouts/partials/sidebar.html" download="sidebar.html" >}} -``` -{{% /code %}} +{{< /code >}} {{% note "`absLangURL` and `relLangURL`" %}} Use the [`absLangUrl`](/functions/abslangurl) or [`relLangUrl`](/functions/rellangurl) functions if your theme makes use of the [multilingual feature](/content-management/multilingual/). In contrast to `absURL` and `relURL`, these two functions add the correct language prefix to the url. @@ -73,7 +71,7 @@ Use the [`absLangUrl`](/functions/abslangurl) or [`relLangUrl`](/functions/rella To enable this menu, add the following to your site `config`: -```toml +``` SectionPagesMenu = "main" ``` @@ -81,7 +79,7 @@ The menu name can be anything, but take a note of what it is. This will create a menu with all the sections as menu items and all the sections' pages as "shadow-members". The _shadow_ implies that the pages isn't represented by a menu-item themselves, but this enables you to create a top-level menu like this: -```html +```