From: Bjørn Erik Pedersen Date: Wed, 18 Jul 2018 09:05:58 +0000 (+0200) Subject: Merge commit 'b6b37a1f00f808f3c0d2715f65ca2d3091f36495' X-Git-Tag: v0.45~27 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=59ebc83d7;p=brevno-suite%2Fhugo Merge commit 'b6b37a1f00f808f3c0d2715f65ca2d3091f36495' --- 59ebc83d72b09d28d62d8600517c73a4ffe70c66 diff --cc docs/config.toml index 63d9cef1,00000000..12398be2 mode 100644,000000..100644 --- a/docs/config.toml +++ b/docs/config.toml @@@ -1,409 -1,0 +1,408 @@@ +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" +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 + +pygmentsOptions = "" +# Use the Chroma stylesheet +pygmentsUseClasses = true +pygmentsUseClassic = false + +# See https://help.farbox.com/pygments.html +pygmentsStyle = "trac" + +[outputs] +home = [ "HTML", "RSS", "REDIR", "HEADERS" ] +section = [ "HTML", "RSS"] + +[mediaTypes] +[mediaTypes."text/netlify"] - suffix = "" +delimiter = "" + +[outputFormats] +[outputFormats.REDIR] +mediatype = "text/netlify" +baseName = "_redirects" +isPlainText = true +notAlternative = true +[outputFormats.HEADERS] +mediatype = "text/netlify" +baseName = "_headers" +isPlainText = true +notAlternative = true + +[related] + +threshold = 80 +includeNewer = true +toLower = false + +[[related.indices]] +name = "keywords" +weight = 100 +[[related.indices]] +name = "date" +weight = 10 +pattern = "2006" + +[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 = "0.45-DEV" + ## 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/" + ## GH Repo for filing a new issue + github_repo = "https://github.com/gohugoio/hugo/issues/new" + ### 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 + # See https://github.com/gohugoio/hugo/issues/2424 + hrefTargetBlank = false + angledQuotes = false + latexDashes = true + +[imaging] +# See https://github.com/disintegration/imaging +# CatmullRom is a sharp bicubic filter which should fit the docs site well with its many screenshots. +# Note that you can also set this per image processing. +resampleFilter = "CatmullRom" + +# Defatult JPEG quality setting. Default is 75. +quality = 75 + +anchor = "smart" + + +## 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/" + + [[menu.global]] + name = "Showcase" + weight = 20 + identifier = "showcase" + url = "/showcase/" + + # 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" + +### LANGUAGES ### + +[languages] + [languages.en] + contentDir = "content/en" + languageName = "English" + weight = 1 + [languages.zh] + contentDir = "content/zh" + languageName = "中文" + weight = 2 + + +### LANGUAGE-SPECIFIC MENUS ### + +# Chinese menus + +[[languages.zh.menu.docs]] + name = "关于 Hugo" + weight = 1 + identifier = "about" + url = "/zh/about/" + +[[languages.zh.menu.docs]] + name = "入门" + weight = 5 + identifier = "getting-started" + url = "/zh/getting-started/" + +[[languages.zh.menu.docs]] + name = "主题" + weight = 15 + identifier = "themes" + post = "break" + url = "/zh/themes/" + +# Core languages.zh.menus + +[[languages.zh.menu.docs]] + name = "内容管理" + weight = 20 + identifier = "content-management" + post = "expanded" + url = "/zh/content-management/" + +[[languages.zh.menu.docs]] + name = "模板" + weight = 25 + identifier = "templates" + url = "/zh/templates/" + +[[languages.zh.menu.docs]] + name = "函数" + weight = 30 + identifier = "functions" + url = "/zh/functions/" + +[[languages.zh.menu.docs]] + name = "变量" + weight = 35 + identifier = "variables" + url = "/zh/variables/" + +[[languages.zh.menu.docs]] + name = "CLI" + weight = 40 + post = "break" + identifier = "commands" + url = "/commands/" + +# LOW LEVEL ITEMS +[[languages.zh.menu.docs]] + name = "故障排除" + weight = 60 + identifier = "troubleshooting" + url = "/zh/troubleshooting/" + +[[languages.zh.menu.docs]] + name = "工具" + weight = 70 + identifier = "tools" + url = "/zh/tools/" + +[[languages.zh.menu.docs]] + name = "托管与部署" + weight = 80 + identifier = "hosting-and-deployment" + url = "/zh/hosting-and-deployment/" + +[[languages.zh.menu.docs]] + name = "贡献" + weight = 100 + post = "break" + identifier = "contribute" + url = "/zh/contribute/" + +[[languages.zh.menu.global]] + name = "新闻" + weight = 1 + identifier = "news" + url = "/zh/news/" + +[[languages.zh.menu.global]] + name = "文档" + weight = 5 + identifier = "docs" + url = "/zh/documentation/" + +[[languages.zh.menu.global]] + name = "主题" + weight = 10 + identifier = "themes" + url = "https://themes.gohugo.io/" + +[[languages.zh.menu.global]] + name = "作品展示" + weight = 20 + identifier = "showcase" + url = "/zh/showcase/" + +# Anything with a weight > 100 gets an external icon +[[languages.zh.menu.global]] + name = "社区" + weight = 150 + icon = true + identifier = "community" + post = "external" + url = "https://discourse.gohugo.io/" + +[[languages.zh.menu.global]] + name = "GitHub" + weight = 200 + identifier = "github" + post = "external" + url = "https://github.com/gohugoio/hugo" diff --cc docs/content/en/about/new-in-032/index.md index b8ca6430,00000000..5ae688fc mode 100644,000000..100644 --- a/docs/content/en/about/new-in-032/index.md +++ b/docs/content/en/about/new-in-032/index.md @@@ -1,209 -1,0 +1,209 @@@ +--- +title: Hugo 0.32 HOWTO +description: About page bundles, image processing and more. +date: 2017-12-28 +keywords: [ssg,static,performance,security] +menu: + docs: + parent: "about" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [] +toc: true +images: +- images/blog/sunset.jpg +--- + + +{{% note %}} +This documentation belongs in other places in this documentation site, but is put here first ... to get something up and running fast. +{{% /note %}} + + +Also see this demo project from [bep](https://github.com/bep/), the clever Norwegian behind these new features: + - * http://hugotest.bep.is/ ++* https://temp.bep.is/hugotest/ +* https://github.com/bep/hugotest (source) + +## Page Resources + +### Organize Your Content + +{{< figure src="/images/hugo-content-bundles.png" title="Pages with image resources" >}} + +The content folder above shows a mix of content pages (`md` (i.e. markdown) files) and image resources. + +{{% note %}} +You can use any file type as a content resource as long as it is a MIME type recognized by Hugo (`json` files will, as one example, work fine). If you want to get exotic, you can define your [own media type](/templates/output-formats/#media-types). +{{% /note %}} + +The 3 page bundles marked in red explained from top to bottom: + +1. The home page with one image resource (`1-logo.png`) +2. The blog section with two images resources and two pages resources (`content1.md`, `content2.md`). Note that the `_index.md` represents the URL for this section. +3. An article (`hugo-is-cool`) with a folder with some images and one content resource (`cats-info.md`). Note that the `index.md` represents the URL for this article. + +The content files below `blog/posts` are just regular standalone pages. + +{{% note %}} +Note that changes to any resource inside the `content` folder will trigger a reload when running in watch (aka server or live reload mode), it will even work with `--navigateToChanged`. +{{% /note %}} + +#### Sort Order + +* Pages are sorted according to standard Hugo page sorting rules. +* Images and other resources are sorted in lexicographical order. + +### Handle Page Resources in Templates + + +#### List all Resources + +```go-html-template +{{ range .Resources }} +
  • {{ .ResourceType | title }}
    • +{{ end }} +``` + +For an absolute URL, use `.Permalink`. + +**Note:** The permalink will be relative to the content page, respecting permalink settings. Also, included page resources will not have a value for `RelPermalink`. + +#### List All Resources by Type + +```go-html-template +{{ with .Resources.ByType "image" }} +{{ end }} + +``` + +Type here is `page` for pages, else the main type in the MIME type, so `image`, `json` etc. + +#### Get a Specific Resource + +```go-html-template +{{ $logo := .Resources.GetByPrefix "logo" }} +{{ with $logo }} +{{ end }} +``` + +#### Include Page Resource Content + +```go-html-template +{{ with .Resources.ByType "page" }} +{{ range . }} +

    {{ .Title }}

    +{{ .Content }} +{{ end }} +{{ end }} + +``` + + +## Image Processing + +The `image` resource implements the methods `Resize`, `Fit` and `Fill`: + +Resize +: Resize to the given dimension, `{{ $logo.Resize "200x" }}` will resize to 200 pixels wide and preserve the aspect ratio. Use `{{ $logo.Resize "200x100" }}` to control both height and width. + +Fit +: Scale down the image to fit the given dimensions, e.g. `{{ $logo.Fit "200x100" }}` will fit the image inside a box that is 200 pixels wide and 100 pixels high. + +Fill +: Resize and crop the image given dimensions, e.g. `{{ $logo.Fill "200x100" }}` will resize and crop to width 200 and height 100 + + +{{% note %}} +Image operations in Hugo currently **do not preserve EXIF data** as this is not supported by Go's [image package](https://github.com/golang/go/search?q=exif&type=Issues&utf8=%E2%9C%93). This will be improved on in the future. +{{% /note %}} + + +### Image Processing Examples + +_The photo of the sunset used in the examples below is Copyright [Bjørn Erik Pedersen](https://commons.wikimedia.org/wiki/User:Bep) (Creative Commons Attribution-Share Alike 4.0 International license)_ + + +{{< imgproc sunset Resize "300x" />}} + +{{< imgproc sunset Fill "90x120 left" />}} + +{{< imgproc sunset Fill "90x120 right" />}} + +{{< imgproc sunset Fit "90x90" />}} + +{{< imgproc sunset Resize "300x q10" />}} + + +This is the shortcode used in the examples above: + + +{{< code file="layouts/shortcodes/imgproc.html" >}} +{{< readfile file="layouts/shortcodes/imgproc.html" >}} +{{< /code >}} + +And it is used like this: + +```go-html-template +{{}} +``` + +### Image Processing Options + +In addition to the dimensions (e.g. `200x100`) where either height or width can be omitted, Hugo supports a set of additional image options: + +Anchor +: Only relevant for `Fill`. This is useful for thumbnail generation where the main motive is located in, say, the left corner. Valid are `Center`, `TopLeft`, `Top`, `TopRight`, `Left`, `Right`, `BottomLeft`, `Bottom`, `BottomRight`. Example: `{{ $logo.Fill "200x100 BottomLeft" }}` + +JPEG Quality +: Only relevant for JPEG images, values 1 to 100 inclusive, higher is better. Default is 75. `{{ $logo.Resize "200x q50" }}` + +Rotate +: Rotates an image by the given angle counter-clockwise. The rotation will be performed first to get the dimensions correct. `{{ $logo.Resize "200x r90" }}`. The main use of this is to be able to manually correct for [EXIF orientation](https://github.com/golang/go/issues/4341) of JPEG images. + +Resample Filter +: Filter used in resizing. Default is `Box`, a simple and fast resampling filter appropriate for downscaling. See https://github.com/disintegration/imaging for more. If you want to trade quality for faster processing, this may be a option to test. + + + +### Performance + +Processed images are stored below `/resources` (can be set with `resourceDir` config setting). This folder is deliberately placed in the project, as it is recommended to check these into source control as part of the project. These images are not "Hugo fast" to generate, but once generated they can be reused. + +If you change your image settings (e.g. size), remove or rename images etc., you will end up with unused images taking up space and cluttering your project. + +To clean up, run: + +```bash +hugo --gc +``` + + +{{% note %}} +**GC** is short for **Garbage Collection**. +{{% /note %}} + + +## Configuration + +### Default Image Processing Config + +You can configure an `imaging` section in `config.toml` with default image processing options: + +```toml +[imaging] +# Default resample filter used for resizing. Default is Box, +# a simple and fast averaging filter appropriate for downscaling. +# See https://github.com/disintegration/imaging +resampleFilter = "box" + +# Defatult JPEG quality setting. Default is 75. +quality = 68 +``` + + + + + diff --cc docs/content/en/about/what-is-hugo.md index 2c7339f7,00000000..de734486 mode 100644,000000..100644 --- a/docs/content/en/about/what-is-hugo.md +++ b/docs/content/en/about/what-is-hugo.md @@@ -1,69 -1,0 +1,65 @@@ +--- +title: What is Hugo +linktitle: What is Hugo +description: Hugo is a fast and modern static site generator written in Go, and designed to make website creation fun again. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +layout: single +menu: + docs: + parent: "about" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [/overview/introduction/,/about/why-i-built-hugo/] +toc: true +--- + +Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator][]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors. + +Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify][], [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [GitLab Pages][], [Surge][], [Aerobatic][], [Firebase][], [Google Cloud Storage][], [Amazon S3][], [Rackspace][], [Azure][], and [CloudFront][] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP. + +We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made. + +## How Fast is Hugo? + +{{< youtube "CdiDYZ51a2o" >}} + +## What Does Hugo Do? + +In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website. + +## Who Should Use Hugo? + +Hugo is for people that prefer writing in a text editor over a browser. + +Hugo is for people who want to hand code their own website without worrying about setting up complicated runtimes, dependencies and databases. + +Hugo is for people building a blog, a company site, a portfolio site, documentation, a single landing page, or a website with thousands of pages. + + + +[@spf13]: https://twitter.com/@spf13 +[Aerobatic]: https://www.aerobatic.com/ - [Amazon S3]: http://aws.amazon.com/s3/ ++[Amazon S3]: https://aws.amazon.com/s3/ +[Azure]: https://blogs.msdn.microsoft.com/acoat/2016/01/28/publish-a-static-web-site-using-azure-web-apps/ - [CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront" - [contributing to it]: https://github.com/gohugoio/hugo - [DreamHost]: http://www.dreamhost.com/ ++[CloudFront]: https://aws.amazon.com/cloudfront/ "Amazon CloudFront" ++[DreamHost]: https://www.dreamhost.com/ +[Firebase]: https://firebase.google.com/docs/hosting/ "Firebase static hosting" +[GitHub Pages]: https://pages.github.com/ +[GitLab Pages]: https://about.gitlab.com/features/pages/ +[Go language]: https://golang.org/ +[GoDaddy]: https://www.godaddy.com/ "Godaddy.com Hosting" - [Google Cloud Storage]: http://cloud.google.com/storage/ ++[Google Cloud Storage]: https://cloud.google.com/storage/ +[Heroku]: https://www.heroku.com/ - [Jekyll]: http://jekyllrb.com/ +[Jekyll]: https://jekyllrb.com/ +[Middleman]: https://middlemanapp.com/ - [Middleman]: https://middlemanapp.com/ - [Nanoc]: http://nanoc.ws/ +[Nanoc]: https://nanoc.ws/ +[Netlify]: https://netlify.com - [rackspace]: https://www.rackspace.com/cloud/files - [static site generator]: /about/benefits/ +[Rackspace]: https://www.rackspace.com/cloud/files - [static site generator]: /about/benefits/ +[Surge]: https://surge.sh ++[contributing to it]: https://github.com/gohugoio/hugo ++[rackspace]: https://www.rackspace.com/cloud/files ++[static site generator]: /about/benefits/ diff --cc docs/content/en/content-management/authors.md index afc94fa6,00000000..530557ac mode 100644,000000..100644 --- a/docs/content/en/content-management/authors.md +++ b/docs/content/en/content-management/authors.md @@@ -1,185 -1,0 +1,185 @@@ +--- +title: Authors +linktitle: Authors +description: +date: 2016-08-22 +publishdate: 2017-03-12 +lastmod: 2017-03-12 +keywords: [authors] +categories: ["content management"] +menu: + docs: + parent: "content-management" + weight: 55 +weight: 55 #rem +draft: true +aliases: [/content/archetypes/] +toc: true +comments: Before this page is published, need to also update both site- and page-level variables documentation. +--- + + + +Larger sites often have multiple content authors. Hugo provides standardized author profiles to organize relationships between content and content creators for sites operating under a distributed authorship model. + +## Author Profiles + +You can create a profile containing metadata for each author on your website. These profiles have to be saved under `data/_authors/`. The filename of the profile will later be used as an identifier. This way Hugo can associate content with one or multiple authors. An author's profile can be defined in the JSON, YAML, or TOML format. + +### Example: Author Profile + +Let's suppose Alice Allison is a blogger. A simple unique identifier would be `alice`. Now, we have to create a file called `alice.toml` in the `data/_authors/` directory. The following example is the standardized template written in TOML: + +{{< code file="data/_authors/alice.toml" >}} +givenName = "Alice" # or firstName as alias +familyName = "Allison" # or lastName as alias +displayName = "Alice Allison" +thumbnail = "static/authors/alice-thumb.jpg" +image = "static/authors/alice-full.jpg" +shortBio = "My name is Alice and I'm a blogger." +bio = "My name is Alice and I'm a blogger... some other stuff" +email = "alice.allison@email.com" +weight = 10 + +[social] + facebook = "alice.allison" + twitter = "alice" + googleplus = "aliceallison1" + website = "www.example.com" + +[params] + random = "whatever you want" +{{< /code >}} + +All variables are optional but it's advised to fill all important ones (e.g. names and biography) because themes can vary in their usage. + +You can store files for the `thumbnail` and `image` attributes in the `static` folder. Then add the path to the photos relative to `static`; e.g., `/static/path/to/thumbnail.jpg`. + +`weight` allows you to define the order of an author in an `.Authors` list and can be accessed on list or via the `.Site.Authors` variable. + +The `social` section contains all the links to the social network accounts of an author. Hugo is able to generate the account links for the most popular social networks automatically. This way, you only have to enter your username. You can find a list of all supported social networks [here](#linking-social-network-accounts-automatically). All other variables, like `website` in the example above remain untouched. + +The `params` section can contain arbitrary data much like the same-named section in the config file. What it contains is up to you. + +## Associate Content Through Identifiers + +Earlier it was mentioned that content can be associated with an author through their corresponding identifier. In our case, blogger Alice has the identifier `alice`. In the front matter of a content file, you can create a list of identifiers and assign it to the `authors` variable. Here are examples for `alice` using YAML and TOML, respectively. + +``` +--- +title: Why Hugo is so Awesome +date: 2016-08-22T14:27:502:00 +authors: ["alice"] +--- + +Nothing to read here. Move along... +``` + +``` ++++ +title = Why Hugo is so Awesome +date = "2016-08-22T14:27:502:00" +authors: ["alice"] ++++ + +Nothing to read here. Move along... +``` + +Future authors who might work on this blog post can append their identifiers to the `authors` array in the front matter as well. + +## Work with Templates + +After a successful setup it's time to give some credit to the authors by showing them on the website. Within the templates Hugo provides a list of the author's profiles if they are listed in the `authors` variable within the front matter. + +The list is accessible via the `.Authors` template variable. Printing all authors of a the blog post is straight forward: + +``` +{{ range .Authors }} + {{ .DisplayName }} +{{ end }} +=> Alice Allison +``` + +Even if there are co-authors you may only want to show the main author. For this case you can use the `.Author` template variable **(note the singular form)**. The template variable contains the profile of the author that is first listed with his identifier in the front matter. + +{{% note %}} +You can find a list of all template variables to access the profile information in [Author Variables](/variables/authors/). +{{% /note %}} + +### Link Social Network Accounts + +As aforementioned, Hugo is able to generate links to profiles of the most popular social networks. The following social networks with their corrersponding identifiers are supported: `github`, `facebook`, `twitter`, `googleplus`, `pinterest`, `instagram`, `youtube` and `linkedin`. + +This is can be done with the `.Social.URL` function. Its only parameter is the name of the social network as they are defined in the profile (e.g. `facebook`, `googleplus`). Custom variables like `website` remain as they are. + +Most articles feature a small section with information about the author at the end. Let's create one containing the author's name, a thumbnail, a (summarized) biography and links to all social networks: + +{{< code file="layouts/partials/author-info.html" download="author-info.html" >}} +{{ with .Author }} +

    {{ .DisplayName }}

    + {{ .DisplayName }} +

    {{ .ShortBio }}

    + +{{ end }} +{{< /code >}} + +## Who Published What? + +That question can be answered with a list of all authors and another list containing all articles that they each have written. Now we have to translate this idea into templates. The [taxonomy][] feature allows us to logically group content based on information that they have in common; e.g. a tag or a category. Well, many articles share the same author, so this should sound familiar, right? + +In order to let Hugo know that we want to group content based on their author, we have to create a new taxonomy called `author` (the name corresponds to the variable in the front matter). Here is the snippet in a `config.yaml` and `config.toml`, respectively: + +``` +taxonomies: + author: authors +``` + +``` +[taxonomies] + author = "authors" +``` + + +### List All Authors + +In the next step we can create a template to list all authors of your website. Later, the list can be accessed at `www.example.com/authors/`. Create a new template in the `layouts/taxonomy/` directory called `authors.term.html`. This template will be exclusively used for this taxonomy. + +{{< code file="layouts/taxonomy/author.term.html" download="author.term.html" >}} + +{{< /code >}} + +`.Data.Terms` contains the identifiers of all authors and we can range over it to create a list with all author names. The `$profile` variable gives us access to the profile of the current author. This allows you to generate a nice info box with a thumbnail, a biography and social media links, like at the [end of a blog post](#linking-social-network-accounts-automatically). + +### List Each Author's Publications + +Last but not least, we have to create the second list that contains all publications of an author. Each list will be shown in its own page and can be accessed at `www.example.com/authors/`. Replace `` with a valid author identifier like `alice`. + +The layout for this page can be defined in the template `layouts/taxonomy/author.html`. + +{{< code file="layouts/taxonomy/author.html" download="author.html" >}} - {{ range .Data.Pages }} ++{{ range .Pages }} +

    {{ .Title }}

    + written by {{ .Author.DisplayName }} + {{ .Summary }} +{{ end }} +{{< /code >}} + +The example above generates a simple list of all posts written by a single author. Inside the loop you've access to the complete set of [page variables][pagevars]. Therefore, you can add additional information about the current posts like the publishing date or the tags. + +With a lot of content this list can quickly become very long. Consider to use the [pagination][] feature. It splits the list into smaller chunks and spreads them over multiple pages. + +[pagevars]: /variables/page/ +[pagination]: /templates/pagination/ diff --cc docs/content/en/content-management/menus.md index c2eadf50,00000000..4278b03b mode 100644,000000..100644 --- a/docs/content/en/content-management/menus.md +++ b/docs/content/en/content-management/menus.md @@@ -1,161 -1,0 +1,122 @@@ +--- +title: Menus +linktitle: Menus +description: Hugo has a simple yet powerful menu system. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-31 +categories: [content management] +keywords: [menus] +draft: false +menu: + docs: + parent: "content-management" + weight: 120 +weight: 120 #rem +aliases: [/extras/menus/] +toc: true +--- + +{{% note "Lazy Blogger"%}} +If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-bloggers). +{{% /note %}} + +You can do this: + +* Place content in one or many menus +* Handle nested menus with unlimited depth +* Create menu entries without being attached to any content +* Distinguish active element (and active branch) + +## What is a Menu in Hugo? + +A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`. + +{{% note "Menus on Multilingual Sites" %}} +If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus. +{{% /note %}} + - A menu entry has the following properties (i.e., variables) available to it: - - `.URL` - : string - - `.Name` - : string - - `.Menu` - : string - - `.Identifier` - : string - - `.Pre` - : template.HTML - - `.Post` - : template.HTML - - `.Weight` - : int - - `.Parent` - : string - - `.Children` - : Menu - - Note that menus also have the following functions available as well: - - `.HasChildren` - : boolean - - Additionally, there are some relevant functions available to menus on a page: - - `.IsMenuCurrent` - : (menu string, menuEntry *MenuEntry ) boolean - - `.HasMenuCurrent` - : (menu string, menuEntry *MenuEntry) boolean ++See the [Menu Entry Properties][me-props] for all the variables and functions related to a menu entry. + +## Add content to menus + +Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/). + +### Simple + +If all you need to do is add an entry to a menu, the simple form works well. + +#### A Single Menu + +``` +--- +menu: "main" +--- +``` + +#### Multiple Menus + +``` +--- +menu: ["main", "footer"] +--- +``` + +#### Advanced + + +``` +--- +menu: + docs: + parent: 'extras' + weight: 20 +--- +``` + +## Add Non-content Entries to a Menu + +You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config]. + +Here’s an example snippet pulled from a configuration file: + +{{< code-toggle file="config.toml" >}} +[[menu.main]] + name = "about hugo" + pre = "" + weight = -110 + identifier = "about" + url = "/about/" +[[menu.main]] + name = "getting started" + pre = "" + weight = -100 + url = "/getting-started/" +{{< /code-toggle >}} + +{{% note %}} +The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`. +{{% /note %}} + +## Nesting - ++ +All nesting of content is done via the `parent` field. + +The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu). + +The following order is used to determine an Identifier: + +`.Name > .LinkTitle > .Title` + +This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed. + +In this example, the top level of the menu is defined in your [site `config` file][config]). All content entries are attached to one of these entries via the `.Parent` field. + +## Render Menus + +See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates. + +[config]: /getting-started/configuration/ +[multilingual]: /content-management/multilingual/ +[sitevars]: /variables/ ++[me-props]: /variables/menus/ diff --cc docs/content/en/content-management/related.md index 5755676c,00000000..9a4c77d4 mode 100644,000000..100644 --- a/docs/content/en/content-management/related.md +++ b/docs/content/en/content-management/related.md @@@ -1,143 -1,0 +1,143 @@@ +--- +title: Related Content +description: List related content in "See Also" sections. +date: 2017-09-05 +categories: [content management] +keywords: [content] +menu: + docs: + parent: "content-management" + weight: 40 +weight: 30 +draft: false +aliases: [/content/related/,/related/] +toc: true +--- + +{{% note %}} +We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock). +{{% /note %}} + +## List Related Content + +To list up to 5 related pages is as simple as including something similar to this partial in your single page template: + +{{< code file="layouts/partials/related.html" >}} +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

    See Also

    + +{{ end }} +{{< /code >}} + + +{{% note %}} +Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. +{{% /note %}} + - The full set of methods available on the page lists can bee seen in this Go interface: ++The full set of methods available on the page lists can be seen in this Go interface: + +```go +// A PageGenealogist finds related pages in a page collection. This interface is implemented +// by Pages and PageGroup, which makes it available as `{{ .RegularPages.Related . }}` etc. +type PageGenealogist interface { + + // Template example: + // {{ $related := .RegularPages.Related . }} + Related(doc related.Document) (Pages, error) + + // Template example: + // {{ $related := .RegularPages.RelatedIndices . "tags" "date" }} + RelatedIndices(doc related.Document, indices ...interface{}) (Pages, error) + + // Template example: + // {{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }} + RelatedTo(args ...types.KeyValues) (Pages, error) +} +``` +## Configure Related Content +Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed. + +{{% note %}} +If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults. +{{% /note %}} + +Below is a sample `config.toml` section: + +``` +[related] + +# Only include matches with rank >= threshold. This is a normalized rank between 0 and 100. +threshold = 80 + +# To get stable "See also" sections we, by default, exclude newer related pages. +includeNewer = false + +# Will lower case keywords in both queries and in the indexes. +toLower = false + +[[related.indices]] +name = "keywords" +weight = 150 +[[related.indices]] +name = "author" +toLower = true +weight = 30 +[[related.indices]] +name = "tags" +weight = 100 +[[related.indices]] +name = "date" +weight = 10 +pattern = "2006" +``` +### Top Level Config Options + +threshold +: A value between 0-100. Lower value will give more, but maybe not so relevant, matches. + +includeNewer +: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added. + +toLower +: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index. + +### Config Options per Index + +name +: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. + +weight +: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. + +pattern +: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. + +toLower +: See above. + +## Performance Considerations + +**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast. + +This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread: + +{{< tweet 898398437527363585 >}} + +Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog. + +He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that: + +* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before. +* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites. + + + + + + + diff --cc docs/content/en/content-management/shortcodes.md index 0116078f,00000000..35305764 mode 100644,000000..100644 --- a/docs/content/en/content-management/shortcodes.md +++ b/docs/content/en/content-management/shortcodes.md @@@ -1,400 -1,0 +1,400 @@@ +--- +title: Shortcodes +linktitle: +description: Shortcodes are simple snippets inside your content files calling built-in or custom templates. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-31 +menu: + docs: + parent: "content-management" + weight: 35 +weight: 35 #rem +categories: [content management] +keywords: [markdown,content,shortcodes] +draft: false +aliases: [/extras/shortcodes/] +toc: true +--- + +## What a Shortcode is + +Hugo loves Markdown because of its simple content format, but there are times when Markdown falls short. Often, content authors are forced to add raw HTML (e.g., video ``) to Markdown content. We think this contradicts the beautiful simplicity of Markdown's syntax. + +Hugo created **shortcodes** to circumvent these limitations. + +A shortcode is a simple snippet inside a content file that Hugo will render using a predefined template. Note that shortcodes will not work in template files. If you need the type of drop-in functionality that shortcodes provide but in a template, you most likely want a [partial template][partials] instead. + +In addition to cleaner Markdown, shortcodes can be updated any time to reflect new classes, techniques, or standards. At the point of site generation, Hugo shortcodes will easily merge in your changes. You avoid a possibly complicated search and replace operation. + +## Use Shortcodes + +{{< youtube 2xkNJL4gJ9E >}} + +In your content files, a shortcode can be called by calling `{{%/* shortcodename parameters */%}}`. Shortcode parameters are space delimited, and parameters with internal spaces can be quoted. + +The first word in the shortcode declaration is always the name of the shortcode. Parameters follow the name. Depending upon how the shortcode is defined, the parameters may be named, positional, or both, although you can't mix parameter types in a single call. The format for named parameters models that of HTML with the format `name="value"`. + +Some shortcodes use or require closing shortcodes. Again like HTML, the opening and closing shortcodes match (name only) with the closing declaration, which is prepended with a slash. + +Here are two examples of paired shortcodes: + +``` +{{%/* mdshortcode */%}}Stuff to `process` in the *center*.{{%/* /mdshortcode */%}} +``` + +``` +{{}} A bunch of code here {{}} +``` + +The examples above use two different delimiters, the difference being the `%` character in the first and the `<>` characters in the second. + +### Shortcodes with Markdown + +The `%` character indicates that the shortcode's inner content---called in the [shortcode template][sctemps] with the [`.Inner` variable][scvars]---needs further processing by the page's rendering processor (i.e. markdown via Blackfriday). In the following example, Blackfriday would convert `**World**` to `World`: + +``` +{{%/* myshortcode */%}}Hello **World!**{{%/* /myshortcode */%}} +``` + +### Shortcodes Without Markdown + +The `<` character indicates that the shortcode's inner content does *not* need further rendering. Often shortcodes without markdown include internal HTML: + +``` +{{}}

    Hello World!

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

    Steve Francia

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

    {{ .Title }}

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