From: Bjørn Erik Pedersen Date: Fri, 21 Jul 2017 09:00:08 +0000 (+0200) Subject: doc: Merge commit '2c0d1ccdcd95de0bddeb39dca2e4d08f0d8056d7' X-Git-Tag: v0.26~35 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=f387cb1b3;p=brevno-suite%2Fhugo doc: Merge commit '2c0d1ccdcd95de0bddeb39dca2e4d08f0d8056d7' --- f387cb1b38fe8b09e4cbca9816caaa840de55c5b diff --cc docs/README.md index 60a554e5,00000000..eba081c9 mode 100644,000000..100644 --- a/docs/README.md +++ b/docs/README.md @@@ -1,13 -1,0 +1,38 @@@ +# Hugo Docs + +Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in GoLang. + - ## Branches ++## Contributing + - * The `master` branch is the **current Hugo version** and will be auto-deployed to [gohugo.io/](https://gohugo.io/). - * Anything not relevant to the current Hugo version goes into the `dev` branch. - * Changes in [hugo/docs](https://github.com/gohugoio/hugo/tree/master/docs) will, in general, be merged once every release, but can be manually merged/cherry picked if needed. This goes both ways. - * All contributions that is not tightly coupled with code changes, should be made directly to `hugoDocs`. - * But we also merge PRs into [hugo/docs](https://github.com/gohugoio/hugo/tree/master/docs), but preferably changes that is related to the code in the PR itself ++We welcome contributions to Hugo of any kind including documentation, suggestions, bug reports, pull requests etc. Also check out our [contribution guide](https://gohugo.io/contribute/documentation/). We would love to hear from you. + - To summarize, we have two branches in this repository: `master` (current Hugo) and `dev` (next Hugo). ++Note that this repository contains solely the documentation for Hugo. For contributions that aren't documentation-related please refer to the [hugo](https://github.com/gohugoio/hugo) repository. ++ ++*Pull requests shall **only** contain changes to the actual documentation. However, changes on the code base of Hugo **and** the documentation shall be a single, atomic pull request in the [hugo](https://github.com/gohugoio/hugo) repository.* ++ ++ ++## Build ++ ++To view the documentation site locally, you need to clone this repository with submodules: ++ ++```bash ++git clone --recursive https://github.com/gohugoio/hugoDocs.git ++``` ++ ++Or if you already have a clone locally: ++ ++```bash ++git submodule update --init ++``` ++Also note that the documentation version for a given version of Hugo can also be found in the `/docs` sub-folder of the [Hugo source repository](https://github.com/gohugoio/hugo). ++ ++Then to view the docs in your browser, run Hugo and open up the link: ++```bash ++hugo serve ++Started building sites ... ++. ++. ++Serving pages from memory ++Web Server is available at http://localhost:1313/ (bind address 127.0.0.1) ++Press Ctrl+C to stop ++``` diff --cc docs/config.toml index aafb6aa0,00000000..08c72176 mode 100644,000000..100644 --- a/docs/config.toml +++ b/docs/config.toml @@@ -1,221 -1,0 +1,230 @@@ +baseURL = "https://gohugo.io/" +paginate = 100 +defaultContentLanguage = "en" +enableEmoji = true +# Set the unicode character used for the "return" link in page footnotes. +footnotereturnlinkcontents = "↩" +languageCode = "en-us" +metaDataFormat = "yaml" +title = "Hugo: A Fast and Flexible Website Generator" +theme = "gohugoioTheme" + +googleAnalytics = "UA-7131036-4" + +pluralizeListTitles = false + +# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below). +disableAliases = true + ++ ++# Highlighting config (Pygments) ++# It is (currently) not in use, but you can do ```go in a content file if you want to. ++pygmentsCodeFences = true ++ ++# See https://help.farbox.com/pygments.html ++pygmentsStyle = "friendly" ++ +[outputs] +home = [ "HTML", "RSS", "REDIR" ] ++section = [ "HTML", "RSS"] + +[mediaTypes] +[mediaTypes."text/netlify"] +suffix = "" +delimiter = "" + +[outputFormats] +[outputFormats.REDIR] +mediatype = "text/netlify" +baseName = "_redirects" +isPlainText = true +notAlternative = true + + +[social] +twitter = "GoHugoIO" + +#CUSTOM PARAMS +[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 = "Hugo-Next" + ## Setting this to true will add a "noindex" to *EVERY* page on the site + removefromexternalsearch = false + ## Gh repo for site footer (include trailing slash) + ghrepo = "https://github.com/gohugoio/hugoDocs/" + ### Edit content repo (set to automatically enter "edit" mode; this is good for "improve this page" links) + ghdocsrepo = "https://github.com/gohugoio/hugoDocs/tree/master/docs" + ## Gitter URL + gitter = "https://gitter.im/spf13/hugo" + ## Discuss Forum URL + forum = "https://discourse.gohugo.io/" + ## Google Tag Manager + gtmid = "" + + # First one is picked as the Twitter card image if not set on page. + images = ["images/gohugoio-card.png"] + + flex_box_interior_classes = "flex-auto w-100 w-40-l mr3 mb3 bg-white ba b--moon-gray nested-copy-line-height" + + #sidebar_direction = "sidebar_left" + +# MARKDOWN +## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday +[blackfriday] + plainIDAnchors = true + hrefTargetBlank = true + angledQuotes = false + latexDashes = true + +## As of v0.20, all content files include a default "categories" value that's the same as the section. This was a cheap future-proofing method and should/could be changed accordingly. +[taxonomies] + category = "categories" + +# High level items + +[[menu.docs]] + name = "About Hugo" + weight = 1 + identifier = "about" + url = "/about/" + +[[menu.docs]] + name = "Getting Started" + weight = 5 + identifier = "getting-started" + url = "/getting-started/" + + +[[menu.docs]] + name = "Themes" + weight = 15 + identifier = "themes" + post = "break" + url = "/themes/" + +# Core Menus + +[[menu.docs]] + name = "Content Management" + weight = 20 + identifier = "content-management" + post = "expanded" + url = "/content-management/" + +[[menu.docs]] + name = "Templates" + weight = 25 + identifier = "templates" + + url = "/templates/" + +[[menu.docs]] + name = "Functions" + weight = 30 + identifier = "functions" + url = "/functions/" + +[[menu.docs]] + name = "Variables" + weight = 35 + identifier = "variables" + url = "/variables/" + +[[menu.docs]] + name = "CLI" + weight = 40 + post = "break" + identifier = "commands" + url = "/commands/" + + + +# LOW LEVEL ITEMS + + +[[menu.docs]] + name = "Troubleshooting" + weight = 60 + identifier = "troubleshooting" + url = "/troubleshooting/" + +[[menu.docs]] + name = "Tools" + weight = 70 + identifier = "tools" + url = "/tools/" + +[[menu.docs]] + name = "Hosting & Deployment" + weight = 80 + identifier = "hosting-and-deployment" + url = "/hosting-and-deployment/" + +[[menu.docs]] + name = "Contribute" + weight = 100 + post = "break" + identifier = "contribute" + url = "/contribute/" + +#[[menu.docs]] +# name = "Tags" +# weight = 120 +# identifier = "tags" +# url = "/tags/" + + +# [[menu.docs]] +# name = "Categories" +# weight = 140 +# identifier = "categories" +# url = "/categories/" + +######## QUICKLINKS + + [[menu.quicklinks]] + name = "Fundamentals" + weight = 1 + identifier = "fundamentals" + url = "/tags/fundamentals/" + + + + +######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES + +[[menu.global]] + name = "News" + weight = 1 + identifier = "news" + url = "/news/" + + [[menu.global]] + name = "Docs" + weight = 5 + identifier = "docs" + url = "/documentation/" + + [[menu.global]] + name = "Themes" + weight = 10 + identifier = "themes" + url = "https://themes.gohugo.io/" + + # Anything with a weight > 100 gets an external icon + [[menu.global]] + name = "Community" + weight = 150 + icon = true + identifier = "community" + post = "external" + url = "https://discourse.gohugo.io/" + + + [[menu.global]] + name = "GitHub" + weight = 200 + identifier = "github" + post = "external" + url = "https://github.com/gohugoio/hugo" diff --cc docs/content/_index.md index f23aa99e,00000000..3f9ad64a mode 100644,000000..100644 --- a/docs/content/_index.md +++ b/docs/content/_index.md @@@ -1,49 -1,0 +1,49 @@@ +--- +title: "Hugo: A Fast and Flexible Website Generator" +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? ++ 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 --cc docs/content/about/license.md index 037e62e9,00000000..7575b79c mode 100644,000000..100644 --- a/docs/content/about/license.md +++ b/docs/content/about/license.md @@@ -1,167 -1,0 +1,165 @@@ +--- +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"] +#tags: ["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" %}} - ``` ++{{< 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 %}} ++{{< /code >}} diff --cc docs/content/content-management/archetypes.md index d6d30b3f,00000000..9fc58139 mode 100644,000000..100644 --- a/docs/content/content-management/archetypes.md +++ b/docs/content/content-management/archetypes.md @@@ -1,208 -1,0 +1,196 @@@ +--- +title: Archetypes +linktitle: Archetypes +description: Archetypes allow you to create new instances of content types and set default parameters from the command line. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +#tags: [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 +--- + +{{% note %}} +This section is outdated, see https://github.com/gohugoio/hugoDocs/issues/11 +{{% /note %}} +{{% todo %}} +See above +{{% /todo %}} + +## What are Archetypes? + +**Archetypes** are content files in the [archetypes directory][] of your project that contain preconfigured [front matter][] for your website's [content types][]. Archetypes facilitate consistent metadata across your website content and allow content authors to quickly generate instances of a content type via the `hugo new` command. + +The `hugo new` generator for archetypes assumes your working directory is the content folder at the root of your project. Hugo is able to infer the appropriate archetype by assuming the content type from the content section passed to the CLI command: + - ```bash ++``` +hugo new / +``` + +We can use this pattern to create a new `.md` file in the `posts` section: + - {{% code file="archetype-example.sh" %}} - ```bash ++{{< code file="archetype-example.sh" >}} +hugo new posts/my-first-post.md - ``` - {{% /code %}} ++{{< /code >}} + +{{% note "Override Content Type in a New File" %}} +To override the content type Hugo infers from `[content-section]`, add the `--kind` flag to the end of the `hugo new` command. +{{% /note %}} + +Running this command in a new site that does not have default or custom archetypes will create the following file: + +{{% output file="content/posts/my-first-post.md" %}} - ```toml ++``` ++++ +date = "2017-02-01T19:20:04-07:00" +title = "my first post" +draft = true ++++ +``` +{{% /output %}} + +{{% note %}} +In this example, if you do not already have a `content/posts` directory, Hugo will create both `content/posts/` and `content/posts/my-first-post.md` for you. +{{% /note %}} + +The auto-populated fields are worth examining: + +* `title` is generated from the new content's filename (i.e. in this case, `my-first-post` becomes `"my first post"`) +* `date` and `title` are the variables that ship with Hugo and are therefore included in *all* content files created with the Hugo CLI. `date` is generated in [RFC 3339 format][] by way of Go's [`now()`][] function, which returns the current time. +* The third variable, `draft = true`, is *not* inherited by your default or custom archetypes but is included in Hugo's automatically scaffolded `default.md` archetype for convenience. + +Three variables per content file are often not enough for effective content management of larger websites. Luckily, Hugo provides a simple mechanism for extending the number of variables through custom archetypes, as well as default archetypes to keep content creation DRY. + +## Lookup Order for Archetypes + +Similar to the [lookup order for templates][lookup] in your `layouts` directory, Hugo looks for a section- or type-specific archetype, then a default archetype, and finally an internal archetype that ships with Hugo. For example, Hugo will look for an archetype for `content/posts/my-first-post.md` in the following order: + +1. `archetypes/posts.md` +2. `archetypes/default.md` +3. `themes//archetypes/posts.md` +4. `themes//archetypes/default.md` (Auto-generated with `hugo new site`) + +{{% note "Using a Theme Archetype" %}} +If you wish to use archetypes that ship with a theme, the `theme` field must be specified in your [configuration file](/getting-started/configuration/). +{{% /note %}} + +## Choose Your Archetype's Front Matter Format + +By default, `hugo new` content files include front matter in the TOML format regardless of the format used in `archetypes/*.md`. + +You can specify a different default format in your site [configuration file][] file using the `metaDataFormat` directive. Possible values are `toml`, `yaml`, and `json`. + +## Default Archetypes + +Default archetypes are convenient if your content's front matter stays consistent across multiple [content sections][sections]. + +### Create the Default Archetype + +When you create a new Hugo project using `hugo new site`, you'll notice that Hugo has already scaffolded a file at `archetypes/default.md`. + +The following examples are from a site that's using `tags` and `categories` as [taxonomies][]. If we assume that all content files will require these two key-values, we can create a `default.md` archetype that *extends* Hugo's base archetype. In this example, we are including "golang" and "hugo" as tags and "web development" as a category. + - {{% code file="archetypes/default.md" %}} - ```toml ++{{< code file="archetypes/default.md" >}} ++++ +tags = ["golang", "hugo"] +categories = ["web development"] ++++ - ``` - {{% /code %}} ++{{< /code >}} + +{{% warning "EOL Characters in Text Editors"%}} +If you get an `EOF error` when using `hugo new`, add a carriage return after the closing `+++` or `---` for your TOML or YAML front matter, respectively. (See the [troubleshooting article on EOF errors](/troubleshooting/eof-error/) for more information.) +{{% /warning %}} + +### Use the Default Archetype + +With an `archetypes/default.md` in place, we can use the CLI to create a new post in the `posts` content section: + - {{% code file="new-post-from-default.sh" %}} - ```bash ++{{< code file="new-post-from-default.sh" >}} +$ hugo new posts/my-new-post.md - ``` - {{% /code %}} ++{{< /code >}} + +Hugo then creates a new markdown file with the following front matter: + +{{% output file="content/posts/my-new-post.md" %}} - ```toml ++``` ++++ +categories = ["web development"] +date = "2017-02-01T19:20:04-07:00" +tags = ["golang", "hugo"] +title = "my new post" ++++ +``` +{{% /output %}} + +We see that the `title` and `date` key-values have been added in addition to the `tags` and `categories` key-values from `archetypes/default.md`. + +{{% note "Ordering of Front Matter" %}} +You may notice that content files created with `hugo new` do not respect the order of the key-values specified in your archetype files. This is a [known issue](https://github.com/gohugoio/hugo/issues/452). +{{% /note %}} + +## Custom Archetypes + +Suppose your site's `posts` section requires more sophisticated front matter than what has been specified in `archetypes/default.md`. You can create a custom archetype for your posts at `archetypes/posts.md` that includes the full set of front matter to be added to the two default archetypes fields. + +### Create a Custom Archetype + - {{% code file="archetypes/posts.md"%}} - ```toml ++{{< code file="archetypes/posts.md">}} ++++ +description = "" +tags = "" +categories = "" ++++ - ``` - {{% /code %}} ++{{< /code >}} + +### Use a Custom Archetype + +With an `archetypes/posts.md` in place, you can use the Hugo CLI to create a new post with your preconfigured front matter in the `posts` content section: + - {{% code file="new-post-from-custom.sh" %}} - ```bash ++{{< code file="new-post-from-custom.sh" >}} +$ hugo new posts/post-from-custom.md - ``` - {{% /code %}} ++{{< /code >}} + +This time, Hugo recognizes our custom `archetypes/posts.md` archetype and uses it instead of `archetypes/default.md`. The generated file will now include the full list of front matter parameters, as well as the base archetype's `title` and `date`: + +{{% output file="content/posts/post-from-custom-archetype.md" %}} - ```toml ++``` ++++ +categories = "" +date = 2017-02-13T17:24:43-08:00 +description = "" +tags = "" +title = "post from custom archetype" ++++ +``` +{{% /output %}} + +### Hugo Docs Custom Archetype + +As an example of archetypes in practice, the following is the `functions` archetype from the Hugo docs: + - {{% code file="archetypes/functions.md" %}} - ```yaml ++{{< code file="archetypes/functions.md" >}} +{{< readfile file="/themes/gohugoioTheme/archetypes/functions.md" >}} - ``` - {{% /code %}} ++{{< /code >}} + +{{% note %}} +The preceding archetype is kept up to date with every Hugo build by using Hugo's [`readFile` function](/functions/readfile/). For similar examples, see [Local File Templates](/templates/files/). +{{% /note %}} + +[archetypes directory]: /getting-started/directory-structure/ +[`now()`]: http://golang.org/pkg/time/#Now +[configuration file]: /getting-started/configuration/ +[sections]: /content-management/sections/ +[content types]: /content-management/types/ +[front matter]: /content-management/front-matter/ +[RFC 3339 format]: https://www.ietf.org/rfc/rfc3339.txt +[taxonomies]: /content-management/taxonomies/ +[lookup]: /templates/lookup/ +[templates]: /templates/ diff --cc docs/content/content-management/authors.md index 80a78391,00000000..0a0d1799 mode 100644,000000..100644 --- a/docs/content/content-management/authors.md +++ b/docs/content/content-management/authors.md @@@ -1,193 -1,0 +1,185 @@@ +--- +title: Authors +linktitle: Authors +description: +date: 2016-08-22 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +#tags: [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" %}} - ```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 %}} ++{{< /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. + - ```yaml ++``` +--- +title: Why Hugo is so Awesome +date: 2016-08-22T14:27:502:00 +authors: ["alice"] +--- + +Nothing to read here. Move along... +``` + - ```toml ++``` ++++ +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" %}} - ```html ++{{< code file="layouts/partials/author-info.html" download="author-info.html" >}} +{{ with .Author }} +

