From: Bjørn Erik Pedersen Date: Mon, 31 Jul 2017 07:21:24 +0000 (+0200) Subject: Merge commit '50ec65fbe1a48475d3320775dab2c47389c02114' X-Git-Tag: v0.26~17 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=1c18f3fc4;p=brevno-suite%2Fhugo Merge commit '50ec65fbe1a48475d3320775dab2c47389c02114' --- 1c18f3fc49051fe75604b804e514be7e15712526 diff --cc docs/README.md index eba081c9,00000000..c482ff63 mode 100644,000000..100644 --- a/docs/README.md +++ b/docs/README.md @@@ -1,38 -1,0 +1,40 @@@ +# Hugo Docs + +Documentation site for [Hugo](https://github.com/gohugoio/hugo), the very fast and flexible static site generator built with love in GoLang. + +## Contributing + +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. + +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 ++▶ hugo server ++ +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/archetypes/default.md index e325a7d9,00000000..0b7f8fdb mode 100644,000000..100644 --- a/docs/archetypes/default.md +++ b/docs/archetypes/default.md @@@ -1,13 -1,0 +1,11 @@@ +--- - linktitle: "" ++title: "{{ replace .TranslationBaseName "-" " " | title }}" ++date: {{ .Date }} +description: "" - godocref: "" - publishdate: "" - lastmod: "" +categories: [] - tags: [] - weight: 00 ++#tags: [] +slug: "" +aliases: [] +toc: false ++draft: true +--- diff --cc docs/config.toml index 08c72176,00000000..61df5b87 mode 100644,000000..100644 --- a/docs/config.toml +++ b/docs/config.toml @@@ -1,230 -1,0 +1,234 @@@ +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" ++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 + +# See https://help.farbox.com/pygments.html +pygmentsStyle = "friendly" + +[outputs] - home = [ "HTML", "RSS", "REDIR" ] ++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 + +[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 3f9ad64a,00000000..ec8883c4 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" ++title: "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? + 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/roadmap.md index 0bc0b02a,00000000..b69126a8 mode 100644,000000..100644 --- a/docs/content/about/roadmap.md +++ b/docs/content/about/roadmap.md @@@ -1,51 -1,0 +1,51 @@@ +--- +title: Roadmap +linktitle: Roadmap +description: Take a look at what's in the pipeline for future versions of the Hugo project. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [about hugo] +#tags: [about,contribute,roadmap] +menu: + docs: + parent: "about" + weight: 50 +weight: 50 +sections_weight: 50 +draft: false +aliases: [/meta/roadmap] +toc: false +--- + +To track Hugo's progress, see our [GitHub Milestones][milestones]. + +In no particular order, here are some other features currently being worked on: + +* Even easier deployment to S3, SSH, GitHub, rsync. Give the [hosting and deployment][] section a shot. +* Import from other website systems. There are already [existing migration tools][migrate], but they don’t cover all major platforms. +* An interactive web-based editor (See the [related forum thread][]) +* Additional [themes][], which are always ongoing and [contributions are welcome][themescontrib]! +* Dynamic image resizing via shortcodes ({{< gh 1014 >}}) +* Native support for additional content formats (AsciiDoc {{< gh 1435>}}, reST {{< gh 1436 >}}) +* And, last but not least, [***your*** best ideas!][] + +## Contributions Welcome + +Feel free to [contribute to Hugo's development][devcontribute], [improve Hugo's documentation][doccontribute], or [open a new issue][newissue] if you have an idea for a new feature. + +[#98]: https://github.com/gohugoio/hugo/issues/98 +[#1014]: https://github.com/gohugoio/hugo/issues/1014 +[#1435]: https://github.com/gohugoio/hugo/issues/1435 +[#1436]: https://github.com/gohugoio/hugo/issues/1436 +[devcontribute]: /contribute/development/ +[doccontribute]: /contribute/documentation/ +[hosting and deployment]: /hosting-and-deployment/ +[migrate]: /tools/migrations/ +[milestones]: https://github.com/gohugoio/hugo/milestone/14 +[newissue]: https://github.com/gohugoio/hugo/issues/ - [related forum thread]: https://disourse.gohugo.io/t/web-based-editor/155 ++[related forum thread]: https://discourse.gohugo.io/t/web-based-editor/155 +[themes]: /themes/ +[themescontrib]: /contribute/themes/ +[tutorials]: /tutorials +[***your*** best ideas!]: /contribute/ diff --cc docs/content/content-management/archetypes.md index 9fc58139,00000000..235de4ff mode 100644,000000..100644 --- a/docs/content/content-management/archetypes.md +++ b/docs/content/content-management/archetypes.md @@@ -1,196 -1,0 +1,192 @@@ +--- +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. + ++{{< youtube S3Tj3UcTFz8 >}} ++ +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: + +``` +hugo new / +``` + +We can use this pattern to create a new `.md` file in the `posts` section: + +{{< code file="archetype-example.sh" >}} +hugo new posts/my-first-post.md +{{< /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" %}} - ``` ++{{< output file="content/posts/my-first-post.md" >}} ++++ +date = "2017-02-01T19:20:04-07:00" +title = "my first post" +draft = true ++++ - ``` - {{% /output %}} ++{{< /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" >}} ++++ +tags = ["golang", "hugo"] +categories = ["web development"] ++++ +{{< /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" >}} +$ hugo new posts/my-new-post.md +{{< /code >}} + +Hugo then creates a new markdown file with the following front matter: + - {{% output file="content/posts/my-new-post.md" %}} - ``` ++{{< output file="content/posts/my-new-post.md" >}} ++++ +categories = ["web development"] +date = "2017-02-01T19:20:04-07:00" +tags = ["golang", "hugo"] +title = "my new post" ++++ - ``` - {{% /output %}} ++{{< /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">}} ++++ +description = "" +tags = "" +categories = "" ++++ +{{< /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" >}} +$ hugo new posts/post-from-custom.md +{{< /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" %}} - ``` ++{{< output file="content/posts/post-from-custom-archetype.md" >}} ++++ +categories = "" +date = 2017-02-13T17:24:43-08:00 +description = "" +tags = "" +title = "post from custom archetype" ++++ - ``` - {{% /output %}} ++{{< /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" >}} +{{< readfile file="/themes/gohugoioTheme/archetypes/functions.md" >}} +{{< /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/formats.md index be84e7cf,00000000..c2837ffc mode 100644,000000..100644 --- a/docs/content/content-management/formats.md +++ b/docs/content/content-management/formats.md @@@ -1,241 -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" >}} +- [ ] a task list item +- [ ] list syntax required +- [ ] incomplete +- [x] completed +{{< /code >}} + +#### Example Task List Output + +The preceding markdown produces the following HTML in your rendered website: + +``` +
    +
  • a task list item
    • +
  • list syntax required
    • +
  • incomplete
    • +
  • completed
    • +
