From: Bjørn Erik Pedersen Date: Wed, 12 Dec 2018 08:06:42 +0000 (+0100) Subject: Merge commit 'eb16165694f868d73e57b6aed5c26ba5e98229de' X-Git-Tag: v0.53~33 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=b17a61a6056a516949dd9aa11034c39c9ad8e37e;p=brevno-suite%2Fhugo Merge commit 'eb16165694f868d73e57b6aed5c26ba5e98229de' --- b17a61a6056a516949dd9aa11034c39c9ad8e37e diff --cc docs/.github/stale.yml index 00000000,00000000..f1074761 new file mode 100644 --- /dev/null +++ b/docs/.github/stale.yml @@@ -1,0 -1,0 +1,21 @@@ ++# Number of days of inactivity before an issue becomes stale ++daysUntilStale: 120 ++# Number of days of inactivity before a stale issue is closed ++daysUntilClose: 30 ++# Issues with these labels will never be considered stale ++exemptLabels: ++ - Keep ++ - Security ++# Label to use when marking an issue as stale ++staleLabel: Stale ++# Comment to post when marking an issue as stale. Set to `false` to disable ++markComment: > ++ This issue has been automatically marked as stale because it has not had ++ recent activity. The resources of the Hugo team are limited, and so we are asking for your help. ++ ++ If you still think this is important, please tell us why. ++ ++ This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions. ++ ++# Comment to post when closing a stale issue. Set to `false` to disable ++closeComment: false diff --cc docs/content/en/content-management/front-matter.md index 4cf6825d,00000000..13016091 mode 100644,000000..100644 --- a/docs/content/en/content-management/front-matter.md +++ b/docs/content/en/content-management/front-matter.md @@@ -1,186 -1,0 +1,184 @@@ +--- +title: Front Matter +linktitle: +description: Hugo allows you to add front matter in yaml, toml, or json to your content files. +date: 2017-01-09 +publishdate: 2017-01-09 +lastmod: 2017-02-24 +categories: [content management] +keywords: ["front matter", "yaml", "toml", "json", "metadata", "archetypes"] +menu: + docs: + parent: "content-management" + weight: 30 +weight: 30 #rem +draft: false +aliases: [/content/front-matter/] +toc: true +--- + +**Front matter** allows you to keep metadata attached to an instance of a [content type][]---i.e., embedded inside a content file---and is one of the many features that gives Hugo its strength. + +{{< youtube Yh2xKRJGff4 >}} + +## Front Matter Formats + +Hugo supports three formats for front matter, each with their own identifying tokens. + +TOML +: identified by opening and closing `+++`. + +YAML +: identified by opening and closing `---`. + +JSON +: a single JSON object surrounded by '`{`' and '`}`', followed by a new line. + +### Example + +{{< code-toggle >}} - +++ +title = "spf13-vim 3.0 release and new website" +description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." +tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] +date = "2012-04-06" +categories = [ + "Development", + "VIM" +] +slug = "spf13-vim-3-0-release-and-new-website" - +++ - {{}} ++{{< /code-toggle >}} + +## 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. + +audio +: an array of paths to audio files related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:audio`. + +date +: the datetime at which the content was created; note this value is auto-populated according to Hugo's built-in [archetype][]. + +description +: the description for the content. + +draft +: if `true`, the content will not be rendered unless the `--buildDrafts` flag is passed to the `hugo` command. + +expiryDate +: the datetime at which the content should no longer be published by Hugo; expired content will not be rendered unless the `--buildExpired` flag is passed to the `hugo` command. + +headless +: if `true`, sets a leaf bundle to be [headless][headless-bundle]. + +images +: an array of paths to images related to the page; used by [internal templates](/templates/internal) such as `_internal/twitter_cards.html`. + +isCJKLanguage +: if `true`, Hugo will explicitly treat the content as a CJK language; both `.Summary` and `.WordCount` work properly in CJK languages. + +keywords +: the meta keywords for the content. + +layout +: the layout Hugo should select from the [lookup order][lookup] when rendering the content. If a `type` is not specified in the front matter, Hugo will look for the layout of the same name in the layout directory that corresponds with a content's section. See ["Defining a Content Type"][definetype] + +lastmod +: the datetime at which the content was last modified. + +linkTitle +: used for creating links to content; if set, Hugo defaults to using the `linktitle` before the `title`. Hugo can also [order lists of content by `linktitle`][bylinktitle]. + +markup +: **experimental**; specify `"rst"` for reStructuredText (requires`rst2html`) or `"md"` (default) for Markdown. + +outputs +: allows you to specify output formats specific to the content. See [output formats][outputs]. + +publishDate +: if in the future, content will not be rendered unless the `--buildFuture` flag is passed to `hugo`. + +resources +: used for configuring page bundle resources. See [Page Resources][page-resources]. + +series +: an array of series this page belongs to, as a subset of the `series` [taxonomy](/content-management/taxonomies/); used by the `opengraph` [internal template](/templates/internal) to populate `og:see_also`. + +slug +: appears as the tail of the output URL. A value specified in front matter will override the segment of the URL based on the filename. + +title +: the title for the content. + +type +: the type of the content; this value will be automatically derived from the directory (i.e., the [section][]) if not specified in front matter. + +url +: the full path to the content from the web root. It makes no assumptions about the path of the content file. It also ignores any language prefixes of +the multilingual feature. + +videos +: an array of paths to videos related to the page; used by the `opengraph` [internal template](/templates/internal) to populate `og:video`. + +weight +: used for [ordering your content in lists][ordering]. Lower weight gets higher precedence. So content with lower weight will come first. + +\ +: field name of the *plural* form of the index. See `tags` and `categories` in the above front matter examples. _Note that the plural form of user-defined taxonomies cannot be the same as any of the predefined front matter variables._ + +{{% note "Hugo's Default URL Destinations" %}} +If neither `slug` nor `url` is present and [permalinks are not configured otherwise in your site `config` file](/content-management/urls/#permalinks), Hugo will use the filename of your content to create the output URL. See [Content Organization](/content-management/organization) for an explanation of paths in Hugo and [URL Management](/content-management/urls/) for ways to customize Hugo's default behaviors. +{{% /note %}} + +### User-Defined + +You can add fields to your front matter arbitrarily to meet your needs. These user-defined key-values are placed into a single `.Params` variable for use in your templates. + +The following fields can be accessed via `.Params.include_toc` and `.Params.show_comments`, respectively. The [Variables][] section provides more information on using Hugo's page- and site-level variables in your templates. + +{{< code-toggle copy="false" >}} +include_toc: true +show_comments: false +{{}} + + +## Order Content Through Front Matter + +You can assign content-specific `weight` in the front matter of your content. These values are especially useful for [ordering][ordering] in list views. You can use `weight` for ordering of content and the convention of [`_weight`][taxweight] for ordering content within a taxonomy. See [Ordering and Grouping Hugo Lists][lists] to see how `weight` can be used to organize your content in list views. + +## Override Global Markdown Configuration + +It's possible to set some options for Markdown rendering in a content's front matter as an override to the [BlackFriday rendering options set in your project configuration][config]. + +## Front Matter Format Specs + +* [TOML Spec][toml] +* [YAML Spec][yaml] +* [JSON Spec][json] + +[variables]: /variables/ +[aliases]: /content-management/urls/#aliases/ +[archetype]: /content-management/archetypes/ +[bylinktitle]: /templates/lists/#by-link-title +[config]: /getting-started/configuration/ "Hugo documentation for site configuration" +[content type]: /content-management/types/ +[contentorg]: /content-management/organization/ +[definetype]: /content-management/types/#defining-a-content-type "Learn how to specify a type and a layout in a content's front matter" +[headless-bundle]: /content-management/page-bundles/#headless-bundle +[json]: https://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf "Specification for JSON, JavaScript Object Notation" +[lists]: /templates/lists/#ordering-content "See how to order content in list pages; for example, templates that look to specific _index.md for content and front matter." +[lookup]: /templates/lookup-order/ "Hugo traverses your templates in a specific order when rendering content to allow for DRYer templating." +[ordering]: /templates/lists/ "Hugo provides multiple ways to sort and order your content in list templates" +[outputs]: /templates/output-formats/ "With the release of v22, you can output your content to any text format using Hugo's familiar templating" +[page-resources]: /content-management/page-resources/ +[pagevars]: /variables/page/ +[section]: /content-management/sections/ +[taxweight]: /content-management/taxonomies/ +[toml]: https://github.com/toml-lang/toml "Specification for TOML, Tom's Obvious Minimal Language" +[urls]: /content-management/urls/ +[variables]: /variables/ +[yaml]: http://yaml.org/spec/ "Specification for YAML, YAML Ain't Markup Language" diff --cc docs/content/en/content-management/multilingual.md index c72cb50c,00000000..e8d2291a mode 100644,000000..100644 --- a/docs/content/en/content-management/multilingual.md +++ b/docs/content/en/content-management/multilingual.md @@@ -1,462 -1,0 +1,463 @@@ +--- +title: Multilingual Mode +linktitle: Multilingual and i18n +description: Hugo supports the creation of websites with multiple languages side by side. +date: 2017-01-10 +publishdate: 2017-01-10 +lastmod: 2017-01-10 +categories: [content management] +keywords: [multilingual,i18n, internationalization] +menu: + docs: + parent: "content-management" + weight: 150 +weight: 150 #rem +draft: false +aliases: [/content/multilingual/,/tutorials/create-a-multilingual-site/] +toc: true +--- + +You should define the available languages in a `languages` section in your site configuration. + +> Also See [Hugo Multilingual Part 1: Content translation](https://regisphilibert.com/blog/2018/08/hugo-multilingual-part-1-managing-content-translation/) + +## Configure Languages + +The following is an example of a site configuration for a multilingual Hugo project: + +{{< code-toggle file="config" >}} +DefaultContentLanguage = "en" +copyright = "Everything is mine" + +[params] +[params.navigation] +help = "Help" + +[languages] +[languages.en] +title = "My blog" +weight = 1 +[languages.en.params] +linkedin = "https://linkedin.com/whoever" + +[languages.fr] +title = "Mon blogue" +weight = 2 +[languages.fr.params] +linkedin = "https://linkedin.com/fr/whoever" +[languages.fr.params.navigation] +help = "Aide" +{{< /code-toggle >}} + +Anything not defined in a `[languages]` block will fall back to the global value for that key (e.g., `copyright` for the English [`en`] language). This also works for `params`, as demonstrated witgh `help` above: You will get the value `Aide` in French and `Help` in all the languages without this parameter set. + +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. + +`defaultContentLanguage` sets the project's default language. If not set, the default language will be `en`. + +If the default language needs to be rendererd below its own language code (`/en`) like the others, set `defaultContentLanguageInSubdir: true`. + +Only the obvious non-global options can be overridden per language. Examples of global options are `baseURL`, `buildDrafts`, etc. + +### Disable a Language + +You can disable one or more languages. This can be useful when working on a new translation. + +```toml +disableLanguages = ["fr", "ja"] +``` + +Note that you cannot disable the default content language. + +We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables): + +```bash +HUGO_DISABLELANGUAGES="fr ja" hugo +``` +If you have already a list of disabled languages in `config.toml`, you can enable them in development like this: + +```bash +HUGO_DISABLELANGUAGES=" " hugo server +``` + + +### Configure Multilingual Multihost + +From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. + +This means that you can now configure a `baseURL` per `language`: + + +> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. + +Example: + +{{< code-toggle file="config" >}} +[languages] +[languages.fr] +baseURL = "https://example.fr" +languageName = "Français" +weight = 1 +title = "En Français" + +[languages.en] +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" +{{}} + +With the above, the two sites will be generated into `public` with their own root: + +```bash +public +├── en +└── no +``` + +**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.** + +When you run `hugo server` we will start multiple HTTP servers. You will typlically see something like this in the console: + +```bash +Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) +Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) +Press Ctrl+C to stop +``` + +Live reload and `--navigateToChanged` between the servers work as expected. + +### Taxonomies and Blackfriday + +Taxonomies and [Blackfriday configuration][config] can also be set per language: + + +{{< code-toggle file="config" >}} +[Taxonomies] +tag = "tags" + +[blackfriday] +angledQuotes = true +hrefTargetBlank = true + +[languages] +[languages.en] +weight = 1 +title = "English" +[languages.en.blackfriday] +angledQuotes = false + +[languages.fr] +weight = 2 +title = "Français" +[languages.fr.Taxonomies] +plaque = "plaques" +{{}} + +## Translate Your Content + +There are two ways to manage your content translation, both ensures each page is assigned a language and linked to its translations. + +### Translation by filename + +Considering the following example: + +1. `/content/about.en.md` +2. `/content/about.fr.md` + +The first file is assigned the english language and linked to the second. +The second file is assigned the french language and linked to the first. + +Their language is __assigned__ according to the language code added as __suffix to the filename__. + +By having the same **path and base filename**, the content pieces are __linked__ together as translated pages. +{{< note >}} + +If a file is missing any language code, it will be assigned the default language. + +{{}} +### Translation by content directory + +This system uses different content directories for each of the languages. Each language's content directory is set using the `contentDir` param. + +{{< code-toggle file="config" >}} + +languages: + en: + weight: 10 + languageName: "English" + contentDir: "content/english" + nn: + weight: 20 + languageName: "Français" + contentDir: "content/french" + +{{< /code-toggle >}} + +The value of `contentDir` can be any valid path, even absolute path references. The only restriction is that the content directories cannot overlap. + +Considering the following example in conjunction with the configuration above: + +1. `/content/english/about.md` +2. `/content/french/about.md` + +The first file is assigned the english language and is linked to the second. +
The second file is assigned the french language and is linked to the first. + +Their language is __assigned__ according to the content directory they are __placed__ in. + +By having the same **path and basename** (relative to their language content directory), the content pieces are __linked__ together as translated pages. + +### Bypassing default linking. + +Any pages sharing the same `translationKey` set in front matter will be linked as translated pages regardless of basename or location. + +Considering the following example: + +1. `/content/about-us.en.md` +2. `/content/om.nn.md` +3. `/content/presentation/a-propos.fr.md` + +```yaml +# set in all three pages +translationKey: "about" +``` + +By setting the `translationKey` front matter param to `about` in all three pages, they will be __linked__ as translated pages. + + +### Localizing permalinks + +Because paths and filenames are used to handle linking, all translated pages, except for the language part, will be sharing the same url. + +To localize the URLs, the [`slug`]({{< ref "/content-management/organization/index.md#slug" >}}) or [`url`]({{< ref "/content-management/organization/index.md#url" >}}) front matter param can be set in any of the non-default language file. + +For example, a french translation (`content/about.fr.md`) can have its own localized slug. + +{{< code-toggle >}} +Title: A Propos +slug: "a-propos" +{{< /code-toggle >}} + + +At render, Hugo will build both `/about/` and `fr/a-propos/` while maintaning their translation linking. +{{% note %}} +If using `url`, remember to include the language part as well: `fr/compagnie/a-propos/`. +{{%/ note %}} + +### Page Bundles + +To avoid the burden of having to duplicate files, each Page Bundle inherits the resources of its linked translated pages' bundles except for the content files (markdown files, html files etc...). + +Therefore, from within a template, the page will have access to the files from all linked pages' bundles. + +If, across the linked bundles, two or more files share the same basenname, only one will be included and chosen as follows: + +* File from current language Bundle, if present. +* First file found across bundles by order of language `Weight`. + +{{% note %}} + +Page Bundle's resources follow the same language assignement logic as content files, be it by filename (`image.jpg`, `image.fr.jpg`) or by directory (`english/about/header.jpg`, `french/about/header.jpg`). + +{{%/ note %}} + +## Reference the Translated Content + +To create a list of links to translated content, use a template similar to the following: + +{{< code file="layouts/partials/i18nlist.html" >}} +{{ if .IsTranslated }} +