{{ .DisplayName }}

+ {{ .DisplayName }} +

{{ .ShortBio }}

+
    + {{ range $network, $username := .Social }} +
  • {{ $network }}
    • + {{ end }} +
+{{ end }} - ``` - {{% /code %}} ++{{< /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: + - ```yaml ++``` +taxonomies: + author: authors +``` + - ```toml ++``` +[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" %}} - ```html ++{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}} + - ``` - {{% /code %}} ++{{< /code >}} + +`.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically). + +### 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" %}} - ```html ++{{< code file="layouts/taxonomy/author.html" download="author.html" >}} +{{ range .Data.Pages }} +

{{ .Title }}

+ written by {{ .Author.DisplayName }} + {{ .Summary }} +{{ end }} - ``` - {{% /code %}} ++{{< /code >}} + +The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags. + +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 --cc docs/content/content-management/comments.md index 33387e57,00000000..2db44973 mode 100644,000000..100644 --- a/docs/content/content-management/comments.md +++ b/docs/content/content-management/comments.md @@@ -1,84 -1,0 +1,84 @@@ +--- +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 +#tags: [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]. The following show the configuration variable in a `config.toml` and `config.yml`, respectively: + - ```toml ++``` +disqusShortname = "yourdiscussshortname" +``` + - ```yaml ++``` +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 --cc docs/content/content-management/cross-references.md index 9a279533,00000000..7ee81f3d mode 100644,000000..100644 --- a/docs/content/content-management/cross-references.md +++ b/docs/content/content-management/cross-references.md @@@ -1,125 -1,0 +1,123 @@@ +--- +title: 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] +#tags: ["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` + - ```md ++``` +{{}} +{{}} +{{}} +{{}} +{{}} +{{}} +``` + +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: + - ```md ++``` +{{}} => `/blog/post/` +{{}} => `/blog/post/` +``` + +If you have the same filename used across multiple sections, you should only use the relative path format; otherwise, the behavior will be `undefined`. This is best illustrated with an example `content` directory: + - ```bash ++``` +. +└── content + ├── events + │   └── 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" %}} - ```md ++{{< code file="content/meta/my-article.md" copy="false" >}} +{{}} => /events/my-birthday/ - ``` - {{% /code %}} ++{{< /code >}} + +{{< todo >}}Remove this warning when https://github.com/gohugoio/hugo/issues/3703 is released.{{< /todo >}} + +A relative document name must *not* begin with a slash (`/`). - ```md ++``` +{{}} => "" +``` + +### 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: + - ```md ++``` +{{}} => #anchors:9decaf7 +{{}} => /blog/post/#who:badcafe +``` + +The above examples render as follows for this very page as well as a reference to the "Content" heading in the Hugo docs features pageyoursite + - ```md ++``` +{{}} => #who:9decaf7 +{{}} => /blog/post/#who:badcafe +``` + +More information about document unique identifiers and headings can be found [below]({{< ref "#hugo-heading-anchors" >}}). + +### Examples + - * `{{}}` => `http://yoursite.com/blog/post/` - * `{{}}` => `http://yoursite.com/blog/post/#tldr:caffebad` ++* `{{}}` => `http://example.com/blog/post/` ++* `{{}}` => `http://example.com/blog/post/#tldr:caffebad` +* `{{}}` => `/blog/post/` +* `{{}}` => `/blog/post/#tldr:caffebad` +* `{{}}` => `#tldr:badcaffe` +* `{{}}` => `#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.) + - ```md ++``` +{{}} +/content-management/cross-references/#hugo-heading-anchors:77cd9ea530577debf4ce0f28c8dca242 +``` + + +[built-in Hugo shortcodes]: /content-management/shortcodes/#using-the-built-in-shortcodes +[lists]: /templates/lists/ +[output formats]: /templates/output-formats/ +[shortcode]: /content-management/shortcodes/ diff --cc docs/content/content-management/formats.md index ae6276db,00000000..be84e7cf mode 100644,000000..100644 --- a/docs/content/content-management/formats.md +++ b/docs/content/content-management/formats.md @@@ -1,249 -1,0 +1,241 @@@ +--- +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] +#tags: [markdown,asciidoc,mmark,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" %}} - ```markdown ++{{< code file="content/my-to-do-list.md" >}} +- [ ] a task list item +- [ ] list syntax required +- [ ] incomplete +- [x] completed - ``` - {{% /code %}} ++{{< /code >}} + +#### Example Task List Output + +The preceding markdown produces the following HTML in your rendered website: + - ```html ++``` +
    +
  • a task list item
    • +
  • list syntax required
    • +
  • 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` nested shortcode][hlsc] to render syntax highlighting via [Pygments][]. For usage examples and a complete explanation, see the [syntax highlighting documentation][hl] in [developer tools][]. + +## 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: + - ```yaml ++``` +--- +title: My Post +date: 2017-04-01 +markdown: 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 %}} ++{{< /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" %}} - ```js ++{{< code file="mathjax-markdown-solution.html" >}} + + + - ``` - {{% /code %}} ++{{< /code >}} + + + +As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page. + - {{% code file="mathjax-style.css" %}} - ```css ++{{< code file="mathjax-style.css" >}} +code.has-jax { + font: inherit; + font-size: 100%; + background: inherit; + border: inherit; + color: #515151; +} - ``` - {{% /code %}} ++{{< /code >}} + +In the CSS snippet, notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my CSS. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body. + +### 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 new concept called _external helpers_. It means that you can write your content using [Asciidoc][ascii], [reStructuredText][rest]. 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. + +{{% 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://asciidoc.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]: /tools/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/ +[Pygments]: http://pygments.org/ +[rest]: http://docutils.sourceforge.net/rst.html +[sc]: /content-management/shortcodes/ +[sct]: /templates/shortcode-templates/ diff --cc docs/content/content-management/front-matter.md index 104050cf,00000000..07032867 mode 100644,000000..100644 --- a/docs/content/content-management/front-matter.md +++ b/docs/content/content-management/front-matter.md @@@ -1,198 -1,0 +1,198 @@@ +--- +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] +#tags: ["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. + +## 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. + +### TOML Example + - ```toml ++``` ++++ +title = "spf13-vim 3.0 release and new website" +description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." +tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] +date = "2012-04-06" +categories = [ + "Development", + "VIM" +] +slug = "spf13-vim-3-0-release-and-new-website" ++++ +``` + +### YAML Example + - ```yaml ++``` +--- +title: "spf13-vim 3.0 release and new website" +description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." +#tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ] +lastmod: 2015-12-23 +date: "2012-04-06" +categories: + - "Development" + - "VIM" +slug: "spf13-vim-3-0-release-and-new-website" +--- +``` + +### JSON Example + - ```json ++``` +{ + "title": "spf13-vim 3.0 release and new website", + "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.", + "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. + +`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`. + +`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. + +`taxonomies` +: these will use the field name of the plural form of the index; see the `tags` and `categories` in the above front matter examples. + +`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]. + +{{% 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. + - ```yaml ++``` +include_toc: true +show_comments: false +``` + +These two user-defined fields can then be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][variables] section provides more information on using Hugo's page- and site-level variables in your templates. + + +## 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" +[json]: /documents/ecma-404-json-spec.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" +[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 --cc docs/content/content-management/menus.md index ddcf3002,00000000..7c877afc mode 100644,000000..100644 --- a/docs/content/content-management/menus.md +++ b/docs/content/content-management/menus.md @@@ -1,183 -1,0 +1,179 @@@ +--- +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] +#tags: [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-blogger). +{{% /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 + - ```yaml ++``` +--- +menu: "main" +--- +``` + +#### Multiple Menus + - ```yaml ++``` +--- +menu: ["main", "footer"] +--- +``` + +#### Advanced + + - ```yaml ++``` +--- +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 `config.toml`: + - {{% code file="config.toml" %}} - ```toml ++{{< code 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 %}} ++{{< /code >}} + +Here's the equivalent snippet in a `config.yaml`: + - {{% code file="config.yml" %}} - ```yaml ++{{< code file="config.yml" >}} +--- +menu: + docs: + - Name: "about hugo" + Pre: "" + Weight: -110 + Identifier: "about" + URL: "/about/" + - Name: "getting started" + Pre: "" + Weight: -100 + URL: "/getting-started/" +--- - ``` - {{% /code %}} ++{{< /code >}} + +{{% note %}} +The URLs must be relative to the context root. If the `baseURL` is `http://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will overide the baseURL. If the value used for `URL` in the above example is `http://subdomain.example.com/`, the output will be `http://subdomain.example.com`. +{{% /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 --cc docs/content/content-management/multilingual.md index 58644640,00000000..e3c65a26 mode 100644,000000..100644 --- a/docs/content/content-management/multilingual.md +++ b/docs/content/content-management/multilingual.md @@@ -1,300 -1,0 +1,294 @@@ +--- +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] +#tags: [multilingual,i18n, internationalization] +menu: + docs: + parent: "content-management" + weight: 150 +weight: 150 #rem +draft: false +aliases: [/content/multilingual/,/content-management/multilingual/] +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 TOML site configuration for a multilingual Hugo project: + - {{% code file="config.toml" download="config.toml" %}} - ```toml ++{{< code file="config.toml" download="config.toml" >}} +DefaultContentLanguage = "en" +copyright = "Everything is mine" + +[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.navigation] +help = "Aide" - ``` - {{% /code %}} ++{{< /code >}} + +Anything not defined in a `[Languages]` block will fall back to the global +value for that key (e.g., `copyright` for the English [`en`] language). + +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. + +## Taxonomies and Blackfriday + +Taxonomies and [Blackfriday configuration][config] can also be set per language: + + - {{% code file="bf-config.toml" %}} - ```toml ++{{< code file="bf-config.toml" >}} +[Taxonomies] +tag = "tags" + +[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" - ``` - {{% /code %}} ++{{< /code >}} + +## 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 eample, 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 *base filename*, the content pieces are linked together as translated pieces. + +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. + +{{%note %}} +Hugo currently uses the base filename as the translation key, which can be an issue with identical filenames in different sections. +We will fix this in https://github.com/gohugoio/hugo/issues/2699 +{{% /note %}} +{{< todo >}}Rewrite/remove the above one issue is fixed.{{< /todo >}} + +## 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" %}} - ```html ++{{< code file="layouts/partials/i18nlist.html" >}} +{{ if .IsTranslated }} +

{{ i18n "translations" }}

+ +{{ end }} - ``` - {{% /code %}} ++{{< /code >}} + +The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page, or if there are translations---in the case of the homepage, section listing, etc.---a site with only render one language. + +The above also uses the [`i18n` function][i18func] described in the next section. + +## 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. + +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: + - ```bash ++``` + 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: + - ```toml ++``` +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. + - ```html ++``` +
    + {{- $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 %}} + +## 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 --cc docs/content/content-management/organization.md index 2f6e2074,00000000..33780c0e mode 100644,000000..100644 --- a/docs/content/content-management/organization.md +++ b/docs/content/content-management/organization.md @@@ -1,247 -1,0 +1,241 @@@ +--- +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] +#tags: [sections,content,organization] +menu: + docs: + parent: "content-management" + weight: 10 +weight: 10 #rem +draft: false +aliases: [/content/sections/] +toc: true +--- + +{{% note %}} +This section is not updated with the new nested sections support in Hugo 0.24, see https://github.com/gohugoio/hugoDocs/issues/36 +{{% /note %}} +{{% todo %}} +See above +{{% /todo %}} + +## 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 [sections][]. Without any additional configuration, the following will just work: + +``` +. +└── content + └── about - | └── _index.md // <- http://yoursite.com/about/ ++ | └── _index.md // <- http://example.com/about/ + ├── post - | ├── firstpost.md // <- http://yoursite.com/post/firstpost/ ++ | ├── firstpost.md // <- http://example.com/post/firstpost/ + | ├── happy - | | └── ness.md // <- http://yoursite.com/post/happy/ness/ - | └── secondpost.md // <- http://yoursite.com/post/secondpost/ ++ | | └── ness.md // <- http://example.com/post/happy/ness/ ++ | └── secondpost.md // <- http://example.com/post/secondpost/ + └── quote - ├── first.md // <- http://yoursite.com/quote/first/ - └── second.md // <- http://yoursite.com/quote/second/ ++ ├── first.md // <- http://example.com/quote/first/ ++ └── second.md // <- http://example.com/quote/second/ +``` + +## Path Breakdown in Hugo + - The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "http://yoursite.com"` in your [site's configuration file][config]. ++The following demonstrates the relationships between your content organization and the output URL structure for your Hugo website when it renders. These examples assume you are [using pretty URLs][pretty], which is the default behavior for Hugo. The examples also assume a key-value of `baseurl = "http://example.com"` in your [site's configuration file][config]. + +### Index Pages: `_index.md` + +`_index.md` has a special role in Hugo. It allows you to add front matter and content to your [list templates][lists] as of v0.18. These templates include those for [section templates][], [taxonomy templates][], [taxonomy terms templates][], and your [homepage template][]. In your templates, you can grab information from `_index.md` using the [`.Site.GetPage` function][getpage]. + +You can keep one `_index.md` for your homepage and one in each of your content sections, taxonomies, and taxonomy terms. The following shows typical placement of an `_index.md` that would contain content and front matter for a `posts` section list page on a Hugo website: + + - ```bash ++``` +. url +. ⊢--^-⊣ +. path slug +. ⊢--^-⊣⊢---^---⊣ +. filepath +. ⊢------^------⊣ +content/posts/_index.md +``` + +At build, this will output to the following destination with the associated values: + - ```bash ++``` + + url ("/posts/") + ⊢-^-⊣ + baseurl section ("posts") +⊢--------^---------⊣⊢-^-⊣ + permalink +⊢----------^-------------⊣ - http://yoursite.com/posts/index.html ++http://example.com/posts/index.html +``` + +### 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`: + + - ```bash ++``` + 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: + - ```bash ++``` + + url ("/posts/my-first-hugo-post/") + ⊢------------^----------⊣ + baseurl section slug +⊢--------^--------⊣⊢-^--⊣⊢-------^---------⊣ + permalink +⊢--------------------^---------------------⊣ - http://yoursite.com/posts/my-first-hugo-post/index.html ++http://example.com/posts/my-first-hugo-post/index.html +``` + +### Section with Nested Directories + +To continue the example, the following demonstrates destination paths for a file located at `content/events/chicago/lollapalooza.md` in the same site: + + - ```bash ++``` + section + ⊢--^--⊣ + url + ⊢-------------^------------⊣ + + baseURL path slug +⊢--------^--------⊣ ⊢------^-----⊣⊢----^------⊣ + permalink +⊢----------------------^-----------------------⊣ - http://yoursite.com/events/chicago/lollapalooza/ ++http://example.com/events/chicago/lollapalooza/ +``` + +{{% note %}} +As of v0.20, Hugo does not recognize nested sections. While you can nest as many content *directories* as you'd like, any child directory of a section will still be considered the same section as that of its parents. Therefore, in the above example, `{{.Section}}` for `lollapalooza.md` is `events` and *not* `chicago`. See the [related issue on GitHub](https://github.com/gohugoio/hugo/issues/465). +{{% /note %}} + +## 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 `yoursite.com/posts/my-post/`). ++This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination (e.g., `content/posts/my-post.md` becomes `example.com/posts/my-post/`). + +### `slug` + +When defined in the front matter, the `slug` can take the place of the filename for the destination. + - {{% code file="content/posts/old-post.md" %}} - ```yaml ++{{< code file="content/posts/old-post.md" >}} +--- +title: New Post +slug: "new-post" +--- - ``` - {{% /code %}} ++{{< /code >}} + +This will render to the following destination according to Hugo's default behavior: + +``` - yoursite.com/posts/new-post/ ++example.com/posts/new-post/ +``` + +### `section` + +`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" %}} - ```yaml ++{{< code file="content/posts/my-post.md" >}} +--- +title: My Post +type: new +layout: mylayout +--- - ``` - {{% /code %}} ++{{< /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" %}} - ```yaml ++{{< code file="content/posts/old-url.md" >}} +--- +title: Old URL +url: /blog/new-url/ +--- - ``` - {{% /code %}} ++{{< /code >}} + - Assuming your `baseURL` is [configured][config] to `https://yoursite.com`, the addition of `url` to the front matter will make `old-url.md` render to the following destination: ++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://yoursite.com/blog/new-url/ ++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 --cc docs/content/content-management/sections.md index b7d95d01,00000000..dcb0025d mode 100644,000000..100644 --- a/docs/content/content-management/sections.md +++ b/docs/content/content-management/sections.md @@@ -1,73 -1,0 +1,73 @@@ +--- +title: Content Sections +linktitle: Sections +description: Hugo supports content sections, which according to Hugo's default behavior, will reflect the structure of the rendered website. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [content management] +#tags: [lists,sections,content types,organization] +menu: + docs: + parent: "content-management" + weight: 50 +weight: 50 #rem +draft: false +aliases: [/content/sections/] +toc: true +--- + +{{% note %}} +This section is not updated with the new nested sections support in Hugo 0.24, see https://github.com/gohugoio/hugoDocs/issues/36 +{{% /note %}} +{{% todo %}} +See above +{{% /todo %}} + +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 (see [directory structure][]). + +Following this pattern, Hugo uses the top level of your content organization as the content **section**. + +The following example shows a content directory structure for a website that has three sections: "authors," "events," and "posts": + - ```bash ++``` +. +└── content + ├── authors - | ├── _index.md // <- yoursite.com/authors/ - | ├── john-doe.md // <- yoursite.com/authors/john-doe/ - | └── jane-doe.md // <- yoursite.com/authors/jane-doe/ ++ | ├── _index.md // <- example.com/authors/ ++ | ├── john-doe.md // <- example.com/authors/john-doe/ ++ | └── jane-doe.md // <- example.com/authors/jane-doe/ + └── events - | ├── _index.md // <- yoursite.com/events/ - | ├── event-1.md // <- yoursite.com/events/event-1/ - | ├── event-2.md // <- yoursite.com/events/event-2/ - | └── event-3.md // <- yoursite.com/events/event-3/ ++ | ├── _index.md // <- example.com/events/ ++ | ├── event-1.md // <- example.com/events/event-1/ ++ | ├── event-2.md // <- example.com/events/event-2/ ++ | └── event-3.md // <- example.com/events/event-3/ + └── posts - | ├── _index.md // <- yoursite.com/posts/ - | ├── event-1.md // <- yoursite.com/posts/event-1/ - | ├── event-2.md // <- yoursite.com/posts/event-2/ - | ├── event-3.md // <- yoursite.com/posts/event-3/ - | ├── event-4.md // <- yoursite.com/posts/event-4/ - | └── event-5.md // <- yoursite.com/posts/event-5/ ++ | ├── _index.md // <- example.com/posts/ ++ | ├── event-1.md // <- example.com/posts/event-1/ ++ | ├── event-2.md // <- example.com/posts/event-2/ ++ | ├── event-3.md // <- example.com/posts/event-3/ ++ | ├── event-4.md // <- example.com/posts/event-4/ ++ | └── event-5.md // <- example.com/posts/event-5/ +``` + +## Content Section Lists + +Hugo will automatically create pages for each section root 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. + +As of Hugo v0.18, section pages can also have a content file and front matter. These section content files must be placed in their corresponding section folder and named `_index.md` in order for Hugo to correctly render the front matter and content. + +{{% warning "`index.md` vs `_index.md`" %}} +Hugo themes developed before v0.18 often used an `index.md`(i.e., without the leading underscore [`_`]) in a content section as a hack to emulate the behavior of `_index.md`. The hack may work...*sometimes*; however, the order of page rendering can be unpredictable in Hugo. What works now may fail to render appropriately as your site grows. It is **strongly advised** to use `_index.md` as content for your section index pages. **Note:** `_index.md`'s layout, as representative of a section, is a [list page template](/templates/section-templates/) and *not* a [single page template](/templates/single-page-templates/). If you want to alter the new default behavior for `_index.md`, configure `disableKinds` accordingly in your [site's configuration](/getting-started/configuration/). +{{% /warning %}} + +## Content *Section* vs Content *Type* + +By default, everything created within a section will use the [content type][] that matches the 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/ + + diff --cc docs/content/content-management/shortcodes.md index 2b4467ff,00000000..3482d672 mode 100644,000000..100644 --- a/docs/content/content-management/shortcodes.md +++ b/docs/content/content-management/shortcodes.md @@@ -1,431 -1,0 +1,409 @@@ +--- +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] +#tags: [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 + +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: + - ```md ++``` +{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}} +``` + - ```md ++``` +{{}} 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`: + - ```md ++``` +{{%/* 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: + - ```md ++``` +{{}}

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` +* `link` +* `title` +* `caption` +* `class` +* `attr` (i.e., attribution) +* `attrlink` +* `alt` + +#### Example `figure` Input + - {{% code file="figure-input-example.md" %}} - ```markdown ++{{< code file="figure-input-example.md" >}} +{{}} - ``` - {{% /code %}} ++{{< /code >}} + +#### Example `figure` Output + +{{% output file="figure-output-example.html" %}} - ```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]: + - ```html ++``` +https://gist.github.com/spf13/7896402 +``` + +We can embed the gist in our content via username and gist ID pulled from the URL: + - ```md ++``` +{{}} +``` + +#### 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" %}} - ```md ++{{< code file="gist-input.md" >}} +{{}} - ``` - {{% /code %}} ++{{< /code >}} + +#### Example `gist` Output + +{{% output file="gist-output.html" %}} - ```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" %}} - ```html ++{{< code file="content/tutorials/learn-html.md" >}} +{{}} +
+
+