+``` + +#### Example Task List Display + +The following shows how the example task list will look to the end users of your website. Note that visual styling of lists is up to you. This list has been styled according to [the Hugo Docs stylesheet][hugocss]. + +- [ ] a task list item +- [ ] list syntax required +- [ ] incomplete +- [x] completed + +### Emojis + +To add emojis directly to content, set `enableEmoji` to `true` in your [site configuration][config]. To use emojis in templates or shortcodes, see [`emojify` function][]. + +For a full list of emojis, see the [Emoji cheat sheet][emojis]. + +### Shortcodes + +If you write in Markdown and find yourself frequently embedding your content with raw HTML, Hugo provides built-in shortcodes functionality. This is one of the most powerful features in Hugo and allows you to create your own Markdown extensions very quickly. + +See [Shortcodes][sc] for usage, particularly for the built-in shortcodes that ship with Hugo, and [Shortcode Templating][sct] to learn how to build your own. + +### Code Blocks + +Hugo supports GitHub-flavored markdown's use of triple back ticks, as well as provides a special [`highlight` 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: + +``` +--- +title: My Post +date: 2017-04-01 - markdown: mmark ++markup: mmark +--- +``` + +{{% warning %}} +Thare are some features not available in Mmark; one example being that shortcodes are not translated when used in an included `.mmark` file ([#3131](https://github.com/gohugoio/hugo/issues/3137)), and `EXTENSION_ABBREVIATION` ([#1970](https://github.com/gohugoio/hugo/issues/1970)) and the aforementioned GFM todo lists ([#2270](https://github.com/gohugoio/hugo/issues/2270)) are not fully supported. Contributions are welcome. +{{% /warning %}} + +## MathJax with Hugo + +[MathJax](http://www.mathjax.org/) is a JavaScript library that allows the display of mathematical expressions described via a LaTeX-style syntax in the HTML (or Markdown) source of a web page. As it is a pure a JavaScript library, getting it to work within Hugo is fairly straightforward, but does have some oddities that will be discussed here. + +This is not an introduction into actually using MathJax to render typeset mathematics on your website. Instead, this page is a collection of tips and hints for one way to get MathJax working on a website built with Hugo. + +### Enable MathJax + +The first step is to enable MathJax on pages that you would like to have typeset math. There are multiple ways to do this (adventurous readers can consult the [Loading and Configuring](http://docs.mathjax.org/en/latest/configuration.html) section of the MathJax documentation for additional methods of including MathJax), but the easiest way is to use the secure MathJax CDN by include a ` +{{< /code >}} + +One way to ensure that this code is included in all pages is to put it in one of the templates that live in the `layouts/partials/` directory. For example, I have included this in the bottom of my template `footer.html` because I know that the footer will be included in every page of my website. + +### Options and Features + +MathJax is a stable open-source library with many features. I encourage the interested reader to view the [MathJax Documentation](http://docs.mathjax.org/en/latest/index.html), specifically the sections on [Basic Usage](http://docs.mathjax.org/en/latest/index.html#basic-usage) and [MathJax Configuration Options](http://docs.mathjax.org/en/latest/index.html#mathjax-configuration-options). + +### Issues with Markdown + +{{% note %}} +The following issues with Markdown assume you are using `.md` for content and BlackFriday for parsing. Using [Mmark](#mmark) as your content format will obviate the need for the following workarounds. + +When using Mmark with MathJax, use `displayMath: [['$$','$$'], ['\\[','\\]']]`. See the [Mmark `README.md`](https://github.com/miekg/mmark/wiki/Syntax#math-blocks) for more information. In addition to MathJax, Mmark has been shown to work well with [KaTeX](https://github.com/Khan/KaTeX). See this [related blog post from a Hugo user](http://nosubstance.me/post/a-great-toolset-for-static-blogging/). +{{% /note %}} + +After enabling MathJax, any math entered between proper markers (see the [MathJax documentation][mathjaxdocs]) will be processed and typeset in the web page. One issue that comes up, however, with Markdown is that the underscore character (`_`) is interpreted by Markdown as a way to wrap text in `emph` blocks while LaTeX (MathJax) interprets the underscore as a way to create a subscript. This "double speak" of the underscore can result in some unexpected and unwanted behavior. + +### Solution + +There are multiple ways to remedy this problem. One solution is to simply escape each underscore in your math code by entering `\_` instead of `_`. This can become quite tedious if the equations you are entering are full of subscripts. + +Another option is to tell Markdown to treat the MathJax code as verbatim code and not process it. One way to do this is to wrap the math expression inside a `
` `
` block. Markdown would ignore these sections and they would get passed directly on to MathJax and processed correctly. This works great for display style mathematics, but for inline math expressions the line break induced by the `
` is not acceptable. The syntax for instructing Markdown to treat inline text as verbatim is by wrapping it in backticks (`` ` ``). You might have noticed, however, that the text included in between backticks is rendered differently than standard text (on this site these are items highlighted in red). To get around this problem, we could create a new CSS entry that would apply standard styling to all inline verbatim text that includes MathJax code. Below I will show the HTML and CSS source that would accomplish this (note this solution was adapted from [this blog post](http://doswa.com/2011/07/20/mathjax-in-markdown.html)---all credit goes to the original author). + +{{< code file="mathjax-markdown-solution.html" >}} + + + +{{< /code >}} + + + +As before, this content should be included in the HTML source of each page that will be using MathJax. The next code snippet contains the CSS that is used to have verbatim MathJax blocks render with the same font style as the body of the page. + +{{< code file="mathjax-style.css" >}} +code.has-jax { + font: inherit; + font-size: 100%; + background: inherit; + border: inherit; + color: #515151; +} +{{< /code >}} + +In the CSS snippet, notice the line `color: #515151;`. `#515151` is the value assigned to the `color` attribute of the `body` class in my CSS. In order for the equations to fit in with the body of a web page, this value should be the same as the color of the body. + +### Usage + +With this setup, everything is in place for a natural usage of MathJax on pages generated using Hugo. In order to include inline mathematics, just put LaTeX code in between `` `$ TeX Code $` `` or `` `\( TeX Code \)` ``. To include display style mathematics, just put LaTeX code in between `
$$TeX Code$$
`. All the math will be properly typeset and displayed within your Hugo generated web page! + +## Additional Formats Through External Helpers + +Hugo has 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/multilingual.md index e3c65a26,00000000..958634c5 mode 100644,000000..100644 --- a/docs/content/content-management/multilingual.md +++ b/docs/content/content-management/multilingual.md @@@ -1,294 -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" >}} +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 >}} + +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" >}} +[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 >}} + +## 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`. ++In this example, the `about.md` will be assigned the configured `defaultContentLanguage`. + +1. `/content/about.md` +2. `/content/about.fr.md` + +This way, you can slowly start to translate your current content without having to rename everything. If left unspecified, the default value for `defaultContentLanguage` is `en`. + +By having the same *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: + +``` +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" >}} +{{ 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, 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: + +``` + hugo --i18n-warnings | grep i18n +i18n|MISSING_TRANSLATION|en|wordCount +``` + +## Customize Dates + +At the time of this writing, Golang does not yet have support for internationalized locales, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content: + +~~~yaml +1: "janvier" +2: "février" +3: "mars" +4: "avril" +5: "mai" +6: "juin" +7: "juillet" +8: "août" +9: "septembre" +10: "octobre" +11: "novembre" +12: "décembre" +~~~ + +... then index the non-English date names in your templates like so: + +~~~html + +~~~ + +This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file. + +## Menus + +You can define your menus for each language independently. The [creation of a menu][menus] works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file: + +``` +defaultContentLanguage = "en" + +[languages.en] +weight = 0 +languageName = "English" + +[[languages.en.menu.main]] +url = "/" +name = "Home" +weight = 0 + + +[languages.de] +weight = 10 +languageName = "Deutsch" + +[[languages.de.menu.main]] +url = "/" +name = "Startseite" +weight = 0 +``` + +The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version as the default content language that resides in the root directory. + +``` +
    + {{- $currentPage := . -}} + {{ range .Site.Menus.main -}} +
  • + {{ .Name }} +
    • + {{- end }} +
+ +``` + +## Missing translations + +If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. + +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. + +{{% note %}} +Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments. +{{% /note %}} + +## 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/shortcodes.md index 3482d672,00000000..a4424a99 mode 100644,000000..100644 --- a/docs/content/content-management/shortcodes.md +++ b/docs/content/content-management/shortcodes.md @@@ -1,409 -1,0 +1,395 @@@ +--- +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: + +``` +{{%/* 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` +* `link` +* `title` +* `caption` +* `class` +* `attr` (i.e., attribution) +* `attrlink` +* `alt` + +#### Example `figure` Input + +{{< code file="figure-input-example.md" >}} +{{}} +{{< /code >}} + +#### Example `figure` Output + - {{% output file="figure-output-example.html" %}} - ``` ++{{< output file="figure-output-example.html" >}} +
+ +
+

Steve Francia

+
+
- ``` - {{% /output %}} ++{{< /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" %}} - ``` ++{{< output file="gist-output.html" >}} +{{< gist spf13 7896402 >}} - ``` - {{% /output %}} ++{{< /output >}} + +#### Example `gist` Display + +To demonstrate the remarkably efficiency of Hugo's shortcode feature, we have embedded the `spf13` `gist` example in this page. The following simulates the experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. + +{{< gist spf13 7896402 >}} + +### `highlight` + +This shortcode will convert the source code provided into syntax-highlighted HTML. Read more on [highlighting](/tools/syntax-highlighting/). `highlight` takes exactly one required `language` parameter and requires a closing shortcode. + +#### Example `highlight` Input + +{{< code file="content/tutorials/learn-html.md" >}} +{{}} +
+
+

{{ .Title }}

+ {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} +
+
+{{}} +{{< /code >}} + +#### Example `highlight` Output + +The `highlight` shortcode example above would produce the following HTML when the site is rendered: + - {{% output file="tutorials/learn-html/index.html" %}} - ``` ++{{< output file="tutorials/learn-html/index.html" >}} +<section id="main"> + <div> + <h1 id="title">{{ .Title }}</h1> + {{ range .Data.Pages }} + {{ .Render "summary"}} + {{ end }} + </div> +</section> - ``` - {{% /output %}} ++{{< /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" %}} - ``` ++{{< output file="instagram-hide-caption-output.html" >}} +{{< instagram BWNjjyYFxVx hidecaption >}} - ``` - {{% /output %}} ++{{< /output >}} + +#### Example `instagram` Display + +Using the preceding `instagram` with hidecaption` example above, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. + +{{< instagram BWNjjyYFxVx hidecaption >}} + + +### `ref` and `relref` + +These shortcodes will look up the pages by their relative path (e.g., `blog/post.md`) or their logical name (`post.md`) and return the permalink (`ref`) or relative permalink (`relref`) for the found page. + +`ref` and `relref` also make it possible to make fragmentary links that work for the header links generated by Hugo. + +{{% note "More on Cross References" %}} +Read a more extensive description of `ref` and `relref` in the [cross references](/content-management/cross-references/) documentation. +{{% /note %}} + +`ref` and `relref` take exactly one required parameter of _reference_, quoted and in position `0`. + +#### Example `ref` and `relref` Input + +``` +[Neat]({{}}) +[Who]({{}}) +``` + +#### Example `ref` and `relref` Output + +Assuming that standard Hugo pretty URLs are turned on. + +``` +Neat +Who +``` + +### `speakerdeck` + +To embed slides from [Speaker Deck][], click on "< /> Embed" (under Share right next to the template on Speaker Deck) and copy the URL: + +``` + +``` + +#### `speakerdeck` Example Input + +Extract the value from the field `data-id` and pass it to the shortcode: + +{{< code file="speakerdeck-example-input.md" >}} +{{}} +{{< /code >}} + +#### `speakerdeck` Example Output + - {{% output file="speakerdeck-example-input.md" %}} - ``` ++{{< output file="speakerdeck-example-input.md" >}} +{{< speakerdeck 4e8126e72d853c0060001f97 >}} - ``` - {{% /output %}} ++{{< /output >}} + +#### `speakerdeck` Example Display + +For the preceding `speakerdeck` example, the following simulates the displayed experience for visitors to your website. Naturally, the final display will be contingent on your stylesheets and surrounding markup. + +{{< speakerdeck 4e8126e72d853c0060001f97 >}} + +### `tweet` + +You want to include a single tweet into your blog post? Everything you need is the URL of the tweet: + +``` +https://twitter.com/spf13/status/877500564405444608 +``` + +#### Example `tweet` Input + +Pass the tweet's ID from the URL as a parameter to the `tweet` shortcode: + +{{< code file="example-tweet-input.md" >}} +{{}} +{{< /code >}} + +#### Example `tweet` Output + +Using the preceding `tweet` example, the following HTML will be added to your rendered website's markup: + - {{% output file="example-tweet-output.html" %}} - ``` ++{{< output file="example-tweet-output.html" >}} +{{< tweet 877500564405444608 >}} - ``` - {{% /output %}} ++{{< /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" %}} - ``` ++{{< output file="example-vimeo-output.html" >}} +{{< vimeo 146022717 >}} - ``` - {{% /output %}} ++{{< /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 `