{{ i18n "translations" }}

+ +{{ end }} +{{< /code >}} + +The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page. + +The above also uses the [`i18n` function][i18func] described in the next section. + +### List All Available Languages + +`.AllTranslations` on a `Page` can be used to list all translations, including itself. Called on the home page it can be used to build a language navigator: + + +{{< code file="layouts/partials/allLanguages.html" >}} + +{{< /code >}} + +## Translation of Strings + +Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows. + +Translations are collected from the `themes//i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc. + +{{% note %}} +From **Hugo 0.31** you no longer need to use a valid language code. It _can be_ anything. + +See https://github.com/gohugoio/hugo/issues/3564 + +{{% /note %}} + +From within your templates, use the `i18n` function like this: + +``` +{{ i18n "home" }} +``` + +This uses a definition like this one in `i18n/en-US.toml`: + +``` +[home] +other = "Home" +``` + +Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`: + +``` +{{ i18n "wordCount" . }} +``` + +This uses a definition like this one in `i18n/en-US.toml`: + +``` +[wordCount] +other = "This article has {{ .WordCount }} words." +``` +An example of singular and plural form: + +``` +[readingTime] +one = "One minute read" +other = "{{.Count}} minutes read" +``` +And then in the template: + +``` +{{ i18n "readingTime" .ReadingTime }} +``` - To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: - - ``` - hugo --i18n-warnings | grep i18n - i18n|MISSING_TRANSLATION|en|wordCount - ``` + +## Customize Dates + +At the time of this writing, Go does not yet have support for internationalized locales, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content: + +~~~yaml +1: "janvier" +2: "février" +3: "mars" +4: "avril" +5: "mai" +6: "juin" +7: "juillet" +8: "août" +9: "septembre" +10: "octobre" +11: "novembre" +12: "décembre" +~~~ + +... then index the non-English date names in your templates like so: + +~~~html + +~~~ + +This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file. + +## Menus + +You can define your menus for each language independently. The [creation of a menu][menus] works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file: + +``` +defaultContentLanguage = "en" + +[languages.en] +weight = 0 +languageName = "English" + +[[languages.en.menu.main]] +url = "/" +name = "Home" +weight = 0 + + +[languages.de] +weight = 10 +languageName = "Deutsch" + +[[languages.de.menu.main]] +url = "/" +name = "Startseite" +weight = 0 +``` + +The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version as the default content language that resides in the root directory. + +``` +
    + {{- $currentPage := . -}} + {{ range .Site.Menus.main -}} +
  • + {{ .Name }} +
    • + {{- end }} +
+ +``` + +## Missing Translations + +If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. + +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. + +{{% note %}} +Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments. +{{% /note %}} + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). + ++To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: ++ ++``` ++ hugo --i18n-warnings | grep i18n ++i18n|MISSING_TRANSLATION|en|wordCount ++``` ++ +## 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 `.RelPermalink` +* 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/en/content-management/shortcodes.md index 5bb404fb,00000000..1990cce5 mode 100644,000000..100644 --- a/docs/content/en/content-management/shortcodes.md +++ b/docs/content/en/content-management/shortcodes.md @@@ -1,419 -1,0 +1,419 @@@ +--- +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/] +testparam: "Hugo Rocks!" +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 .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 .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 >}} + + +### `param` + +Gets a value from the current `Page's` params set in front matter, with a fall back to the site param value. If will log an `ERROR` if the param with the given key could not be found in either. + +```bash +{{}} +``` + - Since `testparam` is a param defined in front matter of this page wi the value `Hugo Rocks!`, the above will print: ++Since `testparam` is a param defined in front matter of this page with the value `Hugo Rocks!`, the above will print: + +{{< param testparam >}} + +To access deeply nested params, use "dot syntax", e.g: + +```bash +{{}} +``` + +### `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 `