From: Bjørn Erik Pedersen Date: Fri, 4 May 2018 07:44:21 +0000 (+0200) Subject: Squashed 'docs/' changes from 896bad9f4..e161ea09d X-Git-Tag: v0.41~9^2~1 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=83bef6955e014d40c0f00db9cebe09113154e999;p=brevno-suite%2Fhugo Squashed 'docs/' changes from 896bad9f4..e161ea09d e161ea09d Add one more Chinese file to workaround reflect: Zero(nil) b595b3a21 Add more Chinese translation 56e4e95d9 Use lang.Merge to "fill in the gaps" for untranslated pages ef079406c Merge commit '650fac3a4e7d256f4505402ab44cfc3c804b8dea' 650fac3a4 Squashed 'themes/gohugoioTheme/' changes from a1768ebb..f31a3dc8 322eff899 Add Chinese language for menus d90b886e0 Fix Markdown table syntax in previous commit 737f3dfca Update the leaf bundle vs branch bundle table 09fa1bc4e Clarify that `.Now` is obsolete 879ea3f6a Make release notes somewhat more consistent 0113e2051 Move 0.40.2-relnotes into content/en/news 77578f5bf Move content/ into new contentDir content/en/ 4dcf7c709 Fix "reflect: Zero(nil)" error in showcase 63dd25505 Release 0.40.2 2076c0d56 releaser: Prepare repository for 0.41-DEV 070fe565e releaser: Add release notes to /docs for release of 0.40.2 4ce52e913 releaser: Bump versions for release of 0.40.2 41907c487 Fix typos in syntax-highlighting.md 91753ef3d Add missing backtick b77274301 Remove duplicate release notes (0.27, 0.27.1, 0.35) 6e00da316 Remove obsolete content/release-notes/ directory 00a6d8c02 Change en dash back to `--` in 0.38.2-relnotes 51b32dc00 Update archetypes.md d0e5c2307 Release 0.40.1 4538a6d5b releaser: Prepare repository for 0.41-DEV 91b391d70 releaser: Add release notes to /docs for release of 0.40.1 e0979d143 releaser: Bump versions for release of 0.40.1 7983967c2 Clean images fe3fdd77d Polish showcase for Flesland Flis e6dde3989 Showcase - Flesland Flis AS by Absoluttweb 73aa62290 Revive @spf13's special Hugo font add67b335 Release Hugo 0.40 c0a26e5a6 Merge branch 'temp40' beeabaaae releaser: Prepare repository for 0.41-DEV e67d5e985 releaser: Add release notes to /docs for release of 0.40 6cdd95273 releaser: Bump versions for release of 0.40 bee21fb9b Revive the other Hugo logos too 4f45e8fe1 Fix the link type attribute for RSS in examples 8c67dc89a Fix example in delimit doc e7f6c00d5 Revive the logo used on the forum 82b0cd26e Merge commit 'a215abf70e018f4bf40d6c09d8bd148d8684b33d' 119c8ca58 Merge commit 'd2ec1a06df8ab6b17ad05cb008d5701b40327d47' db4683bd2 Improve .Get docs 05260b886 .Get function: fix syntax signature git-subtree-dir: docs git-subtree-split: e161ea09d33e3199f4998e4d2e9068d5a850f042 --- diff --git a/config.toml b/config.toml index c950b168..07ba5d1c 100644 --- a/config.toml +++ b/config.toml @@ -70,7 +70,7 @@ twitter = "GoHugoIO" [params] description = "The world’s fastest framework for building websites" ## Used for views in rendered HTML (i.e., rather than using the .Hugo variable) - release = "0.39" + release = "0.40.2" ## Setting this to true will add a "noindex" to *EVERY* page on the site removefromexternalsearch = false ## Gh repo for site footer (include trailing slash) @@ -271,3 +271,139 @@ anchor = "smart" identifier = "github" post = "external" url = "https://github.com/gohugoio/hugo" + +### LANGUAGES ### + +[languages] + [languages.en] + contentDir = "content/en" + languageName = "English" + weight = 1 + [languages.zh] + contentDir = "content/zh" + languageName = "中文" + weight = 2 + + +### LANGUAGE-SPECIFIC MENUS ### + +# Chinese menus + +[[languages.zh.menu.docs]] + name = "关于 Hugo" + weight = 1 + identifier = "about" + url = "/zh/about/" + +[[languages.zh.menu.docs]] + name = "入门" + weight = 5 + identifier = "getting-started" + url = "/zh/getting-started/" + +[[languages.zh.menu.docs]] + name = "主题" + weight = 15 + identifier = "themes" + post = "break" + url = "/zh/themes/" + +# Core languages.zh.menus + +[[languages.zh.menu.docs]] + name = "内容管理" + weight = 20 + identifier = "content-management" + post = "expanded" + url = "/zh/content-management/" + +[[languages.zh.menu.docs]] + name = "模板" + weight = 25 + identifier = "templates" + url = "/zh/templates/" + +[[languages.zh.menu.docs]] + name = "函数" + weight = 30 + identifier = "functions" + url = "/zh/functions/" + +[[languages.zh.menu.docs]] + name = "变量" + weight = 35 + identifier = "variables" + url = "/zh/variables/" + +[[languages.zh.menu.docs]] + name = "CLI" + weight = 40 + post = "break" + identifier = "commands" + url = "/commands/" + +# LOW LEVEL ITEMS +[[languages.zh.menu.docs]] + name = "故障排除" + weight = 60 + identifier = "troubleshooting" + url = "/zh/troubleshooting/" + +[[languages.zh.menu.docs]] + name = "工具" + weight = 70 + identifier = "tools" + url = "/zh/tools/" + +[[languages.zh.menu.docs]] + name = "托管与部署" + weight = 80 + identifier = "hosting-and-deployment" + url = "/zh/hosting-and-deployment/" + +[[languages.zh.menu.docs]] + name = "贡献" + weight = 100 + post = "break" + identifier = "contribute" + url = "/zh/contribute/" + +[[languages.zh.menu.global]] + name = "新闻" + weight = 1 + identifier = "news" + url = "/zh/news/" + +[[languages.zh.menu.global]] + name = "文档" + weight = 5 + identifier = "docs" + url = "/zh/documentation/" + +[[languages.zh.menu.global]] + name = "主题" + weight = 10 + identifier = "themes" + url = "https://themes.gohugo.io/" + +[[languages.zh.menu.global]] + name = "作品展示" + weight = 20 + identifier = "showcase" + url = "/zh/showcase/" + +# Anything with a weight > 100 gets an external icon +[[languages.zh.menu.global]] + name = "社区" + weight = 150 + icon = true + identifier = "community" + post = "external" + url = "https://discourse.gohugo.io/" + +[[languages.zh.menu.global]] + name = "GitHub" + weight = 200 + identifier = "github" + post = "external" + url = "https://github.com/gohugoio/hugo" diff --git a/content/_index.md b/content/_index.md deleted file mode 100644 index c8976eb9..00000000 --- a/content/_index.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: "The world’s fastest framework for building websites" -date: 2017-03-02T12:00:00-05:00 -features: - - heading: Blistering Speed - image_path: /images/icon-fast.svg - tagline: What's modern about waiting for your site to build? - copy: Hugo is the fastest tool of its kind. At <1 ms per page, the average site builds in less than a second. - - - heading: Robust Content Management - image_path: /images/icon-content-management.svg - tagline: Flexibility rules. Hugo is a content strategist's dream. - copy: Hugo supports unlimited content types, taxonomies, menus, dynamic API-driven content, and more, all without plugins. - - - heading: Shortcodes - image_path: /images/icon-shortcodes.svg - tagline: Hugo's shortcodes are Markdown's hidden superpower. - copy: We love the beautiful simplicity of markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility. - - - heading: Built-in Templates - image_path: /images/icon-built-in-templates.svg - tagline: Hugo has common patterns to get your work done quickly. - copy: Hugo ships with pre-made templates to make quick work of SEO, commenting, analytics and other functions. One line of code, and you're done. - - - heading: Multilingual and i18n - image_path: /images/icon-multilingual2.svg - tagline: Polyglot baked in. - copy: Hugo provides full i18n support for multi-language sites with the same straightforward development experience Hugo users love in single-language sites. - - - heading: Custom Outputs - image_path: /images/icon-custom-outputs.svg - 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" - cta: Check out the Hugo's themes. - link: http://themes.gohugo.io/ - color_classes: bg-accent-color white - image: /images/homepage-screenshot-hugo-themes.jpg - copy: "Hugo provides a robust theming system that is easy to implement but capable of producing even the most complicated websites." - - heading: "Capable Templating" - cta: Get Started. - link: templates/ - color_classes: bg-primary-color-light black - image: /images/home-page-templating-example.png - copy: "Hugo's Go-based templating provides just the right amount of logic to build anything from the simple to complex. If you prefer Jade/Pug-like syntax, you can also use Amber, Ace, or any combination of the three." ---- - -Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again. diff --git a/content/about/_index.md b/content/about/_index.md deleted file mode 100644 index 8ed441b6..00000000 --- a/content/about/_index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: About Hugo -linktitle: Overview -description: Hugo's features, roadmap, license, and motivation. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [] -keywords: [] -menu: - docs: - parent: "about" - weight: 1 -weight: 1 -draft: false -aliases: [/about-hugo/,/docs/] -toc: false ---- - -Hugo is not your average static site generator. diff --git a/content/about/benefits.md b/content/about/benefits.md deleted file mode 100644 index 0ba28c5c..00000000 --- a/content/about/benefits.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: The Benefits of Static Site Generators -linktitle: The Benefits of Static -description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -keywords: [ssg,static,performance,security] -menu: - docs: - parent: "about" - weight: 30 -weight: 30 -sections_weight: 30 -draft: false -aliases: [] -toc: false ---- - -The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page. - -Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page. - -Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*. - -This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site. - -## More on Static Site Generators - -* ["An Introduction to Static Site Generators", David Walsh][] -* ["Hugo vs. Wordpress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress] -* ["Static Site Generators", O'Reilly][] -* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)][] -* ["Top 10 Static Website Generators", Netlify blog][] -* ["The Resurgence of Static", dotCMS][dotcms] - - -["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators -["Static Site Generators", O'Reilly]: http://www.oreilly.com/web-platform/free/files/static-site-generators.pdf -["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/ -[hugovwordpress]: https://gettingthingstech.com/hugo-vs.-wordpress-page-load-speed-comparison-hugo-leaves-wordpress-in-its-dust/ -[StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]: https://www.staticgen.com/ -[dotcms]: https://dotcms.com/blog/post/the-resurgence-of-static diff --git a/content/about/features.md b/content/about/features.md deleted file mode 100644 index 9d29c5bd..00000000 --- a/content/about/features.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: Hugo Features -linktitle: Hugo Features -description: Hugo boasts blistering speed, robust content management, and a powerful templating language making it a great fit for all kinds of static websites. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -menu: - docs: - parent: "about" - weight: 20 -weight: 20 -sections_weight: 20 -draft: false -aliases: [/about/features] -toc: true ---- - -## General - -* [Extremely fast][] build times (< 1 ms per page) -* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more -* Renders changes on the fly with [LiveReload][] as you develop -* [Powerful theming][] -* [Host your site anywhere][hostanywhere] - -## Organization - -* Straightforward [organization for your projects][], including website sections -* Customizable [URLs][] -* Support for configurable [taxonomies][], including categories and tags -* [Sort content][] as you desire through powerful template [functions][] -* Automatic [table of contents][] generation -* [Dynamic menu][] creation -* [Pretty URLs][] support -* [Permalink][] pattern support -* Redirects via [aliases][] - -## Content - -* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats][]) -* TOML, YAML, and JSON metadata support in [front matter][] -* Customizable [homepage][] -* Multiple [content types][] -* Automatic and user defined [content summaries][] -* [Shortcodes][] to enable rich content inside of Markdown -* ["Minutes to Read"][pagevars] functionality -* ["Wordcount"][pagevars] functionality - -## Additional Features - -* Integrated [Disqus][] comment support -* Integrated [Google Analytics][] support -* Automatic [RSS][] creation -* Support for [Go][], [Amber], and [Ace][] HTML templates -* [Syntax highlighting][] powered by [Pygments][] - - -[Ace]: /templates/alternatives/ -[aliases]: /content-management/urls/#aliases -[Amber]: https://github.com/eknkc/amber -[content summaries]: /content-management/summaries/ -[content types]: /content-management/types/ -[Disqus]: https://disqus.com/ -[Dynamic menu]: /templates/menus/ -[Extremely fast]: https://github.com/bep/hugo-benchmark -[front matter]: /content-management/front-matter/ -[functions]: /functions/ -[Go]: http://golang.org/pkg/html/template/ -[Google Analytics]: https://google-analytics.com/ -[homepage]: /templates/homepage/ -[hostanywhere]: /hosting-and-deployment/ -[install]: /getting-started/installing/ -[LiveReload]: /getting-started/usage/ -[organization for your projects]: /getting-started/directory-structure/ -[pagevars]: /variables/page/ -[Permalink]: /content-management/urls/#permalinks -[Powerful theming]: /themes/ -[Pretty URLs]: /content-management/urls/ -[Pygments]: http://pygments.org/ -[RSS]: /templates/rss/ -[Shortcodes]: /content-management/shortcodes/ -[sort content]: /templates/ -[supported formats]: /content-management/formats/ -[Syntax highlighting]: /tools/syntax-highlighting/ -[table of contents]: /content-management/toc/ -[taxonomies]: /content-management/taxonomies/ -[URLs]: /content-management/urls/ diff --git a/content/about/license.md b/content/about/license.md deleted file mode 100644 index a8e7c4ab..00000000 --- a/content/about/license.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Apache License -linktitle: License -description: Hugo v0.15 and later are released under the Apache 2.0 license. -date: 2016-02-01 -publishdate: 2016-02-01 -lastmod: 2016-03-02 -categories: ["about hugo"] -keywords: ["License","apache"] -menu: - docs: - parent: "about" - weight: 60 -weight: 60 -sections_weight: 60 -aliases: [/meta/license] -toc: true ---- - -{{% note %}} -Hugo v0.15 and later are released under the Apache 2.0 license. -Earlier versions of Hugo were released under the [Simple Public License](https://opensource.org/licenses/Simple-2.0). -{{% /note %}} - -_Version 2.0, January 2004_
- - -*Terms and Conditions for use, reproduction, and distribution* - -## 1. Definitions - -“License” shall mean the terms and conditions for use, reproduction, and -distribution as defined by Sections 1 through 9 of this document. - -“Licensor” shall mean the copyright owner or entity authorized by the copyright -owner that is granting the License. - -“Legal Entity” shall mean the union of the acting entity and all other entities -that control, are controlled by, or are under common control with that entity. -For the purposes of this definition, “control” means **(i)** the power, direct or -indirect, to cause the direction or management of such entity, whether by -contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the -outstanding shares, or **(iii)** beneficial ownership of such entity. - -“You” (or “Your”) shall mean an individual or Legal Entity exercising -permissions granted by this License. - -“Source” form shall mean the preferred form for making modifications, including -but not limited to software source code, documentation source, and configuration -files. - -“Object” form shall mean any form resulting from mechanical transformation or -translation of a Source form, including but not limited to compiled object code, -generated documentation, and conversions to other media types. - -“Work” shall mean the work of authorship, whether in Source or Object form, made -available under the License, as indicated by a copyright notice that is included -in or attached to the work (an example is provided in the Appendix below). - -“Derivative Works” shall mean any work, whether in Source or Object form, that -is based on (or derived from) the Work and for which the editorial revisions, -annotations, elaborations, or other modifications represent, as a whole, an -original work of authorship. For the purposes of this License, Derivative Works -shall not include works that remain separable from, or merely link (or bind by -name) to the interfaces of, the Work and Derivative Works thereof. - -“Contribution” shall mean any work of authorship, including the original version -of the Work and any modifications or additions to that Work or Derivative Works -thereof, that is intentionally submitted to Licensor for inclusion in the Work -by the copyright owner or by an individual or Legal Entity authorized to submit -on behalf of the copyright owner. For the purposes of this definition, -“submitted” means any form of electronic, verbal, or written communication sent -to the Licensor or its representatives, including but not limited to -communication on electronic mailing lists, source code control systems, and -issue tracking systems that are managed by, or on behalf of, the Licensor for -the purpose of discussing and improving the Work, but excluding communication -that is conspicuously marked or otherwise designated in writing by the copyright -owner as “Not a Contribution.” - -“Contributor” shall mean Licensor and any individual or Legal Entity on behalf -of whom a Contribution has been received by Licensor and subsequently -incorporated within the Work. - -## 2. Grant of Copyright License - -Subject to the terms and conditions of this License, each Contributor hereby -grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, -irrevocable copyright license to reproduce, prepare Derivative Works of, -publicly display, publicly perform, sublicense, and distribute the Work and such -Derivative Works in Source or Object form. - -## 3. Grant of Patent License - -Subject to the terms and conditions of this License, each Contributor hereby -grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, -irrevocable (except as stated in this section) patent license to make, have -made, use, offer to sell, sell, import, and otherwise transfer the Work, where -such license applies only to those patent claims licensable by such Contributor -that are necessarily infringed by their Contribution(s) alone or by combination -of their Contribution(s) with the Work to which such Contribution(s) was -submitted. If You institute patent litigation against any entity (including a -cross-claim or counterclaim in a lawsuit) alleging that the Work or a -Contribution incorporated within the Work constitutes direct or contributory -patent infringement, then any patent licenses granted to You under this License -for that Work shall terminate as of the date such litigation is filed. - -## 4. Redistribution - -You may reproduce and distribute copies of the Work or Derivative Works thereof -in any medium, with or without modifications, and in Source or Object form, -provided that You meet the following conditions: - -* **(a)** You must give any other recipients of the Work or Derivative Works a copy of -this License; and -* **(b)** You must cause any modified files to carry prominent notices stating that You -changed the files; and -* **\(c)** You must retain, in the Source form of any Derivative Works that You distribute, -all copyright, patent, trademark, and attribution notices from the Source form -of the Work, excluding those notices that do not pertain to any part of the -Derivative Works; and -* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. - -You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. - -## 5. Submission of Contributions - -Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. - -## 6. Trademarks - -This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. - -## 7. Disclaimer of Warranty - -Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. - -## 8. Limitation of Liability - -In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. - -## 9. Accepting Warranty or Additional Liability - -While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. - -_END OF TERMS AND CONDITIONS_ - -## APPENDIX: How to apply the Apache License to your work - -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" >}} -Copyright [yyyy] [name of copyright owner] - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -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 >}} diff --git a/content/about/new-in-032/index.md b/content/about/new-in-032/index.md deleted file mode 100644 index b8ca6430..00000000 --- a/content/about/new-in-032/index.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: Hugo 0.32 HOWTO -description: About page bundles, image processing and more. -date: 2017-12-28 -keywords: [ssg,static,performance,security] -menu: - docs: - parent: "about" - weight: 10 -weight: 10 -sections_weight: 10 -draft: false -aliases: [] -toc: true -images: -- images/blog/sunset.jpg ---- - - -{{% note %}} -This documentation belongs in other places in this documentation site, but is put here first ... to get something up and running fast. -{{% /note %}} - - -Also see this demo project from [bep](https://github.com/bep/), the clever Norwegian behind these new features: - -* http://hugotest.bep.is/ -* https://github.com/bep/hugotest (source) - -## Page Resources - -### Organize Your Content - -{{< figure src="/images/hugo-content-bundles.png" title="Pages with image resources" >}} - -The content folder above shows a mix of content pages (`md` (i.e. markdown) files) and image resources. - -{{% note %}} -You can use any file type as a content resource as long as it is a MIME type recognized by Hugo (`json` files will, as one example, work fine). If you want to get exotic, you can define your [own media type](/templates/output-formats/#media-types). -{{% /note %}} - -The 3 page bundles marked in red explained from top to bottom: - -1. The home page with one image resource (`1-logo.png`) -2. The blog section with two images resources and two pages resources (`content1.md`, `content2.md`). Note that the `_index.md` represents the URL for this section. -3. An article (`hugo-is-cool`) with a folder with some images and one content resource (`cats-info.md`). Note that the `index.md` represents the URL for this article. - -The content files below `blog/posts` are just regular standalone pages. - -{{% note %}} -Note that changes to any resource inside the `content` folder will trigger a reload when running in watch (aka server or live reload mode), it will even work with `--navigateToChanged`. -{{% /note %}} - -#### Sort Order - -* Pages are sorted according to standard Hugo page sorting rules. -* Images and other resources are sorted in lexicographical order. - -### Handle Page Resources in Templates - - -#### List all Resources - -```go-html-template -{{ range .Resources }} -
  • {{ .ResourceType | title }}
    • -{{ end }} -``` - -For an absolute URL, use `.Permalink`. - -**Note:** The permalink will be relative to the content page, respecting permalink settings. Also, included page resources will not have a value for `RelPermalink`. - -#### List All Resources by Type - -```go-html-template -{{ with .Resources.ByType "image" }} -{{ end }} - -``` - -Type here is `page` for pages, else the main type in the MIME type, so `image`, `json` etc. - -#### Get a Specific Resource - -```go-html-template -{{ $logo := .Resources.GetByPrefix "logo" }} -{{ with $logo }} -{{ end }} -``` - -#### Include Page Resource Content - -```go-html-template -{{ with .Resources.ByType "page" }} -{{ range . }} -

    {{ .Title }}

    -{{ .Content }} -{{ end }} -{{ end }} - -``` - - -## Image Processing - -The `image` resource implements the methods `Resize`, `Fit` and `Fill`: - -Resize -: Resize to the given dimension, `{{ $logo.Resize "200x" }}` will resize to 200 pixels wide and preserve the aspect ratio. Use `{{ $logo.Resize "200x100" }}` to control both height and width. - -Fit -: Scale down the image to fit the given dimensions, e.g. `{{ $logo.Fit "200x100" }}` will fit the image inside a box that is 200 pixels wide and 100 pixels high. - -Fill -: Resize and crop the image given dimensions, e.g. `{{ $logo.Fill "200x100" }}` will resize and crop to width 200 and height 100 - - -{{% note %}} -Image operations in Hugo currently **do not preserve EXIF data** as this is not supported by Go's [image package](https://github.com/golang/go/search?q=exif&type=Issues&utf8=%E2%9C%93). This will be improved on in the future. -{{% /note %}} - - -### Image Processing Examples - -_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ - - -{{< imgproc sunset Resize "300x" />}} - -{{< imgproc sunset Fill "90x120 left" />}} - -{{< imgproc sunset Fill "90x120 right" />}} - -{{< imgproc sunset Fit "90x90" />}} - -{{< imgproc sunset Resize "300x q10" />}} - - -This is the shortcode used in the examples above: - - -{{< code file="layouts/shortcodes/imgproc.html" >}} -{{< readfile file="layouts/shortcodes/imgproc.html" >}} -{{< /code >}} - -And it is used like this: - -```go-html-template -{{}} -``` - -### Image Processing Options - -In addition to the dimensions (e.g. `200x100`) where either height or width can be omitted, Hugo supports a set of additional image options: - -Anchor -: Only relevant for `Fill`. This is useful for thumbnail generation where the main motive is located in, say, the left corner. Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. Example: `{{ $logo.Fill "200x100 BottomLeft" }}` - -JPEG Quality -: Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. `{{ $logo.Resize "200x q50" }}` - -Rotate -: Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. `{{ $logo.Resize "200x r90" }}`. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. - -Resample Filter -: Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. - - - -### Performance - -Processed images are stored below `/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused. - -If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. - -To clean up, run: - -```bash -hugo --gc -``` - - -{{% note %}} -**GC** is short for **Garbage Collection**. -{{% /note %}} - - -## Configuration - -### Default Image Processing Config - -You can configure an `imaging` section in `config.toml` with default image processing options: - -```toml -[imaging] -# Default resample filter used for resizing. Default is Box, -# a simple and fast averaging filter appropriate for downscaling. -# See https://github.com/disintegration/imaging -resampleFilter = "box" - -# Defatult JPEG quality setting. Default is 75. -quality = 68 -``` - - - - - diff --git a/content/about/new-in-032/sunset.jpg b/content/about/new-in-032/sunset.jpg deleted file mode 100644 index 7d7307be..00000000 Binary files a/content/about/new-in-032/sunset.jpg and /dev/null differ diff --git a/content/about/what-is-hugo.md b/content/about/what-is-hugo.md deleted file mode 100644 index 2c7339f7..00000000 --- a/content/about/what-is-hugo.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: What is Hugo -linktitle: What is Hugo -description: Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -layout: single -menu: - docs: - parent: "about" - weight: 10 -weight: 10 -sections_weight: 10 -draft: false -aliases: [/overview/introduction/,/about/why-i-built-hugo/] -toc: true ---- - -Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator][]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors. - -Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify][], [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [GitLab Pages][], [Surge][], [Aerobatic][], [Firebase][], [Google Cloud Storage][], [Amazon S3][], [Rackspace][], [Azure][], and [CloudFront][] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP. - -We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made. - -## How Fast is Hugo? - -{{< youtube "CdiDYZ51a2o" >}} - -## What Does Hugo Do? - -In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website. - -## Who Should Use Hugo? - -Hugo is for people that prefer writing in a text editor over a browser. - -Hugo is for people who want to hand code their own website without worrying about setting up complicated runtimes, dependencies and databases. - -Hugo is for people building a blog, a company site, a portfolio site, documentation, a single landing page, or a website with thousands of pages. - - - -[@spf13]: https://twitter.com/@spf13 -[Aerobatic]: https://www.aerobatic.com/ -[Amazon S3]: http://aws.amazon.com/s3/ -[Azure]: https://blogs.msdn.microsoft.com/acoat/2016/01/28/publish-a-static-web-site-using-azure-web-apps/ -[CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront" -[contributing to it]: https://github.com/gohugoio/hugo -[DreamHost]: http://www.dreamhost.com/ -[Firebase]: https://firebase.google.com/docs/hosting/ "Firebase static hosting" -[GitHub Pages]: https://pages.github.com/ -[GitLab Pages]: https://about.gitlab.com/features/pages/ -[Go language]: https://golang.org/ -[GoDaddy]: https://www.godaddy.com/ "Godaddy.com Hosting" -[Google Cloud Storage]: http://cloud.google.com/storage/ -[Heroku]: https://www.heroku.com/ -[Jekyll]: http://jekyllrb.com/ -[Jekyll]: https://jekyllrb.com/ -[Middleman]: https://middlemanapp.com/ -[Middleman]: https://middlemanapp.com/ -[Nanoc]: http://nanoc.ws/ -[Nanoc]: https://nanoc.ws/ -[Netlify]: https://netlify.com -[rackspace]: https://www.rackspace.com/cloud/files -[static site generator]: /about/benefits/ -[Rackspace]: https://www.rackspace.com/cloud/files -[static site generator]: /about/benefits/ -[Surge]: https://surge.sh diff --git a/content/commands/hugo.md b/content/commands/hugo.md deleted file mode 100644 index 18aed3b7..00000000 --- a/content/commands/hugo.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo" -slug: hugo -url: /commands/hugo/ ---- -## hugo - -hugo builds your site - -### Synopsis - -hugo is the main command, used to build your Hugo site. - -Hugo is a Fast and Flexible Static Site Generator -built with love by spf13 and friends in Go. - -Complete documentation is available at http://gohugo.io/. - -``` -hugo [flags] -``` - -### Options - -``` - -b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/ - -D, --buildDrafts include content marked as draft - -E, --buildExpired include expired content - -F, --buildFuture include content with publishdate in the future - --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/ - --canonifyURLs (deprecated) if true, all relative URLs will be canonicalized using baseURL - --cleanDestinationDir remove files from destination not found in static directories - --config string config file (default is path/config.yaml|json|toml) - -c, --contentDir string filesystem path to content directory - --debug debug output - -d, --destination string filesystem path to write files to - --disableKinds stringSlice disable different kind of pages (home, RSS etc.) - --enableGitInfo add Git revision, date and author info to the pages - --forceSyncStatic copy all files when static is changed. - --gc enable to run some cleanup tasks (remove unused cache files) after the build - -h, --help help for hugo - --i18n-warnings print missing translations - --ignoreCache ignores the cache directory - -l, --layoutDir string filesystem path to layout directory - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --noChmod don't sync permission mode of files - --noTimes don't sync modification time of files - --pluralizeListTitles (deprecated) pluralize titles in lists using inflect (default true) - --preserveTaxonomyNames (deprecated) preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu") - --quiet build in quiet mode - --renderToMemory render to memory (only useful for benchmark testing) - -s, --source string filesystem path to read files relative from - --stepAnalysis display memory and timing of different steps of the program - --templateMetrics display metrics about template executions - --templateMetricsHints calculate some improvement hints when combined with --templateMetrics - -t, --theme string theme to use (located in /themes/THEMENAME/) - --themesDir string filesystem path to themes directory - --uglyURLs (deprecated) if true, use /filename.html instead of /filename/ - -v, --verbose verbose output - --verboseLog verbose logging - -w, --watch watch filesystem for changes and recreate as needed -``` - -### SEE ALSO - -* [hugo benchmark](/commands/hugo_benchmark/) - Benchmark Hugo by building a site a number of times. -* [hugo check](/commands/hugo_check/) - Contains some verification checks -* [hugo config](/commands/hugo_config/) - Print the site configuration -* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats -* [hugo env](/commands/hugo_env/) - Print Hugo version and environment info -* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. -* [hugo import](/commands/hugo_import/) - Import your site from others. -* [hugo list](/commands/hugo_list/) - Listing out various types of content -* [hugo new](/commands/hugo_new/) - Create new content for your site -* [hugo server](/commands/hugo_server/) - A high performance webserver -* [hugo version](/commands/hugo_version/) - Print the version number of Hugo - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_benchmark.md b/content/commands/hugo_benchmark.md deleted file mode 100644 index 63348c36..00000000 --- a/content/commands/hugo_benchmark.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo benchmark" -slug: hugo_benchmark -url: /commands/hugo_benchmark/ ---- -## hugo benchmark - -Benchmark Hugo by building a site a number of times. - -### Synopsis - -Hugo can build a site many times over and analyze the running process -creating a benchmark. - -``` -hugo benchmark [flags] -``` - -### Options - -``` - -b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/ - -D, --buildDrafts include content marked as draft - -E, --buildExpired include expired content - -F, --buildFuture include content with publishdate in the future - --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/ - --canonifyURLs (deprecated) if true, all relative URLs will be canonicalized using baseURL - --cleanDestinationDir remove files from destination not found in static directories - -c, --contentDir string filesystem path to content directory - -n, --count int number of times to build the site (default 13) - --cpuprofile string path/filename for the CPU profile file - -d, --destination string filesystem path to write files to - --disableKinds stringSlice disable different kind of pages (home, RSS etc.) - --enableGitInfo add Git revision, date and author info to the pages - --forceSyncStatic copy all files when static is changed. - --gc enable to run some cleanup tasks (remove unused cache files) after the build - -h, --help help for benchmark - --i18n-warnings print missing translations - --ignoreCache ignores the cache directory - -l, --layoutDir string filesystem path to layout directory - --memprofile string path/filename for the memory profile file - --noChmod don't sync permission mode of files - --noTimes don't sync modification time of files - --pluralizeListTitles (deprecated) pluralize titles in lists using inflect (default true) - --preserveTaxonomyNames (deprecated) preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu") - --renderToMemory render to memory (only useful for benchmark testing) - -s, --source string filesystem path to read files relative from - --stepAnalysis display memory and timing of different steps of the program - --templateMetrics display metrics about template executions - --templateMetricsHints calculate some improvement hints when combined with --templateMetrics - -t, --theme string theme to use (located in /themes/THEMENAME/) - --themesDir string filesystem path to themes directory - --uglyURLs (deprecated) if true, use /filename.html instead of /filename/ -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_check.md b/content/commands/hugo_check.md deleted file mode 100644 index 239934dc..00000000 --- a/content/commands/hugo_check.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo check" -slug: hugo_check -url: /commands/hugo_check/ ---- -## hugo check - -Contains some verification checks - -### Synopsis - -Contains some verification checks - -### Options - -``` - -h, --help help for check -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site -* [hugo check ulimit](/commands/hugo_check_ulimit/) - Check system ulimit settings - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_check_ulimit.md b/content/commands/hugo_check_ulimit.md deleted file mode 100644 index 340a5125..00000000 --- a/content/commands/hugo_check_ulimit.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo check ulimit" -slug: hugo_check_ulimit -url: /commands/hugo_check_ulimit/ ---- -## hugo check ulimit - -Check system ulimit settings - -### Synopsis - -Hugo will inspect the current ulimit settings on the system. -This is primarily to ensure that Hugo can watch enough files on some OSs - -``` -hugo check ulimit [flags] -``` - -### Options - -``` - -h, --help help for ulimit -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo check](/commands/hugo_check/) - Contains some verification checks - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_config.md b/content/commands/hugo_config.md deleted file mode 100644 index 66f3372a..00000000 --- a/content/commands/hugo_config.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo config" -slug: hugo_config -url: /commands/hugo_config/ ---- -## hugo config - -Print the site configuration - -### Synopsis - -Print the site configuration, both default and custom settings. - -``` -hugo config [flags] -``` - -### Options - -``` - -h, --help help for config - -s, --source string filesystem path to read files relative from -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_convert.md b/content/commands/hugo_convert.md deleted file mode 100644 index 7ed15d30..00000000 --- a/content/commands/hugo_convert.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo convert" -slug: hugo_convert -url: /commands/hugo_convert/ ---- -## hugo convert - -Convert your content to different formats - -### Synopsis - -Convert your content (e.g. front matter) to different formats. - -See convert's subcommands toJSON, toTOML and toYAML for more information. - -### Options - -``` - -h, --help help for convert - -o, --output string filesystem path to write files to - -s, --source string filesystem path to read files relative from - --unsafe enable less safe operations, please backup first -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site -* [hugo convert toJSON](/commands/hugo_convert_tojson/) - Convert front matter to JSON -* [hugo convert toTOML](/commands/hugo_convert_totoml/) - Convert front matter to TOML -* [hugo convert toYAML](/commands/hugo_convert_toyaml/) - Convert front matter to YAML - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_convert_toJSON.md b/content/commands/hugo_convert_toJSON.md deleted file mode 100644 index 03e2f692..00000000 --- a/content/commands/hugo_convert_toJSON.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo convert toJSON" -slug: hugo_convert_toJSON -url: /commands/hugo_convert_tojson/ ---- -## hugo convert toJSON - -Convert front matter to JSON - -### Synopsis - -toJSON converts all front matter in the content directory -to use JSON for the front matter. - -``` -hugo convert toJSON [flags] -``` - -### Options - -``` - -h, --help help for toJSON -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - -o, --output string filesystem path to write files to - --quiet build in quiet mode - -s, --source string filesystem path to read files relative from - --unsafe enable less safe operations, please backup first - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_convert_toTOML.md b/content/commands/hugo_convert_toTOML.md deleted file mode 100644 index 9abb418b..00000000 --- a/content/commands/hugo_convert_toTOML.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo convert toTOML" -slug: hugo_convert_toTOML -url: /commands/hugo_convert_totoml/ ---- -## hugo convert toTOML - -Convert front matter to TOML - -### Synopsis - -toTOML converts all front matter in the content directory -to use TOML for the front matter. - -``` -hugo convert toTOML [flags] -``` - -### Options - -``` - -h, --help help for toTOML -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - -o, --output string filesystem path to write files to - --quiet build in quiet mode - -s, --source string filesystem path to read files relative from - --unsafe enable less safe operations, please backup first - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_convert_toYAML.md b/content/commands/hugo_convert_toYAML.md deleted file mode 100644 index 8d87896e..00000000 --- a/content/commands/hugo_convert_toYAML.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo convert toYAML" -slug: hugo_convert_toYAML -url: /commands/hugo_convert_toyaml/ ---- -## hugo convert toYAML - -Convert front matter to YAML - -### Synopsis - -toYAML converts all front matter in the content directory -to use YAML for the front matter. - -``` -hugo convert toYAML [flags] -``` - -### Options - -``` - -h, --help help for toYAML -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - -o, --output string filesystem path to write files to - --quiet build in quiet mode - -s, --source string filesystem path to read files relative from - --unsafe enable less safe operations, please backup first - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo convert](/commands/hugo_convert/) - Convert your content to different formats - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_env.md b/content/commands/hugo_env.md deleted file mode 100644 index b6062724..00000000 --- a/content/commands/hugo_env.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo env" -slug: hugo_env -url: /commands/hugo_env/ ---- -## hugo env - -Print Hugo version and environment info - -### Synopsis - -Print Hugo version and environment info. This is useful in Hugo bug reports. - -``` -hugo env [flags] -``` - -### Options - -``` - -h, --help help for env -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_gen.md b/content/commands/hugo_gen.md deleted file mode 100644 index 025fe587..00000000 --- a/content/commands/hugo_gen.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo gen" -slug: hugo_gen -url: /commands/hugo_gen/ ---- -## hugo gen - -A collection of several useful generators. - -### Synopsis - -A collection of several useful generators. - -### Options - -``` - -h, --help help for gen -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site -* [hugo gen autocomplete](/commands/hugo_gen_autocomplete/) - Generate shell autocompletion script for Hugo -* [hugo gen chromastyles](/commands/hugo_gen_chromastyles/) - Generate CSS stylesheet for the Chroma code highlighter -* [hugo gen doc](/commands/hugo_gen_doc/) - Generate Markdown documentation for the Hugo CLI. -* [hugo gen man](/commands/hugo_gen_man/) - Generate man pages for the Hugo CLI - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_gen_autocomplete.md b/content/commands/hugo_gen_autocomplete.md deleted file mode 100644 index 2d327f64..00000000 --- a/content/commands/hugo_gen_autocomplete.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo gen autocomplete" -slug: hugo_gen_autocomplete -url: /commands/hugo_gen_autocomplete/ ---- -## hugo gen autocomplete - -Generate shell autocompletion script for Hugo - -### Synopsis - -Generates a shell autocompletion script for Hugo. - -NOTE: The current version supports Bash only. - This should work for *nix systems with Bash installed. - -By default, the file is written directly to /etc/bash_completion.d -for convenience, and the command may need superuser rights, e.g.: - - $ sudo hugo gen autocomplete - -Add `--completionfile=/path/to/file` flag to set alternative -file-path and name. - -Logout and in again to reload the completion scripts, -or just source them in directly: - - $ . /etc/bash_completion - -``` -hugo gen autocomplete [flags] -``` - -### Options - -``` - --completionfile string autocompletion file (default "/etc/bash_completion.d/hugo.sh") - -h, --help help for autocomplete - --type string autocompletion type (currently only bash supported) (default "bash") -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_gen_chromastyles.md b/content/commands/hugo_gen_chromastyles.md deleted file mode 100644 index 4db33e88..00000000 --- a/content/commands/hugo_gen_chromastyles.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo gen chromastyles" -slug: hugo_gen_chromastyles -url: /commands/hugo_gen_chromastyles/ ---- -## hugo gen chromastyles - -Generate CSS stylesheet for the Chroma code highlighter - -### Synopsis - -Generate CSS stylesheet for the Chroma code highlighter for a given style. This stylesheet is needed if pygmentsUseClasses is enabled in config. - -See https://help.farbox.com/pygments.html for preview of available styles - -``` -hugo gen chromastyles [flags] -``` - -### Options - -``` - -h, --help help for chromastyles - --highlightStyle string style used for highlighting lines (see https://github.com/alecthomas/chroma) (default "bg:#ffffcc") - --linesStyle string style used for line numbers (see https://github.com/alecthomas/chroma) - --style string highlighter style (see https://help.farbox.com/pygments.html) (default "friendly") -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_gen_doc.md b/content/commands/hugo_gen_doc.md deleted file mode 100644 index 2abf0c5a..00000000 --- a/content/commands/hugo_gen_doc.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo gen doc" -slug: hugo_gen_doc -url: /commands/hugo_gen_doc/ ---- -## hugo gen doc - -Generate Markdown documentation for the Hugo CLI. - -### Synopsis - -Generate Markdown documentation for the Hugo CLI. - -This command is, mostly, used to create up-to-date documentation -of Hugo's command-line interface for http://gohugo.io/. - -It creates one Markdown file per command with front matter suitable -for rendering in Hugo. - -``` -hugo gen doc [flags] -``` - -### Options - -``` - --dir string the directory to write the doc. (default "/tmp/hugodoc/") - -h, --help help for doc -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_gen_man.md b/content/commands/hugo_gen_man.md deleted file mode 100644 index 50b72d89..00000000 --- a/content/commands/hugo_gen_man.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo gen man" -slug: hugo_gen_man -url: /commands/hugo_gen_man/ ---- -## hugo gen man - -Generate man pages for the Hugo CLI - -### Synopsis - -This command automatically generates up-to-date man pages of Hugo's -command-line interface. By default, it creates the man page files -in the "man" directory under the current directory. - -``` -hugo gen man [flags] -``` - -### Options - -``` - --dir string the directory to write the man pages. (default "man/") - -h, --help help for man -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo gen](/commands/hugo_gen/) - A collection of several useful generators. - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_import.md b/content/commands/hugo_import.md deleted file mode 100644 index 5dae58be..00000000 --- a/content/commands/hugo_import.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo import" -slug: hugo_import -url: /commands/hugo_import/ ---- -## hugo import - -Import your site from others. - -### Synopsis - -Import your site from other web site generators like Jekyll. - -Import requires a subcommand, e.g. `hugo import jekyll jekyll_root_path target_path`. - -### Options - -``` - -h, --help help for import -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site -* [hugo import jekyll](/commands/hugo_import_jekyll/) - hugo import from Jekyll - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_import_jekyll.md b/content/commands/hugo_import_jekyll.md deleted file mode 100644 index c61116c6..00000000 --- a/content/commands/hugo_import_jekyll.md +++ /dev/null @@ -1,44 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo import jekyll" -slug: hugo_import_jekyll -url: /commands/hugo_import_jekyll/ ---- -## hugo import jekyll - -hugo import from Jekyll - -### Synopsis - -hugo import from Jekyll. - -Import from Jekyll requires two paths, e.g. `hugo import jekyll jekyll_root_path target_path`. - -``` -hugo import jekyll [flags] -``` - -### Options - -``` - --force allow import into non-empty target directory - -h, --help help for jekyll -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo import](/commands/hugo_import/) - Import your site from others. - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_list.md b/content/commands/hugo_list.md deleted file mode 100644 index 69c3f8aa..00000000 --- a/content/commands/hugo_list.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo list" -slug: hugo_list -url: /commands/hugo_list/ ---- -## hugo list - -Listing out various types of content - -### Synopsis - -Listing out various types of content. - -List requires a subcommand, e.g. `hugo list drafts`. - -### Options - -``` - -h, --help help for list - -s, --source string filesystem path to read files relative from -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site -* [hugo list drafts](/commands/hugo_list_drafts/) - List all drafts -* [hugo list expired](/commands/hugo_list_expired/) - List all posts already expired -* [hugo list future](/commands/hugo_list_future/) - List all posts dated in the future - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_list_drafts.md b/content/commands/hugo_list_drafts.md deleted file mode 100644 index c5f6251f..00000000 --- a/content/commands/hugo_list_drafts.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo list drafts" -slug: hugo_list_drafts -url: /commands/hugo_list_drafts/ ---- -## hugo list drafts - -List all drafts - -### Synopsis - -List all of the drafts in your content directory. - -``` -hugo list drafts [flags] -``` - -### Options - -``` - -h, --help help for drafts -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -s, --source string filesystem path to read files relative from - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo list](/commands/hugo_list/) - Listing out various types of content - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_list_expired.md b/content/commands/hugo_list_expired.md deleted file mode 100644 index 6e5bc37b..00000000 --- a/content/commands/hugo_list_expired.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo list expired" -slug: hugo_list_expired -url: /commands/hugo_list_expired/ ---- -## hugo list expired - -List all posts already expired - -### Synopsis - -List all of the posts in your content directory which has already -expired. - -``` -hugo list expired [flags] -``` - -### Options - -``` - -h, --help help for expired -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -s, --source string filesystem path to read files relative from - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo list](/commands/hugo_list/) - Listing out various types of content - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_list_future.md b/content/commands/hugo_list_future.md deleted file mode 100644 index 4fc13844..00000000 --- a/content/commands/hugo_list_future.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo list future" -slug: hugo_list_future -url: /commands/hugo_list_future/ ---- -## hugo list future - -List all posts dated in the future - -### Synopsis - -List all of the posts in your content directory which will be -posted in the future. - -``` -hugo list future [flags] -``` - -### Options - -``` - -h, --help help for future -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -s, --source string filesystem path to read files relative from - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo list](/commands/hugo_list/) - Listing out various types of content - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_new.md b/content/commands/hugo_new.md deleted file mode 100644 index 448951c9..00000000 --- a/content/commands/hugo_new.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo new" -slug: hugo_new -url: /commands/hugo_new/ ---- -## hugo new - -Create new content for your site - -### Synopsis - -Create a new content file and automatically set the date and title. -It will guess which kind of file to create based on the path provided. - -You can also specify the kind with `-k KIND`. - -If archetypes are provided in your theme or site, they will be used. - -``` -hugo new [path] [flags] -``` - -### Options - -``` - --editor string edit new content with this editor, if provided - -h, --help help for new - -k, --kind string content type to create - -s, --source string filesystem path to read files relative from -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site -* [hugo new site](/commands/hugo_new_site/) - Create a new site (skeleton) -* [hugo new theme](/commands/hugo_new_theme/) - Create a new theme - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_new_site.md b/content/commands/hugo_new_site.md deleted file mode 100644 index 65316f7c..00000000 --- a/content/commands/hugo_new_site.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo new site" -slug: hugo_new_site -url: /commands/hugo_new_site/ ---- -## hugo new site - -Create a new site (skeleton) - -### Synopsis - -Create a new site in the provided directory. -The new site will have the correct structure, but no content or theme yet. -Use `hugo new [contentPath]` to create new content. - -``` -hugo new site [path] [flags] -``` - -### Options - -``` - --force init inside non-empty directory - -f, --format string config & frontmatter format (default "toml") - -h, --help help for site -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -s, --source string filesystem path to read files relative from - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo new](/commands/hugo_new/) - Create new content for your site - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_new_theme.md b/content/commands/hugo_new_theme.md deleted file mode 100644 index a7def203..00000000 --- a/content/commands/hugo_new_theme.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo new theme" -slug: hugo_new_theme -url: /commands/hugo_new_theme/ ---- -## hugo new theme - -Create a new theme - -### Synopsis - -Create a new theme (skeleton) called [name] in the current directory. -New theme is a skeleton. Please add content to the touched files. Add your -name to the copyright line in the license and adjust the theme.toml file -as you see fit. - -``` -hugo new theme [name] [flags] -``` - -### Options - -``` - -h, --help help for theme -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -s, --source string filesystem path to read files relative from - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo new](/commands/hugo_new/) - Create new content for your site - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_server.md b/content/commands/hugo_server.md deleted file mode 100644 index c3ed93bc..00000000 --- a/content/commands/hugo_server.md +++ /dev/null @@ -1,91 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo server" -slug: hugo_server -url: /commands/hugo_server/ ---- -## hugo server - -A high performance webserver - -### Synopsis - -Hugo provides its own webserver which builds and serves the site. -While hugo server is high performance, it is a webserver with limited options. -Many run it in production, but the standard behavior is for people to use it -in development and use a more full featured server such as Nginx or Caddy. - -'hugo server' will avoid writing the rendered and served content to disk, -preferring to store it in memory. - -By default hugo will also watch your files for any changes you make and -automatically rebuild the site. It will then live reload any open browser pages -and push the latest content to them. As most Hugo sites are built in a fraction -of a second, you will be able to save and see your changes nearly instantly. - -``` -hugo server [flags] -``` - -### Options - -``` - --appendPort append port to baseURL (default true) - -b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/ - --bind string interface to which the server will bind (default "127.0.0.1") - -D, --buildDrafts include content marked as draft - -E, --buildExpired include expired content - -F, --buildFuture include content with publishdate in the future - --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/ - --canonifyURLs (deprecated) if true, all relative URLs will be canonicalized using baseURL - --cleanDestinationDir remove files from destination not found in static directories - -c, --contentDir string filesystem path to content directory - -d, --destination string filesystem path to write files to - --disableFastRender enables full re-renders on changes - --disableKinds stringSlice disable different kind of pages (home, RSS etc.) - --disableLiveReload watch without enabling live browser reload on rebuild - --enableGitInfo add Git revision, date and author info to the pages - --forceSyncStatic copy all files when static is changed. - --gc enable to run some cleanup tasks (remove unused cache files) after the build - -h, --help help for server - --i18n-warnings print missing translations - --ignoreCache ignores the cache directory - -l, --layoutDir string filesystem path to layout directory - --liveReloadPort int port for live reloading (i.e. 443 in HTTPS proxy situations) (default -1) - --meminterval string interval to poll memory usage (requires --memstats), valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". (default "100ms") - --memstats string log memory usage to this file - --navigateToChanged navigate to changed content file on live browser reload - --noChmod don't sync permission mode of files - --noHTTPCache prevent HTTP caching - --noTimes don't sync modification time of files - --pluralizeListTitles (deprecated) pluralize titles in lists using inflect (default true) - -p, --port int port on which the server will listen (default 1313) - --preserveTaxonomyNames (deprecated) preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu") - --renderToDisk render to Destination path (default is render to memory & serve from there) - -s, --source string filesystem path to read files relative from - --stepAnalysis display memory and timing of different steps of the program - --templateMetrics display metrics about template executions - --templateMetricsHints calculate some improvement hints when combined with --templateMetrics - -t, --theme string theme to use (located in /themes/THEMENAME/) - --themesDir string filesystem path to themes directory - --uglyURLs (deprecated) if true, use /filename.html instead of /filename/ - -w, --watch watch filesystem for changes and recreate as needed (default true) -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/commands/hugo_version.md b/content/commands/hugo_version.md deleted file mode 100644 index 308013a4..00000000 --- a/content/commands/hugo_version.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -date: 2018-04-16 -title: "hugo version" -slug: hugo_version -url: /commands/hugo_version/ ---- -## hugo version - -Print the version number of Hugo - -### Synopsis - -All software has versions. This is Hugo's. - -``` -hugo version [flags] -``` - -### Options - -``` - -h, --help help for version -``` - -### Options inherited from parent commands - -``` - --config string config file (default is path/config.yaml|json|toml) - --debug debug output - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --quiet build in quiet mode - -v, --verbose verbose output - --verboseLog verbose logging -``` - -### SEE ALSO - -* [hugo](/commands/hugo/) - hugo builds your site - -###### Auto generated by spf13/cobra on 16-Apr-2018 diff --git a/content/content-management/_index.md b/content/content-management/_index.md deleted file mode 100644 index 28f2ecf8..00000000 --- a/content/content-management/_index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Content Management -linktitle: Content Management Overview -description: Hugo makes managing large static sites easy with support for archetypes, content types, menus, cross references, summaries, and more. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -menu: - docs: - parent: "content-management" - weight: 1 -keywords: [source, organization] -categories: [content management] -weight: 01 #rem -draft: false -aliases: [/content/,/content/organization] -toc: false ---- - -A static site generator needs to extend beyond front matter and a couple of templates to be both scalable and *manageable*. Hugo was designed with not only developers in mind, but also content managers and authors. diff --git a/content/content-management/archetypes.md b/content/content-management/archetypes.md deleted file mode 100644 index 902373d8..00000000 --- a/content/content-management/archetypes.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Archetypes -linktitle: Archetypes -description: Archetypes are templates used when creating new content. -date: 2017-02-01 -publishdate: 2017-02-01 -keywords: [archetypes,generators,metadata,front matter] -categories: ["content management"] -menu: - docs: - parent: "content-management" - weight: 70 - quicklinks: -weight: 70 #rem -draft: false -aliases: [/content/archetypes/] -toc: true ---- - -## What are Archetypes? - -**Archetypes** are content template files in the [archetypes directory][] of your project that contain preconfigured [front matter][] and possibly also a content disposition for your website's [content types][]. These will be used when you run `hugo new`. - - -The `hugo new` uses the `content-section` to find the most suitable archetype template in your project. If your project does not contain any archetype files, it will also look in the theme. - -{{< code file="archetype-example.sh" >}} -hugo new posts/my-first-post.md -{{< /code >}} - -The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these: - -1. `archetypes/posts.md` -2. `archetypes/default.md` -3. `themes/my-theme/posts.md` -4. `themes/my-theme/default.md` - -The last two list items is only applicable if you use a theme and it uses the `my-theme` theme name as an example. - -## Create a New Archetype Template - -A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`. Create a new file in `archetypes/newsletter.md` and open it in a text editor. - -{{< code file="archetypes/newsletter.md" >}} ---- -title: "{{ replace .Name "-" " " | title }}" -date: {{ .Date }} -draft: true ---- - -**Insert Lead paragraph here.** - -## New Cool Posts - -{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }} -* {{ .Title }} -{{ end }} -{{< /code >}} - -When you create a new newsletter with: - -```bash -hugo new newsletter/the-latest-cool.stuff.md -``` - -It will create a new newsletter type of content file based on the archetype template. - -**Note:** the site will only be built if the `.Site` is in use in the archetype file, and this can be time consuming for big sites. - -The above _newsletter type archetype_ illustrates the possibilities: The full Hugo `.Site` and all of Hugo's template funcs can be used in the archetype file. - - -[archetypes directory]: /getting-started/directory-structure/ -[content types]: /content-management/types/ -[front matter]: /content-management/front-matter/ diff --git a/content/content-management/authors.md b/content/content-management/authors.md deleted file mode 100644 index afc94fa6..00000000 --- a/content/content-management/authors.md +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: Authors -linktitle: Authors -description: -date: 2016-08-22 -publishdate: 2017-03-12 -lastmod: 2017-03-12 -keywords: [authors] -categories: ["content management"] -menu: - docs: - parent: "content-management" - weight: 55 -weight: 55 #rem -draft: true -aliases: [/content/archetypes/] -toc: true -comments: Before this page is published, need to also update both site- and page-level variables documentation. ---- - - - -Larger sites often have multiple content authors. Hugo provides standardized author profiles to organize relationships between content and content creators for sites operating under a distributed authorship model. - -## Author Profiles - -You can create a profile containing metadata for each author on your website. These profiles have to be saved under `data/_authors/`. The filename of the profile will later be used as an identifier. This way Hugo can associate content with one or multiple authors. An author's profile can be defined in the JSON, YAML, or TOML format. - -### Example: Author Profile - -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" >}} -givenName = "Alice" # or firstName as alias -familyName = "Allison" # or lastName as alias -displayName = "Alice Allison" -thumbnail = "static/authors/alice-thumb.jpg" -image = "static/authors/alice-full.jpg" -shortBio = "My name is Alice and I'm a blogger." -bio = "My name is Alice and I'm a blogger... some other stuff" -email = "alice.allison@email.com" -weight = 10 - -[social] - facebook = "alice.allison" - twitter = "alice" - googleplus = "aliceallison1" - website = "www.example.com" - -[params] - random = "whatever you want" -{{< /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. - -You can store files for the `thumbnail` and `image` attributes in the `static` folder. Then add the path to the photos relative to `static`; e.g., `/static/path/to/thumbnail.jpg`. - -`weight` allows you to define the order of an author in an `.Authors` list and can be accessed on list or via the `.Site.Authors` variable. - -The `social` section contains all the links to the social network accounts of an author. Hugo is able to generate the account links for the most popular social networks automatically. This way, you only have to enter your username. You can find a list of all supported social networks [here](#linking-social-network-accounts-automatically). All other variables, like `website` in the example above remain untouched. - -The `params` section can contain arbitrary data much like the same-named section in the config file. What it contains is up to you. - -## Associate Content Through Identifiers - -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. - -``` ---- -title: Why Hugo is so Awesome -date: 2016-08-22T14:27:502:00 -authors: ["alice"] ---- - -Nothing to read here. Move along... -``` - -``` -+++ -title = Why Hugo is so Awesome -date = "2016-08-22T14:27:502:00" -authors: ["alice"] -+++ - -Nothing to read here. Move along... -``` - -Future authors who might work on this blog post can append their identifiers to the `authors` array in the front matter as well. - -## Work with Templates - -After a successful setup it's time to give some credit to the authors by showing them on the website. Within the templates Hugo provides a list of the author's profiles if they are listed in the `authors` variable within the front matter. - -The list is accessible via the `.Authors` template variable. Printing all authors of a the blog post is straight forward: - -``` -{{ range .Authors }} - {{ .DisplayName }} -{{ end }} -=> Alice Allison -``` - -Even if there are co-authors you may only want to show the main author. For this case you can use the `.Author` template variable **(note the singular form)**. The template variable contains the profile of the author that is first listed with his identifier in the front matter. - -{{% note %}} -You can find a list of all template variables to access the profile information in [Author Variables](/variables/authors/). -{{% /note %}} - -### Link Social Network Accounts - -As aforementioned, Hugo is able to generate links to profiles of the most popular social networks. The following social networks with their corrersponding identifiers are supported: `github`, `facebook`, `twitter`, `googleplus`, `pinterest`, `instagram`, `youtube` and `linkedin`. - -This is can be done with the `.Social.URL` function. Its only parameter is the name of the social network as they are defined in the profile (e.g. `facebook`, `googleplus`). Custom variables like `website` remain as they are. - -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" >}} -{{ with .Author }} -

    {{ .DisplayName }}

    - {{ .DisplayName }} -

    {{ .ShortBio }}

    -
      - {{ range $network, $username := .Social }} -
    • {{ $network }}
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -## Who Published What? - -That question can be answered with a list of all authors and another list containing all articles that they each have written. Now we have to translate this idea into templates. The [taxonomy][] feature allows us to logically group content based on information that they have in common; e.g. a tag or a category. Well, many articles share the same author, so this should sound familiar, right? - -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: - -``` -taxonomies: - author: authors -``` - -``` -[taxonomies] - author = "authors" -``` - - -### List All Authors - -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" >}} - -{{< /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). - -### List Each Author's Publications - -Last but not least, we have to create the second list that contains all publications of an author. Each list will be shown in its own page and can be accessed at `www.example.com/authors/`. Replace `` with a valid author identifier like `alice`. - -The layout for this page can be defined in the template `layouts/taxonomy/author.html`. - -{{< code file="layouts/taxonomy/author.html" download="author.html" >}} -{{ range .Data.Pages }} -

    {{ .Title }}

    - written by {{ .Author.DisplayName }} - {{ .Summary }} -{{ end }} -{{< /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. - -With a lot of content this list can quickly become very long. Consider to use the [pagination][] feature. It splits the list into smaller chunks and spreads them over multiple pages. - -[pagevars]: /variables/page/ -[pagination]: /templates/pagination/ diff --git a/content/content-management/comments.md b/content/content-management/comments.md deleted file mode 100644 index 20932a82..00000000 --- a/content/content-management/comments.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Comments -linktitle: Comments -description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-03-09 -keywords: [sections,content,organization] -categories: [project organization, fundamentals] -menu: - docs: - parent: "content-management" - weight: 140 -weight: 140 #rem -draft: false -aliases: [/extras/comments/] -toc: true ---- - -Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript. - -Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial]. - -## Add Disqus - -Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup]. - -### Configure Disqus - -Disqus comments require you set a single value in your [site's configuration file][configuration] like so: - -{{< code-toggle copy="false" >}} -disqusShortname = "yourdiscussshortname" -{{}} - -For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file: - -* `disqus_identifier` -* `disqus_title` -* `disqus_url` - -### Render Hugo's Built-in Disqus Partial Template - -See [Partial Templates][partials] to learn how to add the Disqus partial to your Hugo website's templates. - -## Comments Alternatives - -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) -* [IntenseDebate](http://intensedebate.com/) -* [Graph Comment][] -* [Muut](http://muut.com/) -* [isso](http://posativ.org/isso/) (Self-hosted, Python) - * [Tutorial on Implementing Isso with Hugo][issotutorial] - - - - - - - -[configuration]: /getting-started/configuration/ -[disquspartial]: /templates/partials/#disqus -[disqussetup]: https://disqus.com/profile/signup/ -[forum]: https://discourse.gohugo.io -[front matter]: /content-management/front-matter/ -[Graph Comment]: https://graphcomment.com/ -[kaijuissue]: https://github.com/spf13/kaiju/issues/new -[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/ -[partials]: /templates/partials/ -[MongoDB]: https://www.mongodb.com/ -[tweet]: https://twitter.com/spf13 diff --git a/content/content-management/cross-references.md b/content/content-management/cross-references.md deleted file mode 100644 index 2980719e..00000000 --- a/content/content-management/cross-references.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Links and Cross References -description: Hugo makes it easy to link documents together. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-03-31 -categories: [content management] -keywords: ["cross references","references", "anchors", "urls"] -menu: - docs: - parent: "content-management" - weight: 100 -weight: 100 #rem -aliases: [/extras/crossreferences/] -toc: true ---- - - - The `ref` and `relref` shortcodes link documents together, both of which are [built-in Hugo shortcodes][]. These shortcodes are also used to provide links to headings inside of your content, whether across documents or within a document. The only difference between `ref` and `relref` is whether the resulting URL is absolute (`http://1.com/about/`) or relative (`/about/`), respectively. - -## Use `ref` and `relref` - -``` -{{}} -{{}} -{{}} -{{}} -{{}} -{{}} -``` - -The single parameter to `ref` is a string with a content `documentname` (e.g., `about.md`) with or without an appended in-document `anchor` (`#who`) without spaces. - -### Document Names - -The `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: - -``` -{{}} => `/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: - -``` -. -└── content - ├── events - │   └── my-birthday.md - ├── galleries - │   └── my-birthday.md - ├── meta - │   └── my-article.md - └── posts - └── my-birthday.md -``` - -To be sure to get the correct reference in this case, use the full path: - -{{< code file="content/meta/my-article.md" copy="false" >}} -{{}} => /events/my-birthday/ -{{< /code >}} - -### With Multiple Output Formats - -If the page exists in multiple [output formats][], `ref` or `relref` can be used with a output format name: - -``` - [Neat]({{}}) -``` - -### Anchors - -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: - -``` -{{}} => #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 - -``` -{{}} => #who:9decaf7 -{{}} => /blog/post/#who:badcafe -``` - -More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}). - -### Examples - -* `{{}}` => `https://example.com/blog/post/` -* `{{}}` => `https://example.com/blog/post/#tldr:caffebad` -* `{{}}` => `/blog/post/` -* `{{}}` => `/blog/post/#tldr:caffebad` -* `{{}}` => `#tldr:badcaffe` -* `{{}}` => `#tldr:badcaffe` - -## Hugo Heading Anchors - -When using Markdown document types, Hugo generates heading anchors automatically. The generated anchor for this section is `hugo-heading-anchors`. Because the heading anchors are generated automatically, Hugo takes some effort to ensure that heading anchors are unique both inside a document and across the entire site. - -Ensuring heading uniqueness across the site is accomplished with a unique identifier for each document based on its path. Unless a document is renamed or moved between sections *in the filesystem*, the unique identifier for the document will not change: `blog/post.md` will always have a unique identifier of `81df004c333b392d34a49fd3a91ba720`. - -`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.) - -``` -{{}} -/content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242 -``` - -### Manually Specifying Anchors - -For Markdown content files, if the `headerIds` [Blackfriday extension][bfext] is -enabled (which it is by default), user can manually specify the anchor for any -heading. - -Few examples: - -``` -## Alpha 101 {#alpha} - -## Version 1.0 {#version-1-dot-0} -``` - -[built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes -[lists]: /templates/lists/ -[output formats]: /templates/output-formats/ -[shortcode]: /content-management/shortcodes/ -[bfext]: /content-management/formats/#blackfriday-extensions diff --git a/content/content-management/formats.md b/content/content-management/formats.md deleted file mode 100644 index be6fb40e..00000000 --- a/content/content-management/formats.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -title: Supported Content Formats -linktitle: Supported Content Formats -description: Markdown and Emacs Org-Mode have native support, and additional formats (e.g. Asciidoc) come via external helpers. -date: 2017-01-10 -publishdate: 2017-01-10 -lastmod: 2017-04-06 -categories: [content management] -keywords: [markdown,asciidoc,mmark,pandoc,content format] -menu: - docs: - parent: "content-management" - weight: 20 -weight: 20 #rem -draft: false -aliases: [/content/markdown-extras/,/content/supported-formats/,/doc/supported-formats/,/tutorials/mathjax/] -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 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 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. -{{% /note %}} - -## Configure BlackFriday Markdown Rendering - -You can configure multiple aspects of Blackfriday as show in the following list. See the docs on [Configuration][config] for the full list of explicit directions you can give to Hugo when rendering your site. - -{{< readfile file="/content/readfiles/bfconfig.md" markdown="true" >}} - -## Extend Markdown - -Hugo provides some convenient methods for extending markdown. - -### Task Lists - -Hugo supports [GitHub-styled task lists (i.e., TODO lists)][gfmtasks] for the Blackfriday markdown renderer. If you do not want to use this feature, you can disable it in your configuration. - -#### Example Task List Input - -{{< code file="content/my-to-do-list.md" >}} -- [ ] a task list item -- [ ] list syntax required -- [ ] incomplete -- [x] completed -{{< /code >}} - -#### Example Task List Output - -The preceding markdown produces the following HTML in your rendered website: - -``` -
      -
    • a task list item
      • -
    • list syntax required
      • -
    • incomplete
      • -
    • completed
      • -
    -``` - -#### Example Task List Display - -The following shows how the example task list will look to the end users of your website. Note that visual styling of lists is up to you. This list has been styled according to [the Hugo Docs stylesheet][hugocss]. - -- [ ] a task list item -- [ ] list syntax required -- [ ] incomplete -- [x] completed - -### Emojis - -To add emojis directly to content, set `enableEmoji` to `true` in your [site configuration][config]. To use emojis in templates or shortcodes, see [`emojify` function][]. - -For a full list of emojis, see the [Emoji cheat sheet][emojis]. - -### Shortcodes - -If you write in Markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in shortcodes functionality. This is one of the most powerful features in Hugo and allows you to create your own Markdown extensions very quickly. - -See [Shortcodes][sc] for usage, particularly for the built-in shortcodes that ship with Hugo, and [Shortcode Templating][sct] to learn how to build your own. - -### Code Blocks - -Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as provides a special [`highlight` shortcode][hlsc], and syntax highlights those code blocks natively using *Chroma*. Users also have an option to use *Pygments* instead. See the [Syntax Highlighting][hl] section for details. - -## Mmark - -Mmark is a [fork of BlackFriday][mmark] and markdown superset that is well suited for writing [IETF documentation][ietf]. You can see examples of the syntax in the [Mmark GitHub repository][mmarkgh] or the full syntax on [Miek Gieben's website][]. - -### Use Mmark - -As Hugo ships with Mmark, using the syntax is as easy as changing the extension of your content files from `.md` to `.mmark`. - -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: - -``` ---- -title: My Post -date: 2017-04-01 -markup: mmark ---- -``` - -{{% warning %}} -Thare are some features not available in Mmark; one example being that shortcodes are not translated when used in an included `.mmark` file ([#3131](https://github.com/gohugoio/hugo/issues/3137)), and `EXTENSION_ABBREVIATION` ([#1970](https://github.com/gohugoio/hugo/issues/1970)) and the aforementioned GFM todo lists ([#2270](https://github.com/gohugoio/hugo/issues/2270)) are not fully supported. Contributions are welcome. -{{% /warning %}} - -## MathJax with Hugo - -[MathJax](http://www.mathjax.org/) is a JavaScript library that allows the display of mathematical expressions described via a LaTeX-style syntax in the HTML (or Markdown) source of a web page. As it is a pure a JavaScript library, getting it to work within Hugo is fairly straightforward, but does have some oddities that will be discussed here. - -This is not an introduction into actually using MathJax to render typeset mathematics on your website. Instead, this page is a collection of tips and hints for one way to get MathJax working on a website built with Hugo. - -### Enable MathJax - -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 >}} - -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. - -### Options and Features - -MathJax is a stable open-source library with many features. I encourage the interested reader to view the [MathJax Documentation](http://docs.mathjax.org/en/latest/index.html), specifically the sections on [Basic Usage](http://docs.mathjax.org/en/latest/index.html#basic-usage) and [MathJax Configuration Options](http://docs.mathjax.org/en/latest/index.html#mathjax-configuration-options). - -### Issues with Markdown - -{{% note %}} -The following issues with Markdown assume you are using `.md` for content and BlackFriday for parsing. Using [Mmark](#mmark) as your content format will obviate the need for the following workarounds. - -When using Mmark with MathJax, use `displayMath: [['$$','$$'], ['\\[','\\]']]`. See the [Mmark `README.md`](https://github.com/miekg/mmark/wiki/Syntax#math-blocks) for more information. In addition to MathJax, Mmark has been shown to work well with [KaTeX](https://github.com/Khan/KaTeX). See this [related blog post from a Hugo user](http://nosubstance.me/post/a-great-toolset-for-static-blogging/). -{{% /note %}} - -After enabling MathJax, any math entered between proper markers (see the [MathJax documentation][mathjaxdocs]) will be processed and typeset in the web page. One issue that comes up, however, with Markdown is that the underscore character (`_`) is interpreted by Markdown as a way to wrap text in `emph` blocks while LaTeX (MathJax) interprets the underscore as a way to create a subscript. This "double speak" of the underscore can result in some unexpected and unwanted behavior. - -### Solution - -There are multiple ways to remedy this problem. One solution is to simply escape each underscore in your math code by entering `\_` instead of `_`. This can become quite tedious if the equations you are entering are full of subscripts. - -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" >}} - - - -{{< /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" >}} -code.has-jax { - font: inherit; - font-size: 100%; - background: inherit; - border: inherit; - color: #515151; -} -{{< /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. - -### Usage - -With this setup, everything is in place for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `` `$ TeX Code $` `` or `` `\( TeX Code \)` ``. To include display style mathematics, just put LaTeX code in between `
    $$TeX Code$$
    `. All the math will be properly typeset and displayed within your Hugo generated web page! - -## Additional Formats Through External Helpers - -Hugo has a new concept called _external helpers_. It means that you can write your content using [Asciidoc][ascii], [reStructuredText][rest], or [pandoc]. If you have files with associated extensions, Hugo will call external commands to generate the content. ([See the Hugo source code for external helpers][helperssource].) - -For example, for Asciidoc files, Hugo will try to call the `asciidoctor` or `asciidoc` command. This means that you will have to install the associated tool on your machine to be able to use these formats. ([See the Asciidoctor docs for installation instructions](http://asciidoctor.org/docs/install-toolchain/)). - -To use these formats, just use the standard extension and the front matter exactly as you would do with natively supported `.md` files. - -Hugo passes reasonable default arguments to these external helpers by default: - -- `asciidoc`: `--no-header-footer --safe -` -- `asciidoctor`: `--no-header-footer --safe --trace -` -- `rst2html`: `--leave-comments --initial-header-level=2` -- `pandoc`: `--mathjax` - -{{% warning "Performance of External Helpers" %}} -Because additional formats are external commands generation performance will rely heavily on the performance of the external tool you are using. As this feature is still in its infancy, feedback is welcome. -{{% /warning %}} - -## Learn Markdown - -Markdown syntax is simple enough to learn in a single sitting. The following are excellent resources to get you up and running: - -* [Daring Fireball: Markdown, John Gruber (Creator of Markdown)][fireball] -* [Markdown Cheatsheet, Adam Pritchard][mdcheatsheet] -* [Markdown Tutorial (Interactive), Garen Torikian][mdtutorial] - -[`emojify` function]: /functions/emojify/ -[ascii]: http://asciidoctor.org/ -[bfconfig]: /getting-started/configuration/#configuring-blackfriday-rendering -[blackfriday]: https://github.com/russross/blackfriday -[mmark]: https://github.com/miekg/mmark -[config]: /getting-started/configuration/ -[developer tools]: /tools/ -[emojis]: https://www.webpagefx.com/tools/emoji-cheat-sheet/ -[fireball]: https://daringfireball.net/projects/markdown/ -[gfmtasks]: https://guides.github.com/features/mastering-markdown/#syntax -[helperssource]: https://github.com/gohugoio/hugo/blob/77c60a3440806067109347d04eb5368b65ea0fe8/helpers/general.go#L65 -[hl]: /content-management/syntax-highlighting/ -[hlsc]: /content-management/shortcodes/#highlight -[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 -[mdtutorial]: http://www.markdowntutorial.com/ -[Miek Gieben's website]: https://miek.nl/2016/March/05/mmark-syntax-document/ -[mmark]: https://github.com/miekg/mmark -[mmarkgh]: https://github.com/miekg/mmark/wiki/Syntax -[org]: http://orgmode.org/ -[pandoc]: http://www.pandoc.org/ -[Pygments]: http://pygments.org/ -[rest]: http://docutils.sourceforge.net/rst.html -[sc]: /content-management/shortcodes/ -[sct]: /templates/shortcode-templates/ diff --git a/content/content-management/front-matter.md b/content/content-management/front-matter.md deleted file mode 100644 index bf067797..00000000 --- a/content/content-management/front-matter.md +++ /dev/null @@ -1,174 +0,0 @@ ---- -title: Front Matter -linktitle: -description: Hugo allows you to add front matter in yaml, toml, or json to your content files. -date: 2017-01-09 -publishdate: 2017-01-09 -lastmod: 2017-02-24 -categories: [content management] -keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"] -menu: - docs: - parent: "content-management" - weight: 30 -weight: 30 #rem -draft: false -aliases: [/content/front-matter/] -toc: true ---- - -**Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength. - -{{< youtube Yh2xKRJGff4 >}} - -## Front Matter Formats - -Hugo supports three formats for front matter, each with their own identifying tokens. - -TOML -: identified by opening and closing `+++`. - -YAML -: identified by opening and closing `---`. - -JSON -: a single JSON object surrounded by '`{`' and '`}`', followed by a new line. - -### Example - -{{< code-toggle >}} -+++ -title = "spf13-vim 3.0 release and new website" -description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." -tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] -date = "2012-04-06" -categories = [ - "Development", - "VIM" -] -slug = "spf13-vim-3-0-release-and-new-website" -+++ -{{}} - -## Front Matter Variables - -### Predefined - -There are a few predefined variables that Hugo is aware of. See [Page Variables][pagevars] for how to call many of these predefined variables in your templates. - -aliases -: an array of one or more aliases (e.g., old published paths of renamed content) that will be created in the output directory structure . See [Aliases][aliases] for details. - -date -: the datetime at which the content was created; note this value is auto-populated according to Hugo's built-in [archetype][]. - -description -: the description for the content. - -draft -: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command. - -expiryDate -: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command. - -headless -: if `true`, sets a leaf bundle to be [headless][headless-bundle]. - -isCJKLanguage -: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages. - -keywords -: the meta keywords for the content. - -layout -: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See ["Defining a Content Type"][definetype] - -lastmod -: the datetime at which the content was last modified. - -linkTitle -: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle]. - -markup -: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown. - -outputs -: allows you to specify output formats specific to the content. See [output formats][outputs]. - -publishDate -: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`. - -resources -: used for configuring page bundle resources. See [Page Resources][page-resources]. - -slug -: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename. - -title -: the title for the content. - -type -: the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter. - -url -: the full path to the content from the web root. It makes no assumptions about the path of the content file. It also ignores any language prefixes of -the multilingual feature. - -weight -: used for [ordering your content in lists][ordering]. - -\ -: 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._ - -{{% note "Hugo's Default URL Destinations" %}} -If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors. -{{% /note %}} - -### User-Defined - -You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates. - -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. - -{{< code-toggle copy="false" >}} -include_toc: true -show_comments: false -{{}} - - -## Order Content Through Front Matter - -You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views. - -## Override Global Markdown Configuration - -It's possible to set some options for Markdown rendering in a content's front matter as an override to the [BlackFriday rendering options set in your project configuration][config]. - -## Front Matter Format Specs - -* [TOML Spec][toml] -* [YAML Spec][yaml] -* [JSON Spec][json] - -[variables]: /variables/ -[aliases]: /content-management/urls/#aliases/ -[archetype]: /content-management/archetypes/ -[bylinktitle]: /templates/lists/#by-link-title -[config]: /getting-started/configuration/ "Hugo documentation for site configuration" -[content type]: /content-management/types/ -[contentorg]: /content-management/organization/ -[definetype]: /content-management/types/#defining-a-content-type "Learn how to specify a type and a layout in a content's front matter" -[headless-bundle]: /content-management/page-bundles/#headless-bundle -[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" -[lists]: /templates/lists/#ordering-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter." -[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating." -[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates" -[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating" -[page-resources]: /content-management/page-resources/ -[pagevars]: /variables/page/ -[section]: /content-management/sections/ -[taxweight]: /content-management/taxonomies/ -[toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language" -[urls]: /content-management/urls/ -[variables]: /variables/ -[yaml]: http://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language" diff --git a/content/content-management/image-processing/index.md b/content/content-management/image-processing/index.md deleted file mode 100644 index ecc85bb5..00000000 --- a/content/content-management/image-processing/index.md +++ /dev/null @@ -1,195 +0,0 @@ ---- -title: "Image Processing" -description: "Image Page resources can be resized and cropped." -date: 2018-01-24T13:10:00-05:00 -lastmod: 2018-01-26T15:59:07-05:00 -linktitle: "Image Processing" -categories: ["content management"] -keywords: [bundle,content,resources,images] -weight: 4004 -draft: false -toc: true -menu: - docs: - parent: "content-management" - weight: 32 ---- - -## The Image Page Resource - -The `image` is a [Page Resource]({{< relref "content-management/page-resources" >}}), and the processing methods listed below does not work on images inside your `/static` folder. - - -To get all images in a [Page Bundle]({{< relref "content-management/organization#page-bundles" >}}): - - -```go-html-template -{{ with .Resources.ByType "image" }} -{{ end }} - -``` - -## Image Processing Methods - - -The `image` resource implements the methods `Resize`, `Fit` and `Fill`, each returning the transformed image using the specified dimensions and processing options. - -Resize -: Resizes the image to the specified width and height. - -```go -// Resize to a width of 600px and preserve ratio -{{ $image := $resource.Resize "600x" }} - -// Resize to a height of 400px and preserve ratio -{{ $image := $resource.Resize "x400" }} - -// Resize to a width 600px and a height of 400px -{{ $image := $resource.Resize "600x400" }} -``` - -Fit -: Scale down the image to fit the given dimensions while maintaining aspect ratio. Both height and width are required. - -```go -{{ $image := $resource.Fit "600x400" }} -``` - -Fill -: Resize and crop the image to match the given dimensions. Both height and width are required. - -```go -{{ $image := $resource.Fill "600x400" }} -``` - - -{{% note %}} -Image operations in Hugo currently **do not preserve EXIF data** as this is not supported by Go's [image package](https://github.com/golang/go/search?q=exif&type=Issues&utf8=%E2%9C%93). This will be improved on in the future. -{{% /note %}} - - -## Image Processing Options - -In addition to the dimensions (e.g. `600x400`), Hugo supports a set of additional image options. - - -JPEG Quality -: Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. - -```go -{{ $image.Resize "600x q50" }} -``` - -Rotate -: Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. - -```go -{{ $image.Resize "600x r90" }} -``` - -Anchor -: Only relevant for the `Fill` method. This is useful for thumbnail generation where the main motive is located in, say, the left corner. -Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. - -```go -{{ $image.Fill "300x200 BottomLeft" }} -``` - -Resample Filter -: Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. - -Examples are: `Box`, `NearestNeighbor`, `Linear`, `Gaussian`. - -See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. - -```go -{{ $image.Resize "600x400 Gaussian" }} -``` - -## Image Processing Examples - -_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ - - -{{< imgproc sunset Resize "300x" />}} - -{{< imgproc sunset Fill "90x120 left" />}} - -{{< imgproc sunset Fill "90x120 right" />}} - -{{< imgproc sunset Fit "90x90" />}} - -{{< imgproc sunset Resize "300x q10" />}} - - -This is the shortcode used in the examples above: - - -{{< code file="layouts/shortcodes/imgproc.html" >}} -{{< readfile file="layouts/shortcodes/imgproc.html" >}} -{{< /code >}} - -And it is used like this: - -```go-html-template -{{}} -``` - - -{{% note %}} -**Tip:** Note the self-closing shortcode syntax above. The `imgproc` shortcode can be called both with and without **inner content**. -{{% /note %}} - -## Image Processing Config - -You can configure an `imaging` section in `config.toml` with default image processing options: - -```toml -[imaging] -# Default resample filter used for resizing. Default is Box, -# a simple and fast averaging filter appropriate for downscaling. -# See https://github.com/disintegration/imaging -resampleFilter = "box" - -# Defatult JPEG quality setting. Default is 75. -quality = 75 - -# Anchor used when cropping pictures. -# Default is "smart" which does Smart Cropping, using https://github.com/muesli/smartcrop -# Smart Cropping is content aware and tries to find the best crop for each image. -# Valid values are Smart, Center, TopLeft, Top, TopRight, Left, Right, BottomLeft, Bottom, BottomRight -anchor = "smart" - -``` - -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. - -An example using the sunset image from above: - - -{{< imgproc sunset Fill "200x200 smart" />}} - - -## Image Processing Performance Consideration - -Processed images are stored below `/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused. - -If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. - -To clean up, run: - -```bash -hugo --gc -``` - - -{{% note %}} -**GC** is short for **Garbage Collection**. -{{% /note %}} - - - diff --git a/content/content-management/image-processing/sunset.jpg b/content/content-management/image-processing/sunset.jpg deleted file mode 100644 index 7d7307be..00000000 Binary files a/content/content-management/image-processing/sunset.jpg and /dev/null differ diff --git a/content/content-management/menus.md b/content/content-management/menus.md deleted file mode 100644 index c2eadf50..00000000 --- a/content/content-management/menus.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: Menus -linktitle: Menus -description: Hugo has a simple yet powerful menu system. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-03-31 -categories: [content management] -keywords: [menus] -draft: false -menu: - docs: - parent: "content-management" - weight: 120 -weight: 120 #rem -aliases: [/extras/menus/] -toc: true ---- - -{{% note "Lazy Blogger"%}} -If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-bloggers). -{{% /note %}} - -You can do this: - -* Place content in one or many menus -* Handle nested menus with unlimited depth -* Create menu entries without being attached to any content -* Distinguish active element (and active branch) - -## What is a Menu in Hugo? - -A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`. - -{{% note "Menus on Multilingual Sites" %}} -If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus. -{{% /note %}} - -A menu entry has the following properties (i.e., variables) available to it: - -`.URL` -: string - -`.Name` -: string - -`.Menu` -: string - -`.Identifier` -: string - -`.Pre` -: template.HTML - -`.Post` -: template.HTML - -`.Weight` -: int - -`.Parent` -: string - -`.Children` -: Menu - -Note that menus also have the following functions available as well: - -`.HasChildren` -: boolean - -Additionally, there are some relevant functions available to menus on a page: - -`.IsMenuCurrent` -: (menu string, menuEntry *MenuEntry ) boolean - -`.HasMenuCurrent` -: (menu string, menuEntry *MenuEntry) boolean - -## Add content to menus - -Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/). - -### Simple - -If all you need to do is add an entry to a menu, the simple form works well. - -#### A Single Menu - -``` ---- -menu: "main" ---- -``` - -#### Multiple Menus - -``` ---- -menu: ["main", "footer"] ---- -``` - -#### Advanced - - -``` ---- -menu: - docs: - parent: 'extras' - weight: 20 ---- -``` - -## Add Non-content Entries to a Menu - -You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config]. - -Here’s an example snippet pulled from a configuration file: - -{{< code-toggle file="config.toml" >}} -[[menu.main]] - name = "about hugo" - pre = "" - weight = -110 - identifier = "about" - url = "/about/" -[[menu.main]] - name = "getting started" - pre = "" - weight = -100 - url = "/getting-started/" -{{< /code-toggle >}} - -{{% note %}} -The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`. -{{% /note %}} - -## Nesting - -All nesting of content is done via the `parent` field. - -The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu). - -The following order is used to determine an Identifier: - -`.Name > .LinkTitle > .Title` - -This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed. - -In this example, the top level of the menu is defined in your [site `config` file][config]). All content entries are attached to one of these entries via the `.Parent` field. - -## Render Menus - -See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates. - -[config]: /getting-started/configuration/ -[multilingual]: /content-management/multilingual/ -[sitevars]: /variables/ diff --git a/content/content-management/multilingual.md b/content/content-management/multilingual.md deleted file mode 100644 index 28a6e4fe..00000000 --- a/content/content-management/multilingual.md +++ /dev/null @@ -1,386 +0,0 @@ ---- -title: Multilingual Mode -linktitle: Multilingual and i18n -description: Hugo supports the creation of websites with multiple languages side by side. -date: 2017-01-10 -publishdate: 2017-01-10 -lastmod: 2017-01-10 -categories: [content management] -keywords: [multilingual,i18n, internationalization] -menu: - docs: - parent: "content-management" - weight: 150 -weight: 150 #rem -draft: false -aliases: [/content/multilingual/,/content-management/multilingual/,/tutorials/create-a-multilingual-site/] -toc: true ---- - -You should define the available languages in a `languages` section in your site configuration. - -## Configure Languages - -The following is an example of a site configuration for a multilingual Hugo project: - -{{< code-toggle file="config" >}} -DefaultContentLanguage = "en" -copyright = "Everything is mine" - -[params.navigation] -help = "Help" - -[languages] -[languages.en] -title = "My blog" -weight = 1 -[languages.en.params] -linkedin = "english-link" - -[languages.fr] -copyright = "Tout est à moi" -title = "Mon blog" -weight = 2 -[languages.fr.params] -linkedin = "lien-francais" -[languages.fr.params.navigation] -help = "Aide" -{{< /code-toggle >}} - -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). - -With the configuration above, all content, sitemap, RSS feeds, paginations, -and taxonomy pages will be rendered below `/` in English (your default content language) and then below `/fr` in French. - -When working with front matter `Params` in [single page templates][singles], omit the `params` in the key for the translation. - -If you want all of the languages to be put below their respective language code, enable `defaultContentLanguageInSubdir: true`. - -Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. - -## Disable a Language - -You can disable one or more languages. This can be useful when working on a new translation. - -```toml -disableLanguages = ["fr", "jp"] -``` - -Note that you cannot disable the default content language. - -We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables): - -```bash -HUGO_DISABLELANGUAGES="fr jp" hugo -``` -If you have already a list of disabled languages in `config.toml`, you can enable them in development like this: - -```bash -HUGO_DISABLELANGUAGES=" " hugo server -``` - - -## Configure Multilingual Multihost - -From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. - -This means that you can now configure a `baseURL` per `language`: - - -> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. - -Example: - -{{< code-toggle file="config" >}} -[languages] -[languages.no] -baseURL = "https://example.no" -languageName = "Norsk" -weight = 1 -title = "På norsk" - -[languages.en] -baseURL = "https://example.com" -languageName = "English" -weight = 2 -title = "In English" -{{}} - -With the above, the two sites will be generated into `public` with their own root: - -```bash -public -├── en -└── no -``` - -**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.** - -When you run `hugo server` we will start multiple HTTP servers. You will typlically see something like this in the console: - -```bash -Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) -Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) -Press Ctrl+C to stop -``` - -Live reload and `--navigateToChanged` between the servers work as expected. - -## Taxonomies and Blackfriday - -Taxonomies and [Blackfriday configuration][config] can also be set per language: - - -{{< code-toggle file="config" >}} -[Taxonomies] -tag = "tags" - -[blackfriday] -angledQuotes = true -hrefTargetBlank = true - -[languages] -[languages.en] -weight = 1 -title = "English" -[languages.en.blackfriday] -angledQuotes = false - -[languages.fr] -weight = 2 -title = "Français" -[languages.fr.Taxonomies] -plaque = "plaques" -{{}} - -## Translate Your Content - -Translated articles are identified by the name of the content file. - -### Examples of Translated Articles - -1. `/content/about.en.md` -2. `/content/about.fr.md` - -In this example, the `about.md` will be assigned the configured `defaultContentLanguage`. - -1. `/content/about.md` -2. `/content/about.fr.md` - -This way, you can slowly start to translate your current content without having to rename everything. If left unspecified, the default value for `defaultContentLanguage` is `en`. - -By having the same **directory and base filename**, the content pieces are linked together as translated pieces. - -You can also set the key used to link the translations explicitly in front matter: - -```yaml -translationKey: "my-story" -``` - -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" - -``` - -At render, Hugo will build both `/about/` and `/a-propos/` as properly linked translated pages. - -For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). - -## Link to Translated Content - -To create a list of links to translated content, use a template similar to the following: - -{{< code file="layouts/partials/i18nlist.html" >}} -{{ if .IsTranslated }} -

    {{ i18n "translations" }}

    - -{{ end }} -{{< /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. - -The above also uses the [`i18n` function][i18func] described in the next section. - -## List All Available Languages - -`.AllTranslations` on a `Page` can be used to list all translations, including itself. Called on the home page it can be used to build a language navigator: - - -{{< code file="layouts/partials/allLanguages.html" >}} - -{{< /code >}} - -## Translation of Strings - -Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows. - -Translations are collected from the `themes//i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc. - -{{% note %}} -From **Hugo 0.31** you no longer need to use a valid language code. It _can be_ anything. - -See https://github.com/gohugoio/hugo/issues/3564 - -{{% /note %}} - -From within your templates, use the `i18n` function like this: - -``` -{{ i18n "home" }} -``` - -This uses a definition like this one in `i18n/en-US.toml`: - -``` -[home] -other = "Home" -``` - -Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`: - -``` -{{ i18n "wordCount" . }} -``` - -This uses a definition like this one in `i18n/en-US.toml`: - -``` -[wordCount] -other = "This article has {{ .WordCount }} words." -``` -An example of singular and plural form: - -``` -[readingTime] -one = "One minute read" -other = "{{.Count}} minutes read" -``` -And then in the template: - -``` -{{ i18n "readingTime" .ReadingTime }} -``` -To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: - -``` - hugo --i18n-warnings | grep i18n -i18n|MISSING_TRANSLATION|en|wordCount -``` - -## Customize Dates - -At the time of this writing, Golang does not yet have support for internationalized locales, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content: - -~~~yaml -1: "janvier" -2: "février" -3: "mars" -4: "avril" -5: "mai" -6: "juin" -7: "juillet" -8: "août" -9: "septembre" -10: "octobre" -11: "novembre" -12: "décembre" -~~~ - -... then index the non-English date names in your templates like so: - -~~~html - -~~~ - -This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file. - -## Menus - -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: - -``` -defaultContentLanguage = "en" - -[languages.en] -weight = 0 -languageName = "English" - -[[languages.en.menu.main]] -url = "/" -name = "Home" -weight = 0 - - -[languages.de] -weight = 10 -languageName = "Deutsch" - -[[languages.de.menu.main]] -url = "/" -name = "Startseite" -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. - -``` -
      - {{- $currentPage := . -}} - {{ range .Site.Menus.main -}} -
    • - {{ .Name }} -
      • - {{- end }} -
    - -``` - -## Missing Translations - -If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. - -While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. - -{{% note %}} -Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments. -{{% /note %}} - -For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). - -## Multilingual Themes support - -To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria: - -* Come from the built-in `.Permalink` or `.URL` -* Be constructed with - * The [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** - * Prefixed with `{{ .LanguagePrefix }}` - -If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string and is therefore harmless for single-language Hugo websites. - -[abslangurl]: /functions/abslangurl -[config]: /getting-started/configuration/ -[contenttemplate]: /templates/single-page-templates/ -[go-i18n-source]: https://github.com/nicksnyder/go-i18n -[go-i18n]: https://github.com/nicksnyder/go-i18n -[homepage]: /templates/homepage/ -[i18func]: /functions/i18n/ -[menus]: /content-management/menus/ -[rellangurl]: /functions/rellangurl -[RFC 5646]: https://tools.ietf.org/html/rfc5646 -[singles]: /templates/single-page-templates/ diff --git a/content/content-management/organization/1-featured-content-bundles.png b/content/content-management/organization/1-featured-content-bundles.png deleted file mode 100644 index 1706a29d..00000000 Binary files a/content/content-management/organization/1-featured-content-bundles.png and /dev/null differ diff --git a/content/content-management/organization/index.md b/content/content-management/organization/index.md deleted file mode 100644 index b810f617..00000000 --- a/content/content-management/organization/index.md +++ /dev/null @@ -1,240 +0,0 @@ ---- -title: Content Organization -linktitle: Organization -description: Hugo assumes that the same structure that works to organize your source content is used to organize the rendered site. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [content management,fundamentals] -keywords: [sections,content,organization,bundle,resources] -menu: - docs: - parent: "content-management" - weight: 10 -weight: 10 #rem -draft: false -aliases: [/content/sections/] -toc: true ---- - -## Page Bundles - -Hugo `0.32` announced page-relative images and other resources packaged into `Page Bundles`. - -These terms are connected, and you also need to read about [Page Resources]({{< relref "content-management/page-resources" >}}) and [Image Processing]({{< relref "content-management/image-processing" >}}) to get the full picture. - -{{% imgproc 1-featured Resize "300x" %}} -The illustration shows 3 bundles. Note that the home page bundle cannot contain other content pages, but other files (images etc.) are fine. -{{% /imgproc %}} - - -{{% note %}} -The bundle documentation is **work in progress**. We will publish more comprehensive docs about this soon. -{{% /note %}} - - -# Organization of Content Source - - -In Hugo, your content should be organized in a manner that reflects the rendered website. - -While Hugo supports content nested at any level, the top levels (i.e. `content/`) are special in Hugo and are considered the content type used to determine layouts etc. To read more about sections, including how to nest them, see [sections][]. - -Without any additional configuration, the following will just work: - -``` -. -└── content - └── about - | └── _index.md // <- https://example.com/about/ - ├── post - | ├── firstpost.md // <- https://example.com/post/firstpost/ - | ├── happy - | | └── ness.md // <- https://example.com/post/happy/ness/ - | └── secondpost.md // <- https://example.com/post/secondpost/ - └── quote - ├── first.md // <- https://example.com/quote/first/ - └── second.md // <- https://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 = "https://example.com"` in your [site's configuration file][config]. - -### Index Pages: `_index.md` - -`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists]. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][]. - -{{% note %}} -**Tip:** You can get a reference to the content and metadata in `_index.md` using the [`.Site.GetPage` function](/functions/getpage/). -{{% /note %}} - -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: - - -``` -. url -. ⊢--^-⊣ -. path slug -. ⊢--^-⊣⊢---^---⊣ -. filepath -. ⊢------^------⊣ -content/posts/_index.md -``` - -At build, this will output to the following destination with the associated values: - -``` - - url ("/posts/") - ⊢-^-⊣ - baseurl section ("posts") -⊢--------^---------⊣⊢-^-⊣ - permalink -⊢----------^-------------⊣ -https://example.com/posts/index.html -``` - -The [sections][] can be nested as deeply as you need. The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (i.e. `_index.md`). - - -### Single Pages in Sections - -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`: - - -``` - path ("posts/my-first-hugo-post.md") -. ⊢-----------^------------⊣ -. section slug -. ⊢-^-⊣⊢--------^----------⊣ -content/posts/my-first-hugo-post.md -``` - -At the time Hugo builds your site, the content will be output to the following destination: - -``` - - url ("/posts/my-first-hugo-post/") - ⊢------------^----------⊣ - baseurl section slug -⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣ - permalink -⊢--------------------^---------------------⊣ -https://example.com/posts/my-first-hugo-post/index.html -``` - - -## Paths Explained - -The following concepts will provide more insight into the relationship between your project's organization and the default behaviors of Hugo when building the output website. - -### `section` - -A default content type is determined by a piece of content's section. `section` is determined by the location within the project's `content` directory. `section` *cannot* be specified or overridden in front matter. - -### `slug` - -A content's `slug` is either `name.extension` or `name/`. The value for `slug` is determined by - -* the name of the content file (e.g., `lollapalooza.md`) OR -* front matter overrides - -### `path` - -A content's `path` is determined by the section's path to the file. The file `path` - -* is based on the path to the content's location AND -* does not include the slug - -### `url` - -The `url` is the relative URL for the piece of content. The `url` - -* is based on the content's location within the directory structure OR -* is defined in front matter and *overrides all the above* - -## Override Destination Paths via Front Matter - -Hugo believes that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored in the destination. - -There are times where you may need more control over your content. In these cases, there are fields that can be specified in the front matter to determine the destination of a specific piece of content. - -The following items are defined in this order for a specific reason: items explained further down in the list will override earlier items, and not all of these items can be defined in front matter: - -### `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 `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" >}} ---- -title: New Post -slug: "new-post" ---- -{{< /code >}} - -This will render to the following destination according to Hugo's default behavior: - -``` -example.com/posts/new-post/ -``` - -### `section` - -`section` is determined by a content's location on disk and *cannot* be specified in the front matter. See [sections][] for more information. - -### `type` - -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" >}} ---- -title: My Post -type: new -layout: mylayout ---- -{{< /code >}} - - - - - -### `url` - -A complete URL can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseURL (starting with a `/`). `url` will be used exactly as it provided in the front matter and will ignore the `--uglyURLs` setting in your site configuration: - -{{< code file="content/posts/old-url.md" >}} ---- -title: Old URL -url: /blog/new-url/ ---- -{{< /code >}} - -Assuming your `baseURL` is [configured][config] to `https://example.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination: - -``` -https://example.com/blog/new-url/ -``` - -You can see more information on how to control output paths in [URL Management][urls]. - -[config]: /getting-started/configuration/ -[formats]: /content-management/formats/ -[front matter]: /content-management/front-matter/ -[getpage]: /functions/getpage/ -[homepage template]: /templates/homepage/ -[homepage]: /templates/homepage/ -[lists]: /templates/lists/ -[pretty]: /content-management/urls/#pretty-urls -[section templates]: /templates/section-templates/ -[sections]: /content-management/sections/ -[singles]: /templates/single-page-templates/ -[taxonomy templates]: /templates/taxonomy-templates/ -[taxonomy terms templates]: /templates/taxonomy-templates/ -[types]: /content-management/types/ -[urls]: /content-management/urls/ diff --git a/content/content-management/page-bundles.md b/content/content-management/page-bundles.md deleted file mode 100644 index 34620a5e..00000000 --- a/content/content-management/page-bundles.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -title : "Page Bundles" -description : "Content organization using Page Bundles" -date : 2018-01-24T13:09:00-05:00 -lastmod : 2018-01-28T22:26:40-05:00 -linktitle : "Page Bundles" -keywords : ["page", "bundle", "leaf", "branch"] -categories : ["content management"] -toc : true -menu : - docs: - identifier : "page-bundles" - parent : "content-management" - weight : 11 ---- - -Page Bundles are a way to group [Page Resources](/content-management/page-resources/). - -A Page Bundle can be one of: - -- Leaf Bundle (leaf means it has no children) -- Branch Bundle (home page, section, taxonomy terms, taxonomy list) - -| | Leaf Bundle | Branch Bundle | -|-----------------|--------------------------------------------------------|---------------------------------------------------------| -| Usage           | Collection of resources (pages, images etc.) for single pages | Collection of non-page resources (images etc.)for list pages | -| Index file name | `index.md` [^fn:1] | `_index.md` [^fn:1] | -| Layout type | `single` | `list` | -| Nesting | Doesn't allow nesting of more bundles under it | Allows nesting of leaf/branch bundles under it | -| Example | `content/posts/my-post/index.md` | `content/posts/_index.md` | - - -## Leaf Bundles {#leaf-bundles} - -A _Leaf Bundle_ is a directory at any hierarchy within the `content/` -directory, that contains an **`index.md`** file. - -### Examples of Leaf Bundle organization {#examples-of-leaf-bundle-organization} - -```text -content/ -├── about -│ ├── index.md -├── posts -│ ├── my-post -│ │ ├── content1.md -│ │ ├── content2.md -│ │ ├── image1.jpg -│ │ ├── image2.png -│ │ └── index.md -│ └── my-another-post -│    └── index.md -│ -└── another-section - ├── .. -    └── not-a-leaf-bundle - ├── .. -    └── another-leaf-bundle -    └── index.md -``` - -In the above example `content/` directory, there are four leaf -bundles: - -about -: This leaf bundle is at the root level (directly under - `content` directory) and has only the `index.md`. - -my-post -: This leaf bundle has the `index.md`, two other content - Markdown files and two image files. - -my-another-post -: This leaf bundle has only the `index.md`. - -another-leaf-bundle -: This leaf bundle is nested under couple of - directories. This bundle also has only the `index.md`. - -{{% note %}} -The hierarchy depth at which a leaf bundle is created does not matter, -as long as it is not inside another **leaf** bundle. -{{% /note %}} - - -### Headless Bundle {#headless-bundle} - -A headless bundle is a bundle that is configured to not get published -anywhere: - -- It will have no `Permalink` and no rendered HTML in `public/`. -- It will not be part of `.Site.RegularPages`, etc. - -But you can get it by `.Site.GetPage`. Here is an example: - -```go-html-template -{{ $headless := .Site.GetPage "page" "some-headless-bundle" }} -{{ $reusablePages := $headless.Resources.Match "author*" }} -

    Authors

    -{{ range $reusablePages }} -

    {{ .Title }}

    - {{ .Content }} -{{ end }} -``` - -_In this example, we are assuming the `some-headless-bundle` to be a headless - bundle containing one or more **page** resources whose `.Name` matches - `"author*"`._ - -Explanation of the above example: - -1. Get the `some-headless-bundle` Page "object". -2. Collect a *slice* of resources in this *Page Bundle* that matches - `"author*"` using `.Resources.Match`. -3. Loop through that *slice* of nested pages, and output their `.Title` and - `.Content`. - ---- - -A leaf bundle can be made headless by adding below in the Front Matter -(in the `index.md`): - -```toml -headless = true -``` - -{{% note %}} -Only leaf bundles can be made headless. -{{% /note %}} - -There are many use cases of such headless page bundles: - -- Shared media galleries -- Reusable page content "snippets" - - -## Branch Bundles {#branch-bundles} - -A _Branch Bundle_ is any directory at any hierarchy within the -`content/` directory, that contains at least an **`_index.md`** file. - -This `_index.md` can also be directly under the `content/` directory. - -{{% note %}} -Here `md` (markdown) is used just as an example. You can use any file -type as a content resource as long as it is a content type recognized by Hugo. -{{% /note %}} - - -### Examples of Branch Bundle organization {#examples-of-branch-bundle-organization} - -```text -content/ -├── branch-bundle-1 -│   ├── branch-content1.md -│   ├── branch-content2.md -│   ├── image1.jpg -│   ├── image2.png -│   └── _index.md -└── branch-bundle-2 - ├── _index.md - └── a-leaf-bundle - └── index.md -``` - -In the above example `content/` directory, there are two branch -bundles (and a leaf bundle): - -`branch-bundle-1` -: This branch bundle has the `_index.md`, two - other content Markdown files and two image files. - -`branch-bundle-2` -: This branch bundle has the `_index.md` and a - nested leaf bundle. - -{{% note %}} -The hierarchy depth at which a branch bundle is created does not -matter. -{{% /note %}} - -[^fn:1]: The `.md` extension is just an example. The extension can be `.html`, `.json` or any of any valid MIME type. diff --git a/content/content-management/page-resources.md b/content/content-management/page-resources.md deleted file mode 100644 index cefb1cd4..00000000 --- a/content/content-management/page-resources.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -title : "Page Resources" -description : "Page Resources -- images, other pages, documents etc. -- have page-relative URLs and their own metadata." -date: 2018-01-24 -categories: ["content management"] -keywords: [bundle,content,resources] -weight: 4003 -draft: false -toc: true -linktitle: "Page Resources" -menu: - docs: - parent: "content-management" - weight: 31 ---- - -## Properties - -ResourceType -: The main type of the resource. For example, a file of MIME type `image/jpg` has for ResourceType `image`. - -Name -: Default value is the filename (relative to the owning page). Can be set in front matter. - -Title -: Default blank. Can be set in front matter. - -Permalink -: The absolute URL to the resource. Resources of type `page` will have no value. - -RelPermalink -: The relative URL to the resource. Resources of type `page` will have no value. - -## Methods -ByType -: Returns the page resources of the given type. - -```go -{{ .Resources.ByType "image" }} -``` -Match -: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive. - -```go -{{ .Resources.Match "images/*" }} -``` - -GetMatch -: Same as `Match` but will return the first match. - -### Pattern Matching -```go -// Using Match/GetMatch to find this images/sunset.jpg ? -.Resources.Match "images/sun*" ✅ -.Resources.Match "**/Sunset.jpg" ✅ -.Resources.Match "images/*.jpg" ✅ -.Resources.Match "**.jpg" ✅ -.Resources.Match "*" 🚫 -.Resources.Match "sunset.jpg" 🚫 -.Resources.Match "*sunset.jpg" 🚫 - -``` - -## Page Resources Metadata - -Page Resources' metadata is managed from their page's front matter with an array/table parameter named `resources`. You can batch assign values using a [wildcards](http://tldp.org/LDP/GNU-Linux-Tools-Summary/html/x11655.htm). - -{{% note %}} -Resources of type `page` get `Title` etc. from their own front matter. -{{% /note %}} - -name -: Sets the value returned in `Name`. - -{{% warning %}} -The methods `Match` and `GetMatch` use `Name` to match the resources. -{{%/ warning %}} - -title -: Sets the value returned in `Title` - -params -: A map of custom key/values. - - -### Resources metadata example - -{{< code-toggle copy="false">}} -title: Application -date : 2018-01-25 -resources : -- src : "images/sunset.jpg" - name : "header" -- src : "documents/photo_specs.pdf" - title : "Photo Specifications" - params: - icon : "photo" -- src : "documents/guide.pdf" - title : "Instruction Guide" -- src : "documents/checklist.pdf" - title : "Document Checklist" -- src : "documents/payment.docx" - title : "Proof of Payment" -- src : "**.pdf" - name : "pdf-file-:counter" - params : - icon : "pdf" -- src : "**.docx" - params : - icon : "word" -{{}} - -From the example above: - -- `sunset.jpg` will receive a new `Name` and can now be found with `.GetMatch "header"`. -- `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`. -- Every docx in the bundle will receive the `word` icon. - -{{% warning %}} -The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. For example, in the above example, `.Params.icon` is already first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule. -{{%/ warning %}} - -### The `:counter` placeholder in `name` and `title` - -The `:counter` is a special placeholder recognized in `name` and `title` parameters `resources`. - -The counter starts at 1 the first time they are used in either `name` or `title`. - -For example, if a bundle has the resources `photo_specs.pdf`, `other_specs.pdf`, `guide.pdf` and `checklist.pdf`, and the front matter has specified the `resources` as: - -{{< code-toggle copy="false">}} -[[resources]] - src = "*specs.pdf" - title = "Specification #:counter" -[[resources]] - src = "**.pdf" - name = "pdf-file-:counter" -{{}} - -the `Name` and `Title` will be assigned to the resource files as follows: - -| Resource file | `Name` | `Title` | -|-------------------|-------------------|-----------------------| -| checklist.pdf | `"pdf-file-1.pdf` | `"checklist.pdf"` | -| guide.pdf | `"pdf-file-2.pdf` | `"guide.pdf"` | -| other\_specs.pdf | `"pdf-file-3.pdf` | `"Specification #1"` | -| photo\_specs.pdf | `"pdf-file-4.pdf` | `"Specification #2"` | diff --git a/content/content-management/related.md b/content/content-management/related.md deleted file mode 100644 index 6f66e446..00000000 --- a/content/content-management/related.md +++ /dev/null @@ -1,143 +0,0 @@ ---- -title: Related Content -description: List related content in "See Also" sections. -date: 2017-09-05 -categories: [content management] -keywords: [content] -menu: - docs: - parent: "content-management" - weight: 40 -weight: 30 -draft: false -aliases: [/content/related/,/related/] -toc: true ---- - -{{% note %}} -We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock). -{{% /note %}} - -## List Related Content - -To list up to 5 related pages is as simple as including something similar to this partial in your single page template: - -{{< code file="layouts/partials/related.html" >}} -{{ $related := .Site.RegularPages.Related . | first 5 }} -{{ with $related }} -

    See Also

    - -{{ end }} -{{< /code >}} - - -{{% 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. -{{% /note %}} - -The full set of methods available on the page lists can bee seen in this Go interface: - -```go -// A PageGenealogist finds related pages in a page collection. This interface is implemented -// by Pages and PageGroup, which makes it available as `{{ .RegularPages.Related . }}` etc. -type PageGenealogist interface { - - // Template example: - // {{ $related := .RegularPages.Related . }} - Related(doc related.Document) (Pages, error) - - // Template example: - // {{ $related := .RegularPages.RelatedIndices . "tags" "date" }} - RelatedIndices(doc related.Document, indices ...interface{}) (Pages, error) - - // Template example: - // {{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }} - RelatedTo(args ...types.KeyValues) (Pages, error) -} -``` -## Configure Related Content -Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed. - -{{% note %}} -If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults. -{{% /note %}} - -Below is a sample `config.toml` section: - -``` -[related] - -# Only include matches with rank >= threshold. This is a normalized rank between 0 and 100. -threshold = 80 - -# To get stable "See also" sections we, by default, exclude newer related pages. -includeNewer = false - -# Will lower case keywords in both queries and in the indexes. -toLower = false - -[[related.indices]] -name = "keywords" -weight = 150 -[[related.indices]] -name = "author" -toLower = true -weight = 30 -[[related.indices]] -name = "tags" -weight = 100 -[[related.indices]] -name = "date" -weight = 10 -pattern = "2006" -``` -### Top Level Config Options - -threshold -: A value between 0-100. Lower value will give more, but maybe not so relevant, matches. - -includeNewer -: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added. - -toLower -: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index. - -### Config Options per Index - -name -: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. - -weight -: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. - -pattern -: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. - -toLower -: See above. - -## Performance Considerations - -**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast. - -This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread: - -{{< tweet 898398437527363585 >}} - -Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog. - -He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that: - -* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before. -* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites. - - - - - - - diff --git a/content/content-management/sections.md b/content/content-management/sections.md deleted file mode 100644 index e53e0feb..00000000 --- a/content/content-management/sections.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Content Sections -linktitle: Sections -description: "Hugo generates a **section tree** that matches your content." -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [content management] -keywords: [lists,sections,content types,organization] -menu: - docs: - parent: "content-management" - weight: 50 -weight: 50 #rem -draft: false -aliases: [/content/sections/] -toc: true ---- - -A **Section** is a collection of pages that gets defined based on the -organization structure under the `content/` directory. - -By default, all the **first-level** directories under `content/` form their own -sections (**root sections**). - -If a user needs to define a section `foo` at a deeper level, they need to create -a directory named `foo` with an `_index.md` file (see [Branch Bundles][branch bundles] -for more information). - - -{{% note %}} -A **section** cannot be defined or overridden by a front matter parameter -- it -is strictly derived from the content organization structure. -{{% /note %}} - -## Nested Sections - -The sections can be nested as deeply as you need. - -```bash -content -└── blog <-- Section, because first-level dir under content/ - ├── funny-cats - │   ├── mypost.md - │   └── kittens <-- Section, because contains _index.md - │   └── _index.md - └── tech <-- Section, because contains _index.md - └── _index.md -``` - -**The important part to understand is, that to make the section tree fully navigational, at least the lower-most section needs a content file. (e.g. `_index.md`).** - -{{% note %}} -When we talk about a **section** in correlation with template selection, it is -currently always the *root section* only (`/blog/funny-cats/mypost/ => blog`). - -If you need a specific template for a sub-section, you need to adjust either the `type` or `layout` in front matter. -{{% /note %}} - -## Example: Breadcrumb Navigation - -With the available [section variables and methods](#section-page-variables-and-methods) you can build powerful navigation. One common example would be a partial to show Breadcrumb navigation: - -{{< code file="layouts/partials/breadcrumb.html" download="breadcrumb.html" >}} -
      - {{ template "breadcrumbnav" (dict "p1" . "p2" .) }} -
    -{{ define "breadcrumbnav" }} -{{ if .p1.Parent }} -{{ template "breadcrumbnav" (dict "p1" .p1.Parent "p2" .p2 ) }} -{{ else if not .p1.IsHome }} -{{ template "breadcrumbnav" (dict "p1" .p1.Site.Home "p2" .p2 ) }} -{{ end }} - - {{ .p1.Title }} - -{{ end }} -{{< /code >}} - -## Section Page Variables and Methods - -Also see [Page Variables](/variables/page/). - -{{< readfile file="/content/readfiles/sectionvars.md" markdown="true" >}} - -## Content Section Lists - -Hugo will automatically create pages for each *root section* that list all of the content in that section. See the documentation on [section templates][] for details on customizing the way these pages are rendered. - -## Content *Section* vs Content *Type* - -By default, everything created within a section will use the [content `type`][content type] that matches the *root section* name. For example, Hugo will assume that `posts/post-1.md` has a `posts` content `type`. If you are using an [archetype][] for your `posts` section, Hugo will generate front matter according to what it finds in `archetypes/posts.md`. - -[archetype]: /content-management/archetypes/ -[content type]: /content-management/types/ -[directory structure]: /getting-started/directory-structure/ -[section templates]: /templates/section-templates/ -[branch bundles]: /content-management/page-bundles/#branch-bundles diff --git a/content/content-management/shortcodes.md b/content/content-management/shortcodes.md deleted file mode 100644 index e5bc8526..00000000 --- a/content/content-management/shortcodes.md +++ /dev/null @@ -1,424 +0,0 @@ ---- -title: Shortcodes -linktitle: -description: Shortcodes are simple snippets inside your content files calling built-in or custom templates. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-03-31 -menu: - docs: - parent: "content-management" - weight: 35 -weight: 35 #rem -categories: [content management] -keywords: [markdown,content,shortcodes] -draft: false -aliases: [/extras/shortcodes/] -toc: true ---- - -## What a Shortcode is - -Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video ``) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax. - -Hugo created **shortcodes** to circumvent these limitations. - -A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead. - -In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation. - -## Use Shortcodes - -{{< youtube 2xkNJL4gJ9E >}} - -In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted. - -The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`. - -Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash. - -Here are two examples of paired shortcodes: - -``` -{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}} -``` - -``` -{{}} A bunch of code here {{}} -``` - -The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second. - -### Shortcodes with Markdown - -The `%` character indicates that the shortcode's inner content---called in the [shortcode template][sctemps] with the [`.Inner` variable][scvars]---needs further processing by the page's rendering processor (i.e. markdown via Blackfriday). In the following example, Blackfriday would convert `**World**` to `World`: - -``` -{{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}} -``` - -### Shortcodes Without Markdown - -The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML: - -``` -{{}}

    Hello World!

    {{}} -``` - -### Nested Shortcodes - -You can call shortcodes within other shortcodes by creating your own templates that leverage the `.Parent` variable. `.Parent` allows you to check the context in which the shortcode is being called. See [Shortcode templates][sctemps]. - -## Use Hugo's Built-in Shortcodes - -Hugo ships with a set of predefined shortcodes that represent very common usage. These shortcodes are provided for author convenience and to keep your markdown content clean. - -### `figure` - -`figure` is an extension of the image syntax in markdown, which does not provide a shorthand for the more semantic [HTML5 `
    ` element][figureelement]. - -The `figure` shortcode can use the following named parameters: - -src -: URL of the image to be displayed. - -link -: If the image needs to be hyperlinked, URL of the destination. - -target -: Optional `target` attribute for the URL if `link` parameter is set. - -rel -: Optional `rel` attribute for the URL if `link` parameter is set. - -alt -: Alternate text for the image if the image cannot be displayed. - -title -: Image title. - -caption -: Image caption. - -class -: `class` attribute of the HTML `figure` tag. - -height -: `height` attribute of the image. - -width -: `width` attribute of the image. - -attr -: Image attribution text. - -attrlink -: If the attribution text needs to be hyperlinked, URL of the destination. - -#### Example `figure` Input - -{{< code file="figure-input-example.md" >}} -{{}} -{{< /code >}} - -#### Example `figure` Output - -{{< output file="figure-output-example.html" >}} -
    - -
    -

    Steve Francia

    -
    -
    -{{< /output >}} - -### `gist` - -Bloggers often want to include GitHub gists when writing posts. Let's suppose we want to use the [gist at the following url][examplegist]: - -``` -https://gist.github.com/spf13/7896402 -``` - -We can embed the gist in our content via username and gist ID pulled from the URL: - -``` -{{}} -``` - -#### Example `gist` Input - -If the gist contains several files and you want to quote just one of them, you can pass the filename (quoted) as an optional third argument: - -{{< code file="gist-input.md" >}} -{{}} -{{< /code >}} - -#### Example `gist` Output - -{{< output file="gist-output.html" >}} -{{< gist spf13 7896402 >}} -{{< /output >}} - -#### Example `gist` Display - -To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. - -{{< gist spf13 7896402 >}} - -### `highlight` - -This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/tools/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode. - -#### Example `highlight` Input - -{{< code file="content/tutorials/learn-html.md" >}} -{{}} -
    -
    -

    {{ .Title }}

    - {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
    -
    -{{}} -{{< /code >}} - -#### Example `highlight` Output - -The `highlight` shortcode example above would produce the following HTML when the site is rendered: - -{{< output file="tutorials/learn-html/index.html" >}} -<section id="main"> - <div> - <h1 id="title">{{ .Title }}</h1> - {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} - </div> -</section> -{{< /output >}} - -{{% note "More on Syntax Highlighting" %}} -To see even more options for adding syntax-highlighted code blocks to your website, see [Syntax Highlighting in Developer Tools](/tools/syntax-highlighting/). -{{% /note %}} - -### `instagram` - -If you'd like to embed a photo from [Instagram][], you only need the photo's ID. You can discern an Instagram photo ID from the URL: - -``` -https://www.instagram.com/p/BWNjjyYFxVx/ -``` - -#### Example `instagram` Input - -{{< code file="instagram-input.md" >}} -{{}} -{{< /code >}} - -You also have the option to hide the caption: - -{{< code file="instagram-input-hide-caption.md" >}} -{{}} -{{< /code >}} - -#### Example `instagram` Output - -By adding the preceding `hidecaption` example, the following HTML will be added to your rendered website's markup: - -{{< output file="instagram-hide-caption-output.html" >}} -{{< instagram BWNjjyYFxVx hidecaption >}} -{{< /output >}} - -#### Example `instagram` Display - -Using the preceding `instagram` with hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. - -{{< instagram BWNjjyYFxVx hidecaption >}} - - -### `ref` and `relref` - -These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page. - -`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo. - -{{% note "More on Cross References" %}} -Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation. -{{% /note %}} - -`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`. - -#### Example `ref` and `relref` Input - -``` -[Neat]({{}}) -[Who]({{}}) -``` - -#### Example `ref` and `relref` Output - -Assuming that standard Hugo pretty URLs are turned on. - -``` -Neat -Who -``` - -### `speakerdeck` - -To embed slides from [Speaker Deck][], click on "< /> Embed" (under Share right next to the template on Speaker Deck) and copy the URL: - -``` - -``` - -#### `speakerdeck` Example Input - -Extract the value from the field `data-id` and pass it to the shortcode: - -{{< code file="speakerdeck-example-input.md" >}} -{{}} -{{< /code >}} - -#### `speakerdeck` Example Output - -{{< output file="speakerdeck-example-input.md" >}} -{{< speakerdeck 4e8126e72d853c0060001f97 >}} -{{< /output >}} - -#### `speakerdeck` Example Display - -For the preceding `speakerdeck` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. - -{{< speakerdeck 4e8126e72d853c0060001f97 >}} - -### `tweet` - -You want to include a single tweet into your blog post? Everything you need is the URL of the tweet: - -``` -https://twitter.com/spf13/status/877500564405444608 -``` - -#### Example `tweet` Input - -Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode: - -{{< code file="example-tweet-input.md" >}} -{{}} -{{< /code >}} - -#### Example `tweet` Output - -Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup: - -{{< output file="example-tweet-output.html" >}} -{{< tweet 877500564405444608 >}} -{{< /output >}} - -#### Example `tweet` Display - -Using the preceding `tweet` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. - -{{< tweet 877500564405444608 >}} - -### `vimeo` - -Adding a video from [Vimeo][] is equivalent to the YouTube shortcode above. - -``` -https://vimeo.com/channels/staffpicks/146022717 -``` - -#### Example `vimeo` Input - -Extract the ID from the video's URL and pass it to the `vimeo` shortcode: - -{{< code file="example-vimeo-input.md" >}} -{{}} -{{< /code >}} - -#### Example `vimeo` Output - -Using the preceding `vimeo` example, the following HTML will be added to your rendered website's markup: - -{{< output file="example-vimeo-output.html" >}} -{{< vimeo 146022717 >}} -{{< /output >}} - -{{% tip %}} -If you want to further customize the visual styling of the YouTube or Vimeo output, add a `class` named parameter when calling the shortcode. The new `class` will be added to the `
    ` that wraps the ` +
    +{{< /code >}} + +{{< code file="youtube-embed.html" copy="false" >}} +
    + +
    +{{< /code >}} + +### Single Named Example: `image` + +Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files: + +{{< code file="content-image.md" >}} +{{}} +{{< /code >}} + +You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template: + +{{< code file="/layouts/shortcodes/img.html" >}} + +
    + {{ with .Get "link"}}{{ end }} + + {{ if .Get "link"}}{{ end }} + {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}} +
    {{ if isset .Params "title" }} +

    {{ .Get "title" }}

    {{ end }} + {{ if or (.Get "caption") (.Get "attr")}}

    + {{ .Get "caption" }} + {{ with .Get "attrlink"}} {{ end }} + {{ .Get "attr" }} + {{ if .Get "attrlink"}} {{ end }} +

    {{ end }} +
    + {{ end }} +
    + +{{< /code >}} + +Would be rendered as: + +{{< code file="img-output.html" copy="false" >}} +
    + +
    +

    Steve Francia

    +
    +
    +{{< /code >}} + +### Single Flexible Example: `vimeo` + +``` +{{}} +{{}} +``` + +Would load the template found at `/layouts/shortcodes/vimeo.html`: + +{{< code file="/layouts/shortcodes/vimeo.html" >}} +{{ if .IsNamedParams }} +
    + +
    +{{ else }} +
    + +
    +{{ end }} +{{< /code >}} + +Would be rendered as: + +{{< code file="vimeo-iframes.html" copy="false" >}} +
    + +
    +
    + +
    +{{< /code >}} + +### Paired Example: `highlight` + +The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo. + +{{< code file="highlight-example.md" >}} +{{}} + + This HTML + +{{}} +{{< /code >}} + +The template for the `highlight` shortcode uses the following code, which is already included in Hugo: + +``` +{{ .Get 0 | highlight .Inner }} +``` + +The rendered output of the HTML example code block will be as follows: + +{{< code file="syntax-highlighted.html" copy="false" >}} +
    <html>
+    <body> This HTML </body>
+</html>
+
    +{{< /code >}} + +{{% note %}} +The preceding shortcode makes use of a Hugo-specific template function called `highlight`, which uses [Pygments](http://pygments.org) to add syntax highlighting to the example HTML code block. See the [developer tools page on syntax highlighting](/tools/syntax-highlighting/) for more information. +{{% /note %}} + +### Nested Shortcode: Image Gallery + +Hugo's [`.Parent` shortcode variable][parent] returns a boolean value depending on whether the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters. + +The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter: + +{{< code file="layouts/shortcodes/gallery.html" >}} +
    + {{.Inner}} +
    +{{< /code >}} + +You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`: + +{{< code file="layouts/shortcodes/img.html" >}} +{{- $src := .Get "src" -}} +{{- with .Parent -}} + +{{- else -}} + +{{- end }} +{{< /code >}} + +You can then call your shortcode in your content as follows: + +``` +{{}} + {{}} + {{}} +{{}} +{{}} +``` + +This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`: + +``` +
    + + +
    + +``` + +## More Shortcode Examples + +More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes]. + +[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website." +[built-in shortcode]: /content-management/shortcodes/ +[config]: /getting-started/configuration/ "Learn more about Hugo's built-in configuration variables as well as how to us your site's configuration file to include global key-values that can be used throughout your rendered website." +[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes "Check this section if you are not familiar with the definition of what a shortcode is or if you are unfamiliar with how to use Hugo's built-in shortcodes in your content files." +[source organization]: /getting-started/directory-structure/#directory-structure-explained "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories." +[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading." +[figure]: /content-management/shortcodes/#figure +[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes +[lookup order]: /templates/lookup-order/ "See the order in which Hugo traverses your template files to decide where and how to render your content at build time" +[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates." +[parent]: /variables/shortcodes/ +[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template." +[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia." +[templates]: /templates/ "The templates section of the Hugo docs." +[vimeoexample]: #single-flexible-example-vimeo +[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode." diff --git a/content/en/templates/single-page-templates.md b/content/en/templates/single-page-templates.md new file mode 100644 index 00000000..79e1312b --- /dev/null +++ b/content/en/templates/single-page-templates.md @@ -0,0 +1,92 @@ +--- +title: Single Page Templates +linktitle: +description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-04-06 +categories: [templates] +keywords: [page,templates] +menu: + docs: + parent: "templates" + weight: 60 +weight: 60 +sections_weight: 60 +draft: false +aliases: [/layout/content/] +toc: true +--- + +## Single Page Template Lookup Order + +See [Template Lookup](/templates/lookup-order/). + +## Example Single Page Templates + +Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates. + +### `post/single.html` + +This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter. + +{{< code file="layouts/post/single.html" download="single.html" >}} +{{ define "main" }} +
    +

    {{ .Title }}

    +
    +
    + {{ .Content }} +
    +
    +
    + +{{ end }} +{{< /code >}} + +To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes]. + +[archetypes]: /content-management/archetypes/ +[base templates]: /templates/base/ +[config]: /getting-started/configuration/ +[content type]: /content-management/types/ +[directory structure]: /getting-started/directory-structure/ +[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself +[`.Format` function]: /functions/format/ +[front matter]: /content-management/front-matter/ +[pagetaxonomy]: /templates/taxonomy-templates/#displaying-a-single-piece-of-content-s-taxonomies +[pagevars]: /variables/page/ +[partials]: /templates/partials/ +[section]: /content-management/sections/ +[site variables]: /variables/site/ +[spf13]: http://spf13.com/ +[`with`]: /functions/with/ diff --git a/content/en/templates/sitemap-template.md b/content/en/templates/sitemap-template.md new file mode 100644 index 00000000..29b59ad1 --- /dev/null +++ b/content/en/templates/sitemap-template.md @@ -0,0 +1,75 @@ +--- +title: Sitemap Template +# linktitle: Sitemap +description: Hugo ships with a built-in template file observing the v0.9 of the Sitemap Protocol, but you can override this template if needed. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [sitemap, xml, templates] +menu: + docs: + parent: "templates" + weight: 160 +weight: 160 +sections_weight: 160 +draft: false +aliases: [/layout/sitemap/,/templates/sitemap/] +toc: false +--- + +A single Sitemap template is used to generate the `sitemap.xml` file. +Hugo automatically comes with this template file. *No work is needed on +the users' part unless they want to customize `sitemap.xml`.* + +A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use in this template along with Sitemap-specific ones: + +`.Sitemap.ChangeFreq` +: The page change frequency + +`.Sitemap.Priority` +: The priority of the page + +`.Sitemap.Filename` +: The sitemap filename + +If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo. + +## Hugo’s sitemap.xml + +This template respects the version 0.9 of the [Sitemap Protocol](http://www.sitemaps.org/protocol.html). + +``` + + {{ range .Data.Pages }} + + {{ .Permalink }}{{ if not .Lastmod.IsZero }} + {{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}{{ end }}{{ with .Sitemap.ChangeFreq }} + {{ . }}{{ end }}{{ if ge .Sitemap.Priority 0.0 }} + {{ .Sitemap.Priority }}{{ end }} + + {{ end }} + +``` + +{{% note %}} +Hugo will automatically add the following header line to this file +on render. Please don't include this in the template as it's not valid HTML. + +`` +{{% /note %}} + +## Configure `sitemap.xml` + +Defaults for ``, `` and `filename` values can be set in the site's config file, e.g.: + +{{< code-toggle file="config" >}} +[sitemap] + changefreq = "monthly" + priority = 0.5 + filename = "sitemap.xml" +{{}} + +The same fields can be specified in an individual content file's front matter in order to override the value assigned to that piece of content at render time. + +[pagevars]: /variables/page/ \ No newline at end of file diff --git a/content/en/templates/taxonomy-templates.md b/content/en/templates/taxonomy-templates.md new file mode 100644 index 00000000..f3b349a3 --- /dev/null +++ b/content/en/templates/taxonomy-templates.md @@ -0,0 +1,347 @@ +--- +title: Taxonomy Templates +# linktitle: +description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [taxonomies,metadata,front matter,terms,templates] +menu: + docs: + parent: "templates" + weight: 50 +weight: 50 +sections_weight: 50 +draft: false +aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/] +toc: true +--- + + + +Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature. + +Hugo provides multiple ways to use taxonomies throughout your project templates: + +* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-template) +* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-template) +* List a single content's taxonomy terms within a [single page template][] + +## Taxonomy List Templates + +Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists]. + +### Taxonomy List Template Lookup Order + +See [Template Lookup](/templates/lookup-order/). + +## Taxonomy Terms Template + +### Taxonomy Terms Templates Lookup Order + +See [Template Lookup](/templates/lookup-order/). + +### Taxonomy Methods + +A Taxonomy is a `map[string]WeightedPages`. + +.Get(term) +: Returns the WeightedPages for a term. + +.Count(term) +: The number of pieces of content assigned to this term. + +.Alphabetical +: Returns an OrderedTaxonomy (slice) ordered by Term. + +.ByCount +: Returns an OrderedTaxonomy (slice) ordered by number of entries. + +.Reverse +: Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy. + +### OrderedTaxonomy + +Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order. + +``` +[]struct { + Name string + WeightedPages WeightedPages +} +``` + +Each element of the slice has: + +.Term +: The Term used. + +.WeightedPages +: A slice of Weighted Pages. + +.Count +: The number of pieces of content assigned to this term. + +.Pages +: All Pages assigned to this term. All [list methods][renderlists] are available to this. + +## WeightedPages + +WeightedPages is simply a slice of WeightedPage. + +``` +type WeightedPages []WeightedPage +``` + +.Count(term) +: The number of pieces of content assigned to this term. + +.Pages +: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists]. + +## Displaying custom metadata in Taxonomy Terms Templates + +If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content///_index.md` and add your metadata in it's front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Data.Pages` as such: + +``` +
      + {{ range .Data.Pages }} +
    • + {{ .Title }} + {{ .Params.wikipedia }} +
      • + {{ end }} +
    +``` + + + +## Order Taxonomies + +Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key. + +### Order Alphabetically Example + +``` +
      + {{ $data := .Data }} + {{ range $key, $value := .Data.Terms.Alphabetical }} +
    • {{ $value.Name }} {{ $value.Count }}
      • + {{ end }} +
    +``` + +### Order by Popularity Example + +``` +
      + {{ $data := .Data }} + {{ range $key, $value := .Data.Terms.ByCount }} +
    • {{ $value.Name }} {{ $value.Count }}
      • + {{ end }} +
    +``` + +### Order by Least Popular Example + +``` +
      + {{ $data := .Data }} + {{ range $key, $value := .Data.Terms.ByCount.Reverse }} +
    • {{ $value.Name }} {{ $value.Count }}
      • + {{ end }} +
    +``` + + + +## Order Content within Taxonomies + +Hugo uses both `date` and `weight` to order content within taxonomies. + +Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to. + +When iterating over content within taxonomies, the default sort is the same as that used for [section and list pages]() first by weight then by date. This means that if the weights for two pieces of content are the same, than the more recent content will be displayed first. The default weight for any piece of content is 0. + +### Assign Weight + +Content can be assigned weight for each taxonomy that it's assigned to. + +``` ++++ +tags = [ "a", "b", "c" ] +tags_weight = 22 +categories = ["d"] +title = "foo" +categories_weight = 44 ++++ +Front Matter with weighted tags and categories +``` + +The convention is `taxonomyname_weight`. + +In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy. + +It has also been assigned the weight of 44 when rendering the 'd' category. + +With this the same piece of content can appear in different positions in different taxonomies. + +Currently taxonomies only support the default ordering of content which is weight -> date. + + + +There are two different templates that the use of taxonomies will require you to provide. + +Both templates are covered in detail in the templates section. + +A [list template](/templates/list/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages. + +A [taxonomy terms template](/templates/terms/) is a template used to +generate the list of terms for a given template. + + + +There are four common ways you can display the data in your +taxonomies in addition to the automatic taxonomy pages created by hugo +using the [list templates](/templates/list/): + +1. For a given piece of content, you can list the terms attached +2. For a given piece of content, you can list other content with the same + term +3. You can list all terms for a taxonomy +4. You can list all taxonomies (with their terms) + +## Display a Single Piece of Content's Taxonomies + +Within your content templates, you may wish to display the taxonomies that piece of content is assigned to. + +Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.`). + +### Example: List Tags in a Single Page Template + +``` +
      + {{ range .Params.tags }} +
    • {{ . }}
      • + {{ end }} +
    +``` + +If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter. + +To list such taxonomies, use the following: + +### Example: Comma-delimit Tags in a Single Page Template + +``` +{{ if .Params.directors }} + Director{{ if gt (len .Params.directors) 1 }}s{{ end }}: + {{ range $index, $director := .Params.directors }}{{ if gt $index 0 }}, {{ end }}{{ . }}{{ end }} +{{ end }} +``` + +Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion. + +## List Content with the Same Taxonomy Term + +If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content: + +### Example: Showing Content in Same Series + +``` + +``` + +## List All content in a Given taxonomy + +This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content. + +### Example: Grouping "Featured" Content + +``` + +``` + +## Render a Site's Taxonomies + +If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page. + +This may take the form of a tag cloud, a menu, or simply a list. + +The following example displays all terms in a site's tags taxonomy: + +### Example: List All Site Tags + +``` +
      + {{ range $name, $taxonomy := .Site.Taxonomies.tags }} +
    • {{ $name }}
      • + {{ end }} +
    +``` + +### Example: List All Taxonomies, Terms, and Assigned Content + +This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms. + +{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}} +
    +
      + {{ range $taxonomyname, $taxonomy := .Site.Taxonomies }} +
    • {{ $taxonomyname }} +
        + {{ range $key, $value := $taxonomy }} +
      • {{ $key }}
        • + + {{ end }} +
      +
      • + {{ end }} +
    +
    +{{< /code >}} + +## `.Site.GetPage` for Taxonomies + +Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the "List All Site Tags" example above: + +{{< code file="links-to-all-tags" >}} +
      + {{ range ($.Site.GetPage "taxonomyTerm" "tags").Pages }} +
    • {{ .Title}}
      • + {{ end }} +
    +{{< /code >}} + + + + +[delimit]: /functions/delimit/ +[getpage]: /functions/getpage/ +[lists]: /templates/lists/ +[renderlists]: /templates/lists/ +[single page template]: /templates/single-page-templates/ +[sitevars]: /variables/site/ diff --git a/content/en/templates/template-debugging.md b/content/en/templates/template-debugging.md new file mode 100644 index 00000000..e94a073a --- /dev/null +++ b/content/en/templates/template-debugging.md @@ -0,0 +1,81 @@ +--- +title: Template Debugging +# linktitle: Template Debugging +description: You can use Go templates' `printf` function to debug your Hugo templates. These snippets provide a quick and easy visualization of the variables available to you in different contexts. +godocref: http://golang.org/pkg/fmt/ +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [debugging,troubleshooting] +menu: + docs: + parent: "templates" + weight: 180 +weight: 180 +sections_weight: 180 +draft: false +aliases: [] +toc: false +--- + +Here are some snippets you can add to your template to answer some common questions. + +These snippets use the `printf` function available in all Go templates. This function is an alias to the Go function, [fmt.Printf](http://golang.org/pkg/fmt/). + +## What Variables are Available in this Context? + +You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`. + +``` +{{ printf "%#v" $.Site }} +``` + +This will print out the value of `.Permalink`: + + +``` +{{ printf "%#v" .Permalink }} +``` + + +This will print out a list of all the variables scoped to the current context +(`.`, aka ["the dot"][tempintro]). + + +``` +{{ printf "%#v" . }} +``` + + +When developing a [homepage][], what does one of the pages you're looping through look like? + +``` +{{ range .Data.Pages }} + {{/* The context, ".", is now each one of the pages as it goes through the loop */}} + {{ printf "%#v" . }} +{{ end }} +``` + +{{% note "`.Data.Pages` on the Homepage" %}} +`.Data.Pages` on the homepage is equivalent to `.Site.Pages`. +{{% /note %}} + +## Why Am I Showing No Defined Variables? + +Check that you are passing variables in the `partial` function: + +``` +{{ partial "header" }} +``` + +This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][tempintro]. + +``` +{{ partial "header" . }} +``` + +The dot (`.`) is considered fundamental to understanding Hugo templating. For more information, see [Introduction to Hugo Templating][tempintro]. + +[homepage]: /templates/homepage/ +[tempintro]: /templates/introduction/ \ No newline at end of file diff --git a/content/en/templates/views.md b/content/en/templates/views.md new file mode 100644 index 00000000..ac863646 --- /dev/null +++ b/content/en/templates/views.md @@ -0,0 +1,121 @@ +--- +title: Content View Templates +# linktitle: Content Views +description: Hugo can render alternative views of your content, which is especially useful in list and summary views. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [views] +menu: + docs: + parent: "templates" + weight: 70 +weight: 70 +sections_weight: 70 +draft: false +aliases: [] +toc: true +--- + +These alternative **content views** are especially useful in [list templates][lists]. + +The following are common use cases for content views: + +* You want content of every type to be shown on the homepage but only with limited [summary views][summaries]. +* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself. + +## Create a Content View + +To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view. + +``` + ▾ layouts/ + ▾ post/ + li.html + single.html + summary.html + ▾ project/ + li.html + single.html + summary.html +``` + +Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order. + + +``` +▾ layouts/ + ▾ _default/ + li.html + single.html + summary.html +``` + +## Which Template Will be Rendered? + +The following is the [lookup order][lookup] for content views: + +1. `/layouts//.html` +2. `/layouts/_default/.html` +3. `/themes//layouts//.html` +4. `/themes//layouts/_default/.html` + +## Example: Content View Inside a List + +The following example demonstrates how to use content views inside of your [list templates][lists]. + +### `list.html` + +In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows: + +{{< code file="layouts/_default/list.html" download="list.html" >}} +
    +
    +

    {{ .Title }}

    + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
    +
    +{{< /code >}} + +### `summary.html` + +Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.) + +{{< code file="layouts/_default/summary.html" download="summary.html" >}} + +{{< /code >}} + +### `li.html` + +Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`). + +{{< code file="layouts/_default/li.html" download="li.html" >}} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • +{{< /code >}} + +[lists]: /templates/lists/ +[lookup]: /templates/lookup-order/ +[pagevars]: /variables/page/ +[render]: /functions/render/ +[single]: /templates/single-page-templates/ +[spf]: http://spf13.com +[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html +[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html +[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html +[summaries]: /content-management/summaries/ +[taxonomylists]: /templates/taxonomy-templates/ diff --git a/content/en/themes/_index.md b/content/en/themes/_index.md new file mode 100644 index 00000000..9e2bc170 --- /dev/null +++ b/content/en/themes/_index.md @@ -0,0 +1,26 @@ +--- +title: Themes +linktitle: Themes Overview +description: Install, use, and create Hugo themes. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +menu: + docs: + parent: "themes" + weight: 01 +weight: 01 +sections_weight: 01 +categories: [themes] +keywords: [themes,introduction,overview] +draft: false +aliases: [/themes/overview/] +toc: false +--- + +Hugo provides a robust theming system that is easy to implement yet feature complete. You can view the themes created by the Hugo community on the [Hugo themes website][hugothemes]. + +Hugo themes are powered by the excellent Go template library and are designed to reduce code duplication. They are easy to both customize and keep in synch with the upstream theme. + +[goprimer]: /templates/introduction/ +[hugothemes]: http://themes.gohugo.io/ diff --git a/content/en/themes/creating.md b/content/en/themes/creating.md new file mode 100644 index 00000000..a62f7c71 --- /dev/null +++ b/content/en/themes/creating.md @@ -0,0 +1,87 @@ +--- +title: Create a Theme +linktitle: Create a Theme +description: The `hugo new theme` command will scaffold the beginnings of a new theme for you to get you on your way. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [themes] +keywords: [themes, source, organization, directories] +menu: + docs: + parent: "themes" + weight: 30 +weight: 30 +sections_weight: 30 +draft: false +aliases: [/themes/creation/,/tutorials/creating-a-new-theme/] +toc: true +wip: true +--- + +{{% warning "Use Relative Links" %}} +If you're creating a theme with plans to share it with the community, use relative URLs since users of your theme may not publish from the root of their website. See [relURL](/functions/relurl) and [absURL](/functions/absurl). +{{% /warning %}} + +Hugo can initialize a new blank theme directory within your existing `themes` using the `hugo new` command: + +``` +hugo new theme [name] +``` + +## Theme Components + +A theme consists of templates and static assets such as javascript and css files. Themes can also provide [archetypes][], which are archetypal content types used by the `hugo new` command to scaffold new content files with preconfigured front matter. + + +{{% note "Use the Hugo Generator Tag" %}} +The [`.Hugo.Generator`](/variables/hugo/) tag is included in all themes featured in the [Hugo Themes Showcase](http://themes.gohugo.io). We ask that you include the generator tag in all sites and themes you create with Hugo to help the core team track Hugo's usage and popularity. +{{% /note %}} + +## Layouts + +Hugo is built around the concept that things should be as simple as possible. +Fundamentally, website content is displayed in two different ways, a single +piece of content and a list of content items. With Hugo, a theme layout starts +with the defaults. As additional layouts are defined, they are used for the +content type or section they apply to. This keeps layouts simple, but permits +a large amount of flexibility. + +## Single Content + +The default single file layout is located at `layouts/_default/single.html`. + +## List of Contents + +The default list file layout is located at `layouts/_default/list.html`. + +## Partial Templates + +Theme creators should liberally use [partial templates](/templates/partials/) +throughout their theme files. Not only is a good DRY practice to include shared +code, but partials are a special template type that enables the themes end user +to be able to overwrite just a small piece of a file or inject code into the +theme from their local /layouts. These partial templates are perfect for easy +injection into the theme with minimal maintenance to ensure future +compatibility. + +## Static + +Everything in the static directory will be copied directly into the final site +when rendered. No structure is provided here to enable complete freedom. It is +common to organize the static content into: + +``` +/css +/js +/img +``` + +The actual structure is entirely up to you, the theme creator, on how you would like to organize your files. + +## Archetypes + +If your theme makes use of specific keys in the front matter, it is a good idea +to provide an archetype for each content type you have. [Read more about archetypes][archetypes]. + +[archetypes]: /content-management/archetypes/ diff --git a/content/en/themes/customizing.md b/content/en/themes/customizing.md new file mode 100644 index 00000000..3444880f --- /dev/null +++ b/content/en/themes/customizing.md @@ -0,0 +1,80 @@ +--- +title: Customize a Theme +linktitle: Customize a Theme +description: Customize a theme by overriding theme layouts and static assets in your top-level project directories. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [themes] +keywords: [themes, source, organization, directories] +menu: + docs: + parent: "themes" + weight: 20 +weight: 20 +sections_weight: 20 +draft: false +aliases: [/themes/customize/] +toc: true +wip: true +--- + +The following are key concepts for Hugo site customization with themes. Hugo permits you to supplement *or* override any theme template or static file with files in your working directory. + +{{% note %}} +When you use a theme cloned from its git repository, do not edit the theme's files directly. Instead, theme customization in Hugo is a matter of *overriding* the templates made available to you in a theme. This provides the added flexibility of tweaking a theme to meet your needs while staying current with a theme's upstream. +{{% /note %}} + +## Override Static Files + +There are times where you want to include static assets that differ from versions of the same asset that ships with a theme. + +For example, a theme may use jQuery 1.8 in the following location: + +``` +/themes//static/js/jquery.min.js +``` + +You want to replace the version of jQuery that ships with the theme with the newer `jquery-3.1.1.js`. The easiest way to do this is to replace the file *with a file of the same name* in the same relative path in your project's root. Therefore, change `jquery-3.1.1.js` to `jquery.min.js` so that it is *identical* to the theme's version and place the file here: + +``` +/static/js/jquery.min.js +``` + +## Override Template Files + +Anytime Hugo looks for a matching template, it will first check the working directory before looking in the theme directory. If you would like to modify a template, simply create that template in your local `layouts` directory. + +The [template lookup order][lookup] explains the rules Hugo uses to determine which template to use for a given piece of content. Read and understand these rules carefully. + +This is especially helpful when the theme creator used [partial templates][partials]. These partial templates are perfect for easy injection into the theme with minimal maintenance to ensure future compatibility. + +For example: + +``` +/themes//layouts/_default/single.html +``` + +Would be overwritten by + +``` +/layouts/_default/single.html +``` + +{{% warning %}} +This only works for templates that Hugo "knows about" (i.e., that follow its convention for folder structure and naming). If a theme imports template files in a creatively named directory, Hugo won’t know to look for the local `/layouts` first. +{{% /warning %}} + +## Override Archetypes + +If the archetype that ships with the theme for a given content type (or all content types) doesn’t fit with how you are using the theme, feel free to copy it to your `/archetypes` directory and make modifications as you see fit. + +{{% warning "Beware of `layouts/_default`" %}} +The `_default` directory is a very powerful force in Hugo, especially as it pertains to overwriting theme files. If a default file is located in the local [archetypes](/content-management/archetypes/) or layout directory (i.e., `archetypes/default.md` or `/layouts/_default/*.html`, respectively), it will override the file of the same name in the corresponding theme directory (i.e., `themes//archetypes/default.md` or `themes//layout/_defaults/*.html`, respectively). + +It is usually better to override specific files; i.e. rather than using `layouts/_default/*.html` in your working directory. +{{% /warning %}} + +[archetypes]: /content-management/archetypes/ +[lookup]: /templates/lookup-order/ +[partials]: /templates/partials/ \ No newline at end of file diff --git a/content/en/themes/installing-and-using-themes.md b/content/en/themes/installing-and-using-themes.md new file mode 100644 index 00000000..93d81423 --- /dev/null +++ b/content/en/themes/installing-and-using-themes.md @@ -0,0 +1,114 @@ +--- +title: Install and Use Themes +linktitle: Install and Use Themes +description: Install and use a theme from the Hugo theme showcase easily through the CLI. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [themes] +keywords: [install, themes, source, organization, directories,usage] +menu: + docs: + parent: "themes" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [/themes/usage/,/themes/installing/] +toc: true +wip: true +--- + +{{% note "No Default Theme" %}} +Hugo currently doesn’t ship with a “default” theme. This decision is intentional. We leave it up to you to decide which theme best suits your Hugo project. +{{% /note %}} + +## Assumptions + +1. You have already [installed Hugo on your development machine][install]. +2. You have git installed on your machine and you are familiar with basic git usage. + +## Install Themes + +{{< youtube L34JL_3Jkyc >}} + +The community-contributed themes featured on [themes.gohugo.io](//themes.gohugo.io/) are hosted in a [centralized GitHub repository][themesrepo]. The Hugo Themes Repo at is really a meta repository that contains pointers to a set of contributed themes. + +{{% warning "Get `git` First" %}} +Without [Git](https://git-scm.com/) installed on your computer, none of the following theme instructions will work. Git tutorials are beyond the scope of the Hugo docs, but [GitHub](https://try.github.io/) and [codecademy](https://www.codecademy.com/learn/learn-git) offer free, interactive courses for beginners. +{{% /warning %}} + +### Install All Themes + +You can install *all* available Hugo themes by cloning the entire [Hugo Theme repository on GitHub][themesrepo] from within your working directory. Depending on your internet connection the download of all themes might take a while. + +``` +git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes +``` + +Before you use a theme, remove the .git folder in that theme's root folder. Otherwise, this will cause problem if you deploy using Git. + +### Install a Single Theme + +Change into the `themes` directory and download a theme by replacing `URL_TO_THEME` with the URL of the theme repository: + +``` +cd themes +git clone URL_TO_THEME +``` + +The following example shows how to use the "Hyde" theme, which has its source hosted at : + +{{< code file="clone-theme.sh" >}} +cd themes +git clone https://github.com/spf13/hyde +{{< /code >}} + +Alternatively, you can download the theme as a `.zip` file, unzip the theme contents, and then move the unzipped source into your `themes` directory. + +{{% note "Read the `README`" %}} +Always review the `README.md` file that is shipped with a theme. Often, these files contain further instructions required for theme setup; e.g., copying values from an example configuration file. +{{% /note %}} + +## Theme Placement + +Please make certain you have installed the themes you want to use in the +`/themes` directory. This is the default directory used by Hugo. Hugo comes with the ability to change the themes directory via the [`themesDir` variable in your site configuration][config], but this is not recommended. + +## Use Themes + +Hugo applies the decided theme first and then applies anything that is in the local directory. This allows for easier customization while retaining compatibility with the upstream version of the theme. To learn more, go to [customizing themes][customizethemes]. + +### Command Line + +There are two different approaches to using a theme with your Hugo website: via the Hugo CLI or as part of your [site configuration file][config]. + +To change a theme via the Hugo CLI, you can pass the `-t` [flag][] when building your site: + +``` +hugo -t themename +``` + +Likely, you will want to add the theme when running the Hugo local server, especially if you are going to [customize the theme][customizethemes]: + +``` +hugo server -t themename +``` + +### `config` File + +If you've already decided on the theme for your site and do not want to fiddle with the command line, you can add the theme directly to your [site configuration file][config]: + +``` +theme: themename +``` + +{{% note "A Note on `themename`" %}} +The `themename` in the above examples must match the name of the specific theme directory inside `/themes`; i.e., the directory name (likely lowercase and urlized) rather than the name of the theme displayed in the [Themes Showcase site](http://themes.gohugo.io). +{{% /note %}} + +[customizethemes]: /themes/customizing/ +[flag]: /getting-started/usage/ "See the full list of flags in Hugo's basic usage." +[install]: /getting-started/installing/ +[config]: /getting-started/configuration/ "Learn how to customize your Hugo website configuration file in yaml, toml, or json." +[themesrepo]: https://github.com/gohugoio/hugoThemes diff --git a/content/en/tools/_index.md b/content/en/tools/_index.md new file mode 100644 index 00000000..47cfeb1e --- /dev/null +++ b/content/en/tools/_index.md @@ -0,0 +1,25 @@ +--- +title: Developer Tools +linktitle: Developer Tools Overview +description: In addition to Hugo's powerful CLI, there is a large number of community-developed tool chains for Hugo developers. +date: 2016-12-05 +publishdate: 2016-12-05 +lastmod: 2017-02-26 +categories: [developer tools] +keywords: [] +menu: + docs: + parent: "tools" + weight: 01 +weight: 01 +sections_weight: 01 +draft: false +aliases: [/tools/] +--- + +One of Hugo's greatest strengths is it's passionate---and always evolving---developer community. With the exception of the `highlight` shortcode mentioned in [Syntax Highlighting][syntax], the tools and other projects featured in this section are offerings from both commercial services and open-source projects, many of which are developed by Hugo developers just like you. + +[See the popularity of Hugo compared with other static site generators.][staticgen] + +[staticgen]: https://staticgen.com +[syntax]: /tools/syntax-highlighting/ diff --git a/content/en/tools/editors.md b/content/en/tools/editors.md new file mode 100644 index 00000000..419a2a04 --- /dev/null +++ b/content/en/tools/editors.md @@ -0,0 +1,45 @@ +--- +title: Editor Plug-ins for Hugo +linktitle: Editor Plug-ins +description: The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [developer tools] +keywords: [editor, plug-ins] +menu: + docs: + parent: "tools" + weight: 50 +weight: 50 +sections_weight: 50 +draft: false +aliases: [] +toc: false +--- + +The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow. + +## Sublime Text + +* [Hugofy](https://github.com/akmittal/Hugofy). Hugofy is a plugin for Sublime Text 3 to make life easier to use Hugo static site generator. + +## Visual Studio Code + +* [Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy). Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found [here](https://github.com/akmittal/hugofy-vscode). + +## Emacs + +* [emacs-easy-hugo](https://github.com/masasam/emacs-easy-hugo). Emacs major mode for managing hugo blogs. Note that Hugo also supports [Org-mode][formats]. +* [ox-hugo.el](https://ox-hugo.scripter.co). Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org sub-trees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [*Why ox-hugo?*](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more. + +## Vim + +* [Vim Hugo Helper](https://github.com/robertbasic/vim-hugo-helper). A small Vim plugin to help me with writing posts with Hugo. + +## Atom + +* [Hugofy](https://atom.io/packages/hugofy). A Hugo Static Website Generator package for Atom. +* [language-hugo](https://atom.io/packages/language-hugo). Adds syntax highlighting to Hugo files. + +[formats]: /content-management/formats/ diff --git a/content/en/tools/frontends.md b/content/en/tools/frontends.md new file mode 100644 index 00000000..f41751b4 --- /dev/null +++ b/content/en/tools/frontends.md @@ -0,0 +1,34 @@ +--- +title: Frontend Interfaces with Hugo +linktitle: Frontends +description: Do you prefer a graphical user interface over a text editor? Give these frontends a try. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [developer tools] +keywords: [frontend,gui] +menu: + docs: + parent: "tools" + weight: 40 +weight: 40 +sections_weight: 40 +draft: false +aliases: [] +toc: false +--- + +* [enwrite](https://github.com/zzamboni/enwrite). Enwrite enables evernote-powered, statically generated blogs and websites. Now posting to your blog or updating your website is as easy as writing a new note in Evernote! +* [caddy-hugo](https://github.com/hacdias/caddy-hugo). `caddy-hugo` is an add-on for [Caddy](https://caddyserver.com/) that delivers a good UI to edit the content of your Hugo website. +* [Lipi](https://github.com/SohanChy/Lipi). Lipi is a native GUI frontend written in Java to manage your Hugo websites. +* [Netlify CMS](https://netlifycms.org). Netlify CMS is an open source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Netlify CMS starter](https://github.com/netlify-templates/one-click-hugo-cms) is available to get new projects running quickly. + + +## Commercial Services + +* [Appernetic.io](https://appernetic.io) is a Hugo Static Site Generator as a Service that is easy to use for non-technical users. + * **Features:** inline PageDown editor, visual tree view, image upload and digital asset management with Cloudinary, site preview, continuous integration with GitHub, atomic deploy and hosting, Git and Hugo integration, autosave, custom domain, project syncing, theme cloning and management. Developers have complete control over the source code and can manage it with GitHub’s deceptively simple workflow. +* [DATOCMS](https://www.datocms.com) DatoCMS is a fully customizable administrative area for your static websites. Use your favorite website generator, let your clients publish new content independently, and the host the site anywhere you like. +* [Forestry.io](https://forestry.io/). Forestry is a simple CMS for Jekyll and Hugo websites with support for GitHub, GitLab, and Bitbucket. Every time an update is made via the CMS, Forestry will commit changes back to your repo and will compile/deploy your website to S3, GitHub Pages, FTP, etc. +* [Netlify.com](https://www.netlify.com). Netlify builds, deploys, and hosts your static website or app (Hugo, Jekyll, etc). Netlify offers a drag-and-drop interface and automatic deployments from GitHub or Bitbucket. + * **Features:** global CDN, atomic deploys, ultra-fast DNS, instant cache invalidation, high availability, automated hosting, Git integration, form submission hooks, authentication providers, and custom domains. Developers have complete control over the source code and can manage it with GitHub or Bitbucket's deceptively simple workflow. diff --git a/content/en/tools/migrations.md b/content/en/tools/migrations.md new file mode 100644 index 00000000..ef4f169d --- /dev/null +++ b/content/en/tools/migrations.md @@ -0,0 +1,72 @@ +--- +title: Migrate to Hugo +linktitle: Migrations +description: A list of community-developed tools for migrating from your existing static site generator or content management system to Hugo. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +keywords: [migrations,jekyll,wordpress,drupal,ghost,contentful] +menu: + docs: + parent: "tools" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [/developer-tools/migrations/,/developer-tools/migrated/] +toc: true +--- + +This section highlights some projects around Hugo that are independently developed. These tools try to extend the functionality of our static site generator or help you to get started. + +{{% note %}} +Do you know or maintain a similar project around Hugo? Feel free to open a [pull request](https://github.com/gohugoio/hugo/pulls) on GitHub if you think it should be added. +{{% /note %}} + +Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll take care to export your content into Hugo-friendly formats. + +## Jekyll + +Alternatively, you can use the new [Jekyll import command](/commands/hugo_import_jekyll/). + +- [JekyllToHugo](https://github.com/SenjinDarashiva/JekyllToHugo) - A Small script for converting Jekyll blog posts to a Hugo site. +- [ConvertToHugo](https://github.com/coderzh/ConvertToHugo) - Convert your blog from Jekyll to Hugo. + +## Ghost + +- [ghostToHugo](https://github.com/jbarone/ghostToHugo) - Convert Ghost blog posts and export them to Hugo. + +## Octopress + +- [octohug](https://github.com/codebrane/octohug) - Octopress to Hugo migrator. + +## DokuWiki + +- [dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo) - Migrates your dokuwiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extra's like the TODO plugin. Written with extensibility in mind using python 3. Also generates a TOML header for each page. Designed to copypaste the wiki directory into your /content directory. + +## WordPress + +- [wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter) - A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.) + +## Tumblr + +- [tumblr-importr](https://github.com/carlmjohnson/tumblr-importr) - An importer that uses the Tumblr API to create a Hugo static site. +- [tumblr2hugomarkdown](https://github.com/Wysie/tumblr2hugomarkdown) - Export all your Tumblr content to Hugo Markdown files with preserved original formatting. +- [Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo) - A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. Furthermore, "Tumblr to Hugo" creates a CSV file with the original URL and the new path on Hugo, to help you setup the redirections. + +## Drupal + +- [drupal2hugo](https://github.com/danapsimer/drupal2hugo) - Convert a Drupal site to Hugo. + +## Joomla + +- [hugojoomla](https://github.com/davetcc/hugojoomla) - This utility written in Java takes a Joomla database and converts all the content into Markdown files. It changes any URLs that are in Joomla's internal format and converts them to a suitable form. + +## Blogger + +- [blogimport](https://github.com/natefinch/blogimport) - A tool to import from Blogger posts to Hugo. +- [blogger-to-hugo](https://bitbucket.org/petraszd/blogger-to-hugo) - Another tool to import Blogger posts to Hugo. It also downloads embedded images so they will be stored locally. + +## Contentful + +- [contentful2hugo](https://github.com/ArnoNuyts/contentful2hugo) - A tool to create content-files for Hugo from content on [Contentful](https://www.contentful.com/). diff --git a/content/en/tools/other.md b/content/en/tools/other.md new file mode 100644 index 00000000..0502e1cd --- /dev/null +++ b/content/en/tools/other.md @@ -0,0 +1,28 @@ +--- +title: Other Hugo Community Projects +linktitle: Other Projects +description: Some interesting projects developed by the Hugo community that don't quite fit into our other developer tool categories. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [developer tools] +keywords: [frontend,gui] +menu: + docs: + parent: "tools" + weight: 70 +weight: 70 +sections_weight: 70 +draft: false +aliases: [] +toc: false +--- + +And for all the other small things around Hugo: + +* [hugo-gallery](https://github.com/icecreammatt/hugo-gallery) lets you create an image gallery for Hugo sites. +* [flickr-hugo-embed](https://github.com/nikhilm/flickr-hugo-embed) prints shortcodes to embed a set of images from an album on Flickr into Hugo. +* [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page. +* [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) makes it easy to create image galleries using PhotoSwipe. +* [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) Syncs the local build of your Hugo website with your remote webserver via SFTP. +* [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) Emacs package for writing blog posts in markdown or org-mode and building your site with Hugo. diff --git a/content/en/tools/search.md b/content/en/tools/search.md new file mode 100644 index 00000000..2145c187 --- /dev/null +++ b/content/en/tools/search.md @@ -0,0 +1,31 @@ +--- +title: Search for your Hugo Website +linktitle: Search +description: See some of the open-source and commercial search options for your newly created Hugo website. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-26 +categories: [developer tools] +keywords: [search,tools] +menu: + docs: + parent: "tools" + weight: 60 +weight: 60 +sections_weight: 60 +draft: false +aliases: [] +toc: true +--- + +A static website with a dynamic search function? Yes. As alternatives to embeddable scripts from Google or other search engines, you can provide your visitors a custom search by indexing your content files directly. + +* [GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567). This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](http://lunrjs.com/) to serve the search results. +* [hugo-lunr](https://www.npmjs.com/package/hugo-lunr). A simple way to add site search to your static Hugo site using [lunr.js](http://lunrjs.com/). Hugo-lunr will create an index file of any html and markdown documents in your Hugo project. +* [hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh). A bit like Hugo-lunr, but Hugo-lunr-zh can help you separate the Chinese keywords. +* [Github Gist for Fuse.js integration](https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae). This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](http://fusejs.io/) on the client side. Although this gist uses Fuse.js for fuzzy matching, any client side search tool capable of reading JSON indexes will work. Does not require npm, grunt or other build-time tools except Hugo! +* [hugo-search-index](https://www.npmjs.com/package/hugo-search-index). A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project markdown files. + +## Commercial Search Services + +* [Algolia](https://www.algolia.com/)'s Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search. diff --git a/content/en/tools/starter-kits.md b/content/en/tools/starter-kits.md new file mode 100644 index 00000000..0ce81cc4 --- /dev/null +++ b/content/en/tools/starter-kits.md @@ -0,0 +1,40 @@ +--- +title: Starter Kits +linktitle: Starter Kits +description: A list of community-developed projects designed to help you get up and running with Hugo. +date: 2017-02-22 +publishdate: 2017-02-01 +lastmod: 2017-02-22 +keywords: [starters,assets,pipeline] +menu: + docs: + parent: "tools" + weight: 30 +weight: 30 +sections_weight: 30 +draft: false +aliases: [/developer-tools/migrations/,/developer-tools/migrated/] +toc: false +--- + +Know of a Hugo-related starter kit that isn't mentioned here? [Please add it to the list.][addkit] + +{{% note "Starter Kits are Not Maintained by the Hugo Team"%}} +The following starter kits are developed by active members of the Hugo community. If you find yourself having issues with any of the projects, it's best to file an issue directly with the project's maintainer(s). +{{% /note %}} + +* [Victor Hugo][]. Victor Hugo is a Hugo boilerplate for creating truly epic websites using Gulp + Webpack as an asset pipeline. Victor Hugo uses post-css and Babel for CSS and JavaScript, respectively, and is actively maintained. +* [GOHUGO AMP][]. GoHugo AMP is a starter theme that aims to make it easy to adopt [Google's AMP Project][amp]. The starter kit comes with 40+ shortcodes and partials plus automatic structured data. The project also includes a [separate site with extensive documentation][gohugodocs]. +* [Blaupause][]. Blaupause is a developer-friendly Hugo starter kit based on Gulp tasks. It comes ES6-ready with several helpers for SVG and fonts and basic structure for HTML, SCSS, and JavaScript. +* [hugulp][]. hugulp is a tool to optimize the assets of a Hugo website. The main idea is to recreate the famous Ruby on Rails Asset Pipeline, which minifies, concatenates and fingerprints the assets used in your website. +* [Atlas][]. Atlas is a Hugo boilerplate designed to speed up development with support for Netlify, Netlify CMS, Gulp, Linting, SCSS, ES6 & more. It's actively maintained and contributions are always welcome. + + +[addkit]: https://github.com/gohugoio/hugo/edit/master/docs/content/tools/starter-kits.md +[amp]: https://www.ampproject.org/ +[Blaupause]: https://github.com/fspoettel/blaupause +[GOHUGO AMP]: https://github.com/wildhaber/gohugo-amp +[gohugodocs]: https://gohugo-amp.gohugohq.com/ +[hugulp]: https://github.com/jbrodriguez/hugulp +[Victor Hugo]: https://github.com/netlify/victor-hugo +[Atlas]: https://github.com/indigotree/atlas \ No newline at end of file diff --git a/content/en/troubleshooting/_index.md b/content/en/troubleshooting/_index.md new file mode 100644 index 00000000..3b0e9372 --- /dev/null +++ b/content/en/troubleshooting/_index.md @@ -0,0 +1,26 @@ +--- +title: Troubleshoot +linktitle: Troubleshoot +description: Frequently asked questions and known issues pulled from the Hugo Discuss forum. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +menu: + docs: + parent: "troubleshooting" + weight: 1 +weight: 1 +draft: false +hidesectioncontents: false +slug: +aliases: [/troubleshooting/faqs/,/faqs/] +toc: false +notesforauthors: +--- + +The Troubleshooting section includes known issues, recent workarounds, and FAQs pulled from the [Hugo Discussion Forum][forum]. + + + + +[forum]: https://discourse.gohugo.io diff --git a/content/en/troubleshooting/build-performance.md b/content/en/troubleshooting/build-performance.md new file mode 100644 index 00000000..bc4d30d5 --- /dev/null +++ b/content/en/troubleshooting/build-performance.md @@ -0,0 +1,111 @@ +--- +title: Build Performance +linktitle: Build Performance +description: An overview of features used for diagnosing and improving performance issues in site builds. +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +keywords: [performance, build] +categories: [troubleshooting] +menu: + docs: + parent: "troubleshooting" +weight: 3 +slug: +aliases: [] +toc: true +--- + +{{% note %}} +The example site used below is from https://github.com/gohugoio/hugo/tree/master/examples/blog +{{% /note %}} + +## Template Metrics + +Hugo is a very fast static site generator, but it is possible to write +inefficient templates. Hugo's *template metrics* feature is extremely helpful +in pinpointing which templates are executed most often and how long those +executions take **in terms of CPU time**. + +| Metric Name | Description | +|---------------------|-------------| +| cumulative duration | The cumulative time spent executing a given template. | +| average duration | The average time spent executing a given template. | +| maximum duration | The maximum time a single execution took for a given template. | +| count | The number of times a template was executed. | +| template | The template name. | + +``` +▶ hugo --templateMetrics +Started building sites ... + +Built site for language en: +0 draft content +0 future content +0 expired content +2 regular pages created +22 other pages created +0 non-page files copied +0 paginator pages created +4 tags created +3 categories created +total in 18 ms + +Template Metrics: + + cumulative average maximum + duration duration duration count template + ---------- -------- -------- ----- -------- + 6.419663ms 583.605µs 994.374µs 11 _internal/_default/rss.xml + 4.718511ms 1.572837ms 3.880742ms 3 indexes/category.html + 4.642666ms 2.321333ms 3.282842ms 2 post/single.html + 4.364445ms 396.767µs 2.451372ms 11 partials/header.html + 2.346069ms 586.517µs 903.343µs 4 indexes/tag.html + 2.330919ms 211.901µs 2.281342ms 11 partials/header.includes.html + 1.238976ms 103.248µs 446.084µs 12 post/li.html + 972.16µs 972.16µs 972.16µs 1 _internal/_default/sitemap.xml + 953.597µs 953.597µs 953.597µs 1 index.html + 822.263µs 822.263µs 822.263µs 1 indexes/post.html + 567.498µs 51.59µs 112.205µs 11 partials/navbar.html + 348.22µs 31.656µs 88.249µs 11 partials/meta.html + 346.782µs 173.391µs 276.176µs 2 post/summary.html + 235.184µs 21.38µs 124.383µs 11 partials/footer.copyright.html + 132.003µs 12µs 117.999µs 11 partials/menu.html + 72.547µs 6.595µs 63.764µs 11 partials/footer.html +``` + +{{% note %}} +**A Note About Parallelism** + +Hugo builds pages in parallel where multiple pages are generated +simultaneously. Because of this parallelism, the sum of "cumulative duration" +values is usually greater than the actual time it takes to build a site. +{{% /note %}} + + +## Cached Partials + +Some `partial` templates such as sidebars or menus are executed many times +during a site build. Depending on the content within the `partial` template and +the desired output, the template may benefit from caching to reduce the number +of executions. The [`partialCached`][partialCached] template function provides +caching capabilities for `partial` templates. + +{{% tip %}} +Note that you can create cached variants of each `partial` by passing additional +parameters to `partialCached` beyond the initial context. See the +`partialCached` documentation for more details. +{{% /tip %}} + + +## Step Analysis + +Hugo provides a means of seeing metrics about each step in the site build +process. We call that *Step Analysis*. The *step analysis* output shows the +total time per step, the cumulative time after each step (in parentheses), +the memory usage per step, and the total memory allocations per step. + +To enable *step analysis*, use the `--stepAnalysis` option when running Hugo. + + +[partialCached]:{{< ref "functions/partialCached.md" >}} diff --git a/content/en/troubleshooting/faq.md b/content/en/troubleshooting/faq.md new file mode 100644 index 00000000..392d7a8d --- /dev/null +++ b/content/en/troubleshooting/faq.md @@ -0,0 +1,40 @@ +--- +title: Frequently Asked Questions +linktitle: FAQ +description: Solutions to some common Hugo problems. +date: 2018-02-10 +categories: [troubleshooting] +menu: + docs: + parent: "troubleshooting" +keywords: [faqs] +weight: 2 +toc: true +aliases: [/faq/] +--- + +{{% note %}} +**Note:** The answers/solutions presented below are short, and may not be note be enough to solve your problem. Visit [Hugo Discourse](https://discourse.gohugo.io/) and use the search. It that does not help, start a new topic and ask your questions. +{{% /note %}} + +## Can I set configuration variables via OS environment? + +Yes you can! See [Configure with Environment Variables](/getting-started/configuration/#configure-with-environment-variables). + +## How do I schedule posts? + +1. Set `publishDate` in the page [Front Matter](/content-management/front-matter/) to a date in the future. +2. Build and publish at intervals. + +How to automate the "publish at intervals" part depends on your situation: + +* If you deploy from your own PC/server, you can automate with [Cron](https://en.wikipedia.org/wiki/Cron) or similar. +* If your site is hosted on a service similar to [Netlify](https://www.netlify.com/) you can use a service such as [ifttt](https://ifttt.com/date_and_time) to schedule the updates. + +Also see this Twitter thread: + +{{< tweet 962380712027590657 >}} + +## Can I use the latest Hugo version on Netlify? + +Yes you can! Read [this](/hosting-and-deployment/hosting-on-netlify/#configure-hugo-version-in-netlify). diff --git a/content/en/variables/_index.md b/content/en/variables/_index.md new file mode 100644 index 00000000..382ee25d --- /dev/null +++ b/content/en/variables/_index.md @@ -0,0 +1,23 @@ +--- +title: Variables and Params +linktitle: Variables Overview +description: Page-, file-, taxonomy-, and site-level variables and parameters available in templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [variables and params] +keywords: [variables,params,values,globals] +draft: false +menu: + docs: + parent: "variables" + weight: 1 +weight: 01 #rem +sections_weight: 01 +aliases: [/templates/variables/] +toc: false +--- + +Hugo's templates are context aware and make a large number of values available to you as you're creating views for your website. + +[Go templates]: /templates/introduction/ "Understand context in Go templates by learning the language's fundamental templating functions." diff --git a/content/en/variables/files.md b/content/en/variables/files.md new file mode 100644 index 00000000..ac5376db --- /dev/null +++ b/content/en/variables/files.md @@ -0,0 +1,48 @@ +--- +title: File Variables +linktitle: +description: "You can access filesystem-related data for a content file in the `.File` variable." +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [variables and params] +keywords: [files] +draft: false +menu: + docs: + parent: "variables" + weight: 40 +weight: 40 +sections_weight: 40 +aliases: [/variables/file-variables/] +toc: false +--- + +{{% note "Rendering Local Files" %}} +For information on creating shortcodes and templates that tap into Hugo's file-related feature set, see [Local File Templates](/templates/files/). +{{% /note %}} + +The `.File` object contains the following fields: + +.File.Path +: the original relative path of the page (e.g., `content/posts/foo.en.md`) + +.File.LogicalName +: the name of the content file that represents a page (e.g., `foo.en.md`) + +.File.TranslationBaseName +: the filename without extension or optional language identifier (e.g., `foo`) + +.File.BaseFileName +: the filename without extension (e.g., `foo.en`) + +.File.Ext +: the file extension of the content file (e.g., `md`); this can also be called using `.File.Extension` as well. Note that it is *only* the extension without `.`. + +.File.Lang +: the language associated with the given file if Hugo's [Multilingual features][multilingual] are enabled (e.g., `en`) + +.File.Dir +: given the path `content/posts/dir1/dir2/`, the relative directory path of the content file will be returned (e.g., `posts/dir1/dir2/`) + +[Multilingual]: /content-management/multilingual/ \ No newline at end of file diff --git a/content/en/variables/git.md b/content/en/variables/git.md new file mode 100644 index 00000000..f9c15476 --- /dev/null +++ b/content/en/variables/git.md @@ -0,0 +1,58 @@ +--- +title: Git Info Variables +linktitle: Git Variables +description: Get the last Git revision information for every content file. +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +categories: [variables and params] +keywords: [git] +draft: false +menu: + docs: + parent: "variables" + weight: 70 +weight: 70 +sections_weight: 70 +aliases: [/extras/gitinfo/] +toc: false +wip: false +--- + +{{% note "`.GitInfo` Performance Considerations" %}} +Hugo's Git integrations should be fairly performant but *can* increase your build time. This will depend on the size of your Git history. +{{% /note %}} + +## `.GitInfo` Prerequisites + +1. The Hugo site must be in a Git-enabled directory. +2. The Git executable must be installed and in your system `PATH`. +3. The `.GitInfo` feature must be enabled in your Hugo project by passing `--enableGitInfo` flag on the command line or by setting `enableGitInfo` to `true` in your [site's configuration file][configuration]. + +## The `.GitInfo` Object + +The `GitInfo` object contains the following fields: + +.AbbreviatedHash +: the abbreviated commit hash (e.g., `866cbcc`) + +.AuthorName +: the author's name, respecting `.mailmap` + +.AuthorEmail +: the author's email address, respecting `.mailmap` + +.AuthorDate +: the author date + +.Hash +: the commit hash (e.g., `866cbccdab588b9908887ffd3b4f2667e94090c3`) + +.Subject +: commit message subject (e.g., `tpl: Add custom index function`) + +## `.Lastmod` + +If the `.GitInfo` feature is enabled, **and** if the `lastmod` field in the content's front matter is not set, `.Lastmod` (on `Page`) is fetched from Git i.e. `.GitInfo.AuthorDate`. + +[configuration]: /getting-started/configuration/ diff --git a/content/en/variables/hugo.md b/content/en/variables/hugo.md new file mode 100644 index 00000000..c0c5c960 --- /dev/null +++ b/content/en/variables/hugo.md @@ -0,0 +1,39 @@ +--- +title: Hugo-specific Variables +linktitle: Hugo Variables +description: The `.Hugo` variable provides easy access to Hugo-related data. +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +categories: [variables and params] +keywords: [hugo,generator] +draft: false +menu: + docs: + parent: "variables" + weight: 60 +weight: 60 +sections_weight: 60 +aliases: [] +toc: false +wip: false +--- + +It contains the following fields: + +.Hugo.Generator +: `` tag for the version of Hugo that generated the site. `.Hugo.Generator` outputs a *complete* HTML tag; e.g. `` + +.Hugo.Version +: the current version of the Hugo binary you are using e.g. `0.13-DEV`
    + +.Hugo.CommitHash +: the git commit hash of the current Hugo binary e.g. `0e8bed9ccffba0df554728b46c5bbf6d78ae5247` + +.Hugo.BuildDate +: the compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`
    + +{{% note "Use the Hugo Generator Tag" %}} +We highly recommend using `.Hugo.Generator` in your website's ``. `.Hugo.Generator` is included by default in all themes hosted on [themes.gohugo.io](http://themes.gohugo.io). The generator tag allows the Hugo team to track the usage and popularity of Hugo. +{{% /note %}} + diff --git a/content/en/variables/menus.md b/content/en/variables/menus.md new file mode 100644 index 00000000..4216d976 --- /dev/null +++ b/content/en/variables/menus.md @@ -0,0 +1,67 @@ +--- +title: Menu Variables +linktitle: Menu Variables +description: A menu entry in a menu template has specific variables and functions to make menu management easier. +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +categories: [variables and params] +keywords: [menus] +draft: false +menu: + docs: + title: "variables defined by a menu entry" + parent: "variables" + weight: 50 +weight: 50 +sections_weight: 50 +aliases: [/variables/menu/] +toc: false +--- + +The [menu template][] has the following properties: + +.URL +: string + +.Name +: string + +.Title +: string + +This is a link title, meant to be used in `title`-Attributes of the menu's ``-tags. +By default it returns `.Page.LinkTitle`, as long as the menu entry was created +through the page's front matter and not through the site config. +Setting it explicitly in the site config or the page's front matter overrides this behaviour. + +.Page +: [Page Object](/variables/page/) + +The `.Page` variable holds a reference to the page. +It's only set when the menu entry is created from the page's front matter, +not when it's created from the site config. + + +.Menu +: string + +.Identifier +: string + +.Pre +: template.HTML + +.Post +: template.HTML + +.Weight +: int + +.Parent +: string + +.Children +: Menu + +[menu template]: /templates/menu-templates/ diff --git a/content/en/variables/page.md b/content/en/variables/page.md new file mode 100644 index 00000000..4e367355 --- /dev/null +++ b/content/en/variables/page.md @@ -0,0 +1,286 @@ +--- +title: Page Variables +linktitle: +description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [variables and params] +keywords: [pages] +draft: false +menu: + docs: + title: "variables defined by a page" + parent: "variables" + weight: 20 +weight: 20 +sections_weight: 20 +aliases: [/variables/page/] +toc: true +--- + +The following is a list of page-level variables. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself. + +{{% note "`.Scratch`" %}} +See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables. +{{% /note %}} + +## Page Variables + +.AlternativeOutputFormats +: contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's ``. (See [Output Formats](/templates/output-formats/).) + +.Content +: the content itself, defined below the front matter. + +.Data +: the data specific to this type of page. + +.Date +: the date associated with the page; `.Date` pulls from the `date` field in a content's front matter. See also `.ExpiryDate`, `.PublishDate`, and `.Lastmod`. + +.Description +: the description for the page. + +.Dir +: the path of the folder containing this content file. The path is relative to the `content` folder. + +.Draft +: a boolean, `true` if the content is marked as a draft in the front matter. + +.ExpiryDate +: the date on which the content is scheduled to expire; `.ExpiryDate` pulls from the `expirydate` field in a content's front matter. See also `.PublishDate`, `.Date`, and `.Lastmod`. + +.File +: filesystem-related data for this content file. See also [File Variables][]. + +.FuzzyWordCount +: the approximate number of words in the content. + +.Hugo +: see [Hugo Variables](/variables/hugo/). + +.IsHome +: `true` in the context of the [homepage](/templates/homepage/). + +.IsNode +: always `false` for regular content pages. + +.IsPage +: always `true` for regular content pages. + +.IsTranslated +: `true` if there are translations to display. + +.Keywords +: the meta keywords for the content. + +.Kind +: the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections. + +.Lang +: language taken from the language extension notation. + +.Language +: a language object that points to the language's definition in the site +`config`. + +.Lastmod +: the date the content was last modified. `.Lastmod` pulls from the `lastmod` field in a content's front matter. + + - If `lastmod` is not set, and `.GitInfo` feature is disabled, the front matter `date` field will be used. + - If `lastmod` is not set, and `.GitInfo` feature is enabled, `.GitInfo.AuthorDate` will be used instead. + +See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo]. + +.LinkTitle +: access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`. + +.Next +: pointer to the following content (based on the `publishdate` field in front matter). + +.NextInSection +: pointer to the following content within the same section (based on `publishdate` field in front matter). + +.OutputFormats +: contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).) + +.Pages +: a collection of associated pages. This value will be `nil` for regular content pages. `.Pages` is an alias for `.Data.Pages`. + +.Permalink +: the Permanent link for this page; see [Permalinks](/content-management/urls/) + +.Plain +: the Page content stripped of HTML tags and presented as a string. + +.PlainWords +: the Page content stripped of HTML as a `[]string` using Go's [`strings.Fields`](https://golang.org/pkg/strings/#Fields) to split `.Plain` into a slice. + +.Prev +: Pointer to the previous content (based on `publishdate` in front matter). + +.PrevInSection +: Pointer to the previous content within the same section (based on `publishdate` in front matter). For example, `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`. + +.PublishDate +: the date on which the content was or will be published; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`. + +.RSSLink +: link to the taxonomies' RSS link. + +.RawContent +: raw markdown content without the front matter. Useful with [remarkjs.com]( +http://remarkjs.com) + +.ReadingTime +: the estimated time, in minutes, it takes to read the content. + +.Ref +: returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). + +.RelPermalink +: the relative permanent link for this page. + +.RelRef +: returns the relative permalink for a given reference (e.g., `RelRef +"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). + +.Site +: see [Site Variables](/variables/site/). + +.Summary +: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <!--more--> at the appropriate place in the content page. See [Content Summaries](/content-management/summaries/) for more details. + +.TableOfContents +: the rendered [table of contents](/content-management/toc/) for the page. + +.Title +: the title for this page. + +.Translations +: a list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information. + +.Truncated +: a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information. + +.Type +: the [content type](/content-management/types/) of the content (e.g., `post`). + +.URL +: the URL for the page relative to the web root. Note that a `url` set directly in front matter overrides the default relative URL for the rendered page. + +.UniqueID +: the MD5-checksum of the content file's path. + +.Weight +: assigned weight (in the front matter) to this content, used in sorting. + +.WordCount +: the number of words in the content. + +## Section Variables and Methods + +Also see [Sections](/content-management/sections/). + +{{< readfile file="/content/en/readfiles/sectionvars.md" markdown="true" >}} + +## Page-level Params + +Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable. + +``` +--- +title: My First Post +date: 2017-02-20T15:26:23-06:00 +categories: [one] +tags: [two,three,four] +``` + +With the above front matter, the `tags` and `categories` taxonomies are accessible via the following: + +* `.Params.tags` +* `.Params.categories` + +{{% note "Casing of Params" %}} +Page-level `.Params` are *only* accessible in lowercase. +{{% /note %}} + +The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`: + +``` +--- +... +affiliatelink: "http://www.my-book-link.here" +recommendedby: "My Mother" +... +--- +``` + +These fields would then be accessible to the `/themes/yourtheme/layouts/review/single.html` template through `.Params.affiliatelink` and `.Params.recommendedby`, respectively. + +Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors. + +{{< code file="/themes/yourtheme/layouts/review/single.html" >}} +

    Buy this book

    +

    It was recommended by {{ .Params.recommendedby }}.

    +{{< /code >}} + +This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/): + +{{< output file="yourbaseurl/review/book01/index.html" >}} +

    Buy this book

    +

    It was recommended by my Mother.

    +{{< /output >}} + +{{% note %}} +See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content. +{{% /note %}} + +### The `.Param` Method + +In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image): + +``` +{{ $.Param "header_image" }} +``` + +The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your `config`). + +### Access Nested Fields in Front Matter + +When front matter contains nested fields like the following: + +``` +--- +author: + given_name: John + family_name: Feminella + display_name: John Feminella +--- +``` +`.Param` can access these fields by concatenating the field names together with a dot: + +``` +{{ $.Param "author.display_name" }} +``` + +If your front matter contains a top-level key that is ambiguous with a nested key, as in the following case: + +``` +--- +favorites.flavor: vanilla +favorites: + flavor: chocolate +--- +``` + +The top-level key will be preferred. Therefore, the following method, when applied to the previous example, will print `vanilla` and not `chocolate`: + +``` +{{ $.Param "favorites.flavor" }} +=> vanilla +``` + +[gitinfo]: /variables/git/ +[File Variables]: /variables/files/ diff --git a/content/en/variables/shortcodes.md b/content/en/variables/shortcodes.md new file mode 100644 index 00000000..b194eb7d --- /dev/null +++ b/content/en/variables/shortcodes.md @@ -0,0 +1,36 @@ +--- +title: Shortcode Variables +linktitle: Shortcode Variables +description: Shortcodes can access page variables and also have their own specific built-in variables. +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +categories: [variables and params] +keywords: [shortcodes] +draft: false +menu: + docs: + parent: "variables" + weight: 20 +weight: 20 +sections_weight: 20 +aliases: [] +toc: false +--- + +[Shortcodes][shortcodes] have access to parameters delimited in the shortcode declaration via [`.Get`][getfunction], page- and site-level variables, and also the following shortcode-specific fields: + +.Parent +: provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root. + +.IsNamedParams +: boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes] + +.Inner +: represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used + +[getfunction]: /functions/get/ +[markdownshortcode]: /content-management/shortcodes/#shortcodes-with-markdown +[shortcodes]: /templates/shortcode-templates/ + + diff --git a/content/en/variables/site.md b/content/en/variables/site.md new file mode 100644 index 00000000..a5909a56 --- /dev/null +++ b/content/en/variables/site.md @@ -0,0 +1,128 @@ +--- +title: Site Variables +linktitle: Site Variables +description: Many, but not all, site-wide variables are defined in your site's configuration. However, Hugo provides a number of built-in variables for convenient access to global values in your templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [variables and params] +keywords: [global,site] +draft: false +menu: + docs: + parent: "variables" + weight: 10 +weight: 10 +sections_weight: 10 +aliases: [/variables/site-variables/] +toc: true +--- + +The following is a list of site-level (aka "global") variables. Many of these variables are defined in your site's [configuration file][config], whereas others are built into Hugo's core for convenient usage in your templates. + +## Site Variables List + +.Site.AllPages +: array of all pages, regardless of their translation. + +.Site.Author +: a map of the authors as defined in the site configuration. + +.Site.BaseURL +: the base URL for the site as defined in the site configuration. + +.Site.BuildDrafts +: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration. + +.Site.Copyright +: a string representing the copyright of your website as defined in the site configuration. + +.Site.Data +: custom data, see [Data Templates](/templates/data-templates/). + +.Site.DisqusShortname +: a string representing the shortname of the Disqus shortcode as defined in the site configuration. + +.Site.Files +: all source files for the Hugo website. + +.Site.GoogleAnalytics +: a string representing your tracking code for Google Analytics as defined in the site configuration. + +.Site.IsMultiLingual +: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information. + +.Site.IsServer +: a boolean to indicate if the site is being served with Hugo's built-in server. See [`hugo server`](/commands/hugo_server/) for more information. + +.Site.Language.Lang +: the language code of the current locale (e.g., `en`). + +.Site.Language.LanguageName +: the full language name (e.g. `English`). + +.Site.Language.Weight +: the weight that defines the order in the `.Site.Languages` list. + +.Site.Language +: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition. + +.Site.LanguageCode +: a string representing the language as defined in the site configuration. This is mostly used to populate the RSS feeds with the right language code. + +.Site.LanguagePrefix +: this can be used to prefix URLs to point to the correct language. It will even work when only one defined language. See also the functions [absLangURL](/functions/abslangurl/) and [relLangURL](/functions/rellangurl). + +.Site.Languages +: an ordered list (ordered by defined weight) of languages. + +.Site.LastChange +: a string representing the date/time of the most recent change to your site. This string is based on the [`date` variable in the front matter](/content-management/front-matter) of your content pages. + +.Site.Menus +: all of the menus in the site. + +.Site.Pages +: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. + +.Site.Permalinks +: a string to override the default [permalink](/content-management/urls/) format as defined in the site configuration. + +.Site.RegularPages +: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. + +.Site.RSSLink +: the URL for the site RSS. + +.Site.Sections +: top-level directories of the site. + +.Site.Taxonomies +: the [taxonomies](/taxonomies/usage/) for the entire site. Replaces the now-obsolete `.Site.Indexes` since v0.11. Also see section [Taxonomies elsewhere](#taxonomies-elsewhere). + +.Site.Title +: a string representing the title of the site. + +## The `.Site.Params` Variable + +`.Site.Params` is a container holding the values from the `params` section of your site configuration. + +### Example: `.Site.Params` + +The following `config.[yaml|toml|json]` defines a site-wide param for `description`: + +{{< code-toggle file="config" >}} +baseURL = "https://yoursite.example.com/" + +[params] + description = "Tesla's Awesome Hugo Site" + author = "Nikola Tesla" +{{}} + +You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description: + +{{< code file="layouts/partials/head.html" >}} + +{{< /code >}} + +[config]: /getting-started/configuration/ diff --git a/content/en/variables/sitemap.md b/content/en/variables/sitemap.md new file mode 100644 index 00000000..dd926f2b --- /dev/null +++ b/content/en/variables/sitemap.md @@ -0,0 +1,32 @@ +--- +title: Sitemap Variables +linktitle: Sitemap Variables +description: +date: 2017-03-12 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +categories: [variables and params] +keywords: [sitemap] +draft: false +menu: + docs: + parent: "variables" + weight: 80 +weight: 80 +sections_weight: 80 +aliases: [] +toc: false +--- + +A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use sitemap templates. They also have the following sitemap-specific variables available to them: + +.Sitemap.ChangeFreq +: the page change frequency + +.Sitemap.Priority +: the priority of the page + +.Sitemap.Filename +: the sitemap filename + +[pagevars]: /variables/page/ \ No newline at end of file diff --git a/content/en/variables/taxonomy.md b/content/en/variables/taxonomy.md new file mode 100644 index 00000000..5bcdffee --- /dev/null +++ b/content/en/variables/taxonomy.md @@ -0,0 +1,84 @@ +--- +title: Taxonomy Variables +linktitle: +description: Taxonomy pages are of type `Page` and have all page-, site-, and list-level variables available to them. However, taxonomy terms templates have additional variables available to their templates. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [variables and params] +keywords: [taxonomies,terms] +draft: false +menu: + docs: + parent: "variables" + weight: 30 +weight: 30 +sections_weight: 30 +aliases: [] +toc: true +--- + +## Taxonomy Terms Page Variables + +[Taxonomy terms pages][taxonomytemplates] are of the type `Page` and have the following additional variables. + +For example, the following fields would be available in `layouts/_defaults/terms.html`, depending on how you organize your [taxonomy templates][taxonomytemplates]: + +.Data.Singular +: The singular name of the taxonomy (e.g., `tags => tag`) + +.Data.Plural +: The plural name of the taxonomy (e.g., `tags => tags`) + +.Data.Pages +: The list of pages in the taxonomy + +.Data.Terms +: The taxonomy itself + +.Data.Terms.Alphabetical +: The taxonomy terms alphabetized + +.Data.Terms.ByCount +: The Terms ordered by popularity + +Note that `.Data.Terms.Alphabetical` and `.Data.Terms.ByCount` can also be reversed: + +* `.Data.Terms.Alphabetical.Reverse` +* `.Data.Terms.ByCount.Reverse` + +## Use `.Site.Taxonomies` Outside of Taxonomy Templates + +The `.Site.Taxonomies` variable holds all the taxonomies defined site-wide. `.Site.Taxonomies` is a map of the taxonomy name to a list of its values (e.g., `"tags" -> ["tag1", "tag2", "tag3"]`). Each value, though, is not a string but rather a *Taxonomy variable*. + +## The `.Taxonomy` Variable + +The `.Taxonomy` variable, available, for example, as `.Site.Taxonomies.tags`, contains the list of tags (values) and, for each tag, their corresponding content pages. + +### Example Usage of `.Site.Taxonomies` + +The following [partial template][partials] will list all your site's taxonomies, each of their keys, and all the content assigned to each of the keys. For more examples of how to order and render your taxonomies, see [Taxonomy Templates][taxonomytemplates]. + +{{< code file="all-taxonomies-keys-and-pages.html" download="all-taxonomies-keys-and-pages.html" >}} +
    +
      + {{ range $taxonomyname, $taxonomy := .Site.Taxonomies }} +
    • {{ $taxonomyname }} +
        + {{ range $key, $value := $taxonomy }} +
      • {{ $key }}
        • + + {{ end }} +
      +
      • + {{ end }} +
    +
    +{{< /code >}} + +[partials]: /templates/partials/ +[taxonomytemplates]: /templates/taxonomy-templates/ diff --git a/content/functions/GetPage.md b/content/functions/GetPage.md deleted file mode 100644 index 1a8a51c1..00000000 --- a/content/functions/GetPage.md +++ /dev/null @@ -1,82 +0,0 @@ ---- -title: .GetPage -description: "Gets a `Page` of a given `Kind` and `path`." -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [sections,lists,indexes] -signature: [".GetPage KIND PATH"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] ---- - -Every `Page` has a [`Kind` attribute][page_kinds] that shows what kind of page it is. While this attribute can be used to list pages of a certain `kind` using `where`, often it can be useful to fetch a single page by its path. - -`.GetPage` returns a page of a given `Kind` and `path`. - -{{% note %}} -If the `path` is `"foo/bar.md"`, it can be written as exactly that, or broken up -into multiple strings as `"foo" "bar.md"`. -{{% /note %}} - -``` -{{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }} -``` - -This method wil return `nil` when no page could be found, so the above will not print anything if the blog section is not found. - -For a regular page (whose `Kind` is `page`): - -``` -{{ with .Site.GetPage "page" "blog/my-post.md" }}{{ .Title }}{{ end }} -``` - -Note that the `path` can also be supplied like this, where the slash-separated -path elements are added as separate strings: - -``` -{{ with .Site.GetPage "page" "blog" "my-post.md" }}{{ .Title }}{{ end }} -``` - -## `.GetPage` Example - -This code snippet---in the form of a [partial template][partials]---allows you to do the following: - -1. Grab the index object of your `tags` [taxonomy][]. -2. Assign this object to a variable, `$t` -3. Sort the terms associated with the taxonomy by popularity. -4. Grab the top two most popular terms in the taxonomy (i.e., the two most popular tags assigned to content. - -{{< code file="grab-top-two-tags.html" >}} -
      -{{ $t := .Site.GetPage "taxonomyTerm" "tags" }} -{{ range first 2 $t.Data.Terms.ByCount }} -
    • {{ . }}
      • -{{ end }} -
    -{{< /code >}} - -## `.GetPage` on Page Bundles - -If the page retrieved by `.GetPage` is a [Leaf Bundle][leaf_bundle], and you -need to get the nested _**page** resources_ in that, you will need to use the -methods in `.Resources` as explained in the [Page Resources][page_resources] -section. - -See the [Headless Bundle][headless_bundle] documentation for an example. - - -[partials]: /templates/partials/ -[taxonomy]: /content-management/taxonomies/ -[page_kinds]: /templates/section-templates/#page-kinds -[leaf_bundle]: /content-management/page-bundles/#leaf-bundles -[headless_bundle]: /content-management/page-bundles/#headless-bundle -[page_resources]: /content-management/page-resources/ diff --git a/content/functions/NumFmt.md b/content/functions/NumFmt.md deleted file mode 100644 index 795eaaea..00000000 --- a/content/functions/NumFmt.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -title: lang.NumFmt -description: "Formats a number with a given precision using the requested `negative`, `decimal`, and `grouping` options. The `options` parameter is a string consisting of ` `." -godocref: "" -workson: [] -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-08-21 -categories: [functions] -keywords: [numbers] -menu: - docs: - parent: "functions" -toc: false -signature: ["lang.NumFmt PRECISION NUMBER [OPTIONS]"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -draft: false -aliases: [] -comments: ---- - -The default options value is `- . ,`. - -Numbers greater than or equal to 5 are rounded up. For example, if precision is set to `0`, `1.5` becomes `2`, and `1.4` becomes `1`. - -``` -{{ lang.NumFmt 2 12345.6789 }} → 12,345.68 -{{ lang.NumFmt 2 12345.6789 "- , ." }} → 12.345,68 -{{ lang.NumFmt 0 -12345.6789 "- . ," }} → -12,346 -{{ lang.NumFmt 6 -12345.6789 "- ." }} → -12345.678900 -{{ -98765.4321 | lang.NumFmt 2 }} → -98,765.43 -``` diff --git a/content/functions/_index.md b/content/functions/_index.md deleted file mode 100644 index df10f2ae..00000000 --- a/content/functions/_index.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Functions Quick Reference -linktitle: Functions Quick Reference -description: Comprehensive list of Hugo templating functions, including basic and advanced usage examples. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -keywords: [] -menu: - docs: - parent: "functions" -weight: 01 #rem -draft: false -aliases: [/layout/functions/,/templates/functions] ---- - -Go templates are lightweight but extensible. Go itself supplies built-in functions, including comparison operators and other basic tools. These are listed in the [Go template documentation][gofuncs]. Hugo has added additional functions to the basic template logic. - -[gofuncs]: http://golang.org/pkg/text/template/#hdr-Functions diff --git a/content/functions/abslangurl.md b/content/functions/abslangurl.md deleted file mode 100644 index 418ff50f..00000000 --- a/content/functions/abslangurl.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: absLangURL -description: Adds the absolute URL with correct language prefix according to site configuration for multilingual. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [multilingual,i18n,urls] -signature: ["absLangURL INPUT"] -workson: [] -hugoversion: -relatedfuncs: [relLangURL] -deprecated: false -aliases: [] ---- - -Both `absLangURL` and [`relLangURL`](/functions/rellangurl/) are similar to their [`absURL`](/functions/absurl/) and [`relURL`](/functions/relurl) relatives but will add the correct language prefix when the site is configured with more than one language. - -So for a site `baseURL` set to `https://example.com/hugo/` and the current language is `en`: - -``` -{{ "blog/" | absLangURL }} → "https://example.com/hugo/en/blog/" -{{ "blog/" | relLangURL }} → "/hugo/en/blog/" -``` diff --git a/content/functions/absurl.md b/content/functions/absurl.md deleted file mode 100644 index a31dbb0b..00000000 --- a/content/functions/absurl.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: absURL -description: Creates an absolute URL based on the configured baseURL. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [urls] -signature: ["absURL INPUT"] -workson: [] -hugoversion: -relatedfuncs: [relURL] -deprecated: false -aliases: [] ---- - -Both `absURL` and `relURL` consider the configured value of `baseURL` in your site's [`config` file][configuration]. Given a `baseURL` set to `https://example.com/hugo/`: - -``` -{{ "mystyle.css" | absURL }} → "https://example.com/hugo/mystyle.css" -{{ "mystyle.css" | relURL }} → "/hugo/mystyle.css" -{{ "http://gohugo.io/" | relURL }} → "http://gohugo.io/" -{{ "http://gohugo.io/" | absURL }} → "http://gohugo.io/" -``` - -The last two examples may look strange but can be very useful. For example, the following shows how to use `absURL` in [JSON-LD structured data (SEO)][jsonld], where some of your images for a piece of content may or may not be hosted locally: - -{{< code file="layouts/partials/schemaorg-metadata.html" download="schemaorg-metadata.html" >}} - -{{< /code >}} - -The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside ` -{{< /code >}} - -The above uses the [apply function][] and also exposes how the Go template parser JSON-encodes objects inside `` → `` -* `` → `` - diff --git a/content/functions/safeURL.md b/content/functions/safeURL.md deleted file mode 100644 index cb9979cd..00000000 --- a/content/functions/safeURL.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: safeURL -description: Declares the provided string as a safe URL or URL substring. -godocref: https://golang.org/pkg/html/template/#HTMLEscape -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -keywords: [strings,urls] -categories: [functions] -menu: - docs: - parent: "functions" -signature: ["safeURL INPUT"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] ---- - -`safeURL` declares the provided string as a "safe" URL or URL substring (see [RFC 3986][]). A URL like `javascript:checkThatFormNotEditedBeforeLeavingPage()` from a trusted source should go in the page, but by default dynamic `javascript:` URLs are filtered out since they are a frequently exploited injection vector. - -Without `safeURL`, only the URI schemes `http:`, `https:` and `mailto:` are considered safe by Go templates. If any other URI schemes (e.g., `irc:` and `javascript:`) are detected, the whole URL will be replaced with `#ZgotmplZ`. This is to "defang" any potential attack in the URL by rendering it useless. - -The following examples use a [site `config.toml`][configuration] with the following [menu entry][menus]: - -{{< code file="config.toml" copy="false" >}} -[[menu.main]] - name = "IRC: #golang at freenode" - url = "irc://irc.freenode.net/#golang" -{{< /code >}} - -The following is an example of a sidebar partial that may be used in conjunction with the preceding front matter example: - -{{< code file="layouts/partials/bad-url-sidebar-menu.html" copy="false" >}} - -
      - {{ range .Site.Menus.main }} -
    • {{ .Name }}
      • - {{ end }} -
    -{{< /code >}} - -This partial would produce the following HTML output: - -{{< output file="bad-url-sidebar-menu-output.html" >}} - - -{{< /output >}} - -The odd output can be remedied by adding ` | safeURL` to our `.Title` page variable: - -{{< code file="layouts/partials/correct-url-sidebar-menu.html" copy="false" >}} - - -{{< /code >}} - -With the `.URL` page variable piped through `safeURL`, we get the desired output: - -{{< output file="correct-url-sidebar-menu-output.html" >}} - -{{< /output >}} - -[configuration]: /getting-started/configuration/ -[menus]: /content-management/menus/ -[RFC 3986]: http://tools.ietf.org/html/rfc3986 diff --git a/content/functions/scratch.md b/content/functions/scratch.md deleted file mode 100644 index 9df78fe4..00000000 --- a/content/functions/scratch.md +++ /dev/null @@ -1,113 +0,0 @@ ---- -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 -lastmod: 2017-02-01 -keywords: [iteration] -categories: [functions] -menu: - docs: - parent: "functions" -toc: -signature: [] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -draft: false -aliases: [/extras/scratch/,/doc/scratch/] ---- - -In most cases you can do okay without `Scratch`, but due to scoping issues, there are many use cases that aren't solvable in Go Templates without `Scratch`'s help. - -{{% note %}} -See [this Go issue](https://github.com/golang/go/issues/10608) for the main motivation behind Scratch. -{{% /note %}} - -{{% note %}} -For a detailed analysis of `.Scratch` and in context use cases, see this [post](https://regisphilibert.com/blog/2017/04/hugo-scratch-explained-variable/). -{{% /note %}} - -## Methods - -`Scratch` is added to both `Page` and `Shortcode` -- with following methods: - -#### .Set -Set the given value to a given key - -```go-html-template -{{ .Scratch.Set "greeting" "Hello" }} -``` -#### .Get -Get the value of a given key - -```go-html-template -{{ .Scratch.Set "greeting" "Hello" }} ----- -{{ .Scratch.Get "greeting" }} > Hello -``` - -#### .Add -Will add a given value to existing value of the given key. - -For single values, `Add` accepts values that support Go's `+` operator. If the first `Add` for a key is an array or slice, the following adds will be appended to that list. - -```go-html-template -{{ .Scratch.Add "greetings" "Hello" }} -{{ .Scratch.Add "greetings" "Welcome" }} ----- -{{ .Scratch.Get "greetings" }} > HelloWelcome -``` - -```go-html-template -{{ .Scratch.Add "total" 3 }} -{{ .Scratch.Add "total" 7 }} ----- -{{ .Scratch.Get "total" }} > 10 -``` - - -```go-html-template -{{ .Scratch.Add "greetings" (slice "Hello") }} -{{ .Scratch.Add "greetings" (slice "Welcome" "Cheers") }} ----- -{{ .Scratch.Get "greetings" }} > []interface {}{"Hello", "Welcome", "Cheers"} -``` - -#### .SetInMap -Takes a `key`, `mapKey` and `value` and add a map of `mapKey` and `value` to the given `key`. - -```go-html-template -{{ .Scratch.SetInMap "greetings" "english" "Hello" }} -{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }} ----- -{{ .Scratch.Get "greetings" }} > map[french:Bonjour english:Hello] -``` - -#### .GetSortedMapValues -Returns array of values from `key` sorted by `mapKey` - -```go-html-template -{{ .Scratch.SetInMap "greetings" "english" "Hello" }} -{{ .Scratch.SetInMap "greetings" "french" "Bonjour" }} ----- -{{ .Scratch.GetSortedMapValues "greetings" }} > [Hello Bonjour] -``` -#### .Delete -Removes the given key - -```go-html-template -{{ .Scratch.Delete "greetings" }} -``` - -## Scope -The scope of the backing data is global for the given `Page` or `Shortcode`, and spans partial and shortcode includes. - -Note that `.Scratch` from a shortcode will return the shortcode's `Scratch`, which in most cases is what you want. If you want to store it in the page scoped Scratch, then use `.Page.Scratch`. - - - - -[pagevars]: /variables/page/ diff --git a/content/functions/seq.md b/content/functions/seq.md deleted file mode 100644 index 8bef589c..00000000 --- a/content/functions/seq.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: seq -# linktitle: -description: Creates a sequence of integers. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [] -signature: ["seq LAST", "seq FIRST LAST", "seq FIRST INCREMENT LAST"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -draft: false -aliases: [] ---- - -It's named and used in the model of [GNU's seq][]. - -``` -3 → 1, 2, 3 -1 2 4 → 1, 3 --3 → -1, -2, -3 -1 4 → 1, 2, 3, 4 -1 -2 → 1, 0, -1, -2 -``` - -## Example: `seq` with `range` and `after` - -You can use `seq` in combination with `range` and `after`. The following will return 19 elements: - -``` -{{ range after 1 (seq 20)}} -{{ end }} -``` - -However, when ranging with an index, the following may be less confusing in that `$indexStartingAt1` and `$num` will return `1,2,3 ... 20`: - -``` -{{ range $index, $num := (seq 20) }} -$indexStartingAt1 := (add $index 1) -{{ end }} -``` - - -[GNU's seq]: http://www.gnu.org/software/coreutils/manual/html_node/seq-invocation.html#seq-invocation diff --git a/content/functions/sha.md b/content/functions/sha.md deleted file mode 100644 index 4e124346..00000000 --- a/content/functions/sha.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: sha -# linktitle: sha -description: Hashes the given input and returns either an SHA1 or SHA256 checksum. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [sha,checksum] -signature: ["sha1 INPUT", "sha256 INPUT"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] ---- - -`sha1` hashes the given input and returns its SHA1 checksum. - -``` -{{ sha1 "Hello world, gophers!" }} - -``` - -`sha256` hashes the given input and returns its SHA256 checksum. - -``` -{{ sha256 "Hello world, gophers!" }} - -``` diff --git a/content/functions/shuffle.md b/content/functions/shuffle.md deleted file mode 100644 index 9945ba75..00000000 --- a/content/functions/shuffle.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: shuffle -# linktitle: -description: Returns a random permutation of a given array or slice. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-04-30 -keywords: [ordering] -categories: [functions] -menu: - docs: - parent: "functions" -signature: ["shuffle COLLECTION"] -workson: [] -hugoversion: -relatedfuncs: [seq] -deprecated: false -draft: false -aliases: [] ---- - -{{< code file="shuffle-input.html" >}} - -
    {{ shuffle (seq 1 5) }}
    - -
    {{ shuffle (slice "foo" "bar" "buzz") }}
    -{{< /code >}} - -This example would return the following: - -{{< output file="shuffle-output.html" >}} - -
    2 5 3 1 4
    - -
    buzz foo bar
    -{{< /output >}} - -This example also makes use of the [slice](/functions/slice/) and [seq](/functions/seq/) functions. diff --git a/content/functions/singularize.md b/content/functions/singularize.md deleted file mode 100644 index 885eae23..00000000 --- a/content/functions/singularize.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: singularize -# linktitle: singularize -description: Converts a word according to a set of common English singularization rules. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings,singular] -signature: ["singularize INPUT"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] ---- - -`{{ "cats" | singularize }}` → "cat" - -See also the `.Data.Singular` [taxonomy variable](/variables/taxonomy/) for singularizing taxonomy names. - diff --git a/content/functions/slice.md b/content/functions/slice.md deleted file mode 100644 index c8847c0c..00000000 --- a/content/functions/slice.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: slice -# linktitle: slice -description: Creates a slice (array) of all passed arguments. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [slice, array, interface] -signature: ["slice ITEM..."] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -draft: false -aliases: [] -toc: false ---- - -One use case is the concatenation of elements in combination with the [`delimit` function][]: - -{{< code file="slice.html" >}} -{{ delimit (slice "foo" "bar" "buzz") ", " }} - -{{< /code >}} - - -[`delimit` function]: /functions/delimit/ diff --git a/content/functions/slicestr.md b/content/functions/slicestr.md deleted file mode 100644 index 3d245de3..00000000 --- a/content/functions/slicestr.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: slicestr -# linktitle: -description: Creates a slice of a half-open range, including start and end indices. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -signature: ["slicestr STRING START [END]"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] ---- - -For example, 1 and 4 creates a slice including elements 1 through 3. -The `end` index can be omitted; it defaults to the string's length. - -* `{{slicestr "BatMan" 3}}` → "Man" -* `{{slicestr "BatMan" 0 3}}` → "Bat" - diff --git a/content/functions/sort.md b/content/functions/sort.md deleted file mode 100644 index b83e6b0b..00000000 --- a/content/functions/sort.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: sort -# linktitle: sort -description: Sorts maps, arrays, and slices and returns a sorted slice. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [ordering,sorting,lists] -signature: [] -workson: [lists,taxonomies,terms,groups] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] ---- - -A sorted array of map values will be returned with the keys eliminated. There are two optional arguments: `sortByField` and `sortAsc`. If left blank, sort will sort by keys (for maps) in ascending order as its default behavior. - -``` -+++ -keywords: [ "tag3", "tag1", "tag2" ] -+++ - -// Site config -+++ -[params.authors] - [params.authors.Derek] - "firstName" = "Derek" - "lastName" = "Perkins" - [params.authors.Joe] - "firstName" = "Joe" - "lastName" = "Bergevin" - [params.authors.Tanner] - "firstName" = "Tanner" - "lastName" = "Linsley" -+++ -``` - -``` -// Use default sort options - sort by key / ascending -Tags: {{ range sort .Params.tags }}{{ . }} {{ end }} - -→ Outputs Tags: tag1 tag2 tag3 - -// Sort by value / descending -Tags: {{ range sort .Params.tags "value" "desc" }}{{ . }} {{ end }} - -→ Outputs Tags: tag3 tag2 tag1 - -// Use default sort options - sort by value / descending -Authors: {{ range sort .Site.Params.authors }}{{ .firstName }} {{ end }} - -→ Outputs Authors: Derek Joe Tanner - -// Use default sort options - sort by value / descending -Authors: {{ range sort .Site.Params.authors "lastName" "desc" }}{{ .lastName }} {{ end }} - -→ Outputs Authors: Perkins Linsley Bergevin -``` - diff --git a/content/functions/split.md b/content/functions/split.md deleted file mode 100644 index c42f8eb9..00000000 --- a/content/functions/split.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: split -# linktitle: split -description: splits a string into substrings separated by a delimiter -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -signature: ["split STRING DELIM"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] ---- - -* `{{split "tag1,tag2,tag3" "," }}` → ["tag1" "tag2" "tag3"] - - diff --git a/content/functions/string.md b/content/functions/string.md deleted file mode 100644 index d1e1962d..00000000 --- a/content/functions/string.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: string -# linktitle: string -description: Creates a string from the argument passed to the function -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -signature: ["string INPUT"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] ---- - -* `{{string "BatMan"}}` → "BatMan" - diff --git a/content/functions/strings.TrimLeft.md b/content/functions/strings.TrimLeft.md deleted file mode 100644 index 246facd6..00000000 --- a/content/functions/strings.TrimLeft.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: strings.TrimLeft -description: Returns a slice of a given string with all leading characters contained in the cutset removed. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -signature: ["strings.TrimLeft CUTSET STRING"] -workson: [] -hugoversion: -relatedfuncs: [strings.TrimRight] -deprecated: false -aliases: [] ---- - -Given the string `"abba"`, leading `"a"`'s can be removed a follows: - - {{ strings.TrimLeft "abba" "a" }} → "bba" - -Numbers can be handled as well: - - {{ strings.TrimLeft 1221 "12" }} → "" - diff --git a/content/functions/strings.TrimPrefix.md b/content/functions/strings.TrimPrefix.md deleted file mode 100644 index eeeecf76..00000000 --- a/content/functions/strings.TrimPrefix.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: strings.TrimPrefix -description: Returns a given string s without the provided leading prefix string. If s doesn't start with prefix, s is returned unchanged. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -signature: ["strings.TrimPrefix PREFIX STRING"] -workson: [] -hugoversion: -relatedfuncs: [strings.TrimSuffix] -deprecated: false -aliases: [] ---- - -Given the string `"aabbaa"`, the specified prefix is only removed if `"aabbaa"` starts with it: - - {{ strings.TrimPrefix "a" "aabbaa" }} → "abbaa" - {{ strings.TrimPrefix "aa" "aabbaa" }} → "bbaa" - {{ strings.TrimPrefix "aaa" "aabbaa" }} → "aabbaa" \ No newline at end of file diff --git a/content/functions/strings.TrimRight.md b/content/functions/strings.TrimRight.md deleted file mode 100644 index 44cb9edc..00000000 --- a/content/functions/strings.TrimRight.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: strings.TrimRight -description: Returns a slice of a given string with all trailing characters contained in the cutset removed. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -signature: ["strings.TrimRight CUTSET STRING"] -workson: [] -hugoversion: -relatedfuncs: [strings.TrimRight] -deprecated: false -aliases: [] ---- - -Given the string `"abba"`, trailing `"a"`'s can be removed a follows: - - {{ strings.TrimRight "abba" "a" }} → "abb" - -Numbers can be handled as well: - - {{ strings.TrimRight 1221 "12" }} → "" - diff --git a/content/functions/strings.TrimSuffix.md b/content/functions/strings.TrimSuffix.md deleted file mode 100644 index 208e0968..00000000 --- a/content/functions/strings.TrimSuffix.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: strings.TrimSuffix -description: Returns a given string s without the provided trailing suffix string. If s doesn't end with suffix, s is returned unchanged. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -signature: ["strings.TrimSuffix SUFFIX STRING"] -workson: [] -hugoversion: -relatedfuncs: [strings.TrimPrefix] -deprecated: false -aliases: [] ---- - -Given the string `"aabbaa"`, the specified suffix is only removed if `"aabbaa"` ends with it: - - {{ strings.TrimSuffix "a" "aabbaa" }} → "aabba" - {{ strings.TrimSuffix "aa" "aabbaa" }} → "aabb" - {{ strings.TrimSuffix "aaa" "aabbaa" }} → "aabbaa" \ No newline at end of file diff --git a/content/functions/substr.md b/content/functions/substr.md deleted file mode 100644 index 9dde05ec..00000000 --- a/content/functions/substr.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: substr -# linktitle: -description: Extracts parts of a string from a specified character's position and returns the specified number of characters. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -aliases: [] -signature: ["substr STRING START [LENGTH]"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false ---- - -It normally takes two parameters: `start` and `length`. It can also take one parameter: `start`, i.e. `length` is omitted, in which case the substring starting from start until the end of the string will be returned. - -To extract characters from the end of the string, use a negative start number. - -In addition, borrowing from the extended behavior described at http://php.net substr, if `length` is given and is negative, that number of characters will be omitted from the end of string. - -``` -{{substr "BatMan" 0 -3}} → "Bat" -{{substr "BatMan" 3 3}} → "Man" -``` diff --git a/content/functions/time.md b/content/functions/time.md deleted file mode 100644 index 306d3264..00000000 --- a/content/functions/time.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: time -linktitle: -description: Converts a timestamp string into a `time.Time` structure. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [dates,time] -signature: ["time INPUT"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] ---- - -`time` converts a timestamp string into a [`time.Time`](https://godoc.org/time#Time) structure so you can access its fields: - -``` -{{ time "2016-05-28" }} → "2016-05-28T00:00:00Z" -{{ (time "2016-05-28").YearDay }} → 149 -{{ mul 1000 (time "2016-05-28T10:30:00.00+10:00").Unix }} → 1464395400000, or Unix time in milliseconds -``` - -## Example: Using `time` to get Month Index - -The following example takes a UNIX timestamp---set as `utimestamp: "1489276800"` in a content's front matter---converts the timestamp (string) to an integer using the [`int` function][int], and then uses [`printf`][] to convert the `Month` property of `time` into an index. - -The following example may be useful when setting up [multilingual sites][multilingual]: - -{{< code file="unix-to-month-integer.html" >}} -{{$time := time (int .Params.addDate)}} -=> $time = 1489276800 -{{$time.Month}} -=> "March" -{{$monthindex := printf "%d" $time.Month }} -=> $monthindex = 3 -{{< /code >}} - - -[int]: /functions/int/ -[multilingual]: /content-management/multilingual/ -[`printf`]: /functions/printf/ diff --git a/content/functions/title.md b/content/functions/title.md deleted file mode 100644 index 63a34835..00000000 --- a/content/functions/title.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: title -# linktitle: -description: Converts all characters in the provided string to title case. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -signature: ["title INPUT"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] ---- - - -``` -{{title "BatMan"}}` → "Batman" -``` - -Can be combined in pipes. In the following snippet, the link text is cleaned up using `humanize` to remove dashes and `title` to convert the value of `$name` to Initial Caps. - -``` -{{ range $name, $items := .Site.Taxonomies.categories }} -
  • {{ $name | humanize | title }} ({{ len $items }})
    • -{{ end }} -``` diff --git a/content/functions/trim.md b/content/functions/trim.md deleted file mode 100644 index 81ed05c6..00000000 --- a/content/functions/trim.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: trim -# linktitle: -description: Returns a slice of a passed string with all leading and trailing characters from cutset removed. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -signature: ["trim INPUT CUTSET"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false ---- - -``` -{{ trim "++Batman--" "+-" }} → "Batman" -``` - -`trim` *requires* the second argument, which tells the function specifically what to remove from the first argument. There is no default value for the second argument, so **the following usage will not work**: - -``` -{{ trim .Inner}} -``` - -Instead, the following example tells `trim` to remove extra new lines from the content contained in the [shortcode `.Inner` variable][shortcodevars]: - -``` -{{ trim .Inner "\n" }} -``` - -{{% note %}} -Go templates also provide a simple [method for trimming whitespace](/templates/introduction/#whitespace) from either side of a Go tag by including a hyphen (`-`). -{{% /note %}} - - -[shortcodevars]: /variables/shortcodes/ diff --git a/content/functions/truncate.md b/content/functions/truncate.md deleted file mode 100644 index 0336853c..00000000 --- a/content/functions/truncate.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: truncate -# linktitle: truncate -description: Truncates a text to a max length without cutting words or leaving unclosed HTML tags. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [strings] -signature: ["truncate SIZE INPUT", "truncate SIZE ELLIPSIS INPUT"] -workson: [] -hugoversion: 19 -relatedfuncs: [] -deprecated: false ---- - -Since Go templates are HTML-aware, `truncate` will intelligently handle normal strings vs HTML strings: - -``` -{{ "Keep my HTML" | safeHTML | truncate 10 }}` → Keep my …` -``` - -{{% note %}} -If you have a raw string that contains HTML tags you want to remain treated as HTML, you will need to convert the string to HTML using the [`safeHTML` template function](/functions/safehtml) before sending the value to truncate. Otherwise, the HTML tags will be escaped when passed through the `truncate` function. -{{% /note %}} diff --git a/content/functions/union.md b/content/functions/union.md deleted file mode 100644 index 5c93e4bc..00000000 --- a/content/functions/union.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: union -# linktitle: union -description: Given two arrays or slices, returns a new array that contains the elements or objects that belong to either or both arrays/slices. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-03-12 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [filtering,lists] -signature: ["union SET1 SET2"] -workson: [] -hugoversion: 0.20 -relatedfuncs: [intersect,where] -deprecated: false -aliases: [] ---- - -Given two arrays (or slices) A and B, this function will return a new array that contains the elements or objects that belong to either A or to B or to both. The elements supported are strings, integers, and floats (only float64). - -``` -{{ union (slice 1 2 3) (slice 3 4 5) }} - - -{{ union (slice 1 2 3) nil }} - - -{{ union nil (slice 1 2 3) }} - - -{{ union nil nil }} - -``` - - -This is also very useful to use as `OR` filters when combined with where: - -``` -{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }} -{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }} -{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }} -``` - -The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page params. - -See [intersect](/functions/intersect) for `AND`. diff --git a/content/functions/uniq.md b/content/functions/uniq.md deleted file mode 100644 index 9692b247..00000000 --- a/content/functions/uniq.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: uniq -linktitle: uniq -description: Takes in a slice or array and returns a slice with subsequent duplicate elements removed. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [multilingual,i18n,urls] -signature: ["uniq SET"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -aliases: [] -needsexamples: false ---- - -``` -{{ uniq (slice 1 2 3 2) }} -{{ slice 1 2 3 2 | uniq }} - -``` - - - - diff --git a/content/functions/unix.md b/content/functions/unix.md deleted file mode 100644 index a373475f..00000000 --- a/content/functions/unix.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: .Unix -draft: false -description: .Unix returns the local Time corresponding to the given Unix time, sec seconds and nsec nanoseconds since January 1, 1970 UTC. -godocref: https://golang.org/search?q=Unix#Functions -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -keywords: [dates,time] -categories: [functions] -menu: - docs: - parent: "functions" -signature: [".Unix"] -workson: [times] -hugoversion: -relatedfuncs: [Format,dateFormat,now,time] -deprecated: false -aliases: [] ---- - -## Example: Time Passed Since Last Modification - -This very simple one-liner uses `now.Unix` to calculate the amount of time that has passed between the `.LastMod` for the current page and the last build of the current page. - -{{< code file="time-passed.html" >}} -{{ div (sub now.Unix .Lastmod.Unix) 86400 }} -{{< /code >}} - -Since both values are integers, they can be subtracted and then divided by the number of seconds in a day (i.e., `60 * 60 * 24 == 86400`). - -{{% note %}} -Hugo's output is *static*. For the example above to be realistic, the site needs to be built every day. - {{% /note %}} - - - -[partial template]: /templates/partials/ diff --git a/content/functions/upper.md b/content/functions/upper.md deleted file mode 100644 index 2d75b37b..00000000 --- a/content/functions/upper.md +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: upper -# linktitle: upper -description: Converts all characters in a string to uppercase -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -keywords: [] -categories: [functions] -menu: - docs: - parent: "functions" -toc: -signature: ["upper INPUT"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false -draft: false -aliases: [] ---- - -Note that `upper` can be applied in your templates in more than one way: - -``` -{{ upper "BatMan" }} → "BATMAN" -{{ "BatMan" | upper }} → "BATMAN" -``` - diff --git a/content/functions/urlize.md b/content/functions/urlize.md deleted file mode 100644 index 0fd7c229..00000000 --- a/content/functions/urlize.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: urlize -# linktitle: urlize -description: Takes a string, sanitizes it for usage in URLs, and converts spaces to hyphens. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [urls,strings] -godocref: -signature: ["urlize INPUT"] -hugoversion: -deprecated: false -workson: [] -relatedfuncs: [] ---- - -The following examples pull from a content file with the following front matter: - -{{< code file="content/blog/greatest-city.md" copy="false">}} -+++ -title = "The World's Greatest City" -location = "Chicago IL" -tags = ["pizza","beer","hot dogs"] -+++ -{{< /code >}} - -The following might be used as a partial within a [single page template][singletemplate]: - -{{< code file="layouts/partials/content-header.html" download="content-header.html" >}} -
    -

    {{.Title}}

    - {{ with .Params.location }} - - {{ end }} - - {{ with .Params.tags }} -
      - {{range .}} -
    • - {{ . }} -
      • - {{end}} -
    - {{ end }} -
    -{{< /code >}} - -The preceding partial would then output to the rendered page as follows, assuming the page is being built with Hugo's default pretty URLs. - -{{< output file="/blog/greatest-city/index.html" >}} -
    -

    The World's Greatest City

    - - -
    -{{< /output >}} - - -[singletemplate]: /templates/single-page-templates/ diff --git a/content/functions/urls.Parse.md b/content/functions/urls.Parse.md deleted file mode 100644 index 6d0ade0f..00000000 --- a/content/functions/urls.Parse.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: urls.Parse -description: Parse parses a given url, which may be relative or absolute, into a URL structure. -godocref: https://godoc.org/net/url#URL -date: 2017-09-25 -publishdate: 2017-09-25 -lastmod: 2017-09-25 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [urls] -signature: ["urls.Parse URL"] -workson: [] -hugoversion: -deprecated: false -aliases: [] ---- - -`urls.Parse` takes a url as input - - -``` -{{ $url := urls.Parse "http://www.gohugo.io" }} -``` - -and returns a [URL](https://godoc.org/net/url#URL) structure. The struct fields are accessed via the `.` notation: - -``` -{{ $url.Scheme }} → "http" -{{ $url.Host }} → "www.gohugo.io" -``` \ No newline at end of file diff --git a/content/functions/where.md b/content/functions/where.md deleted file mode 100644 index eb311121..00000000 --- a/content/functions/where.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -title: where -# linktitle: where -description: Filters an array to only the elements containing a matching value for a given field. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [filtering] -signature: ["where COLLECTION KEY [OPERATOR] MATCH"] -workson: [lists,taxonomies,terms,groups] -hugoversion: -relatedfuncs: [intersect,first,after,last] -deprecated: false -toc: true -needsexample: true ---- - -`where` filters an array to only the elements containing a matching value for a given field. - -```go-html-template -{{ range where .Data.Pages "Section" "post" }} - {{ .Content }} -{{ end }} -``` - -It can be used by dot-chaining the second argument to refer to a nested element of a value. - -``` -+++ -series: golang -+++ -``` - -```go-html-template -{{ range where .Site.Pages "Params.series" "golang" }} - {{ .Content }} -{{ end }} -``` - -It can also be used with the logical operators `!=`, `>=`, `in`, etc. Without an operator, `where` compares a given field with a matching value equivalent to `=`. - -```go-html-template -{{ range where .Data.Pages "Section" "!=" "post" }} - {{ .Content }} -{{ end }} -``` - -The following logical operators are available with `where`: - -`=`, `==`, `eq` -: `true` if a given field value equals a matching value - -`!=`, `<>`, `ne` -: `true` if a given field value doesn't equal a matching value - -`>=`, `ge` -: `true` if a given field value is greater than or equal to a matching value - -`>`, `gt` -: `true` if a given field value is greater than a matching value - -`<=`, `le` -: `true` if a given field value is lesser than or equal to a matching value - -`<`, `lt` -: `true` if a given field value is lesser than a matching value - -`in` -: `true` if a given field value is included in a matching value; a matching value must be an array or a slice - -`not in` -: `true` if a given field value isn't included in a matching value; a matching value must be an array or a slice - -`intersect` -: `true` if a given field value that is a slice/array of strings or integers contains elements in common with the matching value; it follows the same rules as the [`intersect` function][intersect]. - -## Use `where` with `intersect` - -```go-html-template -{{ range where .Site.Pages ".Params.tags" "intersect" .Params.tags }} - {{ if ne .Permalink $.Permalink }} - {{ .Render "summary" }} - {{ end }} -{{ end }} -``` - -You can also put the returned value of the `where` clauses into a variable: - -{{< code file="where-intersect-variables.html" >}} -{{ $v1 := where .Site.Pages "Params.a" "v1" }} -{{ $v2 := where .Site.Pages "Params.b" "v2" }} -{{ $filtered := $v1 | intersect $v2 }} -{{ range $filtered }} -{{ end }} -{{< /code >}} - -## Use `where` with `first` - -The following grabs the first five content files in `post` using the [default ordering](/templates/lists/) for lists (i.e., `weight => date`): - -{{< code file="where-with-first.html" >}} -{{ range first 5 (where .Data.Pages "Section" "post") }} - {{ .Content }} -{{ end }} -{{< /code >}} - -## Nest `where` Clauses - -You can also nest `where` clauses to drill down on lists of content by more than one parameter. The following first grabs all pages in the "blog" section and then ranges through the result of the first `where` clause and finds all pages that are *not* featured: - -```go-html-template -{{ range where (where .Data.Pages "Section" "blog" ) ".Params.featured" "!=" "true" }} -``` - -## Unset Fields - -Filtering only works for set fields. To check whether a field is set or exists, you can use the operand `nil`. - -This can be useful to filter a small amount of pages from a large pool. Instead of set field on all pages, you can set field on required pages only. - -Only the following operators are available for `nil` - -* `=`, `==`, `eq`: True if the given field is not set. -* `!=`, `<>`, `ne`: True if the given field is set. - -```go-html-template -{{ range where .Data.Pages ".Params.specialpost" "!=" nil }} - {{ .Content }} -{{ end }} -``` - -## Portable `where` filters - -This is especially important for themes, but to list the most relevant pages on the front page or similar, you can use `.Site.Params.mainSections` list. - -This will, by default, list pages from the _section with the most pages_. - -```go-html-template -{{ $pages := where .Site.RegularPages "Type" "in" .Site.Params.mainSections }} -``` - -The user can override the default in `config.toml`: - -```toml -[params] -mainSections = ["blog", "docs"] -``` - -[intersect]: /functions/intersect/ diff --git a/content/functions/with.md b/content/functions/with.md deleted file mode 100644 index 3fad8bd9..00000000 --- a/content/functions/with.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: with -# linktitle: with -description: Rebinds the context (`.`) within its scope and skips the block if the variable is absent. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-03-12 -categories: [functions] -menu: - docs: - parent: "functions" -keywords: [conditionals] -signature: ["with INPUT"] -workson: [] -hugoversion: -relatedfuncs: [] -deprecated: false ---- - -An alternative way of writing an `if` statement and then referencing the same value is to use `with` instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent or unset. - -The following example checks for a [user-defined site variable](/variables/site/) called `twitteruser`. If the key-value is not set, the following will render nothing: - -{{< code file="layouts/partials/twitter.html" >}} -{{with .Site.Params.twitteruser}}{{end}} -{{< /code >}} diff --git a/content/getting-started/_index.md b/content/getting-started/_index.md deleted file mode 100644 index 478d1eaa..00000000 --- a/content/getting-started/_index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Get Started -linktitle: Get Started Overview -description: Quick start and guides for installing Hugo on your preferred operating system. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [getting started] -keywords: [usage,docs] -menu: - docs: - parent: "getting-started" - weight: 1 -weight: 0001 #rem -draft: false -aliases: [/overview/introduction/] -toc: false ---- - -If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start][]. - -[installed]: /getting-started/installing/ -[quick start]: /getting-started/quick-start/ diff --git a/content/getting-started/code-toggle.md b/content/getting-started/code-toggle.md deleted file mode 100644 index 3e6b7da0..00000000 --- a/content/getting-started/code-toggle.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Code Toggle -description: Code Toggle tryout and showcase. -date: 2018-03-16 -categories: [getting started,fundamentals] -keywords: [configuration,toml,yaml,json] -weight: 60 -sections_weight: 60 -draft: false -toc: true ---- - -## The Config Toggler! - -This is an exemple for the Config Toggle shortcode. -Its purpose is to let users choose a Config language by clicking on its corresponding tab. Upon doing so, every Code toggler on the page will be switched to the target language. Also, target language will be saved in user's `localStorage` so when they go to a different pages, Code Toggler display their last "toggled" config language. - -## That Config Toggler - -{{< code-toggle file="config">}} - -baseURL: "https://yoursite.example.com/" -title: "My Hugo Site" -footnoteReturnLinkContents: "↩" -permalinks: - post: /:year/:month/:title/ -params: - Subtitle: "Hugo is Absurdly Fast!" - AuthorName: "Jon Doe" - GitHubUser: "spf13" - ListOfFoo: - - "foo1" - - "foo2" - SidebarRecentLimit: 5 -{{< /code-toggle >}} - -## Another Config Toggler! - -{{< code-toggle file="theme">}} - -# theme.toml template for a Hugo theme - -name = "Hugo Theme" -license = "MIT" -licenselink = "https://github.com/budparr/gohugo.io/blob/master/LICENSE.md" -description = "" -homepage = "https://github.com/budparr/gohugo.io" -tags = ["website"] -features = ["", ""] -min_version = 0.18 - -[author] - name = "Bud Parr" - homepage = "https://github.com/budparr" - -{{< /code-toggle >}} - -## Two regular code blocks - -{{< code file="bf-config.toml" >}} -[blackfriday] - angledQuotes = true - fractions = false - plainIDAnchors = true - extensions = ["hardLineBreak"] -{{< /code >}} - -{{< code file="bf-config.yml" >}} -blackfriday: - angledQuotes: true - fractions: false - plainIDAnchors: true - extensions: - - hardLineBreak -{{< /code >}} diff --git a/content/getting-started/configuration.md b/content/getting-started/configuration.md deleted file mode 100644 index 23fceb56..00000000 --- a/content/getting-started/configuration.md +++ /dev/null @@ -1,404 +0,0 @@ ---- -title: Configure Hugo -linktitle: Configuration -description: How to configure your Hugo site. -date: 2013-07-01 -publishdate: 2017-01-02 -lastmod: 2017-03-05 -categories: [getting started,fundamentals] -keywords: [configuration,toml,yaml,json] -menu: - docs: - parent: "getting-started" - weight: 60 -weight: 60 -sections_weight: 60 -draft: false -aliases: [/overview/source-directory/,/overview/configuration/] -toc: true ---- - -Hugo uses the `config.toml`, `config.yaml`, or `config.json` (if found in the -site root) as the default site config file. - -The user can choose to override that default with one or more site config files -using the command line `--config` switch. - -Examples: - -``` -hugo --config debugconfig.toml -hugo --config a.toml,b.toml,c.toml -``` - -{{% note %}} -Multiple site config files can be specified as a comma-separated string to the `--config` switch. -{{% /note %}} - -## All Configuration Settings - -The following is the full list of Hugo-defined variables with their default -value in parentheses. Users may choose to override those values in their site -config file(s). - -archetypeDir ("archetypes") -: The directory where Hugo finds archetype files (content templates). - -baseURL -: Hostname (and path) to the root, e.g. http://bep.is/ - -blackfriday -: See [Configure Blackfriday](/getting-started/configuration/#configure-blackfriday) - -buildDrafts (false) -: Include drafts when building. - -buildExpired (false) -: Include content already expired. - -buildFuture (false) -: Include content with publishdate in the future. - -canonifyURLs (false) -: Enable to turn relative URLs into absolute. - -contentDir ("content") -: The directory from where Hugo reads content files. - -dataDir ("data") -: The directory from where Hugo reads data files. - -defaultContentLanguage ("en") -: Content without language indicator will default to this language. - -defaultContentLanguageInSubdir (false) -: Render the default content language in subdir, e.g. `content/en/`. The site root `/` will then redirect to `/en/`. - -disableHugoGeneratorInject (false) -: Hugo will, by default, inject a generator meta tag in the HTML head on the _home page only_. You can turn it off, but we would really appreciate if you don't, as this is a good way to watch Hugo's popularity on the rise. - -disableKinds ([]) -: Enable disabling of all pages of the specified *Kinds*. Allowed values in this list: `"page"`, `"home"`, `"section"`, `"taxonomy"`, `"taxonomyTerm"`, `"RSS"`, `"sitemap"`, `"robotsTXT"`, `"404"`. - -disableLiveReload (false) -: Disable automatic live reloading of browser window. - -disablePathToLower (false) -: Do not convert the url/path to lowercase. - -enableEmoji (false) -: Enable Emoji emoticons support for page content; see the [Emoji Cheat Sheet](https://www.webpagefx.com/tools/emoji-cheat-sheet/). - -enableGitInfo (false) -: Enable `.GitInfo` object for each page (if the Hugo site is versioned by Git). This will then update the `Lastmod` parameter for each page using the last git commit date for that content file. - -enableMissingTranslationPlaceholders (false) -: Show a placeholder instead of the default value or an empty string if a translation is missing. - -enableRobotsTXT (false) -: Enable generation of `robots.txt` file. - -frontmatter - -: See [Front matter Configuration](#configure-front-matter). - -footnoteAnchorPrefix ("") -: Prefix for footnote anchors. - -footnoteReturnLinkContents ("") -: Text to display for footnote return links. - -googleAnalytics ("") -: Google Analytics tracking ID. - -hasCJKLanguage (false) -: If true, auto-detect Chinese/Japanese/Korean Languages in the content. This will make `.Summary` and `.WordCount` behave correctly for CJK languages. - -imaging -: See [Image Processing Config](/content-management/image-processing/#image-processing-config). - -languages -: See [Configure Languages](/content-management/multilingual/#configure-languages). - -languageCode ("") -: The site's language code. - -disableLanguages -: See [Disable a Language](/content-management/multilingual/#disable-a-language) - -layoutDir ("layouts") -: The directory from where Hugo reads layouts (templates). - -log (false) -: Enable logging. - -logFile ("") -: Log File path (if set, logging enabled automatically). - -menu -: See [Add Non-content Entries to a Menu](/content-management/menus/#add-non-content-entries-to-a-menu). - -metaDataFormat ("toml") -: Front matter meta-data format. Valid values: `"toml"`, `"yaml"`, or `"json"`. - -newContentEditor ("") -: The editor to use when creating new content. - -noChmod (false) -: Don't sync permission mode of files. - -noTimes (false) -: Don't sync modification time of files. - -paginate (10) -: Default number of pages per page in [pagination](/templates/pagination/). - -paginatePath ("page") -: The path element used during pagination (https://example.com/page/2). - -permalinks -: See [Content Management](/content-management/urls/#permalinks). - -pluralizeListTitles (true) -: Pluralize titles in lists. - -preserveTaxonomyNames (false) -: Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu"). - -publishDir ("public") -: The directory to where Hugo will write the final static site (the HTML files etc.). - -pygmentsCodeFencesGuessSyntax (false) -: Enable syntax guessing for code fences without specified language. - -pygmentsStyle ("monokai") -: Color-theme or style for syntax highlighting. See [Pygments Color Themes](https://help.farbox.com/pygments.html). - -pygmentsUseClasses (false) -: Enable using external CSS for syntax highlighting. - -related -: See [Related Content](/content-management/related/#configure-related-content). - -relativeURLs (false) -: Enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. - -rssLimit (unlimited) -: Maximum number of items in the RSS feed. - -sectionPagesMenu ("") -: See ["Section Menu for Lazy Bloggers"](/templates/menu-templates/#section-menu-for-lazy-bloggers). - -sitemap -: Default [sitemap configuration](/templates/sitemap-template/#configure-sitemap-xml). - -staticDir ("static") -: Relative directory from where Hugo reads static files. - -stepAnalysis (false) -: Display memory and timing of different steps of the program. - -summaryLength (70) -: The length of text to show in a [`.Summary`](/content-management/summaries/#hugo-defined-automatic-summary-splitting). - -taxonomies -: See [Configure Taxonomies](/content-management/taxonomies#configure-taxonomies). - -theme ("") -: Theme to use (located by default in `/themes/THEMENAME/`). - -themesDir ("themes") -: The directory where Hugo reads the themes from. - -title ("") -: Site title. - -uglyURLs (false) -: When enabled, creates URL of the form `/filename.html` instead of `/filename/`. - -verbose (false) -: Enable verbose output. - -verboseLog (false) -: Enable verbose logging. - -watch (false) -: Watch filesystem for changes and recreate as needed. - -{{% note %}} -If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line: -``` -cd ~/sites/yourhugosite -hugo config | grep emoji -``` - -which shows output like - -``` -enableemoji: true -``` -{{% /note %}} - -## Configuration Lookup Order - -Similar to the template [lookup order][], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior: - -1. `./config.toml` -2. `./config.yaml` -3. `./config.json` - -In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project. - - -## Example Configuration - -The following is a typical example of a configuration file. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]: - -{{< code-toggle file="config">}} -baseURL: "https://yoursite.example.com/" -title: "My Hugo Site" -footnoteReturnLinkContents: "↩" -permalinks: - post: /:year/:month/:title/ -params: - Subtitle: "Hugo is Absurdly Fast!" - AuthorName: "Jon Doe" - GitHubUser: "spf13" - ListOfFoo: - - "foo1" - - "foo2" - SidebarRecentLimit: 5 -{{< /code-toggle >}} - -## Configure with Environment Variables - -In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables. - -For example, the following command will effectively set a website's title on Unix-like systems: - -``` -$ env HUGO_TITLE="Some Title" hugo -``` - -This is really useful if you use a service such as Netlify to deploy your site. Look at the Hugo docs [Netlify configuration file](https://github.com/gohugoio/hugoDocs/blob/master/netlify.toml) for an example. - -{{% note "Setting Environment Variables" %}} -Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables. -{{% /note %}} - -{{< todo >}} -Test and document setting params via JSON env var. -{{< /todo >}} - -## Ignore Files When Rendering - -The following statement inside `./config.toml` will cause Hugo to ignore files ending with `.foo` and `.boo` when rendering: - -``` -ignoreFiles = [ "\\.foo$", "\\.boo$" ] -``` - -The above is a list of regular expressions. Note that the backslash (`\`) character is escaped in this example to keep TOML happy. - -## Configure Front Matter - -### Configure Dates - -Dates are important in Hugo, and you can configure how Hugo assigns dates to your content pages. You do this by adding a `frontmatter` section to your `config.toml`. - - -The default configuration is: - -```toml -[frontmatter] -date = ["date","publishDate", "lastmod"] -lastmod = [":git" "lastmod", "date","publishDate"] -publishDate = ["publishDate", "date"] -expiryDate = ["expiryDate"] -``` - -If you, as an example, have a non-standard date parameter in some of your content, you can override the setting for `date`: - - ```toml -[frontmatter] -date = [ "myDate", ":default"] -``` - -The `:default` is a shortcut to the default settings. The above will set `.Date` to the date value in `myDate` if present, if not we will look in `date`,`publishDate`, `lastmod` and pick the first valid date. - -In the list to the right, values starting with ":" are date handlers with a special meaning (see below). The others are just names of date parameters (case insensitive) in your front matter configuration. Also note that Hugo have some built-in aliases to the above: `lastmod` => `modified`, `publishDate` => `pubdate`, `published` and `expiryDate` => `unpublishdate`. With that, as an example, using `pubDate` as a date in front matter, will, by default, be assigned to `.PublishDate`. - -The special date handlers are: - - -`:fileModTime` -: Fetches the date from the content file's last modification timestamp. - -An example: - - ```toml -[frontmatter] -lastmod = ["lastmod" ,":fileModTime", ":default"] -``` - - -The above will try first to extract the value for `.Lastmod` starting with the `lastmod` front matter parameter, then the content file's modification timestamp. The last, `:default` should not be needed here, but Hugo will finally look for a valid date in `:git`, `date` and then `publishDate`. - - -`:filename` -: Fetches the date from the content file's filename. For example, `218-02-22-mypage.md` will extract the date `218-02-22`. Also, if `slug` is not set, `mypage` will be used as the value for `.Slug`. - -An example: - -```toml -[frontmatter] -date = [":filename", ":default"] -``` - -The above will try first to extract the value for `.Date` from the filename, then it will look in front matter parameters `date`, `publishDate` and lastly `lastmod`. - - -`:git` -: This is the Git author date for the last revision of this content file. This will only be set if `--enableGitInfo` is set or `enableGitInfo = true` is set in site config. - -## Configure Blackfriday - -[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine. - -Hugo typically configures Blackfriday with sane default values that should fit most use cases reasonably well. - -However, if you have specific needs with respect to Markdown, Hugo exposes some of its Blackfriday behavior options for you to alter. The following table lists these Hugo options, paired with the corresponding flags from Blackfriday's source code ( [html.go](https://github.com/russross/blackfriday/blob/master/html.go) and [markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)). - -{{< readfile file="/content/readfiles/bfconfig.md" markdown="true" >}} - -{{% note %}} -1. Blackfriday flags are *case sensitive* as of Hugo v0.15. -2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting. -{{% /note %}} - -{{< code-toggle file="config" >}} -[blackfriday] - angledQuotes = true - fractions = false - plainIDAnchors = true - extensions = ["hardLineBreak"] -{{< /code-toggle >}} - -## Configure Additional Output Formats - -Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats][] for information on how to add these values to your Hugo project's configuration file. - -## Configuration Format Specs - -* [TOML Spec][toml] -* [YAML Spec][yaml] -* [JSON Spec][json] - -[`.Site.Params`]: /variables/site/ -[directory structure]: /getting-started/directory-structure -[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" -[lookup order]: /templates/lookup-order/ -[Output Formats]: /templates/output-formats/ -[templates]: /templates/ -[toml]: https://github.com/toml-lang/toml -[yaml]: http://yaml.org/spec/ diff --git a/content/getting-started/directory-structure.md b/content/getting-started/directory-structure.md deleted file mode 100644 index ebfe6646..00000000 --- a/content/getting-started/directory-structure.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -title: Directory Structure -linktitle: Directory Structure -description: Hugo's CLI scaffolds a project directory structure and then takes that single directory and uses it as the input to create a complete website. -date: 2017-01-02 -publishdate: 2017-02-01 -lastmod: 2017-03-09 -categories: [getting started,fundamentals] -keywords: [source, organization, directories] -menu: - docs: - parent: "getting-started" - weight: 50 -weight: 50 -sections_weight: 50 -draft: false -aliases: [/overview/source-directory/] -toc: true ---- - -## New Site Scaffolding - -{{< youtube sB0HLHjgQ7E >}} - -Running the `hugo new site` generator from the command line will create a directory structure with the following elements: - -``` -. -├── archetypes -├── config.toml -├── content -├── data -├── layouts -├── static -└── themes -``` - - -## Directory Structure Explained - -The following is a high-level overview of each of the directories with links to each of their respective sections within the Hugo docs. - -[`archetypes`](/content-management/archetypes/) -: You can create new content files in Hugo using the `hugo new` command. -By default, Hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well. - -[`config.toml`](/getting-started/configuration/) -: Every Hugo project should have a configuration file in TOML, YAML, or JSON format at the root. Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives][] for more granular directions on how you want Hugo to build your website. - -[`content`][] -: All content for your website will live inside this directory. Each top-level folder in Hugo is considered a [content section][]. For example, if your site has three main sections---`blog`, `articles`, and `tutorials`---you will have three directories at `content/blog`, `content/articles`, and `content/tutorials`. Hugo uses sections to assign default [content types][]. - -[`data`](/templates/data-templates/) -: This directory is used to store configuration files that can be -used by Hugo when generating your website. You can write these files in YAML, JSON, or TOML format. In addition to the files you add to this folder, you can also create [data templates][] that pull from dynamic content. - -[`layouts`][] -: Stores templates in the form of `.html` files that specify how views of your content will be rendered into a static website. Templates include [list pages][lists], your [homepage][], [taxonomy templates][], [partials][], [single page templates][singles], and more. - -[`static`][] -: Stores all the static content for your future website: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the `static` folder is for [verifying site ownership on Google Search Console][searchconsole], where you want Hugo to copy over a complete HTML file without modifying its content. - -{{% note %}} -From **Hugo 0.31** you can have multiple static directories. -{{% /note %}} - -{{% note %}} -Hugo does not currently ship with an asset pipeline ([#3207](https://github.com/gohugoio/hugo/issues/3207)). You can solicit support from the community in the [Hugo forums](https://discourse.gohugo.io) or check out a few of the [Hugo starter kits](/tools/starter-kits/) for examples of how Hugo developers are managing static assets. -{{% /note %}} - - -[archetypes]: /content-management/archetypes/ -[configuration directives]: /getting-started/configuration/#all-variables-yaml -[`content`]: /content-management/organization/ -[content section]: /content-management/sections/ -[content types]: /content-management/types/ -[data templates]: /templates/data-templates/ -[homepage]: /templates/homepage/ -[`layouts`]: /templates/ -[`static`]: /content-management/static-files/ -[lists]: /templates/list/ -[pagevars]: /variables/page/ -[partials]: /templates/partials/ -[searchconsole]: https://support.google.com/analytics/answer/1142414?hl=en -[singles]: /templates/single-page-templates/ -[starters]: /tools/starter-kits/ -[taxonomies]: /content-management/taxonomies/ -[taxonomy templates]: /templates/taxonomy-templates/ -[types]: /content-management/types/ diff --git a/content/getting-started/installing.md b/content/getting-started/installing.md deleted file mode 100644 index bf0bde50..00000000 --- a/content/getting-started/installing.md +++ /dev/null @@ -1,502 +0,0 @@ ---- -title: Install Hugo -linktitle: Install Hugo -description: Install Hugo on macOS, Windows, Linux, FreeBSD, and on any machine where the Go compiler tool chain can run. -date: 2016-11-01 -publishdate: 2016-11-01 -lastmod: 2018-01-02 -categories: [getting started,fundamentals] -authors: ["Michael Henderson"] -keywords: [install,pc,windows,linux,macos,binary,tarball] -menu: - docs: - parent: "getting-started" - weight: 30 -weight: 30 -sections_weight: 30 -draft: false -aliases: [/tutorials/installing-on-windows/,/tutorials/installing-on-mac/,/overview/installing/,/getting-started/install,/install/] -toc: true ---- - - -{{% note %}} -There is lots of talk about "Hugo being written in Go", but you don't need to install Go to enjoy Hugo. Just grab a precompiled binary! -{{% /note %}} - -Hugo is written in [Go](https://golang.org/) with support for multiple platforms. The latest release can be found at [Hugo Releases][releases]. - -Hugo currently provides pre-built binaries for the following: - -* macOS (Darwin) for x64, i386, and ARM architectures -* Windows -* Linux -* FreeBSD - -Hugo may also be compiled from source wherever the Go compiler tool chain can run; e.g., on other operating systems such as DragonFly BSD, OpenBSD, Plan 9, Solaris, and others. See for the full set of supported combinations of target operating systems and compilation architectures. - -## Quick Install - -### Binary (Cross-platform) - -Download the appropriate version for your platform from [Hugo Releases][releases]. Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account. - -Ideally, you should install it somewhere in your `PATH` for easy use. `/usr/local/bin` is the most probable location. - -### Homebrew (macOS) - -If you are on macOS and using [Homebrew][brew], you can install Hugo with the following one-liner: - -{{< code file="install-with-homebrew.sh" >}} -brew install hugo -{{< /code >}} - -For more detailed explanations, read the installation guides that follow for installing on macOS and Windows. - -### Chocolatey (Windows) - -If you are on a Windows machine and use [Chocolatey][] for package management, you can install Hugo with the following one-liner: - -{{< code file="install-with-chocolatey.ps1" >}} -choco install hugo -confirm -{{< /code >}} - -### Source - -#### Prerequisite Tools - -* [Git][installgit] -* [Go (latest or previous version)][installgo] - -#### Vendored Dependencies - -Hugo uses [dep][] to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository. Therefore, a simple `go get` is *not* supported because the command is not vendor aware. - -The simplest way is to use [mage][] (a Make alternative for Go projects.) - -#### Fetch from GitHub - -{{< code file="from-gh.sh" >}} -go get github.com/magefile/mage -go get -d github.com/gohugoio/hugo -cd ${GOPATH:-$HOME/go}/src/github.com/gohugoio/hugo -mage vendor -mage install -{{< /code >}} - -{{% note %}} -If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`. -{{% /note %}} - -## macOS - -### Assumptions - -1. You know how to open the macOS terminal. -2. You're running a modern 64-bit Mac. -3. You will use `~/Sites` as the starting point for your site. (`~/Sites` is used for example purposes. If you are familiar enough with the command line and file system, you should have no issues following along with the instructions.) - -### Pick Your Method - -There are three ways to install Hugo on your Mac - -1. The [Homebrew][brew] `brew` utility -2. Distribution (i.e., tarball) -3. Building from Source - -There is no "best" way to install Hugo on your Mac. You should use the method that works best for your use case. - -#### Pros and Cons - -There are pros and cons to each of the aforementioned methods: - -1. **Homebrew.** Homebrew is the simplest method and will require the least amount of work to maintain. The drawbacks aren't severe. The default package will be for the most recent release, so it will not have bug fixes until the next release (i.e., unless you install it with the `--HEAD` option). Hugo `brew` releases may lag a few days behind because it has to be coordinated with another team. Nevertheless, `brew` is the recommended installation method if you want to work from a stable, widely used source. Brew works well and is easy to update. - -2. **Tarball.** Downloading and installing from the tarball is also easy, although it requires a few more command line skills than does Homebrew. Updates are easy as well: you just repeat the process with the new binary. This gives you the flexibility to have multiple versions on your computer. If you don't want to use `brew`, then the tarball/binary is a good choice. - -3. **Building from Source.** Building from source is the most work. The advantage of building from source is that you don't have to wait for a release to add features or bug fixes. The disadvantage is that you need to spend more time managing the setup, which is manageable but requires more time than the preceding two options. - -{{% note %}} -Since building from source is appealing to more seasoned command line users, this guide will focus more on installing Hugo via Homebrew and Tarball. -{{% /note %}} - -### Install Hugo with Brew - -{{< youtube WvhCGlLcrF8 >}} - -#### Step 1: Install `brew` if you haven't already - -Go to the `brew` website, , and follow the directions there. The most important step is the installation from the command line: - -{{< code file="install-brew.sh" >}} -ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" -{{< /code >}} - -#### Step 2: Run the `brew` Command to Install `hugo` - -Installing Hugo using `brew` is as easy as the following: - -{{< code file="install-brew.sh" >}} -brew install hugo -{{< /code >}} - -If Homebrew is working properly, you should see something similar to the following: - -``` -==> Downloading https://homebrew.bintray.com/bottles/hugo-0.21.sierra.bottle.tar.gz -######################################################################### 100.0% -==> Pouring hugo-0.21.sierra.bottle.tar.gz -🍺 /usr/local/Cellar/hugo/0.21: 32 files, 17.4MB -``` - -{{% note "Installing the Latest Hugo with Brew" %}} -Replace `brew install hugo` with `brew install hugo --HEAD` if you want the absolute latest in-development version. -{{% /note %}} - -`brew` should have updated your path to include Hugo. You can confirm by opening a new terminal window and running a few commands: - -``` -$ # show the location of the hugo executable -which hugo -/usr/local/bin/hugo - -# show the installed version -ls -l $( which hugo ) -lrwxr-xr-x 1 mdhender admin 30 Mar 28 22:19 /usr/local/bin/hugo -> ../Cellar/hugo/0.13_1/bin/hugo - -# verify that hugo runs correctly -hugo version -Hugo Static Site Generator v0.13 BuildDate: 2015-03-09T21:34:47-05:00 -``` - -### Install Hugo from Tarball - -#### Step 1: Decide on the location - -When installing from the tarball, you have to decide if you're going to install the binary in `/usr/local/bin` or in your home directory. There are three camps on this: - -1. Install it in `/usr/local/bin` so that all the users on your system have access to it. This is a good idea because it's a fairly standard place for executables. The downside is that you may need elevated privileges to put software into that location. Also, if there are multiple users on your system, they will all run the same version. Sometimes this can be an issue if you want to try out a new release. - -2. Install it in `~/bin` so that only you can execute it. This is a good idea because it's easy to do, easy to maintain, and doesn't require elevated privileges. The downside is that only you can run Hugo. If there are other users on your site, they have to maintain their own copies. That can lead to people running different versions. Of course, this does make it easier for you to experiment with different releases. - -3. Install it in your `Sites` directory. This is not a bad idea if you have only one site that you're building. It keeps every thing in a single place. If you want to try out new releases, you can make a copy of the entire site and update the Hugo executable. - -All three locations will work for you. In the interest of brevity, this guide focuses on option #2. - -#### Step 2: Download the Tarball - -1. Open in your browser. - -2. Find the current release by scrolling down and looking for the green tag that reads "Latest Release." - -3. Download the current tarball for the Mac. The name will be something like `hugo_X.Y_osx-64bit.tgz`, where `X.YY` is the release number. - -4. By default, the tarball will be saved to your `~/Downloads` directory. If you choose to use a different location, you'll need to change that in the following steps. - -#### Step 3: Confirm your download - -Verify that the tarball wasn't corrupted during the download: - -``` -tar tvf ~/Downloads/hugo_X.Y_osx-64bit.tgz --rwxrwxrwx 0 0 0 0 Feb 22 04:02 hugo_X.Y_osx-64bit/hugo_X.Y_osx-64bit.tgz --rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_X.Y_osx-64bit/README.md --rwxrwxrwx 0 0 0 0 Jan 30 18:48 hugo_X.Y_osx-64bit/LICENSE.md -``` - -The `.md` files are documentation for Hugo. The other file is the executable. - -#### Step 4: Install Into Your `bin` Directory - -``` -# create the directory if needed -mkdir -p ~/bin - -# make it the working directory -cd ~/bin - -# extract the tarball -tar -xvzf ~/Downloads/hugo_X.Y_osx-64bit.tgz -Archive: hugo_X.Y_osx-64bit.tgz - x ./ - x ./hugo - x ./LICENSE.md - x ./README.md - -# verify that it runs -./hugo version -Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30-06:00 -``` - -You may need to add your bin directory to your `PATH` variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything. - -``` -# check if hugo is in the path -which hugo -/Users/USERNAME/bin/hugo -``` - -If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor: - -``` -nano ~/.bash_profile -``` - -Add a line to update your `PATH` variable: - -``` -export PATH=$PATH:$HOME/bin -``` - -Then save the file by pressing Control-X, then Y to save the file and return to the prompt. - -Close the terminal and open a new terminal to pick up the changes to your profile. Verify your success by running the `which hugo` command again. - -You've successfully installed Hugo. - -### Build from Source on Mac - -If you want to compile Hugo yourself, you'll need to install Go (aka Golang). You can [install Go directly from the Go website](https://golang.org/dl/) or via Homebrew using the following command: - -``` -brew install go -``` - -#### Step 1: Get the Source - -If you want to compile a specific version of Hugo, go to and download the source code for the version of your choice. If you want to compile Hugo with all the latest changes (which might include bugs), clone the Hugo repository: - -``` -git clone https://github.com/gohugoio/hugo -``` - -{{% warning "Sometimes \"Latest\" = \"Bugs\""%}} -Cloning the Hugo repository directly means taking the good with the bad. By using the bleeding-edge version of Hugo, you make your development susceptible to the latest features, as well as the latest bugs. Your feedback is appreciated. If you find a bug in the latest release, [please create an issue on GitHub](https://github.com/gohugoio/hugo/issues/new). -{{% /warning %}} - -#### Step 2: Compiling - -Make the directory containing the source your working directory and then fetch Hugo's dependencies: - -``` -mkdir -p src/github.com/gohugoio -ln -sf $(pwd) src/github.com/gohugoio/hugo - -# set the build path for Go -export GOPATH=$(pwd) - -go get -``` - -This will fetch the absolute latest version of the dependencies. If Hugo fails to build, it may be the result of a dependency's author introducing a breaking change. - -Once you have properly configured your directory, you can compile Hugo using the following command: - -``` -go build -o hugo main.go -``` - -Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo. - -## Windows - -The following aims to be a complete guide to installing Hugo on your Windows PC. - -{{< youtube G7umPCU-8xc >}} - -### Assumptions - -1. You will use `C:\Hugo\Sites` as the starting point for your new project. -2. You will use `C:\Hugo\bin` to store executable files. - -### Set up Your Directories - -You'll need a place to store the Hugo executable, your [content][], and the generated Hugo website: - -1. Open Windows Explorer. -2. Create a new folder: `C:\Hugo`, assuming you want Hugo on your C drive, although this can go anywhere -3. Create a subfolder in the Hugo folder: `C:\Hugo\bin` -4. Create another subfolder in Hugo: `C:\Hugo\Sites` - -### Technical Users - -1. Download the latest zipped Hugo executable from [Hugo Releases][releases]. -2. Extract all contents to your `..\Hugo\bin` folder. -3. The `hugo` executable will be named as `hugo_hugo-version_platform_arch.exe`. Rename the executable to `hugo.exe` for ease of use. -4. In PowerShell or your preferred CLI, add the `hugo.exe` executable to your PATH by navigating to `C:\Hugo\bin` (or the location of your hugo.exe file) and use the command `set PATH=%PATH%;C:\Hugo\bin`. If the `hugo` command does not work after a reboot, you may have to run the command prompt as administrator. - -### Less-technical Users - -1. Go to the [Hugo Releases][releases] page. -2. The latest release is announced on top. Scroll to the bottom of the release announcement to see the downloads. They're all ZIP files. -3. Find the Windows files near the bottom (they're in alphabetical order, so Windows is last) – download either the 32-bit or 64-bit file depending on whether you have 32-bit or 64-bit Windows. (If you don't know, [see here](https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx).) -4. Move the ZIP file into your `C:\Hugo\bin` folder. -5. Double-click on the ZIP file and extract its contents. Be sure to extract the contents into the same `C:\Hugo\bin` folder – Windows will do this by default unless you tell it to extract somewhere else. -6. You should now have three new files: hugo executable (e.g. `hugo_0.18_windows_amd64.exe`), `license.md`, and `readme.md`. (You can delete the ZIP download now.) Rename that hugo executable (`hugo_hugo-version_platform_arch.exe`) to `hugo.exe` for ease of use. - -Now you need to add Hugo to your Windows PATH settings: - -#### For Windows 10 Users: - -* Right click on the **Start** button. -* Click on **System**. -* Click on **Advanced System Settings** on the left. -* Click on the **Environment Variables...** button on the bottom. -* In the User variables section, find the row that starts with PATH (PATH will be all caps). -* Double-click on **PATH**. -* Click the **New...** button. -* Type in the folder where `hugo.exe` was extracted, which is `C:\Hugo\bin` if you went by the instructions above. *The PATH entry should be the folder where Hugo lives and not the binary.* Press Enter when you're done typing. -* Click OK at every window to exit. - -{{% note "Path Editor in Windows 10"%}} -The path editor in Windows 10 was added in the large [November 2015 Update](https://blogs.windows.com/windowsexperience/2015/11/12/first-major-update-for-windows-10-available-today/). You'll need to have that or a later update installed for the above steps to work. You can see what Windows 10 build you have by clicking on the  Start button → Settings → System → About. See [here](https://www.howtogeek.com/236195/how-to-find-out-which-build-and-version-of-windows-10-you-have/) for more.) -{{% /note %}} - -#### For Windows 7 and 8.x users: - -Windows 7 and 8.1 do not include the easy path editor included in Windows 10, so non-technical users on those platforms are advised to install a free third-party path editor like [Windows Environment Variables Editor][Windows Environment Variables Editor] or [Path Editor](https://patheditor2.codeplex.com/). - -### Verify the Executable - -Run a few commands to verify that the executable is ready to run, and then build a sample site to get started. - -#### 1. Open a Command Prompt - -At the prompt, type `hugo help` and press the Enter key. You should see output that starts with: - -``` -hugo is the main command, used to build your Hugo site. - -Hugo is a Fast and Flexible Static Site Generator -built with love by spf13 and friends in Go. - -Complete documentation is available at https://gohugo.io/. -``` - -If you do, then the installation is complete. If you don't, double-check the path that you placed the `hugo.exe` file in and that you typed that path correctly when you added it to your `PATH` variable. If you're still not getting the output, search the [Hugo discussion forum][forum] to see if others have already figured out our problem. If not, add a note---in the "Support" category---and be sure to include your command and the output. - -At the prompt, change your directory to the `Sites` directory. - -``` -C:\Program Files> cd C:\Hugo\Sites -C:\Hugo\Sites> -``` - -#### 2. Run the Command - -Run the command to generate a new site. I'm using `example.com` as the name of the site. - -``` -C:\Hugo\Sites> hugo new site example.com -``` - -You should now have a directory at `C:\Hugo\Sites\example.com`. Change into that directory and list the contents. You should get output similar to the following: - -``` -C:\Hugo\Sites> cd example.com -C:\Hugo\Sites\example.com> dir -Directory of C:\hugo\sites\example.com - -04/13/2015 10:44 PM . -04/13/2015 10:44 PM .. -04/13/2015 10:44 PM archetypes -04/13/2015 10:44 PM 83 config.toml -04/13/2015 10:44 PM content -04/13/2015 10:44 PM data -04/13/2015 10:44 PM layouts -04/13/2015 10:44 PM static - 1 File(s) 83 bytes - 7 Dir(s) 6,273,331,200 bytes free -``` - -### Troubleshoot Windows Installation - -[@dhersam][] has created a nice video on common issues: - -{{< youtube c8fJIRNChmU >}} - -## Linux - -### Snap Package - -In any of the [Linux distributions that support snaps][snaps]: - -``` -snap install hugo -``` - -### Debian and Ubuntu - -Debian and Ubuntu provide a `hugo` version via `apt-get`: - -``` -sudo apt-get install hugo -``` - -#### Pros - -* Native Debian/Ubuntu package maintained by Debian Developers -* Pre-installed bash completion script and `man` pages - -#### Cons - -* 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. -{{% /note %}} - -### Arch Linux - -You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also for derivatives such as Manjaro. - -``` -sudo pacman -Sy hugo -``` - -### Fedora - -Fedora provides a package for Hugo. The installation is done with the command : - -``` -sudo dnf install hugo -``` - -### CentOS, and Red Hat - -* - -See the [related discussion in the Hugo forums][redhatforum]. - -## Upgrade Hugo - -Upgrading Hugo is as easy as downloading and replacing the executable you’ve placed in your `PATH` or run `brew upgrade hugo` if using Homebrew. - -## Install Pygments (Optional) - -The Hugo executable has one *optional* external dependency for source code highlighting ([Pygments][pygments]). - -If you want to have source code highlighting using the [highlight shortcode][], you need to install the Python-based Pygments program. The procedure is outlined on the [Pygments homepage][pygments]. - -## Next Steps - -Now that you've installed Hugo, read the [Quick Start guide][quickstart] and explore the rest of the documentation. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][forum]. - -[brew]: https://brew.sh/ -[Chocolatey]: https://chocolatey.org/ -[content]: /content-management/ -[@dhersam]: https://github.com/dhersam -[forum]: https://discourse.gohugo.io -[mage]: https://github.com/magefile/mage -[dep]: https://github.com/golang/dep -[highlight shortcode]: /content-management/shortcodes/#highlight -[installgit]: http://git-scm.com/ -[installgo]: https://golang.org/dl/ -[Path Editor]: https://patheditor2.codeplex.com/ -[pygments]: http://pygments.org -[quickstart]: /getting-started/quick-start/ -[redhatforum]: https://discourse.gohugo.io/t/solved-fedora-copr-repository-out-of-service/2491 -[releases]: https://github.com/gohugoio/hugo/releases -[snaps]: http://snapcraft.io/docs/core/install -[windowsarch]: https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx -[Windows Environment Variables Editor]: http://eveditor.com/ diff --git a/content/getting-started/quick-start.md b/content/getting-started/quick-start.md deleted file mode 100644 index 59a8513c..00000000 --- a/content/getting-started/quick-start.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -title: Quick Start -linktitle: Quick Start -description: Create a Hugo site using the beautiful Ananke theme. -date: 2013-07-01 -publishdate: 2013-07-01 -categories: [getting started] -keywords: [quick start,usage] -authors: [Shekhar Gulati, Ryan Watters] -menu: - docs: - parent: "getting-started" - weight: 10 -weight: 10 -sections_weight: 10 -draft: false -aliases: [/quickstart/,/overview/quickstart/] -toc: true ---- - -{{% note %}} -This quick start uses `macOS` in the examples. For instructions about how to install Hugo on other operating systems, see [install](/getting-started/installing). - -You also need [Git installed](https://git-scm.com/downloads) to run this tutorial. -{{% /note %}} - - - -## Step 1: Install Hugo - -{{% note %}} -`Homebrew`, a package manager for `macOS`, can be installed from [brew.sh](https://brew.sh/). See [install](/getting-started/installing) if you are running Windows etc. -{{% /note %}} - -```bash -brew install hugo -``` - -To verify your new install: - -```bash -hugo version -``` - - -{{< asciicast HDlKrUrbfT7yiWsbd6QoxzRTN >}} - - -## Step 2: Create a New Site - -```bash -hugo new site quickstart -``` - -The above will create a new Hugo site in a folder named `quickstart`. - -{{< asciicast 1PH9A2fs14Dnyarx5v8OMYQer >}} - - -## Step 3: Add a Theme - -See [themes.gohugo.io](https://themes.gohugo.io/) for a list of themes to consider. This quickstart uses the beautiful [Ananke theme](https://themes.gohugo.io/gohugo-theme-ananke/). - -```bash -cd quickstart;\ -git init;\ -git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke;\ - -# Edit your config.toml configuration file -# and add the Ananke theme. -echo 'theme = "ananke"' >> config.toml -``` - - -{{< asciicast WJM2LEZQs8VRhNeuZ5NiGPp9I >}} - -## Step 4: Add Some Content - -``` -hugo new posts/my-first-post.md -``` - - -Edit the newly created content file if you want. Now, start the Hugo server with [drafts](/getting-started/usage/#draft-future-and-expired-content) enabled: - -``` -▶ hugo server -D - -Started building sites ... -Built site for language en: -1 of 1 draft rendered -0 future content -0 expired content -1 regular pages created -8 other pages created -0 non-page files copied -1 paginator pages created -0 categories created -0 tags created -total in 18 ms -Watching for changes in /Users/bep/sites/quickstart/{data,content,layouts,static,themes} -Serving pages from memory -Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) -Press Ctrl+C to stop -``` - - -**Navigate to your new site at [http://localhost:1313/](http://localhost:1313/).** - - - -## Step 5: Customize the Theme - -Your new site already looks great, but you will want to tweak it a little before you release it to the public. - -### Site Configuration - -Open up `config.toml` in a text editor: - -``` -baseURL = "https://example.org/" -languageCode = "en-us" -title = "My New Hugo Site" -theme = "ananke" -``` - -Replace the `title` above with something more personal. Also, if you already have a domain ready, set the `baseURL`. Note that this value is not needed when running the local development server. - -{{% note %}} -**Tip:** Make the changes to the site configuration or any other file in your site while the Hugo server is running, and you will see the changes in the browser right away. -{{% /note %}} - - -For theme specific configuration options, see the [theme site](https://github.com/budparr/gohugo-theme-ananke). - -**For further theme customization, see [Customize a Theme](/themes/customizing/).** - -## Recapitulation - -{{< asciicast pWp4uvyAkdWgQllD9RCfeBL5k >}} diff --git a/content/getting-started/usage.md b/content/getting-started/usage.md deleted file mode 100644 index 2ad2910f..00000000 --- a/content/getting-started/usage.md +++ /dev/null @@ -1,230 +0,0 @@ ---- -title: Basic Usage -linktitle: Basic Usage -description: Hugo's CLI is fully featured but simple to use, even for those who have very limited experience working from the command line. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [getting started] -keywords: [usage,livereload,command line,flags] -menu: - docs: - parent: "getting-started" - weight: 40 -weight: 40 -sections_weight: 40 -draft: false -aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/] -toc: true ---- - -The following is a description of the most common commands you will use while developing your Hugo project. See the [Command Line Reference][commands] for a comprehensive view of Hugo's CLI. - -## Test Installation - -Once you have [installed Hugo][install], make sure it is in your `PATH`. You can test that Hugo has been installed correctly via the `help` command: - -``` -hugo help -``` - -The output you see in your console should be similar to the following: - -``` -hugo is the main command, used to build your Hugo site. - -Hugo is a Fast and Flexible Static Site Generator -built with love by spf13 and friends in Go. - -Complete documentation is available at http://gohugo.io/. - -Usage: - hugo [flags] - hugo [command] - -Available Commands: - benchmark Benchmark Hugo by building a site a number of times. - check Contains some verification checks - config Print the site configuration - convert Convert your content to different formats - env Print Hugo version and environment info - gen A collection of several useful generators. - help Help about any command - import Import your site from others. - list Listing out various types of content - new Create new content for your site - server A high performance webserver - version Print the version number of Hugo - -Flags: - -b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/ - -D, --buildDrafts include content marked as draft - -E, --buildExpired include expired content - -F, --buildFuture include content with publishdate in the future - --cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/ - --canonifyURLs (deprecated) if true, all relative URLs will be canonicalized using baseURL - --cleanDestinationDir remove files from destination not found in static directories - --config string config file (default is path/config.yaml|json|toml) - -c, --contentDir string filesystem path to content directory - --debug debug output - -d, --destination string filesystem path to write files to - --disableKinds stringSlice disable different kind of pages (home, RSS etc.) - --enableGitInfo add Git revision, date and author info to the pages - --forceSyncStatic copy all files when static is changed. - --gc enable to run some cleanup tasks (remove unused cache files) after the build - -h, --help help for hugo - --i18n-warnings print missing translations - --ignoreCache ignores the cache directory - -l, --layoutDir string filesystem path to layout directory - --log enable Logging - --logFile string log File path (if set, logging enabled automatically) - --noChmod don't sync permission mode of files - --noTimes don't sync modification time of files - --pluralizeListTitles (deprecated) pluralize titles in lists using inflect (default true) - --preserveTaxonomyNames (deprecated) preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu") - --quiet build in quiet mode - --renderToMemory render to memory (only useful for benchmark testing) - -s, --source string filesystem path to read files relative from - --stepAnalysis display memory and timing of different steps of the program - --templateMetrics display metrics about template executions - --templateMetricsHints calculate some improvement hints when combined with --templateMetrics - -t, --theme string theme to use (located in /themes/THEMENAME/) - --themesDir string filesystem path to themes directory - --uglyURLs (deprecated) if true, use /filename.html instead of /filename/ - -v, --verbose verbose output - --verboseLog verbose logging - -w, --watch watch filesystem for changes and recreate as needed - -Use "hugo [command] --help" for more information about a command. -``` - -## The `hugo` Command - -The most common usage is probably to run `hugo` with your current directory being the input directory. - -This generates your website to the `public/` directory by default, although you can customize the output directory in your [site configuration][config] by changing the `publishDir` field. - -The site Hugo renders into `public/` is ready to be deployed to your web server: - -``` -hugo -0 draft content -0 future content -99 pages created -0 paginator pages created -16 tags created -0 groups created -in 90 ms -``` - -## Draft, Future, and Expired Content - -Hugo allows you to set `draft`, `publishdate`, and even `expirydate` in your content's [front matter][]. By default, Hugo will not publish: - -1. Content with a future `publishdate` value -2. Content with `draft: true` status -3. Content with a past `expirydate` value - -All three of these can be overridden during both local development *and* deployment by adding the following flags to `hugo` and `hugo server`, respectively, or by changing the boolean values assigned to the fields of the same name (without `--`) in your [configuration][config]: - -1. `--buildFuture` -2. `--buildDrafts` -3. `--buildExpired` - -## LiveReload - -Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server with the `hugo server` command and watch for changes: - -``` -hugo server -0 draft content -0 future content -99 pages created -0 paginator pages created -16 tags created -0 groups created -in 120 ms -Watching for changes in /Users/yourname/sites/yourhugosite/{data,content,layouts,static} -Serving pages from /Users/yourname/sites/yourhugosite/public -Web Server is available at http://localhost:1313/ -Press Ctrl+C to stop -``` - -This will run a fully functioning web server while simultaneously watching your file system for additions, deletions, or changes within the following areas of your [project organization][dirs]: - -* `/static/*` -* `/content/*` -* `/data/*` -* `/i18n/*` -* `/layouts/*` -* `/themes//*` -* `config` - -Whenever you make changes, Hugo will simultaneously rebuild the site and continue to serve content. As soon as the build is finished, LiveReload tells the browser to silently reload the page. - -Most Hugo builds are so fast that you may not notice the change unless looking directly at the site in your browser. This means that keeping the site open on a second monitor (or another half of your current monitor) allows you to see the most up-to-date version of your website without the need to leave your text editor. - -{{% note "Closing `` Tag"%}} -Hugo injects the LiveReload ` - -comments powered by Disqus -{{< /code >}} - -The `if` statement skips the initialization of the Disqus comment injection when you are running on `localhost`. - -You can then render your custom Disqus partial template as follows: - -``` -{{ partial "disqus.html" . }} -``` - -## The Internal Templates - -* `_internal/disqus.html` -* `_internal/google_news.html` -* `_internal/google_analytics.html` -* `_internal/google_analytics_async.html` -* `_internal/opengraph.html` -* `_internal/pagination.html` -* `_internal/schema.html` -* `_internal/twitter_cards.html` - -[disqus]: https://disqus.com -[disqussignup]: https://disqus.com/profile/signup/ diff --git a/content/templates/introduction.md b/content/templates/introduction.md deleted file mode 100644 index 32df1129..00000000 --- a/content/templates/introduction.md +++ /dev/null @@ -1,541 +0,0 @@ ---- -title: Introduction to Hugo Templating -linktitle: Introduction -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 -lastmod: 2017-02-25 -categories: [templates,fundamentals] -keywords: [go] -menu: - docs: - parent: "templates" - weight: 10 -weight: 10 -sections_weight: 10 -draft: false -aliases: [/templates/introduction/,/layouts/introduction/,/layout/introduction/, /templates/go-templates/] -toc: true ---- - -{{% 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 %}} - -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. - -{{< youtube gnJbPO-GFIw >}} - -## Basic Syntax - -Golang templates are HTML files with the addition of [variables][variables] and [functions][functions]. Golang template variables and functions are accessible within `{{ }}`. - -### Access a Predefined Variable - -``` -{{ foo }} -``` - -Parameters for functions are separated using spaces. The following example calls the `add` function with inputs of `1` and `2`: - -``` -{{ add 1 2 }} -``` - -#### Methods and Fields are Accessed via dot Notation - -Accessing the Page Parameter `bar` defined in a piece of content's [front matter][]. - -``` -{{ .Params.bar }} -``` - -#### Parentheses Can be Used to Group Items Together - -``` -{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} -``` - -## Variables - -Each Go template gets a data object. In Hugo, each template is passed a `Page`. See [variables][] for more information. - -This is how you access a `Page` variable from a template: - -``` -{{ .Title }} -``` - -Values can also be stored in custom variables and referenced later: - -``` -{{ $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. - -[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo. - -### Example 1: Adding Numbers - -``` -{{ add 1 2 }} -=> 3 -``` - -### Example 2: Comparing Numbers - -``` -{{ lt 1 2 }} -=> true (i.e., since 1 is less than 2) -``` - -Note that both examples make use of Go template's [math functions][]. - -{{% note "Additional Boolean Operators" %}} -There are more boolean operators than those listed in the Hugo docs in the [Golang template documentation](http://golang.org/pkg/text/template/#hdr-Functions). -{{% /note %}} - -## Includes - -When including another template, you will need to pass it the data that it would -need to access. - -{{% note %}} -To pass along the current context, please remember to include a trailing **dot**. -{{% /note %}} - -The templates location will always be starting at the `layouts/` directory -within Hugo. - -### Partial - -The [`partial`][partials] function is used to include *partial* templates using -the syntax `{{ partial "/." . }}`. - -Example: - -``` -{{ partial "header.html" . }} -``` - -### Template - -The `template` function was used to include *partial* templates in much older -Hugo versions. Now it is still useful for calling [*internal* -templates][internal_templates]: - -``` -{{ template "_internal/opengraph.html" . }} -``` - -## Logic - -Go templates provide the most basic iteration and conditional logic. - -### Iteration - -Just like in Go, the Go templates make heavy use of `range` to iterate over -a map, array, or slice. The following are different examples of how to use -range. - -#### Example 1: Using Context - -``` -{{ range array }} - {{ . }} -{{ end }} -``` - -#### Example 2: Declaring Value => Variable name - -``` -{{range $element := array}} - {{ $element }} -{{ end }} -``` - -#### Example 3: Declaring Key-Value Variable Name - -``` -{{range $index, $element := array}} - {{ $index }} - {{ $element }} -{{ end }} -``` - -### Conditionals - -`if`, `else`, `with`, `or`, and `and` provide the framework for handling conditional logic in Go Templates. Like `range`, each statement is closed with an `{{end}}`. - -Go Templates treat the following values as false: - -* false -* 0 -* any zero-length array, slice, map, or string - -#### Example 1: `if` - -``` -{{ if isset .Params "title" }}

    {{ index .Params "title" }}

    {{ end }} -``` - -#### Example 2: `if` … `else` - -``` -{{ if isset .Params "alt" }} - {{ index .Params "alt" }} -{{else}} - {{ index .Params "caption" }} -{{ end }} -``` - -#### Example 3: `and` & `or` - -``` -{{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} -``` - -#### Example 4: `with` - -An alternative way of writing "`if`" and then referencing the same value -is to use "`with`" instead. `with` rebinds the context `.` within its scope -and skips the block if the variable is absent. - -The first example above could be simplified as: - -``` -{{ with .Params.title }}

    {{ . }}

    {{ end }} -``` - -#### Example 5: `if` … `else if` - -``` -{{ if isset .Params "alt" }} - {{ index .Params "alt" }} -{{ else if isset .Params "caption" }} - {{ index .Params "caption" }} -{{ end }} -``` - -## Pipes - -One of the most powerful components of Go templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from Unix pipes, the concept is simple: each pipeline's output becomes the input of the following pipe. - -Because of the very simple syntax of Go templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they can only work with a single value and that value becomes the last parameter of the next pipeline. - -A few simple examples should help convey how to use the pipe. - -### Example 1: `shuffle` - -The following two examples are functionally the same: - -``` -{{ shuffle (seq 1 5) }} -``` - - -``` -{{ (seq 1 5) | shuffle }} -``` - -### Example 2: `index` - -The following accesses the page parameter called "disqus_url" and escapes the HTML. This example also uses the [`index` function][index], which is built into Go templates: - -``` -{{ index .Params "disqus_url" | html }} -``` - -### Example 3: `or` with `isset` - -``` -{{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr") }} -Stuff Here -{{ end }} -``` - -Could be rewritten as - -``` -{{ if isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" }} -Stuff Here -{{ end }} -``` - -### Example 4: Internet Explorer Conditional Comments {#ie-conditional-comments} - -By default, Go Templates remove HTML comments from output. This has the unfortunate side effect of removing Internet Explorer conditional comments. As a workaround, use something like this: - -``` -{{ "" | safeHTML }} -``` - -Alternatively, you can use the backtick (`` ` ``) to quote the IE conditional comments, avoiding the tedious task of escaping every double quotes (`"`) inside, as demonstrated in the [examples](http://golang.org/pkg/text/template/#hdr-Examples) in the Go text/template documentation: - -``` -{{ `` | safeHTML }} -``` - -## Context (aka "the dot") - -The most easily overlooked concept to understand about Go templates is that `{{ . }}` always refers to the current context. In the top level of your template, this will be the data set made available to it. Inside of an iteration, however, it will have the value of the current item in the loop; i.e., `{{ . }}` will no longer refer to the data available to the entire page. If you need to access page-level data (e.g., page params set in front matter) from within the loop, you will likely want to do one of the following: - -### 1. Define a Variable Independent of Context - -The following shows how to define a variable independent of the context. - -{{< code file="tags-range-with-page-variable.html" >}} -{{ $title := .Site.Title }} -
      -{{ range .Params.tags }} -
    • - {{ . }} - - {{ $title }} -
      • -{{ end }} -
    -{{< /code >}} - -{{% note %}} -Notice how once we have entered the loop (i.e. `range`), the value of `{{ . }}` has changed. We have defined a variable outside of the loop (`{{$title}}`) that we've assigned a value so that we have access to the value from within the loop as well. -{{% /note %}} - -### 2. Use `$.` to Access the Global Context - -`$` has special significance in your templates. `$` is set to the starting value of `.` ("the dot") by default. This is a [documented feature of Go text/template][dotdoc]. This means you have access to the global context from anywhere. Here is an equivalent example of the preceding code block but now using `$` to grab `.Site.Title` from the global context: - -{{< code file="range-through-tags-w-global.html" >}} -
      -{{ range .Params.tags }} -
    • - {{ . }} - - {{ $.Site.Title }} -
      • -{{ end }} -
    -{{< /code >}} - -{{% warning "Don't Redefine the Dot" %}} -The built-in magic of `$` would cease to work if someone were to mischievously redefine the special character; e.g. `{{ $ := .Site }}`. *Don't do it.* You may, of course, recover from this mischief by using `{{ $ := . }}` in a global context to reset `$` to its default value. -{{% /warning %}} - -## Whitespace - -Go 1.6 includes the ability to trim the whitespace from either side of a Go tag by including a hyphen (`-`) and space immediately beside the corresponding `{{` or `}}` delimiter. - -For instance, the following Go template will include the newlines and horizontal tab in its HTML output: - -``` -
    - {{ .Title }} -
    -``` - -Which will output: - -``` -
    - Hello, World! -
    -``` - -Leveraging the `-` in the following example will remove the extra white space surrounding the `.Title` variable and remove the newline: - -``` -
    - {{- .Title -}} -
    -``` - -Which then outputs: - -``` -
    Hello, World!
    -``` - -Go considers the following characters whitespace: - -* space -* horizontal tab -* carriage return -* newline - -## Comments - -In order to keep your templates organized and share information throughout your team, you may want to add comments to your templates. There are two ways to do that with Hugo. - -### Go templates comments - -Go templates support `{{/*` and `*/}}` to open and close a comment block. Nothing within that block will be rendered. - -For example: - -``` -Bonsoir, {{/* {{ add 0 + 2 }} */}}Eliott. -``` - -Will render `Bonsoir, Eliott.`, and not care about the syntax error (`add 0 + 2`) in the comment block. - -### HTML comments - -If you need to produce HTML comments from your templates, take a look at the [Internet Explorer conditional comments](#ie-conditional-comments) example. If you need variables to construct such HTML comments, just pipe `printf` to `safeHTML`. For example: - -``` -{{ printf "" .Site.Title | safeHTML }} -``` - -#### HTML comments containing Go templates - -HTML comments are by default stripped, but their content is still evaluated. That means that although the HTML comment will never render any content to the final HTML pages, code contained within the comment may fail the build process. - -{{% note %}} -Do **not** try to comment out Go template code using HTML comments. -{{% /note %}} - -``` - -{{ $author }} -``` - -The templating engine will strip the content within the HTML comment, but will first evaluate any Go template code if present within. So the above example will render `Emma Goldman`, as the `$author` variable got evaluated in the HTML comment. But the build would have failed if that code in the HTML comment had an error. - -## Hugo Parameters - -Hugo provides the option of passing values to your template layer through your [site configuration][config] (i.e. for site-wide values) or through the metadata of each specific piece of content (i.e. the [front matter][]). You can define any values of any type and use them however you want in your templates, as long as the values are supported by the front matter format specified via `metaDataFormat` in your configuration file. - -## Use Content (`Page`) Parameters - -You can provide variables to be used by templates in individual content's [front matter][]. - -An example of this is used in the Hugo docs. Most of the pages benefit from having the table of contents provided, but sometimes the table of contents doesn't make a lot of sense. We've defined a `notoc` variable in our front matter that will prevent a table of contents from rendering when specifically set to `true`. - -Here is the example front matter: - -``` ---- -title: Roadmap -lastmod: 2017-03-05 -date: 2013-11-18 -notoc: true ---- -``` - -Here is an example of corresponding code that could be used inside a `toc.html` [partial template][partials]: - -{{< code file="layouts/partials/toc.html" download="toc.html" >}} -{{ if not .Params.notoc }} - - -{{end}} -{{< /code >}} - -We want the *default* behavior to be for pages to include a TOC unless otherwise specified. This template checks to make sure that the `notoc:` field in this page's front matter is not `true`. - -## Use Site Configuration Parameters - -You can arbitrarily define as many site-level parameters as you want in your [site's configuration file][config]. These parameters are globally available in your templates. - -For instance, you might declare the following: - -{{< code-toggle file="config" >}} -params: - copyrighthtml: "Copyright © 2017 John Doe. All Rights Reserved." - twitteruser: "spf13" - sidebarrecentlimit: 5 -{{< /code >}} - -Within a footer layout, you might then declare a `
    ` that is only rendered if the `copyrighthtml` parameter is provided. If it *is* provided, you will then need to declare the string is safe to use via the [`safeHTML` function][safehtml] so that the HTML entity is not escaped again. This would let you easily update just your top-level config file each January 1st, instead of hunting through your templates. - -``` -{{if .Site.Params.copyrighthtml}}
    -
    {{.Site.Params.CopyrightHTML | safeHTML}}
    -
    {{end}} -``` - -An alternative way of writing the "`if`" and then referencing the same value is to use [`with`][with] instead. `with` rebinds the context (`.`) within its scope and skips the block if the variable is absent: - -{{< code file="layouts/partials/twitter.html" >}} -{{with .Site.Params.twitteruser}} -
    - -
    -{{end}} -{{< /code >}} - -Finally, you can pull "magic constants" out of your layouts as well. The following uses the [`first`][first] function, as well as the [`.RelPermalink`][relpermalink] page variable and the [`.Site.Pages`][sitevars] site variable. - -``` - -``` - -## Example: Show Only Upcoming Events - -Go allows you to do more than what's shown here. Using Hugo's [`where` function][where] and Go built-ins, we can list only the items from `content/events/` whose date (set in a content file's [front matter][]) is in the future. The following is an example [partial template][partials]: - -{{< code file="layouts/partials/upcoming-events.html" download="upcoming-events.html" >}} -

    Upcoming Events

    -
      -{{ range where .Data.Pages.ByDate "Section" "events" }} - {{ if ge .Date.Unix .Now.Unix }} -
    • - - {{ .Type | title }} — - {{ .Title }} on - - {{ .Date.Format "2 January at 3:04pm" }} - at {{ .Params.place }} -
      • - {{ end }} -{{ end }} -
    -{{< /code >}} - - -[`where` function]: /functions/where/ -[config]: /getting-started/configuration/ -[dotdoc]: http://golang.org/pkg/text/template/#hdr-Variables -[first]: /functions/first/ -[front matter]: /content-management/front-matter/ -[functions]: /functions/ "See the full list of Hugo's templating functions with a quick start reference guide and basic and advanced examples." -[Go html/template]: http://golang.org/pkg/html/template/ "Godocs references for Golang's html templating" -[gohtmltemplate]: http://golang.org/pkg/html/template/ "Godocs references for Golang's html templating" -[index]: /functions/index/ -[math functions]: /functions/math/ -[partials]: /templates/partials/ "Link to the partial templates page inside of the templating section of the Hugo docs" -[internal_templates]: /templates/internal/ -[relpermalink]: /variables/page/ -[safehtml]: /functions/safehtml/ -[sitevars]: /variables/site/ -[variables]: /variables/ "See the full extent of page-, site-, and other variables that Hugo make available to you in your templates." -[where]: /functions/where/ -[with]: /functions/with/ -[godocsindex]: http://golang.org/pkg/text/template/ "Godocs page for index function" diff --git a/content/templates/lists.md b/content/templates/lists.md deleted file mode 100644 index a7462317..00000000 --- a/content/templates/lists.md +++ /dev/null @@ -1,591 +0,0 @@ ---- -title: Lists of Content in Hugo -linktitle: List Page Templates -description: Lists have a specific meaning and usage in Hugo when it comes to rendering your site homepage, section page, taxonomy list, or taxonomy terms list. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [lists,sections,rss,taxonomies,terms] -menu: - docs: - parent: "templates" - weight: 22 -weight: 22 -sections_weight: 22 -draft: false -aliases: [/templates/list/,/layout/indexes/] -toc: true ---- - -## What is a List Page Template? - -{{< youtube 8b2YTSMdMps >}} - -A list page template is a template used to render multiple pieces of content in a single HTML page. The exception to this rule is the homepage, which is still a list but has its own [dedicated template][homepage]. - -Hugo uses the term *list* in its truest sense; i.e. a sequential arrangement of material, especially in alphabetical or numerical order. Hugo uses list templates on any output HTML page where content is traditionally listed: - -* [Taxonomy terms pages][taxterms] -* [Taxonomy list pages][taxlists] -* [Section list pages][sectiontemps] -* [RSS][rss] - -For template lookup order, see [Template Lookup](/templates/lookup-order/). - -The idea of a list page comes from the [hierarchical mental model of the web][mentalmodel] and is best demonstrated visually: - -![Image demonstrating a hierarchical website sitemap.](/images/site-hierarchy.svg) - -## List Defaults - -### Default Templates - -Since section lists and taxonomy lists (N.B., *not* [taxonomy terms lists][taxterms]) are both *lists* with regards to their templates, both have the same terminating default of `_default/list.html` or `themes//layouts/_default/list.html` in their lookup order. In addition, both [section lists][sectiontemps] and [taxonomy lists][taxlists] have their own default list templates in `_default`: - -See [Template Lookup Order](/templates/lookup-order/) for the complete reference. - -## Add Content and Front Matter to List Pages - -Since v0.18, [everything in Hugo is a `Page`][bepsays]. This means list pages and the homepage can have associated content files (i.e. `_index.md`) that contain page metadata (i.e., front matter) and content. - -This new model allows you to include list-specific front matter via `.Params` and also means that list templates (e.g., `layouts/_default/list.html`) have access to all [page variables][pagevars]. - -{{% note %}} -It is important to note that all `_index.md` content files will render according to a *list* template and not according to a [single page template](/templates/single-page-templates/). -{{% /note %}} - -### Example Project Directory - -The following is an example of a typical Hugo project directory's content: - -``` -. -... -├── content -| ├── post -| | ├── _index.md -| | ├── post-01.md -| | └── post-02.md -| └── quote -| | ├── quote-01.md -| | └── quote-02.md -... -``` - -Using the above example, let's assume you have the following in `content/post/_index.md`: - -{{< code file="content/post/_index.md" >}} ---- -title: My Golang Journey -date: 2017-03-23 -publishdate: 2017-03-24 ---- - -I decided to start learning Golang in March 2017. - -Follow my journey through this new blog. -{{< /code >}} - -You can now access this `_index.md`'s' content in your list template: - -{{< code file="layouts/_default/list.html" download="list.html" >}} -{{ define "main" }} -
    -
    -
    -

    {{.Title}}

    -
    - - {{.Content}} -
    - -
    -{{ end }} -{{< /code >}} - -This above will output the following HTML: - -{{< code file="example.com/post/index.html" copy="false" >}} - -
    -
    -
    -

    My Golang Journey

    -
    -

    I decided to start learning Golang in March 2017.

    -

    Follow my journey through this new blog.

    -
    - -
    - -{{< /code >}} - -### List Pages Without `_index.md` - -You do *not* have to create an `_index.md` file for every list page (i.e. section, taxonomy, taxonomy terms, etc) or the homepage. If Hugo does not find an `_index.md` within the respective content section when rendering a list template, the page will be created but with no `{{.Content}}` and only the default values for `.Title` etc. - -Using this same `layouts/_default/list.html` template and applying it to the `quotes` section above will render the following output. Note that `quotes` does not have an `_index.md` file to pull from: - -{{< code file="example.com/quote/index.html" copy="false" >}} - -
    -
    -
    - -

    Quotes

    -
    -
    - -
    - -{{< /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/). -{{% /note %}} - -## Example List Templates - -### Section Template - -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" >}} -{{ partial "header.html" . }} -{{ partial "subheader.html" . }} -
    -
    -

    {{ .Title }}

    -
      - - {{ range .Data.Pages }} - {{ .Render "li"}} - {{ end }} -
    -
    -
    -{{ partial "footer.html" . }} -{{< /code >}} - -### Taxonomy Template - -{{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}} -{{ define "main" }} -
    -
    -

    {{ .Title }}

    - - {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
    -
    -{{ end }} -{{< /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: Weight > Date > LinkTitle > FilePath - -{{< code file="layouts/partials/default-order.html" >}} -
      - {{ range .Data.Pages }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By Weight - -{{< code file="layouts/partials/by-weight.html" >}} -
      - {{ range .Data.Pages.ByWeight }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By Date - -{{< code file="layouts/partials/by-date.html" >}} -
      - - {{ range .Data.Pages.ByDate }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By Publish Date - -{{< code file="layouts/partials/by-publish-date.html" >}} -
      - - {{ range .Data.Pages.ByPublishDate }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By Expiration Date - -{{< code file="layouts/partials/by-expiry-date.html" >}} -
      - {{ range .Data.Pages.ByExpiryDate }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By Last Modified Date - -{{< code file="layouts/partials/by-last-mod.html" >}} -
      - - {{ range .Data.Pages.ByLastmod }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By Length - -{{< code file="layouts/partials/by-length.html" >}} -
      - - {{ range .Data.Pages.ByLength }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By Title - -{{< code file="layouts/partials/by-title.html" >}} -
      - - {{ range .Data.Pages.ByTitle }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By Link Title - -{{< code file="layouts/partials/by-link-title.html" >}} -
      - - {{ range .Data.Pages.ByLinkTitle }} -
    • -

      {{ .LinkTitle }}

      - -
      • - {{ end }} -
    -{{< /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" >}} - -{{ range (.Data.Pages.ByParam "rating") }} - -{{ end }} -{{< /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" >}} -{{ range (.Data.Pages.ByParam "author.last_name") }} - -{{ end }} -{{< /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" >}} -
      - {{ range .Data.Pages.ByDate.Reverse }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -## Group Content - -Hugo provides some functions for grouping pages by Section, Type, Date, etc. - -### By Page Field - -{{< code file="layouts/partials/by-page-field.html" >}} - -{{ range .Data.Pages.GroupBy "Section" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /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" >}} - -{{ range .Data.Pages.GroupBy "Section" }} - -{{ with $.Site.GetPage "section" .Key }} -

    {{.Title}}

    -{{ else }} - -

    {{ .Key | title }}

    -{{ end }} -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### By Date - -{{< code file="layouts/partials/by-page-date.html" >}} - -{{ range .Data.Pages.GroupByDate "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### By Publish Date - -{{< code file="layouts/partials/by-page-publish-date.html" >}} - -{{ range .Data.Pages.GroupByPublishDate "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .PublishDate.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### By Page Parameter - -{{< code file="layouts/partials/by-page-param.html" >}} - -{{ range .Data.Pages.GroupByParam "param_key" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /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" >}} - -{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### Reverse Key Order - -Ordering of groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (i.e., with the newest first) for dates. - -While these are logical defaults, they are not always the desired order. There are two different syntaxes to change Hugo's default ordering for groups, both of which work the same way. - -#### 1. Adding the Reverse Method - -``` -{{ range (.Data.Pages.GroupBy "Section").Reverse }} -``` - -``` -{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }} -``` - -#### 2. Providing the Alternate Direction - -``` -{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} -``` - -``` -{{ range .Data.Pages.GroupBy "Section" "desc" }} -``` - -### Order Within Groups - -Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available. - -Here is the ordering for the example that follows: - -1. Content is grouped by month according to the `date` field in front matter. -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" >}} -{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} -

    {{ .Key }}

    -
      - {{ range .Pages.ByTitle }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -## Filter and Limiting Lists - -Sometimes you only want to list a subset of the available content. A common is to only display “Posts” on blog's homepage. You can accomplish this with the `where` function. - -### `where` - -`where` works in a similar manner to the [`where` keyword in SQL][wherekeyword]. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments: - -1. `array` *or* `slice of maps or structs` -2. `key` *or* `field name` -3. `match value` - -{{< code file="layouts/_default/.html" >}} -{{ range where .Data.Pages "Section" "post" }} - {{ .Content }} -{{ end }} -{{< /code >}} - -You can see more examples in the [functions documentation for `where`][wherefunction]. - -### `first` - -`first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input. `first` takes two arguments: - -1. `array` *or* `slice of maps or structs` -2. `number of elements` - -{{< code file="layout/_default/section.html" >}} -{{ range first 10 .Data.Pages }} - {{ .Render "summary" }} -{{ end }} -{{< /code >}} - -### `first` and `where` Together - -Using `first` and `where` together can be very powerful: - -{{< code file="first-and-where-together.html" >}} - -{{ range first 5 (where .Data.Pages "Section" "post").ByTitle }} - {{ .Content }} -{{ end }} -{{< /code >}} - -[base]: /templates/base/ -[bepsays]: http://bepsays.com/en/2016/12/19/hugo-018/ -[directorystructure]: /getting-started/directory-structure/ -[`Format` function]: /functions/format/ -[front matter]: /content-management/front-matter/ -[getpage]: /functions/getpage/ -[homepage]: /templates/homepage/ -[homepage]: /templates/homepage/ -[limitkeyword]: https://www.techonthenet.com/sql/select_limit.php -[mentalmodel]: http://webstyleguide.com/wsg3/3-information-architecture/3-site-structure.html -[pagevars]: /variables/page/ -[partials]: /templates/partials/ -[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification" -[rss]: /templates/rss/ -[sections]: /content-management/sections/ -[sectiontemps]: /templates/section-templates/ -[sitevars]: /variables/site/ -[taxlists]: /templates/taxonomy-templates/#taxonomy-list-templates/ -[taxterms]: /templates/taxonomy-templates/#taxonomy-terms-templates/ -[taxvars]: /variables/taxonomy/ -[views]: /templates/views/ -[wherefunction]: /functions/where/ -[wherekeyword]: https://www.techonthenet.com/sql/where.php diff --git a/content/templates/lookup-order.md b/content/templates/lookup-order.md deleted file mode 100644 index d197b614..00000000 --- a/content/templates/lookup-order.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Hugo's Lookup Order -linktitle: Template Lookup Order -description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific. -godocref: -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-05-25 -categories: [templates,fundamentals] -keywords: [templates] -menu: - docs: - parent: "templates" - weight: 15 - quicklinks: -weight: 15 -sections_weight: 15 -draft: false -aliases: [/templates/lookup/] -toc: true ---- - -## Hugo Layouts Lookup Rules - -Hugo takes the parameters listed below into consideration when choosing a layout for a given page. They are listed in a priority order. This should feel natural, but look at the table below for concrete examples of the different parameter variations. - - -Kind -: The page `Kind` (the home page is one). See the example tables below per kind. This also determines if it is a **single page** (i.e. a regular content page. We then look for a template in `_default/single.html` for HTML) or a **list page** (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in `_default/list.html` for HTML). - -Output Format -: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`, but look for less specific templates. - -Language -: We will consider a language code in the template name. If the site language is `fr`, `index.fr.amp.html` will win over `index.amp.html`, but we will `index.amp.html` will be chosen before `index.fr.html`. - -Layout -: Can be set in page front matter. - -Type -: Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). It will always have a value, so if not set, the value is "page". - -Section -: Is relevant for `section`, `taxonomy` and `taxonomyTerm` types. - -{{% note %}} -**Tip:** The examples below looks long and complex. That is the flexibility talking. Most Hugo sites contain just a handful of templates: - -```bash -├── _default -│   ├── baseof.html -│   ├── list.html -│   └── single.html -└── index.html -``` -{{% /note %}} - - -## Hugo Layouts Lookup Rules With Theme - -In Hugo, layouts can live in either the project's or theme's layout folder, and the most specific layout will be chosen. Hugo will interleave the lookups: - - -1. layouts/page/index.html -2. demoTheme/layouts/page/index.html -3. layouts/... - -This way it is possible to override specific templates from the theme. - -## Examples: Layout Lookup for Regular Pages - -{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -## Examples: Layout Lookup for Home Page - -{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -## Examples: Layout Lookup for Section Pages - -{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -## Examples: Layout Lookup for Taxonomy List Pages - -{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -## Examples: Layout Lookup for Taxonomy Terms Pages - -{{< datatable-filtered "output" "layouts" "Kind == taxonomyTerm" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - - - - diff --git a/content/templates/menu-templates.md b/content/templates/menu-templates.md deleted file mode 100644 index 5efb080d..00000000 --- a/content/templates/menu-templates.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -title: Menu Templates -linktitle: Menu Templates -description: Menus are a powerful but simple feature for content management but can be easily manipulated in your templates to meet your design needs. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [lists,sections,menus] -menu: - docs: - title: "how to use menus in templates" - parent: "templates" - weight: 130 -weight: 130 -sections_weight: 130 -draft: false -aliases: [/templates/menus/] -toc: false ---- - -Hugo makes no assumptions about how your rendered HTML will be -structured. Instead, it provides all of the functions you will need to be -able to build your menu however you want. - -The following is an example: - -{{< code file="layouts/partials/sidebar.html" download="sidebar.html" >}} - - -{{< /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. -{{% /note %}} - -## Section Menu for Lazy Bloggers - -To enable this menu, configure `sectionPagesMenu` in your site `config`: - -``` -sectionPagesMenu = "main" -``` - -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: - -``` - -``` - -In the above, the menu item is marked as active if on the current section's list page or on a page in that section. - - -## Site Config menus - -The above is all that's needed. But if you want custom menu items, e.g. changing weight, name, or link title attribute, you can define them manually in the site config file: - -{{< code-toggle file="config" >}} -[[menu.main]] - name = "This is the blog section" - title = "blog section" - weight = -110 - identifier = "blog" - url = "/blog/" -{{}} - -{{% note %}} -The `identifier` *must* match the section name. -{{% /note %}} - -## Menu Entries from the Page's front matter - -It's also possible to create menu entries from the page (i.e. the `.md`-file). - -Here is a `yaml` example: - -``` ---- -title: Menu Templates -linktitle: Menu Templates -menu: - docs: - title: "how to use menus in templates" - parent: "templates" - weight: 130 ---- -... -``` - -{{% note %}} -You can define more than one menu. It also doesn't have to be a complex value, -`menu` can also be a string, an array of strings, or an array of complex values -like in the example above. -{{% /note %}} - -### Using .Page in Menus - -If you use the front matter method of defining menu entries, you'll get access to the `.Page` variable. -This allows to use every variable that's reachable from the [page variable](/variables/page/). - -This variable is only set when the menu entry is defined in the page's front matter. -Menu entries from the site config don't know anything about `.Page`. - -That's why you have to use the go template's `with` keyword or something similar in your templating language. - -Here's an example: - -``` - -``` diff --git a/content/templates/ordering-and-grouping.md b/content/templates/ordering-and-grouping.md deleted file mode 100644 index 37a35587..00000000 --- a/content/templates/ordering-and-grouping.md +++ /dev/null @@ -1,379 +0,0 @@ ---- -title: Ordere and Grouping Hugo Lists -linktitle: List Ordering and Grouping -description: You can group or order your content in both your templating and content front matter. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [] -menu: - docs: - parent: "templates" - weight: 27 -weight: 27 -sections_weight: 27 -draft: true -aliases: [/templates/ordering/,/templates/grouping/] -toc: true -notes: This was originally going to be a separate page on the new docs site but it now makes more sense to keep everything within the templates/lists page. - rdwatters, 2017-03-12. ---- - -In Hugo, A list template is any template that will be used to render multiple pieces of content in a single HTML page. - -## Example List Templates - -### Section Template - -This list template is used for [spf13.com](http://spf13.com/). It makes use of [partial templates][partials]. All examples use a [view](/templates/views/) called either "li" or "summary." - -{{< code file="layouts/section/post.html" >}} -{{ partial "header.html" . }} -{{ partial "subheader.html" . }} - -
    -
    -

    {{ .Title }}

    -
      - {{ range .Data.Pages }} - {{ .Render "li"}} - {{ end }} -
    -
    -
    -{{ partial "footer.html" . }} -{{< /code >}} - -### Taxonomy Template - -{{< code file="layouts/_default/taxonomies.html" download="taxonomies.html" >}} -{{ define "main" }} -
    -
    -

    {{ .Title }}

    - {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
    -
    -{{ end }} -{{< /code >}} - -## Order Content - -Hugo lists render the content based on metadata provided in the [front matter](/content-management/front-matter/).. - -Here are a variety of different ways you can order the content items in -your list templates: - -### Default: Weight > Date - -{{< code file="layouts/partials/order-default.html" >}} -
      - {{ range .Data.Pages }} -
    • -

      {{ .Title }}

      - -
      • - {{ end }} -
    -{{< /code >}} - -### By Weight - -{{< code file="layouts/partials/by-weight.html" >}} -{{ range .Data.Pages.ByWeight }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • -{{ end }} -{{< /code >}} - -### By Date - -{{< code file="layouts/partials/by-date.html" >}} -{{ range .Data.Pages.ByDate }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • -{{ end }} -{{< /code >}} - -### By Publish Date - -{{< code file="layouts/partials/by-publish-date.html" >}} -{{ range .Data.Pages.ByPublishDate }} -
  • - {{ .Title }} -
    {{ .PublishDate.Format "Mon, Jan 2, 2006" }}
    -
    • -{{ end }} -{{< /code >}} - -### By Expiration Date - -{{< code file="layouts/partials/by-expiry-date.html" >}} -{{ range .Data.Pages.ByExpiryDate }} -
  • - {{ .Title }} -
    {{ .ExpiryDate.Format "Mon, Jan 2, 2006" }}
    -
    • -{{ end }} -{{< /code >}} - -### By Last Modified Date - -{{< code file="layouts/partials/by-last-mod.html" >}} -{{ range .Data.Pages.ByLastmod }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • -{{ end }} -{{< /code >}} - -### By Length - -{{< code file="layouts/partials/by-length.html" >}} -{{ range .Data.Pages.ByLength }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • -{{ end }} -{{< /code >}} - - -### By Title - -{{< code file="layouts/partials/by-title.html" >}} -{{ range .Data.Pages.ByTitle }} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • -{{ end }} -{{< /code >}} - -### By Link Title - -{{< code file="layouts/partials/by-link-title.html" >}} -{{ range .Data.Pages.ByLinkTitle }} -
  • - {{ .LinkTitle }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • -{{ end }} -{{< /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. - -The below example sorts a list of posts by their rating. - -{{< code file="layouts/partials/by-rating.html" >}} -{{ range (.Data.Pages.ByParam "rating") }} - -{{ end }} -{{< /code >}} - -If the front matter field of interest is nested beneath another field, you can -also get it: - -{{< code file="layouts/partials/by-nested-param.html" >}} -{{ range (.Data.Pages.ByParam "author.last_name") }} - -{{ end }} -{{< /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" >}} -{{ range .Data.Pages.ByDate.Reverse }} -
  • -{{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • -{{ end }} -{{< /code >}} - -## Group Content - -Hugo provides some functions for grouping pages by Section, Type, Date, etc. - -### By Page Field - -{{< code file="layouts/partials/by-page-field.html" >}} -{{ range .Data.Pages.GroupBy "Section" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### By Page date - -{{< code file="layouts/partials/by-page-date.html" >}} -{{ range .Data.Pages.GroupByDate "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### By Page publish date - -{{< code file="layouts/partials/by-page-publish-date.html" >}} -{{ range .Data.Pages.GroupByPublishDate "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .PublishDate.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### By Page Param - -{{< code file="layouts/partials/by-page-param.html" >}} -{{ range .Data.Pages.GroupByParam "param_key" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### By Page Param in Date Format - -{{< code file="layouts/partials/by-page-param-as-date.html" >}} -{{ range .Data.Pages.GroupByParamDate "param_key" "2006-01" }} -

    {{ .Key }}

    -
      - {{ range .Pages }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -### Reverse Key Order - -The ordering of the groups is performed by keys in alphanumeric order (A–Z, 1–100) and in reverse chronological order (newest first) for dates. - -While these are logical defaults, they are not always the desired order. There are two different syntaxes to change the order, both of which work the same way. You can use your preferred syntax. - -#### Reverse Method - -``` -{{ range (.Data.Pages.GroupBy "Section").Reverse }} -``` - -``` -{{ range (.Data.Pages.GroupByDate "2006-01").Reverse }} -``` - - -#### Provide the Alternate Direction - -``` -{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} -``` - -``` -{{ range .Data.Pages.GroupBy "Section" "desc" }} -``` - -### Order Within Groups - -Because Grouping returns a `{{.Key}}` and a slice of pages, all of the ordering methods listed above are available. - -In the following example, groups are ordered chronologically and then content -within each group is ordered alphabetically by title. - -{{< code file="layouts/partials/by-group-by-page.html" >}} -{{ range .Data.Pages.GroupByDate "2006-01" "asc" }} -

    {{ .Key }}

    -
      - {{ range .Pages.ByTitle }} -
    • - {{ .Title }} -
      {{ .Date.Format "Mon, Jan 2, 2006" }}
      -
      • - {{ end }} -
    -{{ end }} -{{< /code >}} - -## Filter and Limiting Lists - -Sometimes you only want to list a subset of the available content. A common request is to only display “Posts” on the homepage. You can accomplish this with the `where` function. - -### `where` - -`where` works in a similar manner to the `where` keyword in SQL. It selects all elements of the array or slice that match the provided field and value. `where` takes three arguments: - -1. `array` or a `slice of maps or structs` -2. `key` or `field name` -3. `match value` - -{{< code file="layouts/_default/.html" >}} -{{ range where .Data.Pages "Section" "post" }} - {{ .Content }} -{{ end }} -{{< /code >}} - -### `first` - -`first` works in a similar manner to the [`limit` keyword in SQL][limitkeyword]. It reduces the array to only the `first N` elements. It takes the array and number of elements as input. `first` takes two arguments: - -1. `array` or `slice of maps or structs` -2. `number of elements` - -{{< code file="layout/_default/section.html" >}} -{{ range first 10 .Data.Pages }} - {{ .Render "summary" }} -{{ end }} -{{< /code >}} - -### `first` and `where` Together - -Using `first` and `where` together can be very powerful: - -{{< code file="first-and-where-together.html" >}} -{{ range first 5 (where .Data.Pages "Section" "post") }} - {{ .Content }} -{{ end }} -{{< /code >}} - - -[views]: /templates/views/ diff --git a/content/templates/output-formats.md b/content/templates/output-formats.md deleted file mode 100644 index ff286c9d..00000000 --- a/content/templates/output-formats.md +++ /dev/null @@ -1,237 +0,0 @@ ---- -title: Custom Output Formats -linktitle: Custom Output Formats -description: Hugo can output content in multiple formats, including calendar events, e-book formats, Google AMP, and JSON search indexes, or any custom text format. -date: 2017-03-22 -publishdate: 2017-03-22 -lastmod: 2017-03-22 -categories: [templates] -keywords: ["amp","outputs","rss"] -menu: - docs: - parent: "templates" - weight: 18 -weight: 18 -sections_weight: 18 -draft: false -aliases: [/templates/outputs/,/extras/output-formats/,/content-management/custom-outputs/] -toc: true ---- - -This page describes how to properly configure your site with the media types and output formats, as well as where to create your templates for your custom outputs. - -## Media Types - -A [media type][] (also known as *MIME type* and *content type*) is a two-part identifier for file formats and format contents transmitted on the Internet. - -This is the full set of built-in media types in Hugo: - -{{< datatable "media" "types" "type" "suffix" >}} - -**Note:** - -* It is possible to add custom media types or change the defaults; e.g., if you want to change the suffix for `text/html` to `asp`. -* The `Suffix` is the value that will be used for URLs and filenames for that media type in Hugo. -* The `Type` is the identifier that must be used when defining new/custom `Output Formats` (see below). -* The full set of media types will be registered in Hugo's built-in development server to make sure they are recognized by the browser. - -To add or modify a media type, define it in a `mediaTypes` section in your [site configuration][config], either for all sites or for a given language. - -{{< code-toggle file="config" >}} -[mediaTypes] - [mediaTypes."text/enriched"] - suffix = "enr" - [mediaTypes."text/html"] - suffix = "asp" -{{}} - -The above example adds one new media type, `text/enriched`, and changes the suffix for the built-in `text/html` media type. - -**Note:** these media types are configured for **your output formats**. If you want to redefine one of Hugo's default output formats (e.g. `HTML`), you also need to redefine the output format. So, if you want to change the suffix of the `HTML` output format from `html` (default) to `htm`: - -```toml -[mediaTypes] -[mediaTypes."text/html"] -suffix = "htm" - -# Redefine HTML to update its media type. -[outputFormats] -[outputFormats.HTML] -mediaType = "text/html" -``` - -**Note** that for the above to work, you also need to add an `outputs` definition in your site config. - -## Output Format Definitions - -Given a media type and some additional configuration, you get an **Output Format**. - -This is the full set of Hugo's built-in output formats: - -{{< datatable "output" "formats" "name" "mediaType" "path" "baseName" "rel" "protocol" "isPlainText" "isHTML" "noUgly">}} - -* A page can be output in as many output formats as you want, and you can have an infinite amount of output formats defined **as long as they resolve to a unique path on the file system**. In the above table, the best example of this is `AMP` vs. `HTML`. `AMP` has the value `amp` for `Path` so it doesn't overwrite the `HTML` version; e.g. we can now have both `/index.html` and `/amp/index.html`. -* The `MediaType` must match the `Type` of an already defined media type. -* You can define new output formats or redefine built-in output formats; e.g., if you want to put `AMP` pages in a different path. - -To add or modify an output format, define it in an `outputFormats` section in your site's [configuration file](/getting-started/configuration/), either for all sites or for a given language. - -{{< code-toggle file="config" >}} -[outputFormats.MyEnrichedFormat] -mediaType = "text/enriched" -baseName = "myindex" -isPlainText = true -protocol = "bep://" -{{}} - -The above example is fictional, but if used for the homepage on a site with `baseURL` `https://example.org`, it will produce a plain text homepage with the URL `bep://example.org/myindex.enr`. - -### Configure Output Formats - -The following is the full list of configuration options for output formats and their default values: - -`name` -: the output format identifier. This is used to define what output format(s) you want for your pages. - -`mediaType` -: this must match the `Type` of a defined media type. - -`path` -: sub path to save the output files. - -`baseName` -: the base filename for the list filenames (homepage, etc.). **Default:** `index`. - -`rel` -: can be used to create `rel` values in `link` tags. **Default:** `alternate`. - -`protocol` -: will replace the "http://" or "https://" in your `baseURL` for this output format. - -`isPlainText` -: use Go's plain text templates parser for the templates. **Default:** `false`. - -`isHTML` -: used in situations only relevant for `HTML`-type formats; e.g., page aliases. - -`noUgly` -: used to turn off ugly URLs If `uglyURLs` is set to `true` in your site. **Default:** `false`. - -`notAlternative` -: enable if it doesn't make sense to include this format in an `AlternativeOutputFormats` format listing on `Page` (e.g., with `CSS`). Note that we use the term *alternative* and not *alternate* here, as it does not necessarily replace the other format. **Default:** `false`. - -## Output Formats for Pages - -A `Page` in Hugo can be rendered to multiple *output formats* on the file -system. - -### Default Output Formats -Every `Page` has a [`Kind`][page_kinds] attribute, and the default Output -Formats are set based on that. - -| Kind | Default Output Formats | -|--------------- |----------------------- | -| `page` | HTML | -| `home` | HTML, RSS | -| `section` | HTML, RSS | -| `taxonomyTerm` | HTML, RSS | -| `taxonomy` | HTML, RSS | - -### Customizing Output Formats - -This can be changed by defining an `outputs` list of output formats in either -the `Page` front matter or in the site configuration (either for all sites or -per language). - -Example from site config file`: - -{{< code-toggle file="config" >}} -[outputs] - home = ["HTML", "AMP", "RSS"] - page = ["HTML"] -{{}} - - -Note that in the above examples, the *output formats* for `section`, -`taxonomyTerm` and `taxonomy` will stay at their default value `["HTML", -"RSS"]`. - -* The `outputs` definition is per [`Page` `Kind`][page_kinds] (`page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`). -* The names (e.g. `HTML`, `AMP`) used must match the `Name` of a defined *Output Format*. - * These names are case insensitive. -* These can be overridden per `Page` in the front matter of content files. - -The following is an example of `YAML` front matter in a content file that defines output formats for the rendered `Page`: - -```yaml ---- -date: "2016-03-19" -outputs: -- html -- amp -- json ---- -``` - -## Link to Output Formats - -Each `Page` has both an `.OutputFormats` (all formats, including the current) and an `.AlternativeOutputFormats` variable, the latter of which is useful for creating a `link rel` list in your site's ``: - -```go-html-template -{{ range .AlternativeOutputFormats -}} - -{{ end -}} -``` - -Note that `.Permalink` and `.RelPermalink` on `Page` will return the first output format defined for that page (usually `HTML` if nothing else is defined). - -This is how you link to a given output format: - -```go-html-template -{{ with .OutputFormats.Get "json" -}} -{{ .Name }} -{{- end }} -``` - -From content files, you can use the [`ref` or `relref` shortcodes](/content-management/shortcodes/#ref-and-relref): - -```go-html-template -[Neat]({{}}) -[Who]({{}}) -``` - -## Templates for Your Output Formats - -A new output format needs a corresponding template in order to render anything useful. - -{{% note %}} -The key distinction for Hugo versions 0.20 and newer is that Hugo looks at an output format's `Name` and MediaType's `Suffix` when choosing the template used to render a given `Page`. -{{% /note %}} - -The following table shows examples of different output formats, the suffix used, and Hugo's respective template [lookup order][]. All of the examples in the table can: - -* Use a [base template][base]. -* Include [partial templates][partials] - -{{< datatable "output" "layouts" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -Hugo will now also detect the media type and output format of partials, if possible, and use that information to decide if the partial should be parsed as a plain text template or not. - -Hugo will look for the name given, so you can name it whatever you want. But if you want it treated as plain text, you should use the file suffix and, if needed, the name of the Output Format. The pattern is as follows: - -``` -[partial name].[OutputFormat].[suffix] -``` - -The partial below is a plain text template (Outpuf Format is `CSV`, and since this is the only output format with the suffix `csv`, we don't need to include the Output Format's `Name`): - -``` -{{ partial "mytextpartial.csv" . }} -``` - -[base]: /templates/base/ -[config]: /getting-started/configuration/ -[lookup order]: /templates/lookup/ -[media type]: https://en.wikipedia.org/wiki/Media_type -[partials]: /templates/partials/ -[page_kinds]: /templates/section-templates/#page-kinds diff --git a/content/templates/pagination.md b/content/templates/pagination.md deleted file mode 100644 index 22acb307..00000000 --- a/content/templates/pagination.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -title: Pagination -linktitle: Pagination -description: Hugo supports pagination for your homepage, section pages, and taxonomies. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [lists,sections,pagination] -menu: - docs: - parent: "templates" - weight: 140 -weight: 140 -sections_weight: 140 -draft: false -aliases: [/extras/pagination,/doc/pagination/] -toc: true ---- - -The real power of Hugo pagination shines when combined with the [`where` function][where] and its SQL-like operators: [`first`][], [`last`][], and [`after`][]. You can even [order the content][lists] the way you've become used to with Hugo. - -## Configure Pagination - -Pagination can be configured in your [site configuration][configuration]: - -`Paginate` -: default = `10`. This setting can be overridden within the template. - -`PaginatePath` -: default = `page`. Allows you to set a different path for your pagination pages. - -Setting `Paginate` to a positive value will split the list pages for the homepage, sections and taxonomies into chunks of that size. But note that the generation of the pagination pages for sections, taxonomies and homepage is *lazy* --- the pages will not be created if not referenced by a `.Paginator` (see below). - -`PaginatePath` is used to adapt the `URL` to the pages in the paginator (the default setting will produce URLs on the form `/page/1/`. - -## List Paginator Pages - -{{% warning %}} -`.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`: - -1. The simplest way is just to call `.Paginator.Pages` from a template. It will contain the pages for *that page*. -2. Select a subset of the pages with the available template functions and ordering options, and pass the slice to `.Paginate`, e.g. `{{ range (.Paginate ( first 50 .Data.Pages.ByTitle )).Pages }}`. - -For a given **Page**, it's one of the options above. The `.Paginator` is static and cannot change once created. - -The global page size setting (`Paginate`) can be overridden by providing a positive integer as the last argument. The examples below will give five items per page: - -* `{{ range (.Paginator 5).Pages }}` -* `{{ $paginator := .Paginate (where .Data.Pages "Type" "post") 5 }}` - -It is also possible to use the `GroupBy` functions in combination with pagination: - -``` -{{ range (.Paginate (.Data.Pages.GroupByDate "2006")).PageGroups }} -``` - -## Build the navigation - -The `.Paginator` contains enough information to build a paginator interface. - -The easiest way to add this to your pages is to include the built-in template (with `Bootstrap`-compatible styles): - -``` -{{ template "_internal/pagination.html" . }} -``` - -{{% note "When to Create `.Paginator`" %}} -If you use any filters or ordering functions to create your `.Paginator` *and* you want the navigation buttons to be shown before the page listing, you must create the `.Paginator` before it's used. -{{% /note %}} - -The following example shows how to create `.Paginator` before its used: - -``` -{{ $paginator := .Paginate (where .Data.Pages "Type" "post") }} -{{ template "_internal/pagination.html" . }} -{{ range $paginator.Pages }} - {{ .Title }} -{{ end }} -``` - -Without the `where` filter, the above example is even simpler: - -``` -{{ template "_internal/pagination.html" . }} -{{ range .Paginator.Pages }} - {{ .Title }} -{{ end }} -``` - -If you want to build custom navigation, you can do so using the `.Paginator` object, which includes the following properties: - -`PageNumber` -: The current page's number in the pager sequence - -`URL` -: The relative URL to the current pager - -`Pages` -: The pages in the current pager - -`NumberOfElements` -: The number of elements on this page - -`HasPrev` -: Whether there are page(s) before the current - -`Prev` -: The pager for the previous page - -`HasNext` -: Whether there are page(s) after the current - -`Next` -: The pager for the next page - -`First` -: The pager for the first page - -`Last` -: The pager for the last page - -`Pagers` -: A list of pagers that can be used to build a pagination menu - -`PageSize` -: Size of each pager - -`TotalPages` -: The number of pages in the paginator - -`TotalNumberOfElements` -: The number of elements on all pages in this paginator - -## Additional information - -The pages are built on the following form (`BLANK` means no value): - -``` -[SECTION/TAXONOMY/BLANK]/index.html -[SECTION/TAXONOMY/BLANK]/page/1/index.html => redirect to [SECTION/TAXONOMY/BLANK]/index.html -[SECTION/TAXONOMY/BLANK]/page/2/index.html -.... -``` - - -[`first`]: /functions/first/ -[`last`]: /functions/last/ -[`after`]: /functions/after/ -[configuration]: /getting-started/configuration/ -[lists]: /templates/lists/ -[where]: /functions/where/ diff --git a/content/templates/partials.md b/content/templates/partials.md deleted file mode 100644 index 4cb7fb3a..00000000 --- a/content/templates/partials.md +++ /dev/null @@ -1,165 +0,0 @@ ---- -title: Partial Templates -linktitle: Partial Templates -description: Partials are smaller, context-aware components in your list and page templates that can be used economically to keep your templating DRY. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [lists,sections,partials] -menu: - docs: - parent: "templates" - weight: 90 -weight: 90 -sections_weight: 90 -draft: false -aliases: [/templates/partial/,/layout/chrome/,/extras/analytics/] -toc: true ---- - -{{< youtube pjS4pOLyB7c >}} - -## Partial Template Lookup Order - -Partial templates---like [single page templates][singletemps] and [list page templates][listtemps]---have a specific [lookup order][]. However, partials are simpler in that Hugo will only check in two places: - -1. `layouts/partials/*.html` -2. `themes//layouts/partials/*.html` - -This allows a theme's end user to copy a partial's contents into a file of the same name for [further customization][customize]. - -## Use Partials in your Templates - -All partials for your Hugo project are located in a single `layouts/partials` directory. For better organization, you can create multiple subdirectories within `partials` as well: - -``` -. -└── layouts - └── partials - ├── footer - │   ├── scripts.html - │   └── site-footer.html - ├── head - │   ├── favicons.html - │   ├── metadata.html - │   ├── prerender.html - │   └── twitter.html - └── header - ├── site-header.html - └── site-nav.html -``` - -All partials are called within your templates using the following pattern: - -``` -{{ partial "/.html" . }} -``` - -{{% note %}} -One of the most common mistakes with new Hugo users is failing to pass a context to the partial call. In the pattern above, note how "the dot" (`.`) is required as the second argument to give the partial context. You can read more about "the dot" in the [Hugo templating introduction](/templates/introduction/). -{{% /note %}} - -As shown in the above example directory structure, you can nest your directories within `partials` for better source organization. You only need to call the nested partial's path relative to the `partials` directory: - -``` -{{ partial "header/site-header.html" . }} -{{ partial "footer/scripts.html" . }} -``` - -### Variable Scoping - -The second argument in a partial call is the variable being passed down. The above examples are passing the `.`, which tells the template receiving the partial to apply the current [context][context]. - -This means the partial will *only* be able to access those variables. The partial is isolated and *has no access to the outer scope*. From within the partial, `$.Var` is equivalent to `.Var`. - -### Cached Partials - -The [`partialCached` template function][partialcached] can offer significant performance gains for complex templates that don't need to be re-rendered on every invocation. The simplest usage is as follows: - -``` -{{ partialCached "footer.html" . }} -``` - -You can also pass additional parameters to `partialCached` to create *variants* of the cached partial. - -For example, you can tell Hugo to only render the partial `footer.html` once per section: - -``` -{{ partialCached "footer.html" . .Section }} -``` - -If you need to pass additional parameters to create unique variants, you can pass as many variant parameters as you need: - -``` -{{ partialCached "footer.html" . .Params.country .Params.province }} -``` - -Note that the variant parameters are not made available to the underlying partial template. They are only use to create a unique cache key. - -### Example `header.html` - -The following `header.html` partial template is used for [spf13.com](http://spf13.com/): - -{{< code file="layouts/partials/header.html" download="header.html" >}} - - - - - - {{ partial "meta.html" . }} - - - {{ .Title }} : spf13.com - - {{ if .RSSLink }}{{ end }} - - {{ partial "head_includes.html" . }} - - -{{< /code >}} - -{{% note %}} -The `header.html` example partial was built before the introduction of block templates to Hugo. Read more on [base templates and blocks](/templates/base/) for defining the outer chrome or shell of your master templates (i.e., your site's head, header, and footer). You can even combine blocks and partials for added flexibility. -{{% /note %}} - -### Example `footer.html` - -The following `footer.html` partial template is used for [spf13.com](http://spf13.com/): - -{{< code file="layouts/partials/footer.html" download="footer.html" >}} - - - - -{{< /code >}} - -[context]: /templates/introduction/ "The most easily overlooked concept to understand about Go templating is how the dot always refers to the current context." -[customize]: /themes/customizing/ "Hugo provides easy means to customize themes as long as users are familiar with Hugo's template lookup order." -[listtemps]: /templates/lists/ "To effectively leverage Hugo's system, see how Hugo handles list pages, where content for sections, taxonomies, and the homepage are listed and ordered." -[lookup order]: /templates/lookup-order/ "To keep your templating dry, read the documentation on Hugo's lookup order." -[partialcached]: /functions/partialcached/ "Use the partial cached function to improve build times in cases where Hugo can cache partials that don't need to be rendered with every page." -[singletemps]: /templates/single-page-templates/ "The most common form of template in Hugo is the single content template. Read the docs on how to create templates for individual pages." -[themes]: /themes/ diff --git a/content/templates/robots.md b/content/templates/robots.md deleted file mode 100644 index 5237fec0..00000000 --- a/content/templates/robots.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Robots.txt File -linktitle: Robots.txt -description: Hugo can generate a customized robots.txt in the same way as any other template. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [robots,search engines] -menu: - docs: - parent: "templates" - weight: 165 -weight: 165 -sections_weight: 165 -draft: false -aliases: [/extras/robots-txt/] -toc: false ---- - -To create your robots.txt as a template, first set the `enableRobotsTXT` value to `true` in your [configuration file][config]. By default, this option generates a robots.txt with the following content, which tells search engines that they are allowed to crawl everything: - -``` -User-agent: * -``` - -## Robots.txt Template Lookup Order - -The [lookup order][lookup] for the `robots.txt` template is as follows: - -* `/layouts/robots.txt` -* `/themes//layouts/robots.txt` - -{{% note %}} -If you do not want Hugo to create a default `robots.txt` or leverage the `robots.txt` template, you can hand code your own and place the file in `static`. Remember that everything in the [static directory](/getting-started/directory-structure/) is copied over as-is when Hugo builds your site. -{{% /note %}} - -## Robots.txt Template Example - -The following is an example `robots.txt` layout: - -{{< code file="layouts/robots.txt" download="robots.txt" >}} -User-agent: * - -{{range .Data.Pages}} -Disallow: {{.RelPermalink}} -{{end}} -{{< /code >}} - -This template disallows all the pages of the site by creating one `Disallow` entry for each page. - -[config]: /getting-started/configuration/ -[lookup]: /templates/lookup-order/ -[robots]: http://www.robotstxt.org/ diff --git a/content/templates/rss.md b/content/templates/rss.md deleted file mode 100644 index 9acbeea4..00000000 --- a/content/templates/rss.md +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: RSS Templates -linktitle: RSS Templates -description: Hugo ships with its own RSS 2.0 template that requires almost no configuration, or you can create your own RSS templates. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -keywords: [rss, xml, templates] -categories: [templates] -menu: - docs: - parent: "templates" - weight: 150 -weight: 150 -sections_weight: 150 -draft: false -aliases: [/templates/rss/] -toc: true ---- - -## RSS Template Lookup Order - -See [Template Lookup Order](/templates/lookup-order/) for the complete reference. - -{{% note "Hugo Ships with an RSS Template" %}} -Hugo ships with its own [RSS 2.0 template](#the-embedded-rss-xml). The embedded template will be sufficient for most use cases. -{{% /note %}} - -RSS pages are of the type `Page` and have all the [page variables](/variables/page/) available to use in the templates. - -### Section RSS - -A [section’s][section] RSS will be rendered at `/
    /index.xml` (e.g., http://spf13.com/project/index.xml). - -Hugo provides the ability for you to define any RSS type you wish and can have different RSS files for each section and taxonomy. - -## Lookup Order for RSS Templates - -The table below shows the RSS template lookup order for the different page kinds. The first listing shows the lookup order when running with a theme (`demoTheme`). - -{{< datatable-filtered "output" "layouts" "OutputFormat == RSS" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} - -## Configure RSS - -By default, Hugo will create an unlimited number of RSS entries. You can limit the number of articles included in the built-in RSS templates by assigning a numeric value to `rssLimit:` field in your project's [`config` file][config]. - -The following values will also be included in the RSS output if specified in your site’s configuration: - -```toml -languageCode = "en-us" -copyright = "This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License." - -[author] - name = "My Name Here" -``` - -## The Embedded rss.xml - -This is the default RSS template that ships with Hugo. It adheres to the [RSS 2.0 Specification][RSS 2.0]. - -```xml - - - {{ if eq .Title .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }} - {{ .Permalink }} - Recent content {{ if ne .Title .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }} - Hugo -- gohugo.io{{ with .Site.LanguageCode }} - {{.}}{{end}}{{ with .Site.Author.email }} - {{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}}{{ with .Site.Author.email }} - {{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}}{{ with .Site.Copyright }} - {{.}}{{end}}{{ if not .Date.IsZero }} - {{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}{{ end }} - {{ with .OutputFormats.Get "RSS" }} - {{ printf "" .Permalink .MediaType | safeHTML }} - {{ end }} - {{ range .Data.Pages }} - - {{ .Title }} - {{ .Permalink }} - {{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }} - {{ with .Site.Author.email }}{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}{{end}} - {{ .Permalink }} - {{ .Summary | html }} - - {{ end }} - - -``` - -{{% warning "XML Header" %}} -Hugo will automatically add the following header line to this file on render. Please do *not* include this in the template as it's not valid HTML. -``` - -``` -{{% /warning %}} - -## Reference your RSS Feed in `` - -In your `header.html` template, you can specify your RSS feed in your `` tag using Hugo's [Output Formats][Output Formats] like this: - -``` -{{ range .AlternativeOutputFormats -}} - -{{ end -}} -``` - -If you only want the RSS link, you can query the formats: - -``` -{{ with .OutputFormats.Get "rss" -}} - -{{ end -} -``` - -[config]: /getting-started/configuration/ -[embedded]: #the-embedded-rss-xml -[RSS 2.0]: http://cyber.law.harvard.edu/rss/rss.html "RSS 2.0 Specification" -[section]: /content-management/sections/ -[Output Formats]: /templates/output-formats/#link-to-output-formats \ No newline at end of file diff --git a/content/templates/section-templates.md b/content/templates/section-templates.md deleted file mode 100644 index 577529e3..00000000 --- a/content/templates/section-templates.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Section Page Templates -linktitle: Section Templates -description: Templates used for section pages are **lists** and therefore have all the variables and methods available to list pages. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [lists,sections,templates] -menu: - docs: - parent: "templates" - weight: 40 -weight: 40 -sections_weight: 40 -draft: false -aliases: [/templates/sections/] -toc: true ---- - -## Add Content and Front Matter to Section Templates - -To effectively leverage section page templates, you should first understand Hugo's [content organization](/content-management/organization/) and, specifically, the purpose of `_index.md` for adding content and front matter to section and other list pages. - -## Section Template Lookup Order - -See [Template Lookup](/templates/lookup-order/). - -## Page Kinds - -Every `Page` in Hugo has a `.Kind` attribute. - -| Kind | Description | Example | -|----------------|--------------------------------------------------------------------|-------------------------------------------------------------------------------| -| `home` | The home page | `/index.html` | -| `page` | A page showing a _regular page_ | `my-post` page (`/posts/my-post/index.html`) | -| `section` | A page listing _regular pages_ from a given [_section_][sections] | `posts` section (`/posts/index.html`) | -| `taxonomy` | A page listing _regular pages_ from a given _taxonomy term_ | page for the term `awesome` from `tags` taxonomy (`/tags/awesome/index.html`) | -| `taxonomyTerm` | A page listing terms from a given _taxonomy_ | page for the `tags` taxonomy (`/tags/index.html`) | - -## `.Site.GetPage` with Sections - -`Kind` can easily be combined with the [`where` function][where] in your templates to create kind-specific lists of content. This method is ideal for creating lists, but there are times where you may want to fetch just the index page of a single section via the section's path. - -The [`.GetPage` function][getpage] looks up an index page of a given `Kind` and `path`. - -You can call `.Site.GetPage` with two arguments: `kind` (one of the valid values -of `Kind` from above) and `kind value`. - -Examples: - -- `{{ .Site.GetPage "section" "posts" }}` -- `{{ .Site.GetPage "page" "search" }}` - -## Example: Creating a Default Section Template - -{{< code file="layouts/_default/section.html" download="section.html" >}} -{{ define "main" }} -
    - {{ .Content }} -
      - {{ range .Paginator.Pages }} -
    • {{.Title}} -
      - {{ partial "summary.html" . }} -
      -
      • - {{ end }} -
    - {{ partial "pagination.html" . }} -
    -{{ end }} -{{< /code >}} - -### Example: Using `.Site.GetPage` - -The `.Site.GetPage` example that follows assumes the following project directory structure: - -``` -. -└── content - ├── blog - │   ├── _index.md # "title: My Hugo Blog" in the front matter - │   ├── post-1.md - │   ├── post-2.md - │   └── post-3.md - └── events #Note there is no _index.md file in "events" - ├── event-1.md - └── event-2.md -``` - -`.Site.GetPage` will return `nil` if no `_index.md` page is found. Therefore, if `content/blog/_index.md` does not exist, the template will output the section name: - -``` -

    {{ with .Site.GetPage "section" "blog" }}{{ .Title }}{{ end }}

    -``` - -Since `blog` has a section index page with front matter at `content/blog/_index.md`, the above code will return the following result: - -``` -

    My Hugo Blog

    -``` - -If we try the same code with the `events` section, however, Hugo will default to the section title because there is no `content/events/_index.md` from which to pull content and front matter: - -``` -

    {{ with .Site.GetPage "section" "events" }}{{ .Title }}{{ end }}

    -``` - -Which then returns the following: - -``` -

    Events

    -``` - - -[contentorg]: /content-management/organization/ -[getpage]: /functions/getpage/ -[lists]: /templates/lists/ -[lookup]: /templates/lookup-order/ -[where]: /functions/where/ -[sections]: /content-management/sections/ diff --git a/content/templates/shortcode-templates.md b/content/templates/shortcode-templates.md deleted file mode 100644 index 67e54089..00000000 --- a/content/templates/shortcode-templates.md +++ /dev/null @@ -1,354 +0,0 @@ ---- -title: Create Your Own Shortcodes -linktitle: Shortcode Templates -description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [shortcodes,templates] -menu: - docs: - parent: "templates" - weight: 100 -weight: 100 -sections_weight: 100 -draft: false -aliases: [] -toc: true ---- - -Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside of your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files][]. - -{{% note %}} -Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).) -{{% /note %}} - -## Create Custom Shortcodes - -Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs. - -{{< youtube Eu4zSaKOY4A >}} - -### File Placement - -To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose. - -### Shortcode Template Lookup Order - -Shortcode templates have a simple [lookup order][]: - -1. `/layouts/shortcodes/.html` -2. `/themes//layouts/shortcodes/.html` - -### Positional vs Named Parameters - -You can create shortcodes using the following types of parameters: - -* Positional parameters -* Named parameters -* Positional *or* named parameters (i.e, "flexible") - -In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors. - -For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order. - -Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users. - -### Access Parameters - -All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively. - -To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string: - -``` -{{ .Get "class" }} -``` - -To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed: - -``` -{{ .Get 0 }} -``` - -`with` is great when the output depends on a parameter being set: - -``` -{{ with .Get "class"}} class="{{.}}"{{ end }} -``` - -`.Get` can also be used to check if a parameter has been provided. This is -most helpful when the condition depends on either of the values, or both: - -``` -{{ or .Get "title" | .Get "alt" | if }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }} -``` - -#### `.Inner` - -If a closing shortcode is used, the `.Inner` variable will be populated with all of the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of `.Inner` as an indicator of its existence. - -A shortcode with content declared via the `.Inner` variable can also be declared without the inline content and without the closing shortcode by using the self-closing syntax: - -``` -{{}} -``` - -#### `.Params` - -The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic: - -`$.Params` -: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID) - -`$.Page.Params` -: refers to the page's params; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`). - -`$.Page.Site.Params` -: refers to global variables as defined in your [site's configuration file][config]. - -#### `.IsNamedParams` - -The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value. - -For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows: - -``` -{{}} -``` - -You could then include the following as part of your shortcode templating: - -``` -{{ if .IsNamedParams }} - -{{ else }} - -{{ end }} -``` - -See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action. - -{{% warning %}} -While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{}}` will return an error. -{{% /warning %}} - -You can also use the variable `.Page` to access all the normal [page variables][pagevars]. - -A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root. - -### Checking for Existence - -You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode. - -## Custom Shortcode Examples - -The following are examples of the different types of shortcodes you can create via shortcode template files in `/layouts/shortcodes`. - -### Single-word Example: `year` - -Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your markdown. Your goal is to be able to call the shortcode as follows: - -``` -{{}} -``` - -{{< code file="/layouts/shortcodes/year.html" >}} -{{ now.Format "2006" }} -{{< /code >}} - -### Single Positional Example: `youtube` - -Embedded videos are a common addition to markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]: - -``` -{{}} -``` - -Would load the template at `/layouts/shortcodes/youtube.html`: - -{{< code file="/layouts/shortcodes/youtube.html" >}} -
    - -
    -{{< /code >}} - -{{< code file="youtube-embed.html" copy="false" >}} -
    - -
    -{{< /code >}} - -### Single Named Example: `image` - -Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files: - -{{< code file="content-image.md" >}} -{{}} -{{< /code >}} - -You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template: - -{{< code file="/layouts/shortcodes/img.html" >}} - -
    - {{ with .Get "link"}}{{ end }} - - {{ if .Get "link"}}{{ end }} - {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}} -
    {{ if isset .Params "title" }} -

    {{ .Get "title" }}

    {{ end }} - {{ if or (.Get "caption") (.Get "attr")}}

    - {{ .Get "caption" }} - {{ with .Get "attrlink"}} {{ end }} - {{ .Get "attr" }} - {{ if .Get "attrlink"}} {{ end }} -

    {{ end }} -
    - {{ end }} -
    - -{{< /code >}} - -Would be rendered as: - -{{< code file="img-output.html" copy="false" >}} -
    - -
    -

    Steve Francia

    -
    -
    -{{< /code >}} - -### Single Flexible Example: `vimeo` - -``` -{{}} -{{}} -``` - -Would load the template found at `/layouts/shortcodes/vimeo.html`: - -{{< code file="/layouts/shortcodes/vimeo.html" >}} -{{ if .IsNamedParams }} -
    - -
    -{{ else }} -
    - -
    -{{ end }} -{{< /code >}} - -Would be rendered as: - -{{< code file="vimeo-iframes.html" copy="false" >}} -
    - -
    -
    - -
    -{{< /code >}} - -### Paired Example: `highlight` - -The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo. - -{{< code file="highlight-example.md" >}} -{{}} - - This HTML - -{{}} -{{< /code >}} - -The template for the `highlight` shortcode uses the following code, which is already included in Hugo: - -``` -{{ .Get 0 | highlight .Inner }} -``` - -The rendered output of the HTML example code block will be as follows: - -{{< code file="syntax-highlighted.html" copy="false" >}} -
    <html>
-    <body> This HTML </body>
-</html>
-
    -{{< /code >}} - -{{% note %}} -The preceding shortcode makes use of a Hugo-specific template function called `highlight`, which uses [Pygments](http://pygments.org) to add syntax highlighting to the example HTML code block. See the [developer tools page on syntax highlighting](/tools/syntax-highlighting/) for more information. -{{% /note %}} - -### Nested Shortcode: Image Gallery - -Hugo's [`.Parent` shortcode variable][parent] returns a boolean value depending on whether the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters. - -The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter: - -{{< code file="layouts/shortcodes/gallery.html" >}} -
    - {{.Inner}} -
    -{{< /code >}} - -You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`: - -{{< code file="layouts/shortcodes/img.html" >}} -{{- $src := .Get "src" -}} -{{- with .Parent -}} - -{{- else -}} - -{{- end }} -{{< /code >}} - -You can then call your shortcode in your content as follows: - -``` -{{}} - {{}} - {{}} -{{}} -{{}} -``` - -This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`: - -``` -
    - - -
    - -``` - -## More Shortcode Examples - -More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes]. - -[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website." -[built-in shortcode]: /content-management/shortcodes/ -[config]: /getting-started/configuration/ "Learn more about Hugo's built-in configuration variables as well as how to us your site's configuration file to include global key-values that can be used throughout your rendered website." -[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes "Check this section if you are not familiar with the definition of what a shortcode is or if you are unfamiliar with how to use Hugo's built-in shortcodes in your content files." -[source organization]: /getting-started/directory-structure/#directory-structure-explained "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories." -[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading." -[figure]: /content-management/shortcodes/#figure -[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes -[lookup order]: /templates/lookup-order/ "See the order in which Hugo traverses your template files to decide where and how to render your content at build time" -[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates." -[parent]: /variables/shortcodes/ -[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template." -[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia." -[templates]: /templates/ "The templates section of the Hugo docs." -[vimeoexample]: #single-flexible-example-vimeo -[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode." diff --git a/content/templates/single-page-templates.md b/content/templates/single-page-templates.md deleted file mode 100644 index 79e1312b..00000000 --- a/content/templates/single-page-templates.md +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: Single Page Templates -linktitle: -description: The primary view of content in Hugo is the single view. Hugo will render every Markdown file provided with a corresponding single template. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-04-06 -categories: [templates] -keywords: [page,templates] -menu: - docs: - parent: "templates" - weight: 60 -weight: 60 -sections_weight: 60 -draft: false -aliases: [/layout/content/] -toc: true ---- - -## Single Page Template Lookup Order - -See [Template Lookup](/templates/lookup-order/). - -## Example Single Page Templates - -Content pages are of the type `page` and will therefore have all the [page variables][pagevars] and [site variables][] available to use in their templates. - -### `post/single.html` - -This single page template makes use of Hugo [base templates][], the [`.Format` function][] for dates, the [`.WordCount` page variable][pagevars], and ranges through the single content's specific [taxonomies][pagetaxonomy]. [`with`][] is also used to check whether the taxonomies are set in the front matter. - -{{< code file="layouts/post/single.html" download="single.html" >}} -{{ define "main" }} -
    -

    {{ .Title }}

    -
    -
    - {{ .Content }} -
    -
    -
    - -{{ end }} -{{< /code >}} - -To easily generate new instances of a content type (e.g., new `.md` files in a section like `project/`) with preconfigured front matter, use [content archetypes][archetypes]. - -[archetypes]: /content-management/archetypes/ -[base templates]: /templates/base/ -[config]: /getting-started/configuration/ -[content type]: /content-management/types/ -[directory structure]: /getting-started/directory-structure/ -[dry]: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself -[`.Format` function]: /functions/format/ -[front matter]: /content-management/front-matter/ -[pagetaxonomy]: /templates/taxonomy-templates/#displaying-a-single-piece-of-content-s-taxonomies -[pagevars]: /variables/page/ -[partials]: /templates/partials/ -[section]: /content-management/sections/ -[site variables]: /variables/site/ -[spf13]: http://spf13.com/ -[`with`]: /functions/with/ diff --git a/content/templates/sitemap-template.md b/content/templates/sitemap-template.md deleted file mode 100644 index 29b59ad1..00000000 --- a/content/templates/sitemap-template.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -title: Sitemap Template -# linktitle: Sitemap -description: Hugo ships with a built-in template file observing the v0.9 of the Sitemap Protocol, but you can override this template if needed. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [sitemap, xml, templates] -menu: - docs: - parent: "templates" - weight: 160 -weight: 160 -sections_weight: 160 -draft: false -aliases: [/layout/sitemap/,/templates/sitemap/] -toc: false ---- - -A single Sitemap template is used to generate the `sitemap.xml` file. -Hugo automatically comes with this template file. *No work is needed on -the users' part unless they want to customize `sitemap.xml`.* - -A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use in this template along with Sitemap-specific ones: - -`.Sitemap.ChangeFreq` -: The page change frequency - -`.Sitemap.Priority` -: The priority of the page - -`.Sitemap.Filename` -: The sitemap filename - -If provided, Hugo will use `/layouts/sitemap.xml` instead of the internal `sitemap.xml` template that ships with Hugo. - -## Hugo’s sitemap.xml - -This template respects the version 0.9 of the [Sitemap Protocol](http://www.sitemaps.org/protocol.html). - -``` - - {{ range .Data.Pages }} - - {{ .Permalink }}{{ if not .Lastmod.IsZero }} - {{ safeHTML ( .Lastmod.Format "2006-01-02T15:04:05-07:00" ) }}{{ end }}{{ with .Sitemap.ChangeFreq }} - {{ . }}{{ end }}{{ if ge .Sitemap.Priority 0.0 }} - {{ .Sitemap.Priority }}{{ end }} - - {{ end }} - -``` - -{{% note %}} -Hugo will automatically add the following header line to this file -on render. Please don't include this in the template as it's not valid HTML. - -`` -{{% /note %}} - -## Configure `sitemap.xml` - -Defaults for ``, `` and `filename` values can be set in the site's config file, e.g.: - -{{< code-toggle file="config" >}} -[sitemap] - changefreq = "monthly" - priority = 0.5 - filename = "sitemap.xml" -{{}} - -The same fields can be specified in an individual content file's front matter in order to override the value assigned to that piece of content at render time. - -[pagevars]: /variables/page/ \ No newline at end of file diff --git a/content/templates/taxonomy-templates.md b/content/templates/taxonomy-templates.md deleted file mode 100644 index f3b349a3..00000000 --- a/content/templates/taxonomy-templates.md +++ /dev/null @@ -1,347 +0,0 @@ ---- -title: Taxonomy Templates -# linktitle: -description: Taxonomy templating includes taxonomy list pages, taxonomy terms pages, and using taxonomies in your single page templates. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [taxonomies,metadata,front matter,terms,templates] -menu: - docs: - parent: "templates" - weight: 50 -weight: 50 -sections_weight: 50 -draft: false -aliases: [/taxonomies/displaying/,/templates/terms/,/indexes/displaying/,/taxonomies/templates/,/indexes/ordering/, /templates/taxonomies/, /templates/taxonomy/] -toc: true ---- - - - -Hugo includes support for user-defined groupings of content called **taxonomies**. Taxonomies are classifications that demonstrate logical relationships between content. See [Taxonomies under Content Management](/content-management/taxonomies) if you are unfamiliar with how Hugo leverages this powerful feature. - -Hugo provides multiple ways to use taxonomies throughout your project templates: - -* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-template) -* Order the way the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-template) -* List a single content's taxonomy terms within a [single page template][] - -## Taxonomy List Templates - -Taxonomy list page templates are lists and therefore have all the variables and methods available to [list pages][lists]. - -### Taxonomy List Template Lookup Order - -See [Template Lookup](/templates/lookup-order/). - -## Taxonomy Terms Template - -### Taxonomy Terms Templates Lookup Order - -See [Template Lookup](/templates/lookup-order/). - -### Taxonomy Methods - -A Taxonomy is a `map[string]WeightedPages`. - -.Get(term) -: Returns the WeightedPages for a term. - -.Count(term) -: The number of pieces of content assigned to this term. - -.Alphabetical -: Returns an OrderedTaxonomy (slice) ordered by Term. - -.ByCount -: Returns an OrderedTaxonomy (slice) ordered by number of entries. - -.Reverse -: Returns an OrderedTaxonomy (slice) in reverse order. Must be used with an OrderedTaxonomy. - -### OrderedTaxonomy - -Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order. - -``` -[]struct { - Name string - WeightedPages WeightedPages -} -``` - -Each element of the slice has: - -.Term -: The Term used. - -.WeightedPages -: A slice of Weighted Pages. - -.Count -: The number of pieces of content assigned to this term. - -.Pages -: All Pages assigned to this term. All [list methods][renderlists] are available to this. - -## WeightedPages - -WeightedPages is simply a slice of WeightedPage. - -``` -type WeightedPages []WeightedPage -``` - -.Count(term) -: The number of pieces of content assigned to this term. - -.Pages -: Returns a slice of pages, which then can be ordered using any of the [list methods][renderlists]. - -## Displaying custom metadata in Taxonomy Terms Templates - -If you need to display custom metadata for each taxonomy term, you will need to create a page for that term at `/content///_index.md` and add your metadata in it's front matter, [as explained in the taxonomies documentation](/content-management/taxonomies/#add-custom-meta-data-to-a-taxonomy-term). Based on the Actors taxonomy example shown there, within your taxonomy terms template, you may access your custom fields by iterating through the variable `.Data.Pages` as such: - -``` -
      - {{ range .Data.Pages }} -
    • - {{ .Title }} - {{ .Params.wikipedia }} -
      • - {{ end }} -
    -``` - - - -## Order Taxonomies - -Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key. - -### Order Alphabetically Example - -``` -
      - {{ $data := .Data }} - {{ range $key, $value := .Data.Terms.Alphabetical }} -
    • {{ $value.Name }} {{ $value.Count }}
      • - {{ end }} -
    -``` - -### Order by Popularity Example - -``` -
      - {{ $data := .Data }} - {{ range $key, $value := .Data.Terms.ByCount }} -
    • {{ $value.Name }} {{ $value.Count }}
      • - {{ end }} -
    -``` - -### Order by Least Popular Example - -``` -
      - {{ $data := .Data }} - {{ range $key, $value := .Data.Terms.ByCount.Reverse }} -
    • {{ $value.Name }} {{ $value.Count }}
      • - {{ end }} -
    -``` - - - -## Order Content within Taxonomies - -Hugo uses both `date` and `weight` to order content within taxonomies. - -Each piece of content in Hugo can optionally be assigned a date. It can also be assigned a weight for each taxonomy it is assigned to. - -When iterating over content within taxonomies, the default sort is the same as that used for [section and list pages]() first by weight then by date. This means that if the weights for two pieces of content are the same, than the more recent content will be displayed first. The default weight for any piece of content is 0. - -### Assign Weight - -Content can be assigned weight for each taxonomy that it's assigned to. - -``` -+++ -tags = [ "a", "b", "c" ] -tags_weight = 22 -categories = ["d"] -title = "foo" -categories_weight = 44 -+++ -Front Matter with weighted tags and categories -``` - -The convention is `taxonomyname_weight`. - -In the above example, this piece of content has a weight of 22 which applies to the sorting when rendering the pages assigned to the "a", "b" and "c" values of the 'tag' taxonomy. - -It has also been assigned the weight of 44 when rendering the 'd' category. - -With this the same piece of content can appear in different positions in different taxonomies. - -Currently taxonomies only support the default ordering of content which is weight -> date. - - - -There are two different templates that the use of taxonomies will require you to provide. - -Both templates are covered in detail in the templates section. - -A [list template](/templates/list/) is any template that will be used to render multiple pieces of content in a single html page. This template will be used to generate all the automatically created taxonomy pages. - -A [taxonomy terms template](/templates/terms/) is a template used to -generate the list of terms for a given template. - - - -There are four common ways you can display the data in your -taxonomies in addition to the automatic taxonomy pages created by hugo -using the [list templates](/templates/list/): - -1. For a given piece of content, you can list the terms attached -2. For a given piece of content, you can list other content with the same - term -3. You can list all terms for a taxonomy -4. You can list all taxonomies (with their terms) - -## Display a Single Piece of Content's Taxonomies - -Within your content templates, you may wish to display the taxonomies that piece of content is assigned to. - -Because we are leveraging the front matter system to define taxonomies for content, the taxonomies assigned to each content piece are located in the usual place (i.e., `.Params.`). - -### Example: List Tags in a Single Page Template - -``` -
      - {{ range .Params.tags }} -
    • {{ . }}
      • - {{ end }} -
    -``` - -If you want to list taxonomies inline, you will have to take care of optional plural endings in the title (if multiple taxonomies), as well as commas. Let's say we have a taxonomy "directors" such as `directors: [ "Joel Coen", "Ethan Coen" ]` in the TOML-format front matter. - -To list such taxonomies, use the following: - -### Example: Comma-delimit Tags in a Single Page Template - -``` -{{ if .Params.directors }} - Director{{ if gt (len .Params.directors) 1 }}s{{ end }}: - {{ range $index, $director := .Params.directors }}{{ if gt $index 0 }}, {{ end }}{{ . }}{{ end }} -{{ end }} -``` - -Alternatively, you may use the [delimit template function][delimit] as a shortcut if the taxonomies should just be listed with a separator. See {{< gh 2143 >}} on GitHub for discussion. - -## List Content with the Same Taxonomy Term - -If you are using a taxonomy for something like a series of posts, you can list individual pages associated with the same taxonomy. This is also a quick and dirty method for showing related content: - -### Example: Showing Content in Same Series - -``` - -``` - -## List All content in a Given taxonomy - -This would be very useful in a sidebar as “featured content”. You could even have different sections of “featured content” by assigning different terms to the content. - -### Example: Grouping "Featured" Content - -``` - -``` - -## Render a Site's Taxonomies - -If you wish to display the list of all keys for your site's taxonomy, you can retrieve them from the [`.Site` variable][sitevars] available on every page. - -This may take the form of a tag cloud, a menu, or simply a list. - -The following example displays all terms in a site's tags taxonomy: - -### Example: List All Site Tags - -``` -
      - {{ range $name, $taxonomy := .Site.Taxonomies.tags }} -
    • {{ $name }}
      • - {{ end }} -
    -``` - -### Example: List All Taxonomies, Terms, and Assigned Content - -This example will list all taxonomies and their terms, as well as all the content assigned to each of the terms. - -{{< code file="layouts/partials/all-taxonomies.html" download="all-taxonomies.html" download="all-taxonomies.html" >}} -
    -
      - {{ range $taxonomyname, $taxonomy := .Site.Taxonomies }} -
    • {{ $taxonomyname }} -
        - {{ range $key, $value := $taxonomy }} -
      • {{ $key }}
        • - - {{ end }} -
      -
      • - {{ end }} -
    -
    -{{< /code >}} - -## `.Site.GetPage` for Taxonomies - -Because taxonomies are lists, the [`.GetPage` function][getpage] can be used to get all the pages associated with a particular taxonomy term using a terse syntax. The following ranges over the full list of tags on your site and links to each of the individual taxonomy pages for each term without having to use the more fragile URL construction of the "List All Site Tags" example above: - -{{< code file="links-to-all-tags" >}} -
      - {{ range ($.Site.GetPage "taxonomyTerm" "tags").Pages }} -
    • {{ .Title}}
      • - {{ end }} -
    -{{< /code >}} - - - - -[delimit]: /functions/delimit/ -[getpage]: /functions/getpage/ -[lists]: /templates/lists/ -[renderlists]: /templates/lists/ -[single page template]: /templates/single-page-templates/ -[sitevars]: /variables/site/ diff --git a/content/templates/template-debugging.md b/content/templates/template-debugging.md deleted file mode 100644 index e94a073a..00000000 --- a/content/templates/template-debugging.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Template Debugging -# linktitle: Template Debugging -description: You can use Go templates' `printf` function to debug your Hugo templates. These snippets provide a quick and easy visualization of the variables available to you in different contexts. -godocref: http://golang.org/pkg/fmt/ -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [debugging,troubleshooting] -menu: - docs: - parent: "templates" - weight: 180 -weight: 180 -sections_weight: 180 -draft: false -aliases: [] -toc: false ---- - -Here are some snippets you can add to your template to answer some common questions. - -These snippets use the `printf` function available in all Go templates. This function is an alias to the Go function, [fmt.Printf](http://golang.org/pkg/fmt/). - -## What Variables are Available in this Context? - -You can use the template syntax, `$.`, to get the top-level template context from anywhere in your template. This will print out all the values under, `.Site`. - -``` -{{ printf "%#v" $.Site }} -``` - -This will print out the value of `.Permalink`: - - -``` -{{ printf "%#v" .Permalink }} -``` - - -This will print out a list of all the variables scoped to the current context -(`.`, aka ["the dot"][tempintro]). - - -``` -{{ printf "%#v" . }} -``` - - -When developing a [homepage][], what does one of the pages you're looping through look like? - -``` -{{ range .Data.Pages }} - {{/* The context, ".", is now each one of the pages as it goes through the loop */}} - {{ printf "%#v" . }} -{{ end }} -``` - -{{% note "`.Data.Pages` on the Homepage" %}} -`.Data.Pages` on the homepage is equivalent to `.Site.Pages`. -{{% /note %}} - -## Why Am I Showing No Defined Variables? - -Check that you are passing variables in the `partial` function: - -``` -{{ partial "header" }} -``` - -This example will render the header partial, but the header partial will not have access to any contextual variables. You need to pass variables explicitly. For example, note the addition of ["the dot"][tempintro]. - -``` -{{ partial "header" . }} -``` - -The dot (`.`) is considered fundamental to understanding Hugo templating. For more information, see [Introduction to Hugo Templating][tempintro]. - -[homepage]: /templates/homepage/ -[tempintro]: /templates/introduction/ \ No newline at end of file diff --git a/content/templates/views.md b/content/templates/views.md deleted file mode 100644 index ac863646..00000000 --- a/content/templates/views.md +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Content View Templates -# linktitle: Content Views -description: Hugo can render alternative views of your content, which is especially useful in list and summary views. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [templates] -keywords: [views] -menu: - docs: - parent: "templates" - weight: 70 -weight: 70 -sections_weight: 70 -draft: false -aliases: [] -toc: true ---- - -These alternative **content views** are especially useful in [list templates][lists]. - -The following are common use cases for content views: - -* You want content of every type to be shown on the homepage but only with limited [summary views][summaries]. -* You only want a bulleted list of your content on a [taxonomy list page][taxonomylists]. Views make this very straightforward by delegating the rendering of each different type of content to the content itself. - -## Create a Content View - -To create a new view, create a template in each of your different content type directories with the view name. The following example contains an "li" view and a "summary" view for the `post` and `project` content types. As you can see, these sit next to the [single content view][single] template, `single.html`. You can even provide a specific view for a given type and continue to use the `_default/single.html` for the primary view. - -``` - ▾ layouts/ - ▾ post/ - li.html - single.html - summary.html - ▾ project/ - li.html - single.html - summary.html -``` - -Hugo also has support for a default content template to be used in the event that a specific content view template has not been provided for that type. Content views can also be defined in the `_default` directory and will work the same as list and single templates who eventually trickle down to the `_default` directory as a matter of the lookup order. - - -``` -▾ layouts/ - ▾ _default/ - li.html - single.html - summary.html -``` - -## Which Template Will be Rendered? - -The following is the [lookup order][lookup] for content views: - -1. `/layouts//.html` -2. `/layouts/_default/.html` -3. `/themes//layouts//.html` -4. `/themes//layouts/_default/.html` - -## Example: Content View Inside a List - -The following example demonstrates how to use content views inside of your [list templates][lists]. - -### `list.html` - -In this example, `.Render` is passed into the template to call the [render function][render]. `.Render` is a special function that instructs content to render itself with the view template provided as the first argument. In this case, the template is going to render the `summary.html` view that follows: - -{{< code file="layouts/_default/list.html" download="list.html" >}} -
    -
    -

    {{ .Title }}

    - {{ range .Data.Pages }} - {{ .Render "summary"}} - {{ end }} -
    -
    -{{< /code >}} - -### `summary.html` - -Hugo will pass the entire page object to the following `summary.html` view template. (See [Page Variables][pagevars] for a complete list.) - -{{< code file="layouts/_default/summary.html" download="summary.html" >}} - -{{< /code >}} - -### `li.html` - -Continuing on the previous example, we can change our render function to use a smaller `li.html` view by changing the argument in the call to the `.Render` function (i.e., `{{ .Render "li" }}`). - -{{< code file="layouts/_default/li.html" download="li.html" >}} -
  • - {{ .Title }} -
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    -
    • -{{< /code >}} - -[lists]: /templates/lists/ -[lookup]: /templates/lookup-order/ -[pagevars]: /variables/page/ -[render]: /functions/render/ -[single]: /templates/single-page-templates/ -[spf]: http://spf13.com -[spfsourceli]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/li.html -[spfsourcesection]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/section.html -[spfsourcesummary]: https://github.com/spf13/spf13.com/blob/master/layouts/_default/summary.html -[summaries]: /content-management/summaries/ -[taxonomylists]: /templates/taxonomy-templates/ diff --git a/content/themes/_index.md b/content/themes/_index.md deleted file mode 100644 index 9e2bc170..00000000 --- a/content/themes/_index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Themes -linktitle: Themes Overview -description: Install, use, and create Hugo themes. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -menu: - docs: - parent: "themes" - weight: 01 -weight: 01 -sections_weight: 01 -categories: [themes] -keywords: [themes,introduction,overview] -draft: false -aliases: [/themes/overview/] -toc: false ---- - -Hugo provides a robust theming system that is easy to implement yet feature complete. You can view the themes created by the Hugo community on the [Hugo themes website][hugothemes]. - -Hugo themes are powered by the excellent Go template library and are designed to reduce code duplication. They are easy to both customize and keep in synch with the upstream theme. - -[goprimer]: /templates/introduction/ -[hugothemes]: http://themes.gohugo.io/ diff --git a/content/themes/creating.md b/content/themes/creating.md deleted file mode 100644 index a62f7c71..00000000 --- a/content/themes/creating.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: Create a Theme -linktitle: Create a Theme -description: The `hugo new theme` command will scaffold the beginnings of a new theme for you to get you on your way. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [themes] -keywords: [themes, source, organization, directories] -menu: - docs: - parent: "themes" - weight: 30 -weight: 30 -sections_weight: 30 -draft: false -aliases: [/themes/creation/,/tutorials/creating-a-new-theme/] -toc: true -wip: true ---- - -{{% warning "Use Relative Links" %}} -If you're creating a theme with plans to share it with the community, use relative URLs since users of your theme may not publish from the root of their website. See [relURL](/functions/relurl) and [absURL](/functions/absurl). -{{% /warning %}} - -Hugo can initialize a new blank theme directory within your existing `themes` using the `hugo new` command: - -``` -hugo new theme [name] -``` - -## Theme Components - -A theme consists of templates and static assets such as javascript and css files. Themes can also provide [archetypes][], which are archetypal content types used by the `hugo new` command to scaffold new content files with preconfigured front matter. - - -{{% note "Use the Hugo Generator Tag" %}} -The [`.Hugo.Generator`](/variables/hugo/) tag is included in all themes featured in the [Hugo Themes Showcase](http://themes.gohugo.io). We ask that you include the generator tag in all sites and themes you create with Hugo to help the core team track Hugo's usage and popularity. -{{% /note %}} - -## Layouts - -Hugo is built around the concept that things should be as simple as possible. -Fundamentally, website content is displayed in two different ways, a single -piece of content and a list of content items. With Hugo, a theme layout starts -with the defaults. As additional layouts are defined, they are used for the -content type or section they apply to. This keeps layouts simple, but permits -a large amount of flexibility. - -## Single Content - -The default single file layout is located at `layouts/_default/single.html`. - -## List of Contents - -The default list file layout is located at `layouts/_default/list.html`. - -## Partial Templates - -Theme creators should liberally use [partial templates](/templates/partials/) -throughout their theme files. Not only is a good DRY practice to include shared -code, but partials are a special template type that enables the themes end user -to be able to overwrite just a small piece of a file or inject code into the -theme from their local /layouts. These partial templates are perfect for easy -injection into the theme with minimal maintenance to ensure future -compatibility. - -## Static - -Everything in the static directory will be copied directly into the final site -when rendered. No structure is provided here to enable complete freedom. It is -common to organize the static content into: - -``` -/css -/js -/img -``` - -The actual structure is entirely up to you, the theme creator, on how you would like to organize your files. - -## Archetypes - -If your theme makes use of specific keys in the front matter, it is a good idea -to provide an archetype for each content type you have. [Read more about archetypes][archetypes]. - -[archetypes]: /content-management/archetypes/ diff --git a/content/themes/customizing.md b/content/themes/customizing.md deleted file mode 100644 index 3444880f..00000000 --- a/content/themes/customizing.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Customize a Theme -linktitle: Customize a Theme -description: Customize a theme by overriding theme layouts and static assets in your top-level project directories. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [themes] -keywords: [themes, source, organization, directories] -menu: - docs: - parent: "themes" - weight: 20 -weight: 20 -sections_weight: 20 -draft: false -aliases: [/themes/customize/] -toc: true -wip: true ---- - -The following are key concepts for Hugo site customization with themes. Hugo permits you to supplement *or* override any theme template or static file with files in your working directory. - -{{% note %}} -When you use a theme cloned from its git repository, do not edit the theme's files directly. Instead, theme customization in Hugo is a matter of *overriding* the templates made available to you in a theme. This provides the added flexibility of tweaking a theme to meet your needs while staying current with a theme's upstream. -{{% /note %}} - -## Override Static Files - -There are times where you want to include static assets that differ from versions of the same asset that ships with a theme. - -For example, a theme may use jQuery 1.8 in the following location: - -``` -/themes//static/js/jquery.min.js -``` - -You want to replace the version of jQuery that ships with the theme with the newer `jquery-3.1.1.js`. The easiest way to do this is to replace the file *with a file of the same name* in the same relative path in your project's root. Therefore, change `jquery-3.1.1.js` to `jquery.min.js` so that it is *identical* to the theme's version and place the file here: - -``` -/static/js/jquery.min.js -``` - -## Override Template Files - -Anytime Hugo looks for a matching template, it will first check the working directory before looking in the theme directory. If you would like to modify a template, simply create that template in your local `layouts` directory. - -The [template lookup order][lookup] explains the rules Hugo uses to determine which template to use for a given piece of content. Read and understand these rules carefully. - -This is especially helpful when the theme creator used [partial templates][partials]. These partial templates are perfect for easy injection into the theme with minimal maintenance to ensure future compatibility. - -For example: - -``` -/themes//layouts/_default/single.html -``` - -Would be overwritten by - -``` -/layouts/_default/single.html -``` - -{{% warning %}} -This only works for templates that Hugo "knows about" (i.e., that follow its convention for folder structure and naming). If a theme imports template files in a creatively named directory, Hugo won’t know to look for the local `/layouts` first. -{{% /warning %}} - -## Override Archetypes - -If the archetype that ships with the theme for a given content type (or all content types) doesn’t fit with how you are using the theme, feel free to copy it to your `/archetypes` directory and make modifications as you see fit. - -{{% warning "Beware of `layouts/_default`" %}} -The `_default` directory is a very powerful force in Hugo, especially as it pertains to overwriting theme files. If a default file is located in the local [archetypes](/content-management/archetypes/) or layout directory (i.e., `archetypes/default.md` or `/layouts/_default/*.html`, respectively), it will override the file of the same name in the corresponding theme directory (i.e., `themes//archetypes/default.md` or `themes//layout/_defaults/*.html`, respectively). - -It is usually better to override specific files; i.e. rather than using `layouts/_default/*.html` in your working directory. -{{% /warning %}} - -[archetypes]: /content-management/archetypes/ -[lookup]: /templates/lookup-order/ -[partials]: /templates/partials/ \ No newline at end of file diff --git a/content/themes/installing-and-using-themes.md b/content/themes/installing-and-using-themes.md deleted file mode 100644 index 93d81423..00000000 --- a/content/themes/installing-and-using-themes.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: Install and Use Themes -linktitle: Install and Use Themes -description: Install and use a theme from the Hugo theme showcase easily through the CLI. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [themes] -keywords: [install, themes, source, organization, directories,usage] -menu: - docs: - parent: "themes" - weight: 10 -weight: 10 -sections_weight: 10 -draft: false -aliases: [/themes/usage/,/themes/installing/] -toc: true -wip: true ---- - -{{% note "No Default Theme" %}} -Hugo currently doesn’t ship with a “default” theme. This decision is intentional. We leave it up to you to decide which theme best suits your Hugo project. -{{% /note %}} - -## Assumptions - -1. You have already [installed Hugo on your development machine][install]. -2. You have git installed on your machine and you are familiar with basic git usage. - -## Install Themes - -{{< youtube L34JL_3Jkyc >}} - -The community-contributed themes featured on [themes.gohugo.io](//themes.gohugo.io/) are hosted in a [centralized GitHub repository][themesrepo]. The Hugo Themes Repo at is really a meta repository that contains pointers to a set of contributed themes. - -{{% warning "Get `git` First" %}} -Without [Git](https://git-scm.com/) installed on your computer, none of the following theme instructions will work. Git tutorials are beyond the scope of the Hugo docs, but [GitHub](https://try.github.io/) and [codecademy](https://www.codecademy.com/learn/learn-git) offer free, interactive courses for beginners. -{{% /warning %}} - -### Install All Themes - -You can install *all* available Hugo themes by cloning the entire [Hugo Theme repository on GitHub][themesrepo] from within your working directory. Depending on your internet connection the download of all themes might take a while. - -``` -git clone --depth 1 --recursive https://github.com/gohugoio/hugoThemes.git themes -``` - -Before you use a theme, remove the .git folder in that theme's root folder. Otherwise, this will cause problem if you deploy using Git. - -### Install a Single Theme - -Change into the `themes` directory and download a theme by replacing `URL_TO_THEME` with the URL of the theme repository: - -``` -cd themes -git clone URL_TO_THEME -``` - -The following example shows how to use the "Hyde" theme, which has its source hosted at : - -{{< code file="clone-theme.sh" >}} -cd themes -git clone https://github.com/spf13/hyde -{{< /code >}} - -Alternatively, you can download the theme as a `.zip` file, unzip the theme contents, and then move the unzipped source into your `themes` directory. - -{{% note "Read the `README`" %}} -Always review the `README.md` file that is shipped with a theme. Often, these files contain further instructions required for theme setup; e.g., copying values from an example configuration file. -{{% /note %}} - -## Theme Placement - -Please make certain you have installed the themes you want to use in the -`/themes` directory. This is the default directory used by Hugo. Hugo comes with the ability to change the themes directory via the [`themesDir` variable in your site configuration][config], but this is not recommended. - -## Use Themes - -Hugo applies the decided theme first and then applies anything that is in the local directory. This allows for easier customization while retaining compatibility with the upstream version of the theme. To learn more, go to [customizing themes][customizethemes]. - -### Command Line - -There are two different approaches to using a theme with your Hugo website: via the Hugo CLI or as part of your [site configuration file][config]. - -To change a theme via the Hugo CLI, you can pass the `-t` [flag][] when building your site: - -``` -hugo -t themename -``` - -Likely, you will want to add the theme when running the Hugo local server, especially if you are going to [customize the theme][customizethemes]: - -``` -hugo server -t themename -``` - -### `config` File - -If you've already decided on the theme for your site and do not want to fiddle with the command line, you can add the theme directly to your [site configuration file][config]: - -``` -theme: themename -``` - -{{% note "A Note on `themename`" %}} -The `themename` in the above examples must match the name of the specific theme directory inside `/themes`; i.e., the directory name (likely lowercase and urlized) rather than the name of the theme displayed in the [Themes Showcase site](http://themes.gohugo.io). -{{% /note %}} - -[customizethemes]: /themes/customizing/ -[flag]: /getting-started/usage/ "See the full list of flags in Hugo's basic usage." -[install]: /getting-started/installing/ -[config]: /getting-started/configuration/ "Learn how to customize your Hugo website configuration file in yaml, toml, or json." -[themesrepo]: https://github.com/gohugoio/hugoThemes diff --git a/content/tools/_index.md b/content/tools/_index.md deleted file mode 100644 index 47cfeb1e..00000000 --- a/content/tools/_index.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Developer Tools -linktitle: Developer Tools Overview -description: In addition to Hugo's powerful CLI, there is a large number of community-developed tool chains for Hugo developers. -date: 2016-12-05 -publishdate: 2016-12-05 -lastmod: 2017-02-26 -categories: [developer tools] -keywords: [] -menu: - docs: - parent: "tools" - weight: 01 -weight: 01 -sections_weight: 01 -draft: false -aliases: [/tools/] ---- - -One of Hugo's greatest strengths is it's passionate---and always evolving---developer community. With the exception of the `highlight` shortcode mentioned in [Syntax Highlighting][syntax], the tools and other projects featured in this section are offerings from both commercial services and open-source projects, many of which are developed by Hugo developers just like you. - -[See the popularity of Hugo compared with other static site generators.][staticgen] - -[staticgen]: https://staticgen.com -[syntax]: /tools/syntax-highlighting/ diff --git a/content/tools/editors.md b/content/tools/editors.md deleted file mode 100644 index 419a2a04..00000000 --- a/content/tools/editors.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Editor Plug-ins for Hugo -linktitle: Editor Plug-ins -description: The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [developer tools] -keywords: [editor, plug-ins] -menu: - docs: - parent: "tools" - weight: 50 -weight: 50 -sections_weight: 50 -draft: false -aliases: [] -toc: false ---- - -The Hugo community uses a wide range of preferred tools and has developed plug-ins for some of the most popular text editors to help automate parts of your workflow. - -## Sublime Text - -* [Hugofy](https://github.com/akmittal/Hugofy). Hugofy is a plugin for Sublime Text 3 to make life easier to use Hugo static site generator. - -## Visual Studio Code - -* [Hugofy](https://marketplace.visualstudio.com/items?itemName=akmittal.hugofy). Hugofy is a plugin for Visual Studio Code to "make life easier" when developing with Hugo. The source code can be found [here](https://github.com/akmittal/hugofy-vscode). - -## Emacs - -* [emacs-easy-hugo](https://github.com/masasam/emacs-easy-hugo). Emacs major mode for managing hugo blogs. Note that Hugo also supports [Org-mode][formats]. -* [ox-hugo.el](https://ox-hugo.scripter.co). Native Org-mode exporter that exports to Blackfriday Markdown with Hugo front-matter. `ox-hugo` supports two common Org blogging flows --- exporting multiple Org sub-trees in a single file to multiple Hugo posts, and exporting a single Org file to a single Hugo post. It also leverages the Org tag and property inheritance features. See [*Why ox-hugo?*](https://ox-hugo.scripter.co/doc/why-ox-hugo/) for more. - -## Vim - -* [Vim Hugo Helper](https://github.com/robertbasic/vim-hugo-helper). A small Vim plugin to help me with writing posts with Hugo. - -## Atom - -* [Hugofy](https://atom.io/packages/hugofy). A Hugo Static Website Generator package for Atom. -* [language-hugo](https://atom.io/packages/language-hugo). Adds syntax highlighting to Hugo files. - -[formats]: /content-management/formats/ diff --git a/content/tools/frontends.md b/content/tools/frontends.md deleted file mode 100644 index f41751b4..00000000 --- a/content/tools/frontends.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Frontend Interfaces with Hugo -linktitle: Frontends -description: Do you prefer a graphical user interface over a text editor? Give these frontends a try. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [developer tools] -keywords: [frontend,gui] -menu: - docs: - parent: "tools" - weight: 40 -weight: 40 -sections_weight: 40 -draft: false -aliases: [] -toc: false ---- - -* [enwrite](https://github.com/zzamboni/enwrite). Enwrite enables evernote-powered, statically generated blogs and websites. Now posting to your blog or updating your website is as easy as writing a new note in Evernote! -* [caddy-hugo](https://github.com/hacdias/caddy-hugo). `caddy-hugo` is an add-on for [Caddy](https://caddyserver.com/) that delivers a good UI to edit the content of your Hugo website. -* [Lipi](https://github.com/SohanChy/Lipi). Lipi is a native GUI frontend written in Java to manage your Hugo websites. -* [Netlify CMS](https://netlifycms.org). Netlify CMS is an open source, serverless solution for managing Git based content in static sites, and it works on any platform that can host static sites. A [Hugo/Netlify CMS starter](https://github.com/netlify-templates/one-click-hugo-cms) is available to get new projects running quickly. - - -## Commercial Services - -* [Appernetic.io](https://appernetic.io) is a Hugo Static Site Generator as a Service that is easy to use for non-technical users. - * **Features:** inline PageDown editor, visual tree view, image upload and digital asset management with Cloudinary, site preview, continuous integration with GitHub, atomic deploy and hosting, Git and Hugo integration, autosave, custom domain, project syncing, theme cloning and management. Developers have complete control over the source code and can manage it with GitHub’s deceptively simple workflow. -* [DATOCMS](https://www.datocms.com) DatoCMS is a fully customizable administrative area for your static websites. Use your favorite website generator, let your clients publish new content independently, and the host the site anywhere you like. -* [Forestry.io](https://forestry.io/). Forestry is a simple CMS for Jekyll and Hugo websites with support for GitHub, GitLab, and Bitbucket. Every time an update is made via the CMS, Forestry will commit changes back to your repo and will compile/deploy your website to S3, GitHub Pages, FTP, etc. -* [Netlify.com](https://www.netlify.com). Netlify builds, deploys, and hosts your static website or app (Hugo, Jekyll, etc). Netlify offers a drag-and-drop interface and automatic deployments from GitHub or Bitbucket. - * **Features:** global CDN, atomic deploys, ultra-fast DNS, instant cache invalidation, high availability, automated hosting, Git integration, form submission hooks, authentication providers, and custom domains. Developers have complete control over the source code and can manage it with GitHub or Bitbucket's deceptively simple workflow. diff --git a/content/tools/migrations.md b/content/tools/migrations.md deleted file mode 100644 index ef4f169d..00000000 --- a/content/tools/migrations.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Migrate to Hugo -linktitle: Migrations -description: A list of community-developed tools for migrating from your existing static site generator or content management system to Hugo. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -keywords: [migrations,jekyll,wordpress,drupal,ghost,contentful] -menu: - docs: - parent: "tools" - weight: 10 -weight: 10 -sections_weight: 10 -draft: false -aliases: [/developer-tools/migrations/,/developer-tools/migrated/] -toc: true ---- - -This section highlights some projects around Hugo that are independently developed. These tools try to extend the functionality of our static site generator or help you to get started. - -{{% note %}} -Do you know or maintain a similar project around Hugo? Feel free to open a [pull request](https://github.com/gohugoio/hugo/pulls) on GitHub if you think it should be added. -{{% /note %}} - -Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll take care to export your content into Hugo-friendly formats. - -## Jekyll - -Alternatively, you can use the new [Jekyll import command](/commands/hugo_import_jekyll/). - -- [JekyllToHugo](https://github.com/SenjinDarashiva/JekyllToHugo) - A Small script for converting Jekyll blog posts to a Hugo site. -- [ConvertToHugo](https://github.com/coderzh/ConvertToHugo) - Convert your blog from Jekyll to Hugo. - -## Ghost - -- [ghostToHugo](https://github.com/jbarone/ghostToHugo) - Convert Ghost blog posts and export them to Hugo. - -## Octopress - -- [octohug](https://github.com/codebrane/octohug) - Octopress to Hugo migrator. - -## DokuWiki - -- [dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo) - Migrates your dokuwiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extra's like the TODO plugin. Written with extensibility in mind using python 3. Also generates a TOML header for each page. Designed to copypaste the wiki directory into your /content directory. - -## WordPress - -- [wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter) - A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.) - -## Tumblr - -- [tumblr-importr](https://github.com/carlmjohnson/tumblr-importr) - An importer that uses the Tumblr API to create a Hugo static site. -- [tumblr2hugomarkdown](https://github.com/Wysie/tumblr2hugomarkdown) - Export all your Tumblr content to Hugo Markdown files with preserved original formatting. -- [Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo) - A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. Furthermore, "Tumblr to Hugo" creates a CSV file with the original URL and the new path on Hugo, to help you setup the redirections. - -## Drupal - -- [drupal2hugo](https://github.com/danapsimer/drupal2hugo) - Convert a Drupal site to Hugo. - -## Joomla - -- [hugojoomla](https://github.com/davetcc/hugojoomla) - This utility written in Java takes a Joomla database and converts all the content into Markdown files. It changes any URLs that are in Joomla's internal format and converts them to a suitable form. - -## Blogger - -- [blogimport](https://github.com/natefinch/blogimport) - A tool to import from Blogger posts to Hugo. -- [blogger-to-hugo](https://bitbucket.org/petraszd/blogger-to-hugo) - Another tool to import Blogger posts to Hugo. It also downloads embedded images so they will be stored locally. - -## Contentful - -- [contentful2hugo](https://github.com/ArnoNuyts/contentful2hugo) - A tool to create content-files for Hugo from content on [Contentful](https://www.contentful.com/). diff --git a/content/tools/other.md b/content/tools/other.md deleted file mode 100644 index 0502e1cd..00000000 --- a/content/tools/other.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -title: Other Hugo Community Projects -linktitle: Other Projects -description: Some interesting projects developed by the Hugo community that don't quite fit into our other developer tool categories. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [developer tools] -keywords: [frontend,gui] -menu: - docs: - parent: "tools" - weight: 70 -weight: 70 -sections_weight: 70 -draft: false -aliases: [] -toc: false ---- - -And for all the other small things around Hugo: - -* [hugo-gallery](https://github.com/icecreammatt/hugo-gallery) lets you create an image gallery for Hugo sites. -* [flickr-hugo-embed](https://github.com/nikhilm/flickr-hugo-embed) prints shortcodes to embed a set of images from an album on Flickr into Hugo. -* [hugo-openapispec-shortcode](https://github.com/tenfourty/hugo-openapispec-shortcode) A shortcode that allows you to include [Open API Spec](https://openapis.org) (formerly known as Swagger Spec) in a page. -* [HugoPhotoSwipe](https://github.com/GjjvdBurg/HugoPhotoSwipe) makes it easy to create image galleries using PhotoSwipe. -* [Hugo SFTP Upload](https://github.com/thomasmey/HugoSftpUpload) Syncs the local build of your Hugo website with your remote webserver via SFTP. -* [Emacs Easy Hugo](https://github.com/masasam/emacs-easy-hugo) Emacs package for writing blog posts in markdown or org-mode and building your site with Hugo. diff --git a/content/tools/search.md b/content/tools/search.md deleted file mode 100644 index 2145c187..00000000 --- a/content/tools/search.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: Search for your Hugo Website -linktitle: Search -description: See some of the open-source and commercial search options for your newly created Hugo website. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-26 -categories: [developer tools] -keywords: [search,tools] -menu: - docs: - parent: "tools" - weight: 60 -weight: 60 -sections_weight: 60 -draft: false -aliases: [] -toc: true ---- - -A static website with a dynamic search function? Yes. As alternatives to embeddable scripts from Google or other search engines, you can provide your visitors a custom search by indexing your content files directly. - -* [GitHub Gist for Hugo Workflow](https://gist.github.com/sebz/efddfc8fdcb6b480f567). This gist contains a simple workflow to create a search index for your static website. It uses a simple Grunt script to index all your content files and [lunr.js](http://lunrjs.com/) to serve the search results. -* [hugo-lunr](https://www.npmjs.com/package/hugo-lunr). A simple way to add site search to your static Hugo site using [lunr.js](http://lunrjs.com/). Hugo-lunr will create an index file of any html and markdown documents in your Hugo project. -* [hugo-lunr-zh](https://www.npmjs.com/package/hugo-lunr-zh). A bit like Hugo-lunr, but Hugo-lunr-zh can help you separate the Chinese keywords. -* [Github Gist for Fuse.js integration](https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1cb41ae). This gist demonstrates how to leverage Hugo's existing build time processing to generate a searchable JSON index used by [Fuse.js](http://fusejs.io/) on the client side. Although this gist uses Fuse.js for fuzzy matching, any client side search tool capable of reading JSON indexes will work. Does not require npm, grunt or other build-time tools except Hugo! -* [hugo-search-index](https://www.npmjs.com/package/hugo-search-index). A library containing Gulp tasks and a prebuilt browser script that implements search. Gulp generates a search index from project markdown files. - -## Commercial Search Services - -* [Algolia](https://www.algolia.com/)'s Search API makes it easy to deliver a great search experience in your apps and websites. Algolia Search provides hosted full-text, numerical, faceted, and geolocalized search. diff --git a/content/tools/starter-kits.md b/content/tools/starter-kits.md deleted file mode 100644 index 0ce81cc4..00000000 --- a/content/tools/starter-kits.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Starter Kits -linktitle: Starter Kits -description: A list of community-developed projects designed to help you get up and running with Hugo. -date: 2017-02-22 -publishdate: 2017-02-01 -lastmod: 2017-02-22 -keywords: [starters,assets,pipeline] -menu: - docs: - parent: "tools" - weight: 30 -weight: 30 -sections_weight: 30 -draft: false -aliases: [/developer-tools/migrations/,/developer-tools/migrated/] -toc: false ---- - -Know of a Hugo-related starter kit that isn't mentioned here? [Please add it to the list.][addkit] - -{{% note "Starter Kits are Not Maintained by the Hugo Team"%}} -The following starter kits are developed by active members of the Hugo community. If you find yourself having issues with any of the projects, it's best to file an issue directly with the project's maintainer(s). -{{% /note %}} - -* [Victor Hugo][]. Victor Hugo is a Hugo boilerplate for creating truly epic websites using Gulp + Webpack as an asset pipeline. Victor Hugo uses post-css and Babel for CSS and JavaScript, respectively, and is actively maintained. -* [GOHUGO AMP][]. GoHugo AMP is a starter theme that aims to make it easy to adopt [Google's AMP Project][amp]. The starter kit comes with 40+ shortcodes and partials plus automatic structured data. The project also includes a [separate site with extensive documentation][gohugodocs]. -* [Blaupause][]. Blaupause is a developer-friendly Hugo starter kit based on Gulp tasks. It comes ES6-ready with several helpers for SVG and fonts and basic structure for HTML, SCSS, and JavaScript. -* [hugulp][]. hugulp is a tool to optimize the assets of a Hugo website. The main idea is to recreate the famous Ruby on Rails Asset Pipeline, which minifies, concatenates and fingerprints the assets used in your website. -* [Atlas][]. Atlas is a Hugo boilerplate designed to speed up development with support for Netlify, Netlify CMS, Gulp, Linting, SCSS, ES6 & more. It's actively maintained and contributions are always welcome. - - -[addkit]: https://github.com/gohugoio/hugo/edit/master/docs/content/tools/starter-kits.md -[amp]: https://www.ampproject.org/ -[Blaupause]: https://github.com/fspoettel/blaupause -[GOHUGO AMP]: https://github.com/wildhaber/gohugo-amp -[gohugodocs]: https://gohugo-amp.gohugohq.com/ -[hugulp]: https://github.com/jbrodriguez/hugulp -[Victor Hugo]: https://github.com/netlify/victor-hugo -[Atlas]: https://github.com/indigotree/atlas \ No newline at end of file diff --git a/content/troubleshooting/_index.md b/content/troubleshooting/_index.md deleted file mode 100644 index 3b0e9372..00000000 --- a/content/troubleshooting/_index.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: Troubleshoot -linktitle: Troubleshoot -description: Frequently asked questions and known issues pulled from the Hugo Discuss forum. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -menu: - docs: - parent: "troubleshooting" - weight: 1 -weight: 1 -draft: false -hidesectioncontents: false -slug: -aliases: [/troubleshooting/faqs/,/faqs/] -toc: false -notesforauthors: ---- - -The Troubleshooting section includes known issues, recent workarounds, and FAQs pulled from the [Hugo Discussion Forum][forum]. - - - - -[forum]: https://discourse.gohugo.io diff --git a/content/troubleshooting/build-performance.md b/content/troubleshooting/build-performance.md deleted file mode 100644 index bc4d30d5..00000000 --- a/content/troubleshooting/build-performance.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Build Performance -linktitle: Build Performance -description: An overview of features used for diagnosing and improving performance issues in site builds. -date: 2017-03-12 -publishdate: 2017-03-12 -lastmod: 2017-03-12 -keywords: [performance, build] -categories: [troubleshooting] -menu: - docs: - parent: "troubleshooting" -weight: 3 -slug: -aliases: [] -toc: true ---- - -{{% note %}} -The example site used below is from https://github.com/gohugoio/hugo/tree/master/examples/blog -{{% /note %}} - -## Template Metrics - -Hugo is a very fast static site generator, but it is possible to write -inefficient templates. Hugo's *template metrics* feature is extremely helpful -in pinpointing which templates are executed most often and how long those -executions take **in terms of CPU time**. - -| Metric Name | Description | -|---------------------|-------------| -| cumulative duration | The cumulative time spent executing a given template. | -| average duration | The average time spent executing a given template. | -| maximum duration | The maximum time a single execution took for a given template. | -| count | The number of times a template was executed. | -| template | The template name. | - -``` -▶ hugo --templateMetrics -Started building sites ... - -Built site for language en: -0 draft content -0 future content -0 expired content -2 regular pages created -22 other pages created -0 non-page files copied -0 paginator pages created -4 tags created -3 categories created -total in 18 ms - -Template Metrics: - - cumulative average maximum - duration duration duration count template - ---------- -------- -------- ----- -------- - 6.419663ms 583.605µs 994.374µs 11 _internal/_default/rss.xml - 4.718511ms 1.572837ms 3.880742ms 3 indexes/category.html - 4.642666ms 2.321333ms 3.282842ms 2 post/single.html - 4.364445ms 396.767µs 2.451372ms 11 partials/header.html - 2.346069ms 586.517µs 903.343µs 4 indexes/tag.html - 2.330919ms 211.901µs 2.281342ms 11 partials/header.includes.html - 1.238976ms 103.248µs 446.084µs 12 post/li.html - 972.16µs 972.16µs 972.16µs 1 _internal/_default/sitemap.xml - 953.597µs 953.597µs 953.597µs 1 index.html - 822.263µs 822.263µs 822.263µs 1 indexes/post.html - 567.498µs 51.59µs 112.205µs 11 partials/navbar.html - 348.22µs 31.656µs 88.249µs 11 partials/meta.html - 346.782µs 173.391µs 276.176µs 2 post/summary.html - 235.184µs 21.38µs 124.383µs 11 partials/footer.copyright.html - 132.003µs 12µs 117.999µs 11 partials/menu.html - 72.547µs 6.595µs 63.764µs 11 partials/footer.html -``` - -{{% note %}} -**A Note About Parallelism** - -Hugo builds pages in parallel where multiple pages are generated -simultaneously. Because of this parallelism, the sum of "cumulative duration" -values is usually greater than the actual time it takes to build a site. -{{% /note %}} - - -## Cached Partials - -Some `partial` templates such as sidebars or menus are executed many times -during a site build. Depending on the content within the `partial` template and -the desired output, the template may benefit from caching to reduce the number -of executions. The [`partialCached`][partialCached] template function provides -caching capabilities for `partial` templates. - -{{% tip %}} -Note that you can create cached variants of each `partial` by passing additional -parameters to `partialCached` beyond the initial context. See the -`partialCached` documentation for more details. -{{% /tip %}} - - -## Step Analysis - -Hugo provides a means of seeing metrics about each step in the site build -process. We call that *Step Analysis*. The *step analysis* output shows the -total time per step, the cumulative time after each step (in parentheses), -the memory usage per step, and the total memory allocations per step. - -To enable *step analysis*, use the `--stepAnalysis` option when running Hugo. - - -[partialCached]:{{< ref "functions/partialCached.md" >}} diff --git a/content/troubleshooting/faq.md b/content/troubleshooting/faq.md deleted file mode 100644 index 392d7a8d..00000000 --- a/content/troubleshooting/faq.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Frequently Asked Questions -linktitle: FAQ -description: Solutions to some common Hugo problems. -date: 2018-02-10 -categories: [troubleshooting] -menu: - docs: - parent: "troubleshooting" -keywords: [faqs] -weight: 2 -toc: true -aliases: [/faq/] ---- - -{{% note %}} -**Note:** The answers/solutions presented below are short, and may not be note be enough to solve your problem. Visit [Hugo Discourse](https://discourse.gohugo.io/) and use the search. It that does not help, start a new topic and ask your questions. -{{% /note %}} - -## Can I set configuration variables via OS environment? - -Yes you can! See [Configure with Environment Variables](/getting-started/configuration/#configure-with-environment-variables). - -## How do I schedule posts? - -1. Set `publishDate` in the page [Front Matter](/content-management/front-matter/) to a date in the future. -2. Build and publish at intervals. - -How to automate the "publish at intervals" part depends on your situation: - -* If you deploy from your own PC/server, you can automate with [Cron](https://en.wikipedia.org/wiki/Cron) or similar. -* If your site is hosted on a service similar to [Netlify](https://www.netlify.com/) you can use a service such as [ifttt](https://ifttt.com/date_and_time) to schedule the updates. - -Also see this Twitter thread: - -{{< tweet 962380712027590657 >}} - -## Can I use the latest Hugo version on Netlify? - -Yes you can! Read [this](/hosting-and-deployment/hosting-on-netlify/#configure-hugo-version-in-netlify). diff --git a/content/variables/_index.md b/content/variables/_index.md deleted file mode 100644 index 382ee25d..00000000 --- a/content/variables/_index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Variables and Params -linktitle: Variables Overview -description: Page-, file-, taxonomy-, and site-level variables and parameters available in templates. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [variables and params] -keywords: [variables,params,values,globals] -draft: false -menu: - docs: - parent: "variables" - weight: 1 -weight: 01 #rem -sections_weight: 01 -aliases: [/templates/variables/] -toc: false ---- - -Hugo's templates are context aware and make a large number of values available to you as you're creating views for your website. - -[Go templates]: /templates/introduction/ "Understand context in Go templates by learning the language's fundamental templating functions." diff --git a/content/variables/files.md b/content/variables/files.md deleted file mode 100644 index ac5376db..00000000 --- a/content/variables/files.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: File Variables -linktitle: -description: "You can access filesystem-related data for a content file in the `.File` variable." -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [variables and params] -keywords: [files] -draft: false -menu: - docs: - parent: "variables" - weight: 40 -weight: 40 -sections_weight: 40 -aliases: [/variables/file-variables/] -toc: false ---- - -{{% note "Rendering Local Files" %}} -For information on creating shortcodes and templates that tap into Hugo's file-related feature set, see [Local File Templates](/templates/files/). -{{% /note %}} - -The `.File` object contains the following fields: - -.File.Path -: the original relative path of the page (e.g., `content/posts/foo.en.md`) - -.File.LogicalName -: the name of the content file that represents a page (e.g., `foo.en.md`) - -.File.TranslationBaseName -: the filename without extension or optional language identifier (e.g., `foo`) - -.File.BaseFileName -: the filename without extension (e.g., `foo.en`) - -.File.Ext -: the file extension of the content file (e.g., `md`); this can also be called using `.File.Extension` as well. Note that it is *only* the extension without `.`. - -.File.Lang -: the language associated with the given file if Hugo's [Multilingual features][multilingual] are enabled (e.g., `en`) - -.File.Dir -: given the path `content/posts/dir1/dir2/`, the relative directory path of the content file will be returned (e.g., `posts/dir1/dir2/`) - -[Multilingual]: /content-management/multilingual/ \ No newline at end of file diff --git a/content/variables/git.md b/content/variables/git.md deleted file mode 100644 index f9c15476..00000000 --- a/content/variables/git.md +++ /dev/null @@ -1,58 +0,0 @@ ---- -title: Git Info Variables -linktitle: Git Variables -description: Get the last Git revision information for every content file. -date: 2017-03-12 -publishdate: 2017-03-12 -lastmod: 2017-03-12 -categories: [variables and params] -keywords: [git] -draft: false -menu: - docs: - parent: "variables" - weight: 70 -weight: 70 -sections_weight: 70 -aliases: [/extras/gitinfo/] -toc: false -wip: false ---- - -{{% note "`.GitInfo` Performance Considerations" %}} -Hugo's Git integrations should be fairly performant but *can* increase your build time. This will depend on the size of your Git history. -{{% /note %}} - -## `.GitInfo` Prerequisites - -1. The Hugo site must be in a Git-enabled directory. -2. The Git executable must be installed and in your system `PATH`. -3. The `.GitInfo` feature must be enabled in your Hugo project by passing `--enableGitInfo` flag on the command line or by setting `enableGitInfo` to `true` in your [site's configuration file][configuration]. - -## The `.GitInfo` Object - -The `GitInfo` object contains the following fields: - -.AbbreviatedHash -: the abbreviated commit hash (e.g., `866cbcc`) - -.AuthorName -: the author's name, respecting `.mailmap` - -.AuthorEmail -: the author's email address, respecting `.mailmap` - -.AuthorDate -: the author date - -.Hash -: the commit hash (e.g., `866cbccdab588b9908887ffd3b4f2667e94090c3`) - -.Subject -: commit message subject (e.g., `tpl: Add custom index function`) - -## `.Lastmod` - -If the `.GitInfo` feature is enabled, **and** if the `lastmod` field in the content's front matter is not set, `.Lastmod` (on `Page`) is fetched from Git i.e. `.GitInfo.AuthorDate`. - -[configuration]: /getting-started/configuration/ diff --git a/content/variables/hugo.md b/content/variables/hugo.md deleted file mode 100644 index c0c5c960..00000000 --- a/content/variables/hugo.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -title: Hugo-specific Variables -linktitle: Hugo Variables -description: The `.Hugo` variable provides easy access to Hugo-related data. -date: 2017-03-12 -publishdate: 2017-03-12 -lastmod: 2017-03-12 -categories: [variables and params] -keywords: [hugo,generator] -draft: false -menu: - docs: - parent: "variables" - weight: 60 -weight: 60 -sections_weight: 60 -aliases: [] -toc: false -wip: false ---- - -It contains the following fields: - -.Hugo.Generator -: `` tag for the version of Hugo that generated the site. `.Hugo.Generator` outputs a *complete* HTML tag; e.g. `` - -.Hugo.Version -: the current version of the Hugo binary you are using e.g. `0.13-DEV`
    - -.Hugo.CommitHash -: the git commit hash of the current Hugo binary e.g. `0e8bed9ccffba0df554728b46c5bbf6d78ae5247` - -.Hugo.BuildDate -: the compile date of the current Hugo binary formatted with RFC 3339 e.g. `2002-10-02T10:00:00-05:00`
    - -{{% note "Use the Hugo Generator Tag" %}} -We highly recommend using `.Hugo.Generator` in your website's ``. `.Hugo.Generator` is included by default in all themes hosted on [themes.gohugo.io](http://themes.gohugo.io). The generator tag allows the Hugo team to track the usage and popularity of Hugo. -{{% /note %}} - diff --git a/content/variables/menus.md b/content/variables/menus.md deleted file mode 100644 index 4216d976..00000000 --- a/content/variables/menus.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Menu Variables -linktitle: Menu Variables -description: A menu entry in a menu template has specific variables and functions to make menu management easier. -date: 2017-03-12 -publishdate: 2017-03-12 -lastmod: 2017-03-12 -categories: [variables and params] -keywords: [menus] -draft: false -menu: - docs: - title: "variables defined by a menu entry" - parent: "variables" - weight: 50 -weight: 50 -sections_weight: 50 -aliases: [/variables/menu/] -toc: false ---- - -The [menu template][] has the following properties: - -.URL -: string - -.Name -: string - -.Title -: string - -This is a link title, meant to be used in `title`-Attributes of the menu's ``-tags. -By default it returns `.Page.LinkTitle`, as long as the menu entry was created -through the page's front matter and not through the site config. -Setting it explicitly in the site config or the page's front matter overrides this behaviour. - -.Page -: [Page Object](/variables/page/) - -The `.Page` variable holds a reference to the page. -It's only set when the menu entry is created from the page's front matter, -not when it's created from the site config. - - -.Menu -: string - -.Identifier -: string - -.Pre -: template.HTML - -.Post -: template.HTML - -.Weight -: int - -.Parent -: string - -.Children -: Menu - -[menu template]: /templates/menu-templates/ diff --git a/content/variables/page.md b/content/variables/page.md deleted file mode 100644 index f3a50d21..00000000 --- a/content/variables/page.md +++ /dev/null @@ -1,286 +0,0 @@ ---- -title: Page Variables -linktitle: -description: Page-level variables are defined in a content file's front matter, derived from the content's file location, or extracted from the content body itself. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [variables and params] -keywords: [pages] -draft: false -menu: - docs: - title: "variables defined by a page" - parent: "variables" - weight: 20 -weight: 20 -sections_weight: 20 -aliases: [/variables/page/] -toc: true ---- - -The following is a list of page-level variables. Many of these will be defined in the front matter, derived from file location, or extracted from the content itself. - -{{% note "`.Scratch`" %}} -See [`.Scratch`](/functions/scratch/) for page-scoped, writable variables. -{{% /note %}} - -## Page Variables - -.AlternativeOutputFormats -: contains all alternative formats for a given page; this variable is especially useful `link rel` list in your site's ``. (See [Output Formats](/templates/output-formats/).) - -.Content -: the content itself, defined below the front matter. - -.Data -: the data specific to this type of page. - -.Date -: the date associated with the page; `.Date` pulls from the `date` field in a content's front matter. See also `.ExpiryDate`, `.PublishDate`, and `.Lastmod`. - -.Description -: the description for the page. - -.Dir -: the path of the folder containing this content file. The path is relative to the `content` folder. - -.Draft -: a boolean, `true` if the content is marked as a draft in the front matter. - -.ExpiryDate -: the date on which the content is scheduled to expire; `.ExpiryDate` pulls from the `expirydate` field in a content's front matter. See also `.PublishDate`, `.Date`, and `.Lastmod`. - -.File -: filesystem-related data for this content file. See also [File Variables][]. - -.FuzzyWordCount -: the approximate number of words in the content. - -.Hugo -: see [Hugo Variables](/variables/hugo/). - -.IsHome -: `true` in the context of the [homepage](/templates/homepage/). - -.IsNode -: always `false` for regular content pages. - -.IsPage -: always `true` for regular content pages. - -.IsTranslated -: `true` if there are translations to display. - -.Keywords -: the meta keywords for the content. - -.Kind -: the page's *kind*. Possible return values are `page`, `home`, `section`, `taxonomy`, or `taxonomyTerm`. Note that there are also `RSS`, `sitemap`, `robotsTXT`, and `404` kinds, but these are only available during the rendering of each of these respective page's kind and therefore *not* available in any of the `Pages` collections. - -.Lang -: language taken from the language extension notation. - -.Language -: a language object that points to the language's definition in the site -`config`. - -.Lastmod -: the date the content was last modified. `.Lastmod` pulls from the `lastmod` field in a content's front matter. - - - If `lastmod` is not set, and `.GitInfo` feature is disabled, the front matter `date` field will be used. - - If `lastmod` is not set, and `.GitInfo` feature is enabled, `.GitInfo.AuthorDate` will be used instead. - -See also `.ExpiryDate`, `.Date`, `.PublishDate`, and [`.GitInfo`][gitinfo]. - -.LinkTitle -: access when creating links to the content. If set, Hugo will use the `linktitle` from the front matter before `title`. - -.Next -: pointer to the following content (based on the `publishdate` field in front matter). - -.NextInSection -: pointer to the following content within the same section (based on `publishdate` field in front matter). - -.OutputFormats -: contains all formats, including the current format, for a given page. Can be combined the with [`.Get` function](/functions/get/) to grab a specific format. (See [Output Formats](/templates/output-formats/).) - -.Pages -: a collection of associated pages. This value will be `nil` for regular content pages. `.Pages` is an alias for `.Data.Pages`. - -.Permalink -: the Permanent link for this page; see [Permalinks](/content-management/urls/) - -.Plain -: the Page content stripped of HTML tags and presented as a string. - -.PlainWords -: the Page content stripped of HTML as a `[]string` using Go's [`strings.Fields`](https://golang.org/pkg/strings/#Fields) to split `.Plain` into a slice. - -.Prev -: Pointer to the previous content (based on `publishdate` in front matter). - -.PrevInSection -: Pointer to the previous content within the same section (based on `publishdate` in front matter). For example, `{{if .PrevInSection}}{{.PrevInSection.Permalink}}{{end}}`. - -.PublishDate -: the date on which the content was or will be published; `.Publishdate` pulls from the `publishdate` field in a content's front matter. See also `.ExpiryDate`, `.Date`, and `.Lastmod`. - -.RSSLink -: link to the taxonomies' RSS link. - -.RawContent -: raw markdown content without the front matter. Useful with [remarkjs.com]( -http://remarkjs.com) - -.ReadingTime -: the estimated time, in minutes, it takes to read the content. - -.Ref -: returns the permalink for a given reference (e.g., `.Ref "sample.md"`). `.Ref` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). - -.RelPermalink -: the relative permanent link for this page. - -.RelRef -: returns the relative permalink for a given reference (e.g., `RelRef -"sample.md"`). `.RelRef` does *not* handle in-page fragments correctly. See [Cross References](/content-management/cross-references/). - -.Site -: see [Site Variables](/variables/site/). - -.Summary -: a generated summary of the content for easily showing a snippet in a summary view. The breakpoint can be set manually by inserting <!--more--> at the appropriate place in the content page. See [Content Summaries](/content-management/summaries/) for more details. - -.TableOfContents -: the rendered [table of contents](/content-management/toc/) for the page. - -.Title -: the title for this page. - -.Translations -: a list of translated versions of the current page. See [Multilingual Mode](/content-management/multilingual/) for more information. - -.Truncated -: a boolean, `true` if the `.Summary` is truncated. Useful for showing a "Read more..." link only when necessary. See [Summaries](/content-management/summaries/) for more information. - -.Type -: the [content type](/content-management/types/) of the content (e.g., `post`). - -.URL -: the URL for the page relative to the web root. Note that a `url` set directly in front matter overrides the default relative URL for the rendered page. - -.UniqueID -: the MD5-checksum of the content file's path. - -.Weight -: assigned weight (in the front matter) to this content, used in sorting. - -.WordCount -: the number of words in the content. - -## Section Variables and Methods - -Also see [Sections](/content-management/sections/). - -{{< readfile file="/content/readfiles/sectionvars.md" markdown="true" >}} - -## Page-level Params - -Any other value defined in the front matter in a content file, including taxonomies, will be made available as part of the `.Params` variable. - -``` ---- -title: My First Post -date: 2017-02-20T15:26:23-06:00 -categories: [one] -tags: [two,three,four] -``` - -With the above front matter, the `tags` and `categories` taxonomies are accessible via the following: - -* `.Params.tags` -* `.Params.categories` - -{{% note "Casing of Params" %}} -Page-level `.Params` are *only* accessible in lowercase. -{{% /note %}} - -The `.Params` variable is particularly useful for the introduction of user-defined front matter fields in content files. For example, a Hugo website on book reviews could have the following front matter in `/content/review/book01.md`: - -``` ---- -... -affiliatelink: "http://www.my-book-link.here" -recommendedby: "My Mother" -... ---- -``` - -These fields would then be accessible to the `/themes/yourtheme/layouts/review/single.html` template through `.Params.affiliatelink` and `.Params.recommendedby`, respectively. - -Two common situations where this type of front matter field could be introduced is as a value of a certain attribute like `href=""` or by itself to be displayed as text to the website's visitors. - -{{< code file="/themes/yourtheme/layouts/review/single.html" >}} -

    Buy this book

    -

    It was recommended by {{ .Params.recommendedby }}.

    -{{< /code >}} - -This template would render as follows, assuming you've set [`uglyURLs`](/content-management/urls/) to `false` in your [site `config`](/getting-started/configuration/): - -{{< output file="yourbaseurl/review/book01/index.html" >}} -

    Buy this book

    -

    It was recommended by my Mother.

    -{{< /output >}} - -{{% note %}} -See [Archetypes](/content-management/archetypes/) for consistency of `Params` across pieces of content. -{{% /note %}} - -### The `.Param` Method - -In Hugo, you can declare params in individual pages and globally for your entire website. A common use case is to have a general value for the site param and a more specific value for some of the pages (i.e., a header image): - -``` -{{ $.Param "header_image" }} -``` - -The `.Param` method provides a way to resolve a single value according to it's definition in a page parameter (i.e. in the content's front matter) or a site parameter (i.e., in your `config`). - -### Access Nested Fields in Front Matter - -When front matter contains nested fields like the following: - -``` ---- -author: - given_name: John - family_name: Feminella - display_name: John Feminella ---- -``` -`.Param` can access these fields by concatenating the field names together with a dot: - -``` -{{ $.Param "author.display_name" }} -``` - -If your front matter contains a top-level key that is ambiguous with a nested key, as in the following case: - -``` ---- -favorites.flavor: vanilla -favorites: - flavor: chocolate ---- -``` - -The top-level key will be preferred. Therefore, the following method, when applied to the previous example, will print `vanilla` and not `chocolate`: - -``` -{{ $.Param "favorites.flavor" }} -=> vanilla -``` - -[gitinfo]: /variables/git/ -[File Variables]: /variables/files/ diff --git a/content/variables/shortcodes.md b/content/variables/shortcodes.md deleted file mode 100644 index b194eb7d..00000000 --- a/content/variables/shortcodes.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Shortcode Variables -linktitle: Shortcode Variables -description: Shortcodes can access page variables and also have their own specific built-in variables. -date: 2017-03-12 -publishdate: 2017-03-12 -lastmod: 2017-03-12 -categories: [variables and params] -keywords: [shortcodes] -draft: false -menu: - docs: - parent: "variables" - weight: 20 -weight: 20 -sections_weight: 20 -aliases: [] -toc: false ---- - -[Shortcodes][shortcodes] have access to parameters delimited in the shortcode declaration via [`.Get`][getfunction], page- and site-level variables, and also the following shortcode-specific fields: - -.Parent -: provides access to the parent shortcode context in nested shortcodes. This can be very useful for inheritance of common shortcode parameters from the root. - -.IsNamedParams -: boolean that returns `true` when the shortcode in question uses [named rather than positional parameters][shortcodes] - -.Inner -: represents the content between the opening and closing shortcode tags when a [closing shortcode][markdownshortcode] is used - -[getfunction]: /functions/get/ -[markdownshortcode]: /content-management/shortcodes/#shortcodes-with-markdown -[shortcodes]: /templates/shortcode-templates/ - - diff --git a/content/variables/site.md b/content/variables/site.md deleted file mode 100644 index a5909a56..00000000 --- a/content/variables/site.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -title: Site Variables -linktitle: Site Variables -description: Many, but not all, site-wide variables are defined in your site's configuration. However, Hugo provides a number of built-in variables for convenient access to global values in your templates. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [variables and params] -keywords: [global,site] -draft: false -menu: - docs: - parent: "variables" - weight: 10 -weight: 10 -sections_weight: 10 -aliases: [/variables/site-variables/] -toc: true ---- - -The following is a list of site-level (aka "global") variables. Many of these variables are defined in your site's [configuration file][config], whereas others are built into Hugo's core for convenient usage in your templates. - -## Site Variables List - -.Site.AllPages -: array of all pages, regardless of their translation. - -.Site.Author -: a map of the authors as defined in the site configuration. - -.Site.BaseURL -: the base URL for the site as defined in the site configuration. - -.Site.BuildDrafts -: a boolean (default: `false`) to indicate whether to build drafts as defined in the site configuration. - -.Site.Copyright -: a string representing the copyright of your website as defined in the site configuration. - -.Site.Data -: custom data, see [Data Templates](/templates/data-templates/). - -.Site.DisqusShortname -: a string representing the shortname of the Disqus shortcode as defined in the site configuration. - -.Site.Files -: all source files for the Hugo website. - -.Site.GoogleAnalytics -: a string representing your tracking code for Google Analytics as defined in the site configuration. - -.Site.IsMultiLingual -: whether there are more than one language in this site. See [Multilingual](/content-management/multilingual/) for more information. - -.Site.IsServer -: a boolean to indicate if the site is being served with Hugo's built-in server. See [`hugo server`](/commands/hugo_server/) for more information. - -.Site.Language.Lang -: the language code of the current locale (e.g., `en`). - -.Site.Language.LanguageName -: the full language name (e.g. `English`). - -.Site.Language.Weight -: the weight that defines the order in the `.Site.Languages` list. - -.Site.Language -: indicates the language currently being used to render the website. This object's attributes are set in site configurations' language definition. - -.Site.LanguageCode -: a string representing the language as defined in the site configuration. This is mostly used to populate the RSS feeds with the right language code. - -.Site.LanguagePrefix -: this can be used to prefix URLs to point to the correct language. It will even work when only one defined language. See also the functions [absLangURL](/functions/abslangurl/) and [relLangURL](/functions/rellangurl). - -.Site.Languages -: an ordered list (ordered by defined weight) of languages. - -.Site.LastChange -: a string representing the date/time of the most recent change to your site. This string is based on the [`date` variable in the front matter](/content-management/front-matter) of your content pages. - -.Site.Menus -: all of the menus in the site. - -.Site.Pages -: array of all content ordered by Date with the newest first. This array contains only the pages in the current language. - -.Site.Permalinks -: a string to override the default [permalink](/content-management/urls/) format as defined in the site configuration. - -.Site.RegularPages -: a shortcut to the *regular* page collection. `.Site.RegularPages` is equivalent to `where .Site.Pages "Kind" "page"`. - -.Site.RSSLink -: the URL for the site RSS. - -.Site.Sections -: top-level directories of the site. - -.Site.Taxonomies -: the [taxonomies](/taxonomies/usage/) for the entire site. Replaces the now-obsolete `.Site.Indexes` since v0.11. Also see section [Taxonomies elsewhere](#taxonomies-elsewhere). - -.Site.Title -: a string representing the title of the site. - -## The `.Site.Params` Variable - -`.Site.Params` is a container holding the values from the `params` section of your site configuration. - -### Example: `.Site.Params` - -The following `config.[yaml|toml|json]` defines a site-wide param for `description`: - -{{< code-toggle file="config" >}} -baseURL = "https://yoursite.example.com/" - -[params] - description = "Tesla's Awesome Hugo Site" - author = "Nikola Tesla" -{{}} - -You can use `.Site.Params` in a [partial template](/templates/partials/) to call the default site description: - -{{< code file="layouts/partials/head.html" >}} - -{{< /code >}} - -[config]: /getting-started/configuration/ diff --git a/content/variables/sitemap.md b/content/variables/sitemap.md deleted file mode 100644 index dd926f2b..00000000 --- a/content/variables/sitemap.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -title: Sitemap Variables -linktitle: Sitemap Variables -description: -date: 2017-03-12 -publishdate: 2017-03-12 -lastmod: 2017-03-12 -categories: [variables and params] -keywords: [sitemap] -draft: false -menu: - docs: - parent: "variables" - weight: 80 -weight: 80 -sections_weight: 80 -aliases: [] -toc: false ---- - -A sitemap is a `Page` and therefore has all the [page variables][pagevars] available to use sitemap templates. They also have the following sitemap-specific variables available to them: - -.Sitemap.ChangeFreq -: the page change frequency - -.Sitemap.Priority -: the priority of the page - -.Sitemap.Filename -: the sitemap filename - -[pagevars]: /variables/page/ \ No newline at end of file diff --git a/content/variables/taxonomy.md b/content/variables/taxonomy.md deleted file mode 100644 index 5bcdffee..00000000 --- a/content/variables/taxonomy.md +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: Taxonomy Variables -linktitle: -description: Taxonomy pages are of type `Page` and have all page-, site-, and list-level variables available to them. However, taxonomy terms templates have additional variables available to their templates. -date: 2017-02-01 -publishdate: 2017-02-01 -lastmod: 2017-02-01 -categories: [variables and params] -keywords: [taxonomies,terms] -draft: false -menu: - docs: - parent: "variables" - weight: 30 -weight: 30 -sections_weight: 30 -aliases: [] -toc: true ---- - -## Taxonomy Terms Page Variables - -[Taxonomy terms pages][taxonomytemplates] are of the type `Page` and have the following additional variables. - -For example, the following fields would be available in `layouts/_defaults/terms.html`, depending on how you organize your [taxonomy templates][taxonomytemplates]: - -.Data.Singular -: The singular name of the taxonomy (e.g., `tags => tag`) - -.Data.Plural -: The plural name of the taxonomy (e.g., `tags => tags`) - -.Data.Pages -: The list of pages in the taxonomy - -.Data.Terms -: The taxonomy itself - -.Data.Terms.Alphabetical -: The taxonomy terms alphabetized - -.Data.Terms.ByCount -: The Terms ordered by popularity - -Note that `.Data.Terms.Alphabetical` and `.Data.Terms.ByCount` can also be reversed: - -* `.Data.Terms.Alphabetical.Reverse` -* `.Data.Terms.ByCount.Reverse` - -## Use `.Site.Taxonomies` Outside of Taxonomy Templates - -The `.Site.Taxonomies` variable holds all the taxonomies defined site-wide. `.Site.Taxonomies` is a map of the taxonomy name to a list of its values (e.g., `"tags" -> ["tag1", "tag2", "tag3"]`). Each value, though, is not a string but rather a *Taxonomy variable*. - -## The `.Taxonomy` Variable - -The `.Taxonomy` variable, available, for example, as `.Site.Taxonomies.tags`, contains the list of tags (values) and, for each tag, their corresponding content pages. - -### Example Usage of `.Site.Taxonomies` - -The following [partial template][partials] will list all your site's taxonomies, each of their keys, and all the content assigned to each of the keys. For more examples of how to order and render your taxonomies, see [Taxonomy Templates][taxonomytemplates]. - -{{< code file="all-taxonomies-keys-and-pages.html" download="all-taxonomies-keys-and-pages.html" >}} -
    -
      - {{ range $taxonomyname, $taxonomy := .Site.Taxonomies }} -
    • {{ $taxonomyname }} -
        - {{ range $key, $value := $taxonomy }} -
      • {{ $key }}
        • - - {{ end }} -
      -
      • - {{ end }} -
    -
    -{{< /code >}} - -[partials]: /templates/partials/ -[taxonomytemplates]: /templates/taxonomy-templates/ diff --git a/content/zh/_index.md b/content/zh/_index.md new file mode 100644 index 00000000..78f9ef15 --- /dev/null +++ b/content/zh/_index.md @@ -0,0 +1,49 @@ +--- +title: "世界上最快的网站构建框架 The world’s fastest framework for building websites" +date: 2017-03-02T12:00:00-05:00 +features: + - heading: Blistering Speed + image_path: /images/icon-fast.svg + tagline: What's modern about waiting for your site to build? + copy: Hugo is the fastest tool of its kind. At <1 ms per page, the average site builds in less than a second. + + - heading: Robust Content Management + image_path: /images/icon-content-management.svg + tagline: Flexibility rules. Hugo is a content strategist's dream. + copy: Hugo supports unlimited content types, taxonomies, menus, dynamic API-driven content, and more, all without plugins. + + - heading: Shortcodes + image_path: /images/icon-shortcodes.svg + tagline: Hugo's shortcodes are Markdown's hidden superpower. + copy: We love the beautiful simplicity of markdown’s syntax, but there are times when we want more flexibility. Hugo shortcodes allow for both beauty and flexibility. + + - heading: Built-in Templates + image_path: /images/icon-built-in-templates.svg + tagline: Hugo has common patterns to get your work done quickly. + copy: Hugo ships with pre-made templates to make quick work of SEO, commenting, analytics and other functions. One line of code, and you're done. + + - heading: Multilingual and i18n + image_path: /images/icon-multilingual2.svg + tagline: Polyglot baked in. + copy: Hugo provides full i18n support for multi-language sites with the same straightforward development experience Hugo users love in single-language sites. + + - heading: Custom Outputs + image_path: /images/icon-custom-outputs.svg + 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" + cta: Check out the Hugo's themes. + link: http://themes.gohugo.io/ + color_classes: bg-accent-color white + image: /images/homepage-screenshot-hugo-themes.jpg + copy: "Hugo provides a robust theming system that is easy to implement but capable of producing even the most complicated websites." + - heading: "Capable Templating" + cta: Get Started. + link: templates/ + color_classes: bg-primary-color-light black + image: /images/home-page-templating-example.png + copy: "Hugo's Go-based templating provides just the right amount of logic to build anything from the simple to complex. If you prefer Jade/Pug-like syntax, you can also use Amber, Ace, or any combination of the three." +--- + +Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again. diff --git a/content/zh/about/_index.md b/content/zh/about/_index.md new file mode 100644 index 00000000..bf19807d --- /dev/null +++ b/content/zh/about/_index.md @@ -0,0 +1,20 @@ +--- +title: 关于 Hugo +linktitle: 概览 +description: Hugo 的特色、规划、许可和动力。 +date: 2018-04-26 +publishdate: 2018-04-26 +lastmod: 2018-04-26 +categories: [] +keywords: [] +menu: + docs: + parent: "about" + weight: 1 +weight: 1 +draft: false +aliases: [/about-hugo/,/docs/] +toc: false +--- + +Hugo 不是一般的静态网站生成器。 diff --git a/content/zh/content-management/_index.md b/content/zh/content-management/_index.md new file mode 100644 index 00000000..8c088dc5 --- /dev/null +++ b/content/zh/content-management/_index.md @@ -0,0 +1,21 @@ +--- +title: 内容管理 +linktitle: 内容管理概览 +description: Hugo 可以管理大型的静态网站，支持骨架、内容类型、菜单、引用、概要等等。 +date: 2018-04-23 +publishdate: 2018-04-23 +lastmod: 2018-04-23 +menu: + docs: + parent: "content-management" + weight: 1 +keywords: [source, organization] +categories: [content management] +weight: 01 #rem +draft: false +aliases: [/content/,/content/organization] +toc: false +isCJKLanguage: true +--- + +一个实用的静态网站生成器，需要超越“文件头” (front matter) 和模板的等基本功能，才能兼备可伸缩性和可管理性，满足用户所需。Hugo 不仅是给开发者设计的，也同样适用于内容管理员和写作人员。 diff --git a/content/zh/documentation.md b/content/zh/documentation.md new file mode 100644 index 00000000..1639bbcd --- /dev/null +++ b/content/zh/documentation.md @@ -0,0 +1,21 @@ +--- +title: Hugo 说明文档 +linktitle: Hugo +description: Hugo is the world's fastest static website engine. It's written in Go (aka Golang) and developed by bep, spf13 and friends. +date: 2017-02-01 +publishdate: 2017-02-01 +menu: + main: + parent: "section name" + weight: 01 +weight: 01 #rem +draft: false +slug: +aliases: [] +toc: false +layout: documentation-home +isCJKLanguage: true +--- +Hugo 号称**世界上最快的静态网站引擎**。它是以 Go (即 Golang) 编程语言所写成，并由 [bep](https://github.com/bep)、[spf13](https://github.com/spf13) 和[朋友们](https://github.com/gohugoio/hugo/graphs/contributors) 共同开发。 + +下面是我们说明文档中最常用和实用的章节： diff --git a/content/zh/news/_index.md b/content/zh/news/_index.md new file mode 100644 index 00000000..286d32e1 --- /dev/null +++ b/content/zh/news/_index.md @@ -0,0 +1,4 @@ +--- +title: "Hugo 新闻" +aliases: [/release-notes/] +--- diff --git a/content/zh/templates/_index.md b/content/zh/templates/_index.md new file mode 100644 index 00000000..3cd8df43 --- /dev/null +++ b/content/zh/templates/_index.md @@ -0,0 +1,19 @@ +--- +title: 模板 Templates +linktitle: 模板概览 +description: Go templating, template types and lookup order, shortcodes, and data. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +menu: + docs: + parent: "templates" + weight: 01 +weight: 01 #rem +categories: [templates] +keywords: [] +draft: false +aliases: [/templates/overview/,/templates/content] +toc: false +notesforauthors: +--- diff --git a/content/zh/templates/base.md b/content/zh/templates/base.md new file mode 100644 index 00000000..8f98cfdf --- /dev/null +++ b/content/zh/templates/base.md @@ -0,0 +1,132 @@ +--- +title: Base 模板 and Blocks +linktitle: +description: The base and block constructs allow you to define the outer shell of your master templates (i.e., the chrome of the page). +godocref: https://golang.org/pkg/text/template/#example_Template_block +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates,fundamentals] +keywords: [blocks,base] +menu: + docs: + parent: "templates" + weight: 20 +weight: 20 +sections_weight: 20 +draft: false +aliases: [/templates/blocks/,/templates/base-templates-and-blocks/] +toc: true +--- + +The `block` keyword allows you to define the outer shell of your pages' one or more master template(s) and then fill in or override portions as necessary. + +{{< youtube QVOMCYitLEc >}} + +## Base Template Lookup Order + +The [lookup order][lookup] for base templates is as follows: + +1. `/layouts/section/-baseof.html` +2. `/themes//layouts/section/-baseof.html` +3. `/layouts//baseof.html` +4. `/themes//layouts//baseof.html` +5. `/layouts/section/baseof.html` +6. `/themes//layouts/section/baseof.html` +7. `/layouts/_default/-baseof.html` +8. `/themes//layouts/_default/-baseof.html` +9. `/layouts/_default/baseof.html` +10. `/themes//layouts/_default/baseof.html` + +Variables are denoted by capitalized text set within `<>`. Note that Hugo's default behavior is for `type` to inherit from `section` unless otherwise specified. + +### Example Base Template Lookup Order + +As an example, let's assume your site is using a theme called "mytheme" when rendering the section list for a `post` section. Hugo picks `layout/section/post.html` as the template for [rendering the section][]. The `{{define}}` block in this template tells Hugo that the template is an extension of a base template. + +Here is the lookup order for the `post` base template: + +1. `/layouts/section/post-baseof.html` +2. `/themes/mytheme/layouts/section/post-baseof.html` +3. `/layouts/post/baseof.html` +4. `/themes/mytheme/layouts/post/baseof.html` +5. `/layouts/section/baseof.html` +6. `/themes/mytheme/layouts/section/baseof.html` +7. `/layouts/_default/post-baseof.html` +8. `/themes/mytheme/layouts/_default/post-baseof.html` +9. `/layouts/_default/baseof.html` +10. `/themes/mytheme/layouts/_default/baseof.html` + +## Define the Base Template + +The following defines a simple base template at `_default/baseof.html`. As a default template, it is the shell from which all your pages will be rendered unless you specify another `*baseof.html` closer to the beginning of the lookup order. + +{{< code file="layouts/_default/baseof.html" download="baseof.html" >}} + + + + + {{ block "title" . }} + <!-- Blocks may include default content. --> + {{ .Site.Title }} + {{ end }} + + + + {{ block "main" . }} + + {{ end }} + {{ block "footer" . }} + + {{ end }} + + +{{< /code >}} + +## Override the Base Template + +From the above base template, you can define a [default list template][hugolists]. The default list template will inherit all of the code defined above and can then implement its own `"main"` block from: + +{{< code file="layouts/_default/list.html" download="list.html" >}} +{{ define "main" }} +

    Posts

    + {{ range .Data.Pages }} +
    +

    {{ .Title }}

    + {{ .Content }} +
    + {{ end }} +{{ end }} +{{< /code >}} + +This replaces the contents of our (basically empty) "main" block with something useful for the list template. In this case, we didn't define a `"title"` block, so the contents from our base template remain unchanged in lists. + +{{% warning %}} +Code that you put outside the block definitions *can* break your layout. This even includes HTML comments. For example: + +``` + +{{ define "main" }} +...your code here +{{ end }} +``` +[See this thread from the Hugo discussion forums.](https://discourse.gohugo.io/t/baseof-html-block-templates-and-list-types-results-in-empty-pages/5612/6) +{{% /warning %}} + +The following shows how you can override both the `"main"` and `"title"` block areas from the base template with code unique to your [default single page template][singletemplate]: + +{{< code file="layouts/_default/single.html" download="single.html" >}} +{{ define "title" }} + + {{ .Title }} – {{ .Site.Title }} +{{ end }} +{{ define "main" }} +

    {{ .Title }}

    + {{ .Content }} +{{ end }} +{{< /code >}} + +[hugolists]: /templates/lists +[lookup]: /templates/lookup-order/ +[rendering the section]: /templates/section-templates/ +[singletemplate]: /templates/single-page-templates/ diff --git a/netlify.toml b/netlify.toml index caf6bc3e..ee649cf6 100644 --- a/netlify.toml +++ b/netlify.toml @@ -3,7 +3,7 @@ publish = "public" command = "hugo" [context.production.environment] -HUGO_VERSION = "0.39" +HUGO_VERSION = "0.40.2" HUGO_ENV = "production" HUGO_ENABLEGITINFO = "true" @@ -11,20 +11,20 @@ HUGO_ENABLEGITINFO = "true" command = "hugo --enableGitInfo" [context.split1.environment] -HUGO_VERSION = "0.39" +HUGO_VERSION = "0.40.2" HUGO_ENV = "production" [context.deploy-preview] command = "hugo -b $DEPLOY_PRIME_URL" [context.deploy-preview.environment] -HUGO_VERSION = "0.39" +HUGO_VERSION = "0.40.2" [context.branch-deploy] command = "hugo -b $DEPLOY_PRIME_URL" [context.branch-deploy.environment] -HUGO_VERSION = "0.39" +HUGO_VERSION = "0.40.2" [context.next.environment] HUGO_ENABLEGITINFO = "true" diff --git a/resources/_gen/images/news/0.39-relnotes/featured-hugo-39-poster_hu2a1fdf8d3d53aa00bce401a32585d7ec_216872_640x0_resize_catmullrom_2.png b/resources/_gen/images/news/0.39-relnotes/featured-hugo-39-poster_hu2a1fdf8d3d53aa00bce401a32585d7ec_216872_640x0_resize_catmullrom_2.png deleted file mode 100644 index 18d992df..00000000 Binary files a/resources/_gen/images/news/0.39-relnotes/featured-hugo-39-poster_hu2a1fdf8d3d53aa00bce401a32585d7ec_216872_640x0_resize_catmullrom_2.png and /dev/null differ diff --git a/resources/_gen/images/news/0.40-relnotes/featured-hugo-40-poster_hu20c69e2a166f65e329d8fbabe8d2cc58_69238_480x0_resize_catmullrom_2.png b/resources/_gen/images/news/0.40-relnotes/featured-hugo-40-poster_hu20c69e2a166f65e329d8fbabe8d2cc58_69238_480x0_resize_catmullrom_2.png new file mode 100644 index 00000000..656e02b3 Binary files /dev/null and b/resources/_gen/images/news/0.40-relnotes/featured-hugo-40-poster_hu20c69e2a166f65e329d8fbabe8d2cc58_69238_480x0_resize_catmullrom_2.png differ diff --git a/resources/_gen/images/news/0.40-relnotes/featured-hugo-40-poster_hu20c69e2a166f65e329d8fbabe8d2cc58_69238_640x0_resize_catmullrom_2.png b/resources/_gen/images/news/0.40-relnotes/featured-hugo-40-poster_hu20c69e2a166f65e329d8fbabe8d2cc58_69238_640x0_resize_catmullrom_2.png new file mode 100644 index 00000000..0939f8d0 Binary files /dev/null and b/resources/_gen/images/news/0.40-relnotes/featured-hugo-40-poster_hu20c69e2a166f65e329d8fbabe8d2cc58_69238_640x0_resize_catmullrom_2.png differ diff --git a/resources/_gen/images/showcase/flesland-flis/featured_hue4fd3c0e7519777bd75019750a0f5391_309284_1024x512_fill_catmullrom_top_2.png b/resources/_gen/images/showcase/flesland-flis/featured_hue4fd3c0e7519777bd75019750a0f5391_309284_1024x512_fill_catmullrom_top_2.png new file mode 100644 index 00000000..755f765a Binary files /dev/null and b/resources/_gen/images/showcase/flesland-flis/featured_hue4fd3c0e7519777bd75019750a0f5391_309284_1024x512_fill_catmullrom_top_2.png differ diff --git a/resources/_gen/images/showcase/flesland-flis/featured_hue4fd3c0e7519777bd75019750a0f5391_309284_640x0_resize_catmullrom_2.png b/resources/_gen/images/showcase/flesland-flis/featured_hue4fd3c0e7519777bd75019750a0f5391_309284_640x0_resize_catmullrom_2.png new file mode 100644 index 00000000..950b2e08 Binary files /dev/null and b/resources/_gen/images/showcase/flesland-flis/featured_hue4fd3c0e7519777bd75019750a0f5391_309284_640x0_resize_catmullrom_2.png differ diff --git a/resources/_gen/images/showcase/flesland-flis/featured_hue4fd3c0e7519777bd75019750a0f5391_309284_f66ed2dc2e475b0cb21d76296890c5a2.png b/resources/_gen/images/showcase/flesland-flis/featured_hue4fd3c0e7519777bd75019750a0f5391_309284_f66ed2dc2e475b0cb21d76296890c5a2.png new file mode 100644 index 00000000..3056bc37 Binary files /dev/null and b/resources/_gen/images/showcase/flesland-flis/featured_hue4fd3c0e7519777bd75019750a0f5391_309284_f66ed2dc2e475b0cb21d76296890c5a2.png differ diff --git a/static/css/hugofont.css b/static/css/hugofont.css new file mode 100644 index 00000000..09d6ce07 --- /dev/null +++ b/static/css/hugofont.css @@ -0,0 +1,184 @@ +@font-face { + font-family: 'hugo'; + src:url('../fonts/hugo.eot'); + src:url('../fonts/hugo.eot?#iefix') format('embedded-opentype'), + url('../fonts/hugo.woff') format('woff'), + url('../fonts/hugo.ttf') format('truetype'), + url('../fonts/hugo.svg#hugo') format('svg'); + font-weight: normal; + font-style: normal; +} + +[class^="icon-"], [class*=" icon-"] { + font-family: 'hugo'; + speak: none; + font-style: normal; + font-weight: normal; + font-variant: normal; + text-transform: none; + line-height: 1; + + /* Better Font Rendering =========== */ + -webkit-font-smoothing: antialiased; + -moz-osx-font-smoothing: grayscale; +} + +.icon-home:before { + content: "\21"; +} +.icon-html5:before { + content: "\23"; +} +.icon-css3:before { + content: "\24"; +} +.icon-console:before { + content: "\25"; +} +.icon-link:before { + content: "\26"; +} +.icon-fire:before { + content: "\28"; +} +.icon-check-alt:before { + content: "\29"; +} +.icon-hugo_serif:before { + content: "\e600"; +} +.icon-x-altx-alt:before { + content: "\2a"; +} +.icon-circlestar:before { + content: "\2b"; +} +.icon-file-css:before { + content: "\2c"; +} +.icon-radio-checked:before { + content: "\2e"; +} +.icon-quote:before { + content: "\44"; +} +.icon-airplane2:before { + content: "\45"; +} +.icon-heart:before { + content: "\46"; +} +.icon-rocket:before { + content: "\47"; +} +.icon-house:before { + content: "\48"; +} +.icon-arrow-right:before { + content: "\e001"; +} +.icon-arrow-left:before { + content: "\e002"; +} +.icon-flow-branch:before { + content: "\e004"; +} +.icon-pen:before { + content: "\e005"; +} +.icon-idea:before { + content: "\3b"; +} +.icon-gears:before { + content: "\3c"; +} +.icon-talking:before { + content: "\3d"; +} +.icon-tag:before { + content: "\3e"; +} +.icon-rocket2:before { + content: "\3f"; +} +.icon-octocat:before { + content: "\41"; +} +.icon-announce:before { + content: "\42"; +} +.icon-edit:before { + content: "\43"; +} +.icon-power-cord:before { + content: "\50"; +} +.icon-apple:before { + content: "\51"; +} +.icon-windows8:before { + content: "\52"; +} +.icon-tux:before { + content: "\53"; +} +.icon-file-xml:before { + content: "\54"; +} +.icon-fork:before { + content: "\55"; +} +.icon-arrow-down:before { + content: "\56"; +} +.icon-pacman:before { + content: "\e000"; +} +.icon-embed:before { + content: "\2f"; +} +.icon-code:before { + content: "\30"; +} +.icon-cc:before { + content: "\31"; +} +.icon-cc-by:before { + content: "\32"; +} +.icon-cc-nc:before { + content: "\33"; +} +.icon-beaker-alt:before { + content: "\39"; +} +.icon-w3c:before { + content: "\3a"; +} +.icon-bolt:before { + content: "\49"; +} +.icon-flow-tree:before { + content: "\4a"; +} +.icon-twitter:before { + content: "\4b"; +} +.icon-beaker:before { + content: "\4c"; +} +.icon-images:before { + content: "\4d"; +} +.icon-bubbles:before { + content: "\4e"; +} +.icon-meter2:before { + content: "\4f"; +} +.icon-hugo_sans:before { + content: "\68"; +} +.icon-spf13:before { + content: "\27"; +} diff --git a/static/fonts/hugo.eot b/static/fonts/hugo.eot new file mode 100644 index 00000000..b92f00f9 Binary files /dev/null and b/static/fonts/hugo.eot differ diff --git a/static/fonts/hugo.svg b/static/fonts/hugo.svg new file mode 100644 index 00000000..7913f7c1 --- /dev/null +++ b/static/fonts/hugo.svg @@ -0,0 +1,63 @@ + + + +Generated by IcoMoon + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/static/fonts/hugo.ttf b/static/fonts/hugo.ttf new file mode 100644 index 00000000..962914d3 Binary files /dev/null and b/static/fonts/hugo.ttf differ diff --git a/static/fonts/hugo.woff b/static/fonts/hugo.woff new file mode 100644 index 00000000..4693fbe7 Binary files /dev/null and b/static/fonts/hugo.woff differ diff --git a/static/img/hugo-logo-med.png b/static/img/hugo-logo-med.png new file mode 100644 index 00000000..dcc14169 Binary files /dev/null and b/static/img/hugo-logo-med.png differ diff --git a/static/img/hugo-logo.png b/static/img/hugo-logo.png new file mode 100644 index 00000000..a4f1321b Binary files /dev/null and b/static/img/hugo-logo.png differ diff --git a/static/img/hugo.png b/static/img/hugo.png new file mode 100644 index 00000000..48acf346 Binary files /dev/null and b/static/img/hugo.png differ diff --git a/static/img/hugoSM.png b/static/img/hugoSM.png new file mode 100644 index 00000000..f64f4308 Binary files /dev/null and b/static/img/hugoSM.png differ diff --git a/themes/gohugoioTheme/layouts/_default/list.html b/themes/gohugoioTheme/layouts/_default/list.html index a0835342..3b7a2307 100755 --- a/themes/gohugoioTheme/layouts/_default/list.html +++ b/themes/gohugoioTheme/layouts/_default/list.html @@ -1,4 +1,5 @@ {{ define "main" }} - {{ $section_to_display := .Sections | default .Paginator.Pages }} + {{ $paginator := .Paginate (.Pages | lang.Merge (where .Sites.First.RegularPages "Section" .Section)) }} + {{ $section_to_display := .Sections | default $paginator.Pages }} {{ partial "pagelayout.html" (dict "context" . "section_to_display" $section_to_display ) }} {{ end }} diff --git a/themes/gohugoioTheme/layouts/news/list.html b/themes/gohugoioTheme/layouts/news/list.html index 716966e1..5a528465 100644 --- a/themes/gohugoioTheme/layouts/news/list.html +++ b/themes/gohugoioTheme/layouts/news/list.html @@ -28,7 +28,8 @@ {{ $interior_classes := $.Site.Params.flex_box_interior_classes }}
    - {{ range .Paginator.Pages }} + {{ $paginator := .Paginate (.Pages | lang.Merge (where .Sites.First.RegularPages "Section" .Section)) -}} + {{ range $paginator.Pages }} {{ partial "boxes-section-summaries" (dict "context" . "classes" $interior_classes "fullcontent" false) }} {{ end }}
    diff --git a/themes/gohugoioTheme/layouts/page/documentation-home.html b/themes/gohugoioTheme/layouts/page/documentation-home.html index 04b57d4c..91f744c3 100644 --- a/themes/gohugoioTheme/layouts/page/documentation-home.html +++ b/themes/gohugoioTheme/layouts/page/documentation-home.html @@ -1,4 +1,4 @@ {{ define "main" }} -{{ $section_to_display := (.Site.Taxonomies.categories.fundamentals).Pages }} +{{ $section_to_display := (.Site.Taxonomies.categories.fundamentals).Pages | lang.Merge (.Sites.First.Taxonomies.categories.fundamentals).Pages }} {{ partial "pagelayout.html" (dict "context" . "section_to_display" $section_to_display ) }} {{ end }} diff --git a/themes/gohugoioTheme/layouts/partials/home-page-sections/showcase.html b/themes/gohugoioTheme/layouts/partials/home-page-sections/showcase.html index 774c10e0..c73cfa5e 100644 --- a/themes/gohugoioTheme/layouts/partials/home-page-sections/showcase.html +++ b/themes/gohugoioTheme/layouts/partials/home-page-sections/showcase.html @@ -5,10 +5,12 @@
    {{ $showcasePages := where .Site.RegularPages "Section" "showcase" }} + {{ if $showcasePages }} {{ template "home_showcase_item" (index $showcasePages 0) }} {{ range $p := first 10 ($showcasePages | after 1 | shuffle) }} {{template "home_showcase_item" $p }} {{end}} + {{end}}
    diff --git a/themes/gohugoioTheme/layouts/partials/nav-links-docs.html b/themes/gohugoioTheme/layouts/partials/nav-links-docs.html index d695008c..61aa11dd 100644 --- a/themes/gohugoioTheme/layouts/partials/nav-links-docs.html +++ b/themes/gohugoioTheme/layouts/partials/nav-links-docs.html @@ -4,20 +4,20 @@ {{ range .Site.Menus.docs.ByWeight }} {{ $post := printf "%s" .Post }}
  • - {{ .Name }} + {{ .Name }} - {{ if .HasChildren }} - - {{end}} -
    • - {{end}} + {{- if .HasChildren }} + + {{- end}} + + {{- end}} diff --git a/themes/gohugoioTheme/theme.toml b/themes/gohugoioTheme/theme.toml index 7334c0e2..fe55ec76 100644 --- a/themes/gohugoioTheme/theme.toml +++ b/themes/gohugoioTheme/theme.toml @@ -8,7 +8,7 @@ description = "" homepage = "https://github.com/budparr/gohugo.io" tags = ["website"] features = ["", ""] -min_version = 0.18 +min_version = 0.38 [author] name = "Bud Parr"