{{ .Title }}

+ {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
+
+{{}} - ``` - {{% /code %}} ++{{< /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" %}} - ```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: + - ```html ++``` +https://www.instagram.com/p/BWNjjyYFxVx/ +``` + +#### Example `instagram` Input + - {{% code file="instagram-input.md" %}} - ```md ++{{< code file="instagram-input.md" >}} +{{}} - ``` - {{% /code %}} ++{{< /code >}} + +You also have the option to hide the caption: + - {{% code file="instagram-input-hide-caption.md" %}} - ```md ++{{< code file="instagram-input-hide-caption.md" >}} +{{}} - ``` - {{% /code %}} ++{{< /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" %}} - ```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 + - ```md ++``` +[Neat]({{}}) +[Who]({{}}) +``` + +#### Example `ref` and `relref` Output + +Assuming that standard Hugo pretty URLs are turned on. + - ```html ++``` +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: + - ```html ++``` + +``` + +#### `speakerdeck` Example Input + +Extract the value from the field `data-id` and pass it to the shortcode: + - {{% code file="speakerdeck-example-input.md" %}} - ```md ++{{< code file="speakerdeck-example-input.md" >}} +{{}} - ``` - {{% /code %}} ++{{< /code >}} + +#### `speakerdeck` Example Output + +{{% output file="speakerdeck-example-input.md" %}} - ```html ++``` +{{< 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" %}} - ```md ++{{< code file="example-tweet-input.md" >}} +{{}} - ``` - {{% /code %}} ++{{< /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" %}} - ```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" %}} - ```md ++{{< code file="example-vimeo-input.md" >}} +{{}} - ``` - {{% /code %}} ++{{< /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" %}} - ```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 >}} + - {{% code file="youtube-embed.html" copy="false" %}} - ```html ++{{< code file="youtube-embed.html" copy="false" >}} +
+ +
- ``` - {{% /code %}} ++{{< /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" %}} - ```golang ++{{< code file="content-image.md" >}} +{{}} - ``` - {{% /code %}} ++{{< /code >}} + +You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template: + - {{% code file="/layouts/shortcodes/img.html" %}} - ```html ++{{< 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 %}} ++{{< /code >}} + +Would be rendered as: + - {{% code file="img-output.html" copy="false" %}} - ```html ++{{< code file="img-output.html" copy="false" >}} +
+ +
+

Steve Francia

+
+
- ``` - {{% /code %}} ++{{< /code >}} + +### Single Flexible Example: `vimeo` + - ```golang ++``` +{{}} +{{}} +``` + +Would load the template found at `/layouts/shortcodes/vimeo.html`: + - {{% code file="/layouts/shortcodes/vimeo.html" %}} - ```html ++{{< code file="/layouts/shortcodes/vimeo.html" >}} +{{ if .IsNamedParams }} +
+ +
+{{ else }} +
+ +
+{{ end }} - ``` - {{% /code %}} ++{{< /code >}} + +Would be rendered as: + - {{% code file="vimeo-iframes.html" copy="false" %}} - ```html ++{{< code file="vimeo-iframes.html" copy="false" >}} +
+ +
+
+ +
- ``` - {{% /code %}} ++{{< /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" %}} - ```markdown ++{{< code file="highlight-example.md" >}} +{{}} + + This HTML + +{{}} - ``` - {{% /code %}} ++{{< /code >}} + +The template for the `highlight` shortcode uses the following code, which is already included in Hugo: + - ```golang ++``` +{{ .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 ++{{< code file="syntax-highlighted.html" copy="false" >}} +
<html>
 +    <body> This HTML </body>
 +</html>
 +
- ``` - {{% /code %}} ++{{< /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" %}} - ```html ++{{< code file="layouts/shortcodes/gallery.html" >}} +
+ {{.Inner}} +
- ``` - {{% /code %}} ++{{< /code >}} + +You also have an `image` 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 `image`: + - {{% code file="layouts/shortcodes/image.html" %}} - ```html ++{{< code file="layouts/shortcodes/image.html" >}} +{{- $src := .Get "src" -}} +{{- with .Parent -}} + +{{- else -}} + +{{- end }} - ``` - {{% /code %}} ++{{< /code >}} + +You can then call your shortcode in your content as follows: + - ```markdown ++``` +{{}} + {{}} + {{}} +{{}} +{{}} +``` + +This will output the following HTML. Note how the first two `image` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `image` only uses `src`: + - ```html ++``` +
+ + +
+ +``` + +## 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 --cc docs/content/templates/single-page-templates.md index c1293924,00000000..20942e5d mode 100644,000000..100644 --- a/docs/content/templates/single-page-templates.md +++ b/docs/content/templates/single-page-templates.md @@@ -1,107 -1,0 +1,105 @@@ +--- +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] +#tags: [page] +menu: + docs: + parent: "templates" + weight: 60 +weight: 60 +sections_weight: 60 +draft: false +aliases: [/layout/content/] +toc: true +--- + +## Single Page Template Lookup Order + +You can specify a [content's `type`][content type] and `layout` in a single content file's [front matter][]. However, you cannot specify `section` because this is determined based on file location (see [content section][section]). + +Hugo assumes your content section and content type are the same unless you tell Hugo otherwise by providing a `type` directly in the front matter of a content file. This is why #1 and #3 come before #2 and #4, respectively, in the following lookup order. Values in angle brackets (`<>`) are variable. + +1. `/layouts//.html` +2. `/layouts/
>/.html` +3. `/layouts//single.html` +4. `/layouts/
/single.html` +5. `/layouts/_default/single.html` +6. `/themes//layouts//.html` +7. `/themes//layouts/
/.html` +8. `/themes//layouts//single.html` +9. `/themes//layouts/
/single.html` +10. `/themes//layouts/_default/single.html` + +## 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" %}} - ```html ++{{< code file="layouts/post/single.html" download="single.html" >}} +{{ define "main" }} +
+

{{ .Title }}

+
+
+ {{ .Content }} +
+
+
+ +{{ end }} - ``` - {{% /code %}} ++{{< /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 --cc docs/content/templates/sitemap-template.md index 740fdbf2,00000000..43bd7ff3 mode 100644,000000..100644 --- a/docs/content/templates/sitemap-template.md +++ b/docs/content/templates/sitemap-template.md @@@ -1,75 -1,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] +#tags: [sitemap, xml] +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). + - ```xml ++``` + + {{ 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.: + - ```toml ++``` +[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/ diff --cc docs/content/templates/taxonomy-templates.md index e2a40c3b,00000000..a13e2f2e mode 100644,000000..100644 --- a/docs/content/templates/taxonomy-templates.md +++ b/docs/content/templates/taxonomy-templates.md @@@ -1,341 -1,0 +1,337 @@@ +--- +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] +#tags: [taxonomies,metadata,front matter,terms] +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 the terms for a taxonomy are displayed in a [taxonomy terms template](#taxonomy-terms-template) +* Order the way content associated with a taxonomy term is displayed in a [taxonomy list template](#taxonomy-list-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 + +A taxonomy will be rendered at /`PLURAL`/`TERM`/ (e.g., http://spf13.com/topics/golang/) according to the following lookup order: + +1. `/layouts/taxonomy/.html` +2. `/layouts/_default/taxonomy.html` +3. `/layouts/_default/list.html` +4. `/themes//layouts/taxonomy/.html` +5. `/themes//layouts/_default/taxonomy.html` +6. `/themes//layouts/_default/list.html` + +## Taxonomy Terms Template + +### Taxonomy Terms Templates Lookup Order + - A taxonomy terms page will be rendered at `yoursite.com/`/ (e.g., http://spf13.com/topics/) according to the following lookup order: ++A taxonomy terms page will be rendered at `example.com/`/ (e.g., http://spf13.com/topics/) according to the following lookup order: + +1. `/layouts/taxonomy/.terms.html` +2. `/layouts/_default/terms.html` +3. `/themes//layouts/taxonomy/.terms.html` +4. `/themes//layouts/_default/terms.html` + +{{% warning "The Taxonomy Terms Template has a Unique Lookup Order" %}} +If Hugo does not find a terms template in `layout/` or `/themes//layouts/`, Hugo will *not* render a taxonomy terms page. +{{% /warning %}} + + +Hugo makes a set of values and methods available on the various Taxonomy structures. + +### 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. + +### OrderedTaxonomy + +Since Maps are unordered, an OrderedTaxonomy is a special structure that has a defined order. + - ```go ++``` +[]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. + - ```go ++``` +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]. + + + +## Order Taxonomies + +Taxonomies can be ordered by either alphabetical key or by the number of content pieces assigned to that key. + +### Order Alphabetically Example + - ```html ++``` +
    + {{ $data := .Data }} + {{ range $key, $value := .Data.Taxonomy.Alphabetical }} +
  • {{ $value.Name }} {{ $value.Count }}
    • + {{ end }} +
+``` + +### Order by Popularity Example + - ```html ++``` +
    + {{ $data := .Data }} + {{ range $key, $value := .Data.Taxonomy.ByCount }} +
  • {{ $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. + - ```toml ++``` ++++ +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 + - ```html ++``` +
    + {{ 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 + - ```html ++``` +{{ 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 + - ```html ++``` + +``` + +## 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 + - ```html ++``` + +``` + +## 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 + - ```html ++``` +
    + {{ 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" %}} - ```html ++{{< 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 %}} ++{{< /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" %}} - ```html ++{{< code file="links-to-all-tags" >}} +
    + {{ range ($.Site.GetPage "taxonomyTerm" "tags").Pages }} +
  • {{ .Title}}
    • + {{ end }} +
- ``` - {{% /code %}} ++{{< /code >}} + + + + +[delimit]: /functions/delimit/ +[getpage]: /functions/getpage/ +[lists]: /templates/lists/ +[renderlists]: /templates/lists/ +[single page template]: /templates/single-page-templates/ +[sitevars]: /variables/site/ diff --cc docs/content/templates/template-debugging.md index 208259f7,00000000..1905f6db mode 100644,000000..100644 --- a/docs/content/templates/template-debugging.md +++ b/docs/content/templates/template-debugging.md @@@ -1,81 -1,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] +#tags: [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`. + - ```html ++``` +{{ printf "%#v" $.Site }} +``` + +This will print out the value of `.Permalink`: + + - ```html ++``` +{{ printf "%#v" .Permalink }} +``` + + +This will print out a list of all the variables scoped to the current context +(`.`, aka ["the dot"][tempintro]). + + - ```html ++``` +{{ printf "%#v" . }} +``` + + +When developing a [homepage][], what does one of the pages you're looping through look like? + - ```html ++``` +{{ 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: + - ```html ++``` +{{ 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]. + - ```html ++``` +{{ 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/ diff --cc docs/content/templates/views.md index 2fba25cb,00000000..0383636a mode 100644,000000..100644 --- a/docs/content/templates/views.md +++ b/docs/content/templates/views.md @@@ -1,127 -1,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] +#tags: [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. + - ```bash ++``` + ▾ 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. + + - ```bash ++``` +▾ 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" %}} - ``` ++{{< code file="layouts/_default/list.html" download="list.html" >}} +
+
+

{{ .Title }}

+ {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
+
- ``` - {{% /code %}} ++{{< /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" %}} - ```html ++{{< code file="layouts/_default/summary.html" download="summary.html" >}} + - ``` - {{% /code %}} ++{{< /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" %}} - ```html ++{{< code file="layouts/_default/li.html" download="li.html" >}} +
  • + {{ .Title }} +
    {{ .Date.Format "Mon, Jan 2, 2006" }}
    +
    • - ``` - {{% /code %}} ++{{< /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 --cc docs/content/themes/creating.md index 5f921d30,00000000..52edaeae mode 100644,000000..100644 --- a/docs/content/themes/creating.md +++ b/docs/content/themes/creating.md @@@ -1,87 -1,0 +1,87 @@@ +--- - title: Creating a Theme - linktitle: Creating a Theme ++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] +#tags: [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: + - ```bash ++``` +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 conte 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 --cc docs/content/themes/customizing.md index b0fbdd06,00000000..1c82b2b7 mode 100644,000000..100644 --- a/docs/content/themes/customizing.md +++ b/docs/content/themes/customizing.md @@@ -1,80 -1,0 +1,80 @@@ +--- - title: Customizing a Theme - linktitle: Customizing a Theme ++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] +#tags: [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: + - ```bash ++``` +/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: + - ```bash ++``` +/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: + - ```bash ++``` +/themes//layouts/_default/single.html +``` + +Would be overwritten by + - ```bash ++``` +/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/ diff --cc docs/content/themes/installing-and-using-themes.md index f1e35477,00000000..474b7b03 mode 100644,000000..100644 --- a/docs/content/themes/installing-and-using-themes.md +++ b/docs/content/themes/installing-and-using-themes.md @@@ -1,114 -1,0 +1,112 @@@ +--- - title: Installing and Using Themes - linktitle: Installing and Using Themes ++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] +#tags: [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 + +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. + - ```bash ++``` +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: + - ```bash ++``` +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" %}} - ```bash ++{{< code file="clone-theme.sh" >}} +cd themes +git clone https://github.com/spf13/hyde - ``` - {{% /code %}} ++{{< /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 + +To change a theme via the Hugo CLI, you can pass the `-t` [flag][] when building your site: + - ```bash ++``` +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]: + - ```bash ++``` +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]: + - ```yaml ++``` +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 --cc docs/content/tools/syntax-highlighting.md index ef32f7ee,00000000..1cb7ec6c mode 100644,000000..100644 --- a/docs/content/tools/syntax-highlighting.md +++ b/docs/content/tools/syntax-highlighting.md @@@ -1,241 -1,0 +1,239 @@@ +--- +title: Syntax Highlighting +linktitle: +description: Hugo provides server-side syntax highlighting via Pygments and, like most static site generators, works very well with client-side (JavaScript) syntax highlighting libraries as well. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +#tags: [highlighting,pygments,code blocks,syntax] +categories: [developer tools] +menu: + docs: + parent: "tools" + weight: 20 +weight: 20 +sections_weight: 20 +draft: false +aliases: [/extras/highlighting/,/extras/highlight/] +toc: true +--- + +Hugo can highlight source code in _two different ways_—either pre-processed server side from your content or to defer the processing to the client side, using a JavaScript library. + +## Server-side + +For the pre-processed approach, highlighting is performed by an external Python-based program called [Pygments](http://pygments.org/) and is triggered via an embedded Hugo shortcode (see [example](#example-highlight-shortcode-input) below). If Pygments is absent from the path, it will silently simply pass the content along without highlighting. + +### Server-side Advantages + +The advantages of server-side syntax highlighting are that it doesn’t depend on a JavaScript library and, consequently, works very well when read from an RSS feed. + +### Pygments + +If you have never worked with Pygments before, here is a brief primer: + ++ Install Python from [python.org](https://www.python.org/downloads/). Version 2.7.x is already sufficient. ++ Run `pip install Pygments` in order to install Pygments. Once installed, Pygments gives you a command `pygmentize`. Make sure it sits in your PATH; otherwise, Hugo will not be able to find and use it. + +On Debian and Ubuntu systems, you may also install Pygments by running `sudo apt-get install python3-pygments`. + +Hugo gives you two options that you can set with the variable `pygmentsuseclasses` (default `false`) in your [site configuration](/getting-started/configuration/). + +1. Color codes for highlighting keywords are directly inserted if `pygmentsuseclasses = false` (default). The color codes depend on your choice of the `pygmentsstyle` (default = `"monokai"`). You can explore the different color styles on [pygments.org](http://pygments.org/) after inserting some example code. +2. If you choose `pygmentsuseclasses = true`, Hugo includes class names in your code instead of color codes. For class-names to be meaningful, you need to include a `.css` file in your website representing your color scheme. You can either generate this `.css` files according to the [description from the Pygments documentation](http://pygments.org/docs/cmdline/) or download the one of the many pre-built color schemes from [Pygment's GitHub css repository](https://github.com/richleland/pygments-css). + +### Server-side Usage + +Highlighting is carried out via the [built-in shortcode](/content-management/shortcodes/) `highlight`. `highlight` takes exactly one required parameter for the programming language to be highlighted and requires a closing shortcode. Note that `highlight` is *not* used for client-side javascript highlighting. + +### Example `highlight` Shortcode Input + - {{% code file="example-highlight-shortcode-input.md" %}} - ```html ++{{< code file="example-highlight-shortcode-input.md" >}} +{{}} +
    +
    +

    {{ .Title }}

    + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
    +
    +{{}} - ``` - {{% /code %}} ++{{< /code >}} + +### Example `highlight` Shortcode Output + +{{% output file="example-highlight-shortcode-output.html" %}} +``` +<section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} + </div> +</section> +``` +{{% /output %}} + +### Options + +Options for controlling highlighting can be added in the second argument as a quoted, comma-separated key-value list. The example below will syntax highlight in `go` with inline line numbers and line numbers 2 and 3 highlighted. + +``` +{{}} +var a string +var b string +var c string +var d string +{{}} +``` + +The `highlight` shortcode includes the following supported keywords: + +* `style` +* `encoding` +* `noclasses` +* `hl_lines` +* `linenos` + +Note that `style` and `noclasses` will override the similar setting in the [global config](/getting-started/configuration/). + +The keywords in the `highlight` shortcode mirror those of Pygments from the command line. See the [Pygments documentation](http://pygments.org/docs/) for more information. + +### Code Fences + +It is also possible to add syntax highlighting with GitHub flavored code fences. To enable this, set the `PygmentsCodeFences` to `true` in Hugo's [configuration file](/getting-started/configuration/); + - ```` - ```html ++``` ++``` +
    +
    +

    {{ .Title }}

    + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
    +
    +``` - ```` ++``` + +{{% note "Disclaimers on Pygments" %}} +* Pygments is relatively slow and _causes a performance hit when building your site_, but Hugo has been designed to cache the results to disk. +* The caching can be turned off by setting the `--ignoreCache` flag to `true`. +* The languages available for highlighting depend on your Pygments installation. +{{% /note %}} + +## Client-side + +Alternatively, code highlighting can be applied to your code blocks in client-side JavaScript. + +Client-side syntax highlighting is very simple to add. You'll need to pick +a library and a corresponding theme. Some popular libraries are: + +- [Highlight.js] +- [Prism] +- [Rainbow] +- [Syntax Highlighter] +- [Google Prettify] + +### Client-side Advantages + +The advantages of client-side syntax highlighting are that it doesn’t cost anything when building your site, and some of the highlighting scripts available cover more languages than Pygments does. + +### Highlight.js Example + +This example uses the popular [Highlight.js] library, hosted by [Yandex], a popular Russian search engine. + +In your `./layouts/partials/` (or `./layouts/chrome/`) folder, depending on your specific theme, there will be a snippet that will be included in every generated HTML page, such as `header.html` or `header.includes.html`. Simply add the css and js to initialize [Highlight.js]: + +``` + + + +``` + +### Prism example + +Prism is another popular highlighter library and is used on some major sites. +The [download section of the prism.js website][prismdownload] is simple to use and affords you a high degree of customization to pick only the languages you'll be using on your site. + +Similar to Highlight.js, you simply load `prism.css` in your `` via whatever Hugo partial template is creating that part of your pages: + - ```html ++``` +... + +... +``` + +Add `prism.js` near the bottom of your `` tag in whatever Hugo partial template is appropriate for your site or theme. + - ```html ++``` +... + + +``` + +In this example, the local paths indicate that your downloaded copy of these files are being added to the site, typically under `./static/css/` and `./static/js/`, respectively. + +### Client-side Usage + +To use client-side highlighting, most of these javascript libraries expect your code to be wrapped in semantically correct `` elements with language-specific class attributes. For example, a code block for HTML would have `class="language-html"`. + +The client-side highlighting script therefore looks for programming language classes according to this convention: `language-go`, `language-html`, `language-css`, `language-bash`, etc. If you look at the page's source, you might see something like the following: + - ```html ++``` +
     +  
 +  body {
 +    font-family: "Noto Sans", sans-serif;
 +  }
 +  
 +
    +``` + +If you are using markdown, your content pages needs to use the following syntax, with the name of the language to be highlighted entered directly after the first "fence." A fenced code block can be noted by opening and closing triple tilde ~ or triple back ticks `: + +{{< nohighlight >}} +~~~css +body { + font-family: "Noto Sans", sans-serif; +} +~~~ +{{< /nohighlight >}} + +Here is the same example but with triple back ticks to denote the fenced code block: + +{{< nohighlight >}} - ```css ++``` +body { + font-family: "Noto Sans", sans-serif; +} +``` +{{< /nohighlight >}} + +Passing the above examples through the highlighter script would yield the following markup: + +{{< nohighlight >}} +<pre><code class="language-css hljs">;<span class="hljs-selector-tag">body</span> { + <span class="hljs-attribute">font-family</span>: <span class="hljs-string">"Noto Sans"</span>, sans-serif; +} +{{< /nohighlight >}} + +In the case of the coding color scheme used by the Hugo docs, the resulting output would then look like the following to the website's end users: + - ```css ++``` +body { + font-family: "Noto Sans", sans-serif; +} +``` + +Please see individual libraries' documentation for how to implement each of the JavaScript-based libraries. + +[Prism]: http://prismjs.com +[prismdownload]: http://prismjs.com/download.html +[Highlight.js]: http://highlightjs.org/ +[Rainbow]: http://craig.is/making/rainbows +[Syntax Highlighter]: http://alexgorbatchev.com/SyntaxHighlighter/ +[Google Prettify]: https://github.com/google/code-prettify +[Yandex]: http://yandex.ru/ diff --cc docs/content/troubleshooting/_index.md index 614ea209,00000000..8900d78e mode 100644,000000..100644 --- a/docs/content/troubleshooting/_index.md +++ b/docs/content/troubleshooting/_index.md @@@ -1,26 -1,0 +1,26 @@@ +--- - title: Troubleshooting - linktitle: Troubleshooting ++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: 01 +weight: 01 #rem +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 --cc docs/content/troubleshooting/accented-characters-in-urls.md index 1b2340ee,00000000..a902377c mode 100644,000000..100644 --- a/docs/content/troubleshooting/accented-characters-in-urls.md +++ b/docs/content/troubleshooting/accented-characters-in-urls.md @@@ -1,60 -1,0 +1,60 @@@ +--- +title: Accented Characters in URLs +linktitle: Accented Characters in URLs +description: If you're having trouble with special characters in your taxonomies or titles adding odd characters to your URLs. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +#tags: [urls,multilingual,special characters] +categories: [troubleshooting] +menu: + docs: + parent: "troubleshooting" +weight: +draft: false +slug: +aliases: [/troubleshooting/categories-with-accented-characters/] +toc: true +--- + +## Trouble: Categories with accented characters + +> One of my categories is named "Le-carré," but the link ends up being generated like this: +> - > ```bash ++> ``` +> categories/le-carr%C3%A9 +> ``` +> +> And not working. Is there an easy fix for this that I'm overlooking? + +## Solution + +Are you a macOS user? If so, you are likely a victim of HFS Plus file system's insistence to store the "é" (U+00E9) character in Normal Form Decomposed (NFD) mode, i.e. as "e" + " ́" (U+0065 U+0301). + +`le-carr%C3%A9` is actually correct, `%C3%A9` being the UTF-8 version of U+00E9 as expected by the web server. The problem is that OS X turns [U+00E9] into [U+0065 U+0301], and thus `le-carr%C3%A9` no longer works. Instead, only `le-carre%CC%81` ending with `e%CC%81` would match that [U+0065 U+0301] at the end. + +This is unique to OS X. The rest of the world does not do this, and most certainly not your web server which is most likely running Linux. This is not a Hugo-specific problem either. Other people have been bitten by this when they have accented characters in their HTML files. + +Note that this problem is not specific to Latin scripts. Japanese Mac users often run into the same issue; e.g., with `だ` decomposing into `た` and `゙`. (Read the [Japanese Perl users article][]). + +Rsync 3.x to the rescue! From [an answer posted on Server Fault][]: + +> You can use rsync's `--iconv` option to convert between UTF-8 NFC & NFD, at least if you're on a Mac. There is a special `utf-8-mac` character set that stands for UTF-8 NFD. So to copy files from your Mac to your web server, you'd need to run something like: +> +> `rsync -a --iconv=utf-8-mac,utf-8 localdir/ mywebserver:remotedir/` +> +> This will convert all the local filenames from UTF-8 NFD to UTF-8 NFC on the remote server. The files' contents won't be affected. - [Server Fault][] + +Please make sure you have the latest version of rsync 3.x installed. The rsync that ships with OS X is outdated. Even the version that comes packaged with 10.10 (Yosemite) is version 2.6.9 protocol version 29. The `--iconv` flag is new in rsync 3.x. + +### Discussion Forum References + +* http://discourse.gohugo.io/t/categories-with-accented-characters/505 +* http://wiki.apache.org/subversion/NonNormalizingUnicodeCompositionAwareness +* https://en.wikipedia.org/wiki/Unicode_equivalence#Example +* http://zaiste.net/2012/07/brand_new_rsync_for_osx/ +* https://gogo244.wordpress.com/2014/09/17/drived-me-crazy-convert-utf-8-mac-to-utf-8/ + +[an Answer posted on Server Fault]: http://serverfault.com/questions/397420/converting-utf-8-nfd-filenames-to-utf-8-nfc-in-either-rsync-or-afpd "Converting UTF-8 NFD filenames to UTF-8 NFC in either rsync or afpd, Server Fault Discussion" +[Japanese Perl users article]: http://perl-users.jp/articles/advent-calendar/2010/english/24 "Encode::UTF8Mac makes you happy while handling file names on MacOSX" +[Server Fault]: http://serverfault.com/questions/397420/converting-utf-8-nfd-filenames-to-utf-8-nfc-in-either-rsync-or-afpd "Converting UTF-8 NFD filenames to UTF-8 NFC in either rsync or afpd, Server Fault Discussion" diff --cc docs/content/troubleshooting/eof-error.md index 6e715cde,00000000..da1b827f mode 100644,000000..100644 --- a/docs/content/troubleshooting/eof-error.md +++ b/docs/content/troubleshooting/eof-error.md @@@ -1,49 -1,0 +1,49 @@@ +--- +title: EOF Error +linktitle: EOF Error +description: If you find yourself seeing an EOF error in the console whenever you create a new content file from Hugo's archetype feature. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [troubleshooting] +menu: + docs: + parent: "troubleshooting" +#tags: [eof, end of file, error, faqs] +draft: false +weight: +aliases: [/troubleshooting/strange-eof-error/] +toc: true +--- + +## Trouble: `hugo new` Aborts with EOF error + +> I'm running into an issue where I cannot get archetypes working, when running `hugo new showcase/test.md`, for example, I see an `EOF` error thrown by Hugo. +> +> When I run Hugo with v0.12 via `hugo new -v showcase/test.md`, I see the following output: +> - > ```bash ++> ``` +> INFO: 2015/01/04 Using config file: /private/tmp/test/config.toml +> INFO: 2015/01/04 attempting to create showcase/test.md of showcase +> INFO: 2015/01/04 curpath: /private/tmp/test/archetypes/showcase.md +> ERROR: 2015/01/04 EOF +> ``` +> +> Is there something that I am blatantly missing? + +## Solution: Carriage Returns + +The solution is to add a final newline (i.e., `EOL`) to the end of your default.md archetype file of your theme. You can do this by adding a carriage return after the closing `+++` or `---` of your TOML or YAML front matter, respectively. + +{{% note "Final EOL Unnecessary in v0.13+" %}} +As of v0.13, Hugo's parser has been enhanced to accommodate archetype files without final EOL thanks to the great work by [@tatsushid](https://github.com/tatsushid). +{{% /note %}} + +## Discussion Forum References + +* http://discourse.gohugo.io/t/archetypes-not-properly-working-in-0-12/544 +* http://discourse.gohugo.io/t/eol-f-in-archetype-files/554 + +## Related Hugo Issues + +* https://github.com/gohugoio/hugo/issues/776 diff --cc docs/content/variables/page.md index 78c811b9,00000000..49def75b mode 100644,000000..100644 --- a/docs/content/variables/page.md +++ b/docs/content/variables/page.md @@@ -1,272 -1,0 +1,270 @@@ +--- +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] +#tags: [pages] +draft: false +menu: + docs: + 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. + +`.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`. + +`.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, Hugo will default to the `date` field. See also `.ExpiryDate`, `.Date`, and `.PublishDate`. + +`.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/). + +`.Section` +: the [section](/content-management/sections/) this content belongs to. + +`.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. + +## 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. + - ```yaml ++``` +--- +title: My First Post +date: 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`: + - ```yaml ++``` +--- +... +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" %}} - ```html ++{{< code file="/themes/yourtheme/layouts/review/single.html" >}} +

    Buy this book

    +

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

    - ``` - {{% /code %}} ++{{< /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" %}} - ```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): + - ```golang ++``` +{{ $.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: + - ```yaml ++``` +--- +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`: + - ```golang ++``` +{{ $.Param "favorites.flavor" }} +=> vanilla +``` diff --cc docs/content/variables/site.md index d037cb06,00000000..68b94338 mode 100644,000000..100644 --- a/docs/content/variables/site.md +++ b/docs/content/variables/site.md @@@ -1,127 -1,0 +1,125 @@@ +--- +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] +#tags: [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.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.toml` defines a site-wide param for `description`: + - ```toml ++``` +baseURL = "http://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" %}} - ```html ++{{< code file="layouts/partials/head.html" >}} + - ``` - {{% /code %}} ++{{< /code >}} + +[config]: /getting-started/configuration/ diff --cc docs/content/variables/taxonomy.md index 7ab95d26,00000000..ef20156b mode 100644,000000..100644 --- a/docs/content/variables/taxonomy.md +++ b/docs/content/variables/taxonomy.md @@@ -1,86 -1,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] +#tags: [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" %}} - ```html ++{{< 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 %}} ++{{< /code >}} + +[partials]: /templates/partials/ +[taxonomytemplates]: /templates/taxonomy-templates/ diff --cc docs/layouts/shortcodes/code.html index 6df49956,00000000..009aeb71 mode 100644,000000..100644 --- a/docs/layouts/shortcodes/code.html +++ b/docs/layouts/shortcodes/code.html @@@ -1,15 -1,0 +1,17 @@@ -
    - {{- with .Get "file" -}} ++{{ $file := .Get "file" }} ++{{ $isHTML := strings.HasSuffix $file "html" }} ++
    ++ {{- with $file -}} +
    {{.}}
    + {{- end -}} + + {{ if ne (.Get "copy") "false" }} + + {{/* Functionality located within filesaver.js The copy here is located in the css with .copy class so it can be replaced with JS on success */}} + {{end}} +
    - {{- .Inner -}} ++ {{ if $isHTML }}{{- highlight .Inner "html" "" | -}}{{ else }}
    {{- .Inner | string -}}
    {{ end }} +
    + +
    diff --cc docs/requirements.txt index 00000000,00000000..e0f2f62d new file mode 100644 --- /dev/null +++ b/docs/requirements.txt @@@ -1,0 -1,0 +1,1 @@@ ++Pygments==2.1.3 diff --cc docs/themes/gohugoioTheme index 18141c49,00000000..d0445e2a mode 160000,000000..160000 --- a/docs/themes/gohugoioTheme +++ b/docs/themes/gohugoioTheme @@@ -1,1 -1,0 +1,1 @@@ - Subproject commit 18141c496f18ac74bfef480403b4bbb69c44bbbe ++Subproject commit d0445e2ad6bcffcbfa305650dd66e308543bcfdc