From: Bjørn Erik Pedersen Date: Tue, 20 Mar 2018 20:11:45 +0000 (+0100) Subject: Merge commit '0a23baa6a90901f772c234107c4f12c16c76f4aa' X-Git-Tag: v0.38~20 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=84f4b731d23bbcb1821eed46958bf73476f00543;p=brevno-suite%2Fhugo Merge commit '0a23baa6a90901f772c234107c4f12c16c76f4aa' --- 84f4b731d23bbcb1821eed46958bf73476f00543 diff --cc docs/config.toml index 2c274383,00000000..74b10fce mode 100644,000000..100644 --- a/docs/config.toml +++ b/docs/config.toml @@@ -1,274 -1,0 +1,274 @@@ +baseURL = "https://gohugo.io/" +paginate = 100 +defaultContentLanguage = "en" +enableEmoji = true +# Set the unicode character used for the "return" link in page footnotes. +footnotereturnlinkcontents = "↩" +languageCode = "en-us" +metaDataFormat = "yaml" +title = "Hugo" +theme = "gohugoioTheme" + +googleAnalytics = "UA-7131036-4" + +pluralizeListTitles = false + +# We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below). +disableAliases = true + - +# Highlighting config (Pygments) +# It is (currently) not in use, but you can do ```go in a content file if you want to. +pygmentsCodeFences = true + +pygmentsOptions = "" +# Use the Chroma stylesheet - pygmentsUseClasses = true ++# TODO(bep) build new CSS when we have picked a new style. ++pygmentsUseClasses = false +pygmentsUseClassic = false + +# See https://help.farbox.com/pygments.html - pygmentsStyle = "friendly" ++pygmentsStyle = "trac" + +[outputs] +home = [ "HTML", "RSS", "REDIR", "HEADERS" ] +section = [ "HTML", "RSS"] + +[mediaTypes] +[mediaTypes."text/netlify"] +suffix = "" +delimiter = "" + +[outputFormats] +[outputFormats.REDIR] +mediatype = "text/netlify" +baseName = "_redirects" +isPlainText = true +notAlternative = true +[outputFormats.HEADERS] +mediatype = "text/netlify" +baseName = "_headers" +isPlainText = true +notAlternative = true + +[related] + +threshold = 80 +includeNewer = true +toLower = false + +[[related.indices]] +name = "keywords" +weight = 100 +[[related.indices]] +name = "date" +weight = 10 +pattern = "2006" + +[social] +twitter = "GoHugoIO" + +#CUSTOM PARAMS +[params] + description = "The world’s fastest framework for building websites" + ## Used for views in rendered HTML (i.e., rather than using the .Hugo variable) + release = "0.38-DEV" + ## Setting this to true will add a "noindex" to *EVERY* page on the site + removefromexternalsearch = false + ## Gh repo for site footer (include trailing slash) + ghrepo = "https://github.com/gohugoio/hugoDocs/" + ## GH Repo for filing a new issue + github_repo = "https://github.com/gohugoio/hugo/issues/new" + ### Edit content repo (set to automatically enter "edit" mode; this is good for "improve this page" links) + ghdocsrepo = "https://github.com/gohugoio/hugoDocs/tree/master/docs" + ## Gitter URL + gitter = "https://gitter.im/spf13/hugo" + ## Discuss Forum URL + forum = "https://discourse.gohugo.io/" + ## Google Tag Manager + gtmid = "" + + # First one is picked as the Twitter card image if not set on page. + images = ["images/gohugoio-card.png"] + + flex_box_interior_classes = "flex-auto w-100 w-40-l mr3 mb3 bg-white ba b--moon-gray nested-copy-line-height" + + #sidebar_direction = "sidebar_left" + +# MARKDOWN +## Configuration for BlackFriday markdown parser: https://github.com/russross/blackfriday +[blackfriday] + plainIDAnchors = true + # See https://github.com/gohugoio/hugo/issues/2424 + hrefTargetBlank = false + angledQuotes = false + latexDashes = true + +[imaging] +# See https://github.com/disintegration/imaging +# CatmullRom is a sharp bicubic filter which should fit the docs site well with its many screenshots. +# Note that you can also set this per image processing. +resampleFilter = "CatmullRom" + +# Defatult JPEG quality setting. Default is 75. +quality = 75 + +anchor = "smart" + + +## As of v0.20, all content files include a default "categories" value that's the same as the section. This was a cheap future-proofing method and should/could be changed accordingly. +[taxonomies] + category = "categories" + +# High level items + +[[menu.docs]] + name = "About Hugo" + weight = 1 + identifier = "about" + url = "/about/" + +[[menu.docs]] + name = "Getting Started" + weight = 5 + identifier = "getting-started" + url = "/getting-started/" + + +[[menu.docs]] + name = "Themes" + weight = 15 + identifier = "themes" + post = "break" + url = "/themes/" + +# Core Menus + +[[menu.docs]] + name = "Content Management" + weight = 20 + identifier = "content-management" + post = "expanded" + url = "/content-management/" + +[[menu.docs]] + name = "Templates" + weight = 25 + identifier = "templates" + + url = "/templates/" + +[[menu.docs]] + name = "Functions" + weight = 30 + identifier = "functions" + url = "/functions/" + +[[menu.docs]] + name = "Variables" + weight = 35 + identifier = "variables" + url = "/variables/" + +[[menu.docs]] + name = "CLI" + weight = 40 + post = "break" + identifier = "commands" + url = "/commands/" + + + +# LOW LEVEL ITEMS + + +[[menu.docs]] + name = "Troubleshooting" + weight = 60 + identifier = "troubleshooting" + url = "/troubleshooting/" + +[[menu.docs]] + name = "Tools" + weight = 70 + identifier = "tools" + url = "/tools/" + +[[menu.docs]] + name = "Hosting & Deployment" + weight = 80 + identifier = "hosting-and-deployment" + url = "/hosting-and-deployment/" + +[[menu.docs]] + name = "Contribute" + weight = 100 + post = "break" + identifier = "contribute" + url = "/contribute/" + +#[[menu.docs]] +# name = "Tags" +# weight = 120 +# identifier = "tags" +# url = "/tags/" + + +# [[menu.docs]] +# name = "Categories" +# weight = 140 +# identifier = "categories" +# url = "/categories/" + +######## QUICKLINKS + + [[menu.quicklinks]] + name = "Fundamentals" + weight = 1 + identifier = "fundamentals" + url = "/tags/fundamentals/" + + + + +######## GLOBAL ITEMS TO BE SHARED WITH THE HUGO SITES + +[[menu.global]] + name = "News" + weight = 1 + identifier = "news" + url = "/news/" + + [[menu.global]] + name = "Docs" + weight = 5 + identifier = "docs" + url = "/documentation/" + + [[menu.global]] + name = "Themes" + weight = 10 + identifier = "themes" + url = "https://themes.gohugo.io/" + + [[menu.global]] + name = "Showcase" + weight = 20 + identifier = "showcase" + url = "/showcase/" + + # Anything with a weight > 100 gets an external icon + [[menu.global]] + name = "Community" + weight = 150 + icon = true + identifier = "community" + post = "external" + url = "https://discourse.gohugo.io/" + + + [[menu.global]] + name = "GitHub" + weight = 200 + identifier = "github" + post = "external" + url = "https://github.com/gohugoio/hugo" diff --cc docs/content/about/benefits.md index 74c5dde3,00000000..0ba28c5c mode 100644,000000..100644 --- a/docs/content/about/benefits.md +++ b/docs/content/about/benefits.md @@@ -1,43 -1,0 +1,43 @@@ +--- +title: The Benefits of Static Site Generators +linktitle: The Benefits of Static +description: Improved performance, security and ease of use are just a few of the reasons static site generators are so appealing. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +keywords: [ssg,static,performance,security] +menu: + docs: + parent: "about" + weight: 30 +weight: 30 +sections_weight: 30 +draft: false +aliases: [] +toc: false +--- + +The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page. + +Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page. + +Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*. + +This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site. + +## More on Static Site Generators + +* ["An Introduction to Static Site Generators", David Walsh][] +* ["Hugo vs. Wordpress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress] - * ["Static Site Generators", O-Reilly][] ++* ["Static Site Generators", O'Reilly][] +* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)][] +* ["Top 10 Static Website Generators", Netlify blog][] +* ["The Resurgence of Static", dotCMS][dotcms] + + +["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators - ["Static Site Generators", O-Reilly]: /documents/oreilly-static-site-generators.pdf ++["Static Site Generators", O'Reilly]: http://www.oreilly.com/web-platform/free/files/static-site-generators.pdf +["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/ +[hugovwordpress]: https://gettingthingstech.com/hugo-vs.-wordpress-page-load-speed-comparison-hugo-leaves-wordpress-in-its-dust/ +[StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]: https://www.staticgen.com/ +[dotcms]: https://dotcms.com/blog/post/the-resurgence-of-static diff --cc docs/content/content-management/multilingual.md index 213cd99f,00000000..d27195a9 mode 100644,000000..100644 --- a/docs/content/content-management/multilingual.md +++ b/docs/content/content-management/multilingual.md @@@ -1,386 -1,0 +1,386 @@@ +--- +title: Multilingual Mode +linktitle: Multilingual and i18n +description: Hugo supports the creation of websites with multiple languages side by side. +date: 2017-01-10 +publishdate: 2017-01-10 +lastmod: 2017-01-10 +categories: [content management] +keywords: [multilingual,i18n, internationalization] +menu: + docs: + parent: "content-management" + weight: 150 +weight: 150 #rem +draft: false +aliases: [/content/multilingual/,/content-management/multilingual/,/tutorials/create-a-multilingual-site/] +toc: true +--- + +You should define the available languages in a `languages` section in your site configuration. + +## Configure Languages + +The following is an example of a 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" - - # skip params key for front matter - [languages.fr.navigation] ++[languages.fr.params.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. + +## Disable a Language + +You can disable one or more languages. This can be useful when working on a new translation. + +```toml +disableLanguages = ["fr", "jp"] +``` + +Note that you cannot disable the default content language. + +We kept this as a standalone setting to make it easier to set via [OS environment](/getting-started/configuration/#configure-with-environment-variables): + +```bash +HUGO_DISABLELANGUAGES="fr jp" hugo +``` +If you have already a list of disabled languages in `config.toml`, you can enable them in development like this: + +```bash +HUGO_DISABLELANGUAGES=" " hugo server +``` + + +## Configure Multilingual Multihost + +From **Hugo 0.31** we support multiple languages in a multihost configuration. See [this issue](https://github.com/gohugoio/hugo/issues/4027) for details. + +This means that you can now configure a `baseURL` per `language`: + + +> If a `baseURL` is set on the `language` level, then all languages must have one and they must all be different. + +Example: + +```bash +[languages] +[languages.no] +baseURL = "https://example.no" +languageName = "Norsk" +weight = 1 +title = "PÃ¥ norsk" + +[languages.en] +baseURL = "https://example.com" +languageName = "English" +weight = 2 +title = "In English" +``` + +With the above, the two sites will be generated into `public` with their own root: + +```bash +public +├── en +└── no +``` + +**All URLs (i.e `.Permalink` etc.) will be generated from that root. So the English home page above will have its `.Permalink` set to `https://example.com/`.** + +When you run `hugo server` we will start multiple HTTP servers. You will typlically see something like this in the console: + +```bash +Web Server is available at 127.0.0.1:1313 (bind address 127.0.0.1) +Web Server is available at 127.0.0.1:1314 (bind address 127.0.0.1) +Press Ctrl+C to stop +``` + +Live reload and `--navigateToChanged` between the servers work as expected. + +## Taxonomies and Blackfriday + +Taxonomies and [Blackfriday configuration][config] can also be set per language: + + +{{< code 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 example, the `about.md` will be assigned the configured `defaultContentLanguage`. + +1. `/content/about.md` +2. `/content/about.fr.md` + +This way, you can slowly start to translate your current content without having to rename everything. If left unspecified, the default value for `defaultContentLanguage` is `en`. + +By having the same **directory and base filename**, the content pieces are linked together as translated pieces. + +You can also set the key used to link the translations explicitly in front matter: + +```yaml +translationKey: "my-story" +``` + +If you need distinct URLs per language, you can set the slug in the non-default language file. For example, you can define a custom slug for a French translation in the front matter of `content/about.fr.md` as follows: + +```yaml +slug: "a-propos" + +``` + +At render, Hugo will build both `/about/` and `/a-propos/` as properly linked translated pages. + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). + +## Link to Translated Content + +To create a list of links to translated content, use a template similar to the following: + +{{< code file="layouts/partials/i18nlist.html" >}} +{{ if .IsTranslated }} +

{{ i18n "translations" }}

+ +{{ end }} +{{< /code >}} + +The above can be put in a `partial` (i.e., inside `layouts/partials/`) and included in any template, be it for a [single content page][contenttemplate] or the [homepage][]. It will not print anything if there are no translations for a given page. + +The above also uses the [`i18n` function][i18func] described in the next section. + +## List All Available Languages + +`.AllTranslations` on a `Page` can be used to list all translations, including itself. Called on the home page it can be used to build a language navigator: + + +{{< code file="layouts/partials/allLanguages.html" >}} + +{{< /code >}} + +## Translation of Strings + +Hugo uses [go-i18n][] to support string translations. [See the project's source repository][go-i18n-source] to find tools that will help you manage your translation workflows. + +Translations are collected from the `themes//i18n/` folder (built into the theme), as well as translations present in `i18n/` at the root of your project. In the `i18n`, the translations will be merged and take precedence over what is in the theme folder. Language files should be named according to [RFC 5646][] with names such as `en-US.toml`, `fr.toml`, etc. + +{{% note %}} +From **Hugo 0.31** you no longer need to use a valid language code. It _can be_ anything. + +See https://github.com/gohugoio/hugo/issues/3564 + +{{% /note %}} + +From within your templates, use the `i18n` function like this: + +``` +{{ i18n "home" }} +``` + +This uses a definition like this one in `i18n/en-US.toml`: + +``` +[home] +other = "Home" +``` + +Often you will want to use to the page variables in the translations strings. To do that, pass on the "." context when calling `i18n`: + +``` +{{ i18n "wordCount" . }} +``` + +This uses a definition like this one in `i18n/en-US.toml`: + +``` +[wordCount] +other = "This article has {{ .WordCount }} words." +``` +An example of singular and plural form: + +``` +[readingTime] +one = "One minute read" +other = "{{.Count}} minutes read" +``` +And then in the template: + +``` +{{ i18n "readingTime" .ReadingTime }} +``` +To track down missing translation strings, run Hugo with the `--i18n-warnings` flag: + +``` + hugo --i18n-warnings | grep i18n +i18n|MISSING_TRANSLATION|en|wordCount +``` + +## Customize Dates + +At the time of this writing, Golang does not yet have support for internationalized locales, but if you do some work, you can simulate it. For example, if you want to use French month names, you can add a data file like ``data/mois.yaml`` with this content: + +~~~yaml +1: "janvier" +2: "février" +3: "mars" +4: "avril" +5: "mai" +6: "juin" +7: "juillet" +8: "août" +9: "septembre" +10: "octobre" +11: "novembre" +12: "décembre" +~~~ + +... then index the non-English date names in your templates like so: + +~~~html + +~~~ + +This technique extracts the day, month and year by specifying ``.Date.Day``, ``.Date.Month``, and ``.Date.Year``, and uses the month number as a key, when indexing the month name data file. + +## Menus + +You can define your menus for each language independently. The [creation of a menu][menus] works analogous to earlier versions of Hugo, except that they have to be defined in their language-specific block in the configuration file: + +``` +defaultContentLanguage = "en" + +[languages.en] +weight = 0 +languageName = "English" + +[[languages.en.menu.main]] +url = "/" +name = "Home" +weight = 0 + + +[languages.de] +weight = 10 +languageName = "Deutsch" + +[[languages.de.menu.main]] +url = "/" +name = "Startseite" +weight = 0 +``` + +The rendering of the main navigation works as usual. `.Site.Menus` will just contain the menu of the current language. Pay attention to the generation of the menu links. `absLangURL` takes care that you link to the correct locale of your website. Otherwise, both menu entries would link to the English version as the default content language that resides in the root directory. + +``` + + +``` + +## Missing Translations + +If a string does not have a translation for the current language, Hugo will use the value from the default language. If no default value is set, an empty string will be shown. + +While translating a Hugo website, it can be handy to have a visual indicator of missing translations. The [`enableMissingTranslationPlaceholders` configuration option][config] will flag all untranslated strings with the placeholder `[i18n] identifier`, where `identifier` is the id of the missing translation. + +{{% note %}} +Hugo will generate your website with these missing translation placeholders. It might not be suited for production environments. +{{% /note %}} + +For merging of content from other languages (i.e. missing content translations), see [lang.Merge](/functions/lang.merge/). + +## Multilingual Themes support + +To support Multilingual mode in your themes, some considerations must be taken for the URLs in the templates. If there is more than one language, URLs must meet the following criteria: + +* Come from the built-in `.Permalink` or `.URL` +* Be constructed with + * The [`relLangURL` template function][rellangurl] or the [`absLangURL` template function][abslangurl] **OR** + * Prefixed with `{{ .LanguagePrefix }}` + +If there is more than one language defined, the `LanguagePrefix` variable will equal `/en` (or whatever your `CurrentLanguage` is). If not enabled, it will be an empty string and is therefore harmless for single-language Hugo websites. + +[abslangurl]: /functions/abslangurl +[config]: /getting-started/configuration/ +[contenttemplate]: /templates/single-page-templates/ +[go-i18n-source]: https://github.com/nicksnyder/go-i18n +[go-i18n]: https://github.com/nicksnyder/go-i18n +[homepage]: /templates/homepage/ +[i18func]: /functions/i18n/ +[menus]: /content-management/menus/ +[rellangurl]: /functions/rellangurl +[RFC 5646]: https://tools.ietf.org/html/rfc5646 +[singles]: /templates/single-page-templates/ diff --cc docs/content/contribute/themes.md index e6070c38,00000000..256f4609 mode 100644,000000..100644 --- a/docs/content/contribute/themes.md +++ b/docs/content/contribute/themes.md @@@ -1,150 -1,0 +1,150 @@@ +--- +title: Add Your Hugo Theme to the Showcase +linktitle: Themes +description: If you've built a Hugo theme and want to contribute back to the Hugo Community, add your theme to the Hugo Showcase. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-27 +categories: [contribute] +keywords: [contribute,themes,design] +authors: [digitalcraftsman] +menu: + docs: + parent: "contribute" + weight: 30 +weight: 30 +sections_weight: 30 +draft: false +aliases: [/contribute/theme/] +wip: true +toc: true +--- + +A collection of all themes created by the Hugo community, including screenshots and demos, can be found at . Every theme in this list will automatically be added to the theme site. Theme updates aren't scheduled but usually happen at least once a week. + +## tl;dr + +1. Create your theme using `hugo new theme `; - 2. Test your theme against \* ++2. Test your theme against \* +3. Add a `theme.toml` file to the root of the theme with all required metadata +4. Add a descriptive `README.md` to the root of the theme source +5. Add `/images/screenshot.png` and `/images/tn.png` + +\* If your theme doesn't fit into the `Hugo Basic Example` site, we encourage theme authors to supply a self-contained Hugo site in `/exampleSite`. + +{{% note %}} +The folder name here---`exampleSite`---is important, as this folder will be picked up and used by the script that generates the Hugo Theme Site. It mirrors the root directory of a Hugo website and allows you to add custom content, assets, and a `config` file with preset values. +{{% /note %}} + +See the [Hugo Artist theme's exampleSite][artistexample] for a good example. + +{{% note %}} +Please make your example site's content is as neutral as possible. We hope this goes without saying. +{{% /note %}} + +## Theme Requirements + +In order to add your theme to the Hugo Themes Showcase, the following requirements need to be met: + +1. `theme.toml` with all required fields +2. Images for thumbnail and screenshot +3. A good README file instructions for users +4. Addition to the hugoThemes GitHub repository + +### Add Your Theme to the Repo + +The easiest way to add your theme is to [open up a new issue in the theme repository][themeissuenew] with a link to the theme's repository on GitHub. + +### Create a `theme.toml` File + +`theme.toml` contains metadata about the theme and its creator and should be created automatically when running the `hugo new theme`. The auto-generated file is provided here as well for easy downloading: + +{{< code file="theme.toml" download="theme.toml" >}} +name = "" +license = "MIT" +licenselink = "https://github.com///blob/master/LICENSE.md" +description = "" +homepage = "https://example.com/" +tags = [] +features = [] +min_version = 0.19 + +[author] + name = "" + homepage = "" + +# If porting an existing theme +[original] + name = "" + homepage = "" + repo = "" +{{< /code >}} + +The following fields are required: + +``` +name = "Hyde" +license = "MIT" +licenselink = "https://github.com/spf13/hyde/blob/master/LICENSE.md" +description = "An elegant open source and mobile first theme" +homepage = "http://siteforthistheme.com/" +tags = ["blog", "company"] +features = ["blog"] +min_version = 0.13 + +[author] + name = "spf13" + homepage = "http://spf13.com/" + +# If porting an existing theme +[original] + author = "mdo" + homepage = "http://hyde.getpoole.com/" + repo = "https://www.github.com/mdo/hyde" +``` + +{{% note %}} +1. This is different from the `theme.toml` file created by `hugo new theme` in Hugo versions before v0.14. +2. Only `theme.toml` is accepted; ie. not `theme.yaml` and `theme.json`. +{{% /note %}} + +### Images + +Screenshots are used for previews in the Hugo Theme Gallery. Make sure that they have the right dimensions: + +* Thumbnail should be 900px × 600px +* Screenshot should be 1500px × 1000px +* Media must be located in + * /images/screenshot.png + * /images/tn.png + +Additional media may be provided in the same directory. + +### Create a README File + +Your theme's README file should be written in markdown and saved at the root of your theme's directory structure. Your `README.md` serves as + +1. Content for your theme's details page at +2. General information about the theme in your GitHub repository (i.e., it's usual purpose) + +#### Example `README.md` + +You can download the following `README.md` as an outline: + +{{< code file="README.md" download="README.md" >}} + +# Theme Title + +**Need input from @digitalcraftsman on what could be added to this file.** + + + + +{{< /code >}} + +{{% note "Screenshots in your `README.md`"%}} +If you add screenshots to the README, please make use of absolute file paths instead of relative ones like `/images/screenshot.png`. Relative paths work great on GitHub but they don't correspond to the directory structure of [themes.gohugo.io](http://themes.gohugo.io/). Therefore, browsers will not be able to display screenshots on the theme site under the given (relative) path. +{{% /note %}} + +[artistexample]: https://github.com/digitalcraftsman/hugo-artists-theme/tree/master/exampleSite +[themeissuenew]: https://github.com/gohugoio/hugoThemes/issues/new diff --cc docs/content/functions/countwords.md index cf699b1b,00000000..44f9360c mode 100644,000000..100644 --- a/docs/content/functions/countwords.md +++ b/docs/content/functions/countwords.md @@@ -1,29 -1,0 +1,29 @@@ +--- +title: countwords +description: Counts the number of words in a string. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [counting, word count] +signature: ["countwords INPUT"] +workson: [] +hugoversion: +relatedfuncs: [countrunes] +deprecated: false - aliases: [/functions/countrunes/,/functions/countwords/] ++aliases: [/functions/countwords/] +--- + +The template function works similar to the [.WordCount page variable][pagevars]. + +``` +{{ "Hugo is a static site generator." | countwords }} + +``` + + +[pagevars]: /variables/page/ diff --cc docs/content/hosting-and-deployment/hosting-on-github.md index fc874f89,00000000..37b82ab2 mode 100644,000000..100644 --- a/docs/content/hosting-and-deployment/hosting-on-github.md +++ b/docs/content/hosting-and-deployment/hosting-on-github.md @@@ -1,252 -1,0 +1,252 @@@ +--- +title: Host on GitHub +linktitle: Host on GitHub +description: Deploy Hugo as a GitHub Pages project or personal/organizational site and automate the whole process with a simple shell script. +date: 2014-03-21 +publishdate: 2014-03-21 +lastmod: 2017-03-30 +categories: [hosting and deployment] +keywords: [github,git,deployment,hosting] +authors: [Spencer Lyon, Gunnar Morling] +menu: + docs: + parent: "hosting-and-deployment" + weight: 30 +weight: 30 +sections_weight: 30 +draft: false +toc: true +aliases: [/tutorials/github-pages-blog/] +--- + +GitHub provides free and fast static hosting over SSL for personal, organization, or project pages directly from a GitHub repository via its [GitHub Pages service][]. + +## Assumptions + - 1. You have Git 2.5 or greater [installed on your machine][installgit]. ++1. You have Git 2.8 or greater [installed on your machine][installgit]. +2. You have a GitHub account. [Signing up][ghsignup] for GitHub is free. +3. You have a ready-to-publish Hugo website or have at least completed the [Quick Start][]. + +## Types of GitHub Pages + +There are 2 types of GitHub Pages: + +- User/Organization Pages (`https://.github.io/`) +- Project Pages (`https://.github.io//`) + +Please refer to the [GitHub Pages documentation][ghorgs] to decide which type of site you would like to create as it will determine which of the below methods to use. + +To create a User/Organization Pages site, follow the single method in the *GitHub User and Organization Pages* section below. + +To create a Project Pages site, choose a method from the *Project Pages* section below. + +## GitHub User or Organization Pages + +As mentioned [the GitHub Pages documentation][ghorgs], you can host a user/organization page in addition to project pages. Here are the key differences in GitHub Pages websites for Users and Organizations: + +1. You must use a `.github.io` to host your **generated** content +2. Content from the `master` branch will be used to publish your GitHub Pages site + +This is a much simpler setup as your Hugo files and generated content are published into two different repositories. + +### Step-by-step Instructions + +1. Create a `` (e.g. `blog`) repository on GitHub. This repository will contain Hugo's content and other source files. +2. Create a `.github.io` GitHub repository. This is the repository that will contain the fully rendered version of your Hugo website. +3. `git clone && cd ` +4. Make your website work locally (`hugo server` or `hugo server -t `) and open your browser to . +5. Once you are happy with the results: + * Press Ctrl+C to kill the server + * `rm -rf public` to completely remove the `public` directory +6. `git submodule add -b master git@github.com:/.github.io.git public`. This creates a git [submodule][]. Now when you run the `hugo` command to build your site to `public`, the created `public` directory will have a different remote origin (i.e. hosted GitHub repository). You can automate some of these steps with the following script. + +### Put it Into a Script + +You're almost done. You can also add a `deploy.sh` script to automate the preceding steps for you. You can also make it executable with `chmod +x deploy.sh`. + +The following are the contents of the `deploy.sh` script: + +``` +#!/bin/bash + +echo -e "\033[0;32mDeploying updates to GitHub...\033[0m" + +# Build the project. +hugo # if using a theme, replace with `hugo -t ` + +# Go To Public folder +cd public +# Add changes to git. +git add . + +# Commit changes. +msg="rebuilding site `date`" +if [ $# -eq 1 ] + then msg="$1" +fi +git commit -m "$msg" + +# Push source and build repos. +git push origin master + +# Come Back up to the Project Root +cd .. +``` + + +You can then run `./deploy.sh "Your optional commit message"` to send changes to `.github.io`. Note that you likely will want to commit changes to your `` repository as well. + +That's it! Your personal page should be up and running at `https://.github.io` within a couple minutes. + +## GitHub Project Pages + +{{% note %}} +Make sure your `baseURL` key-value in your [site configuration](/getting-started/configuration/) reflects the full URL of your GitHub pages repository if you're using the default GH Pages URL (e.g., `.github.io//`) and not a custom domain. +{{% /note %}} + +### Deployment of Project Pages from `/docs` folder on `master` branch + +[As described in the GitHub Pages documentation][ghpfromdocs], you can deploy from a folder called `docs/` on your master branch. To effectively use this feature with Hugo, you need to change the Hugo publish directory in your [site's][config] `config.toml` and `config.yaml`, respectively: + +``` +publishDir = "docs" +``` +``` +publishDir: docs +``` + +After running `hugo`, push your master branch to the remote repository and choose the `docs/` folder as the website source of your repo. Do the following from within your GitHub project: + +1. Go to **Settings** → **GitHub Pages** +2. From **Source**, select "master branch /docs folder". If the option isn't enabled, you likely do not have a `docs/` folder in the root of your project. + +{{% note %}} +The `docs/` option is the simplest approach but requires you set a publish directory in your site configuration. You cannot currently configure GitHub pages to publish from another directory on master, and not everyone prefers the output site live concomitantly with source files in version control. +{{% /note %}} + +### Deployment of Project Pages From Your `gh-pages` branch + +You can also tell GitHub pages to treat your `master` branch as the published site or point to a separate `gh-pages` branch. The latter approach is a bit more complex but has some advantages: + +* It keeps your source and generated website in different branches and therefore maintains version control history for both. +* Unlike the preceding `docs/` option, it uses the default `public` folder. + +#### Preparations for `gh-pages` Branch + +These steps only need to be done once. Replace `upstream` with the name of your remote; e.g., `origin`: + +##### Add the `public` Folder + +First, add the `public` folder to your `.gitignore` file at the project root so that the directory is ignored on the master branch: + +``` +echo "public" >> .gitignore +``` + +##### Initialize Your `gh-pages` Branch + +You can now initialize your `gh-pages` branch as an empty [orphan branch][]: + +``` +git checkout --orphan gh-pages +git reset --hard +git commit --allow-empty -m "Initializing gh-pages branch" +git push upstream gh-pages +git checkout master +``` + +#### Build and Deployment + +Now check out the `gh-pages` branch into your `public` folder using git's [worktree feature][]. Essentially, the worktree allows you to have multiple branches of the same local repository to be checked out in different directories: + +``` +rm -rf public +git worktree add -B gh-pages public upstream/gh-pages +``` + +Regenerate the site using the `hugo` command and commit the generated files on the `gh-pages` branch: + +{{< code file="commit-gh-pages-files.sh">}} +hugo +cd public && git add --all && git commit -m "Publishing to gh-pages" && cd .. +{{< /code >}} + +If the changes in your local `gh-pages` branch look alright, push them to the remote repo: + +``` +git push upstream gh-pages +``` + +##### Set `gh-pages` as Your Publish Branch + +In order to use your `gh-pages` branch as your publishing branch, you'll need to configure the repository within the GitHub UI. This will likely happen automatically once GitHub realizes you've created this branch. You can also set the branch manually from within your GitHub project: + +1. Go to **Settings** → **GitHub Pages** +2. From **Source**, select "gh-pages branch" and then **Save**. If the option isn't enabled, you likely have not created the branch yet OR you have not pushed the branch from your local machine to the hosted repository on GitHub. + +After a short while, you'll see the updated contents on your GitHub Pages site. + +#### Put it Into a Script + +To automate these steps, you can create a script with the following contents: + +{{< code file="publish_to_ghpages.sh" >}} +#!/bin/sh + +DIR=$(dirname "$0") + +cd $DIR/.. + +if [[ $(git status -s) ]] +then + echo "The working directory is dirty. Please commit any pending changes." + exit 1; +fi + +echo "Deleting old publication" +rm -rf public +mkdir public +git worktree prune +rm -rf .git/worktrees/public/ + +echo "Checking out gh-pages branch into public" +git worktree add -B gh-pages public upstream/gh-pages + +echo "Removing existing files" +rm -rf public/* + +echo "Generating site" +hugo + +echo "Updating gh-pages branch" +cd public && git add --all && git commit -m "Publishing to gh-pages (publish.sh)" +{{< /code >}} + +This will abort if there are pending changes in the working directory and also makes sure that all previously existing output files are removed. Adjust the script to taste, e.g. to include the final push to the remote repository if you don't need to take a look at the gh-pages branch before pushing. Or adding `echo yourdomainname.com >> CNAME` if you set up for your gh-pages to use customize domain. + +### Deployment of Project Pages from Your `master` Branch + +To use `master` as your publishing branch, you'll need your rendered website to live at the root of the GitHub repository. Steps should be similar to that of the `gh-pages` branch, with the exception that you will create your GitHub repository with the `public` directory as the root. Note that this does not provide the same benefits of the `gh-pages` branch in keeping your source and output in separate, but version controlled, branches within the same repo. + +You will also need to set `master` as your publishable branch from within the GitHub UI: + +1. Go to **Settings** → **GitHub Pages** +2. From **Source**, select "master branch" and then **Save**. + +## Use a Custom Domain + +If you'd like to use a custom domain for your GitHub Pages site, create a file `static/CNAME`. Your custom domain name should be the only contents inside `CNAME`. Since it's inside `static`, the published site will contain the CNAME file at the root of the published site, which is a requirements of GitHub Pages. + +Refer to the [official documentation for custom domains][domains] for further information. + +[config]: /getting-started/configuration/ +[domains]: https://help.github.com/articles/using-a-custom-domain-with-github-pages/ +[ghorgs]: https://help.github.com/articles/user-organization-and-project-pages/#user--organization-pages +[ghpfromdocs]: https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/#publishing-your-github-pages-site-from-a-docs-folder-on-your-master-branch +[ghsignup]: https://github.com/join +[GitHub Pages service]: https://help.github.com/articles/what-is-github-pages/ +[installgit]: https://git-scm.com/downloads +[orphan branch]: https://git-scm.com/docs/git-checkout/#git-checkout---orphanltnewbranchgt +[Quick Start]: /getting-started/quick-start/ +[submodule]: https://github.com/blog/2104-working-with-submodules +[worktree feature]: https://git-scm.com/docs/git-worktree diff --cc docs/content/showcase/forestry/index.md index ee1ebe07,00000000..1a9c0faa mode 100644,000000..100644 --- a/docs/content/showcase/forestry/index.md +++ b/docs/content/showcase/forestry/index.md @@@ -1,48 -1,0 +1,48 @@@ +--- +title: Forestry.io +date: 2018-03-16 - description: "A Git-backed CMS (content management system) for websites and web products built using static site generators." ++description: "Showcase: \"Seeing Hugo in action is a whole different world of awesome.\"" +siteURL: https://forestry.io/ +siteSource: https://github.com/forestryio/forestry.io +--- + +It was clear from the get-go that we had to go with a static site generator. Static sites are secure, performant, and give you 100% flexibility. At [Forestry.io](https://forestry.io/) we provide Content Management Solutions for websites built with static site generators, so we might be a little biased. The only question: Which static site generator was the right choice for us? + +### Why Hugo? + +In our early research we looked at Ionic’s [site](https://github.com/ionic-team/ionic) to get some inspiration. They used Jekyll to build their website. While Jekyll is a great generator, the build times for larger sites can be painfully slow. With more than 150 pages plus many custom configurations and add-ons, our website doesn’t fall into the low-volume category anymore. Our developers want a smooth experience when working on the website and our content editors need the ability to preview content quickly. In short, we need our builds to be lightning fast. + +We knew Hugo was fast but we did [some additional benchmarking](https://forestry.io/blog/hugo-vs-jekyll-benchmark/) before making our decision. Seeing Hugo in action is a whole different world of awesome. Hugo takes less than one second to build our 150-page site! Take a look: + +```bash + | EN ++------------------+-----+ + Pages | 141 + Paginator pages | 4 + Non-page files | 0 + Static files | 537 + Processed images | 0 + Aliases | 60 + Sitemaps | 1 + Cleaned | 0 + +Total in 739 ms +``` + +In fact, we liked Hugo so much that our wizard Chris made his workflow public and we started the open-source project [Create-Static-Site](https://github.com/forestryio/create-static-site). It's [a simple way to spin up sites](https://forestry.io/blog/up-and-running-with-hugo/) and set up a modern web development workflow with one line of code. Essentially it adds build configurations as a dependency for JS, CSS and Image Processing. + +Lastly, we want to take the opportunity to give some love to other amazing tools we used building our website. + +### What tools did we use? + +* Our Norwegian designer Nichlas is in love with [**Sketch**](https://www.sketchapp.com/). From what we hear it’s a designer’s dream come true. +* Some say our main graphic is [mesmerizing](https://twitter.com/hmncllctv/status/968907474664284160). Nichlas created it using [**3DS Max**](https://www.autodesk.com/products/3ds-max/overview). +* [**Hugo**](https://gohugo.io/) -- of course. +* Chris can’t think of modern web development without [**Gulp**](https://gulpjs.com/) & [**Webpack**](https://webpack.js.org/). We used them to add additional build steps such as Browsersync, CSS, JS and SVG optimization. +* Speaking about adding steps to our build, our lives would be much harder without [**CircleCI**](https://circleci.com/) for continuous deployment and automated testing purposes. - * We can’t stop raving about [**Algolia**](https://www.algolia.com/). Chris loves it and even wrote a tutorial on [how to implement Algolia]([https://forestry.io/blog/search-with-algolia-in-hugo/) into static sites using Hugo’s [Custom Outputs](https://gohugo.io/templates/output-formats/). ++* We can’t stop raving about [**Algolia**](https://www.algolia.com/). Chris loves it and even wrote a tutorial on [how to implement Algolia](https://forestry.io/blog/search-with-algolia-in-hugo/) into static sites using Hugo’s [Custom Outputs](https://gohugo.io/templates/output-formats/). +* [**Cloudinary**](https://cloudinary.com/) is probably one of the easiest ways to get responsive images into your website. +* We might be a little biased on this one - We think [**Forestry.io**](https://forestry.io/) is a great way to add a content management system with a clean UI on top of your site without interrupting your experience as a developer. +* For hosting purposes we use the almighty [**AWS**](https://aws.amazon.com/). +* [**Formspree.io**](https://formspree.io/) is managing our support and enterprise requests. +* We also use browser cookies and JS to customize our user’s experience and give it a more dynamic feel. diff --cc docs/content/templates/404.md index 8f6caa3a,00000000..eaa479d2 mode 100644,000000..100644 --- a/docs/content/templates/404.md +++ b/docs/content/templates/404.md @@@ -1,55 -1,0 +1,61 @@@ +--- +title: Custom 404 Page +linktitle: 404 Page +description: If you know how to create a single page template, you have unlimited options for creating a custom 404. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-31 +categories: [templates] +keywords: [404, page not found] +menu: + docs: + parent: "templates" + weight: 120 +weight: 120 #rem +draft: false +aliases: [/templates/404/] +toc: false +--- + +When using Hugo with [GitHub Pages](http://pages.github.com/), you can provide your own template for a [custom 404 error page](https://help.github.com/articles/custom-404-pages/) by creating a 404.html template file in your `/layouts` folder. When Hugo generates your site, the `404.html` file will be placed in the root. + +404 pages will have all the regular [page variables][pagevars] available to use in the templates. + +In addition to the standard page variables, the 404 page has access to all site content accessible from `.Data.Pages`. + +``` +▾ layouts/ + 404.html +``` + +## 404.html + +This is a basic example of a 404.html template: + +{{< code file="layouts/404.html" download="404.html" >}} +{{ define "main"}} +
+
+

Go Home

+
+
+{{ end }} +{{< /code >}} + +## Automatic Loading + +Your 404.html file can be set to load automatically when a visitor enters a mistaken URL path, dependent upon the web serving environment you are using. For example: + +* [GitHub Pages](/hosting-and-deployment/hosting-on-github/). The 404 page is automatic. +* Apache. You can specify `ErrorDocument 404 /404.html` in an `.htaccess` file in the root of your site. +* Nginx. You might specify `error_page 404 /404.html;` in your `nginx.conf` file. +* Amazon AWS S3. When setting a bucket up for static web serving, you can specify the error file from within the S3 GUI. +* Caddy Server. Using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors) + - [pagevars]: /variables/page/ ++{{% note %}} ++`hugo server` will not automatically load your custom `404.html` file, but you ++can test the appearance of your custom "not found" page by navigating your ++browser to `/404.html`. ++{{% /note %}} ++ ++[pagevars]: /variables/page/ diff --cc docs/content/templates/lookup-order.md index fd03d597,00000000..d197b614 mode 100644,000000..100644 --- a/docs/content/templates/lookup-order.md +++ b/docs/content/templates/lookup-order.md @@@ -1,92 -1,0 +1,92 @@@ +--- +title: Hugo's Lookup Order +linktitle: Template Lookup Order +description: Hugo searches for the layout to use for a given page in a well defined order, starting from the most specific. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-05-25 +categories: [templates,fundamentals] +keywords: [templates] +menu: + docs: + parent: "templates" + weight: 15 + quicklinks: +weight: 15 +sections_weight: 15 +draft: false +aliases: [/templates/lookup/] +toc: true +--- + +## Hugo Layouts Lookup Rules + +Hugo takes the parameters listed below into consideration when choosing a layout for a given page. They are listed in a priority order. This should feel natural, but look at the table below for concrete examples of the different parameter variations. + + +Kind +: The page `Kind` (the home page is one). See the example tables below per kind. This also determines if it is a **single page** (i.e. a regular content page. We then look for a template in `_default/single.html` for HTML) or a **list page** (section listings, home page, taxonomy lists, taxonomy terms. We then look for a template in `_default/list.html` for HTML). + +Output Format +: See [Custom Output Formats](/templates/output-formats). An output format has both a `name` (e.g. `rss`, `amp`, `html`) and a `suffix` (e.g. `xml`, `html`). We prefer matches with both (e.g. `index.amp.html`, but look for less specific templates. + +Language +: We will consider a language code in the template name. If the site language is `fr`, `index.fr.amp.html` will win over `index.amp.html`, but we will `index.amp.html` will be chosen before `index.fr.html`. + +Layout +: Can be set in page front matter. + +Type - : Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). If will always have a value, so if not set, the value is "page". ++: Is value of `type` if set in front matter, else it is the name of the root section (e.g. "blog"). It will always have a value, so if not set, the value is "page". + +Section +: Is relevant for `section`, `taxonomy` and `taxonomyTerm` types. + +{{% note %}} +**Tip:** The examples below looks long and complex. That is the flexibility talking. Most Hugo sites contain just a handful of templates: + +```bash +├── _default +│   ├── baseof.html +│   ├── list.html +│   └── single.html +└── index.html +``` +{{% /note %}} + + +## Hugo Layouts Lookup Rules With Theme + +In Hugo, layouts can live in either the project's or theme's layout folder, and the most specific layout will be chosen. Hugo will interleave the lookups: + + +1. layouts/page/index.html +2. demoTheme/layouts/page/index.html +3. layouts/... + +This way it is possible to override specific templates from the theme. + +## Examples: Layout Lookup for Regular Pages + +{{< datatable-filtered "output" "layouts" "Kind == page" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Home Page + +{{< datatable-filtered "output" "layouts" "Kind == home" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Section Pages + +{{< datatable-filtered "output" "layouts" "Kind == section" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Taxonomy List Pages + +{{< datatable-filtered "output" "layouts" "Kind == taxonomy" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + +## Examples: Layout Lookup for Taxonomy Terms Pages + +{{< datatable-filtered "output" "layouts" "Kind == taxonomyTerm" "Example" "OutputFormat" "Suffix" "Template Lookup Order" >}} + + + + diff --cc docs/content/templates/shortcode-templates.md index 08f1b4c8,00000000..67e54089 mode 100644,000000..100644 --- a/docs/content/templates/shortcode-templates.md +++ b/docs/content/templates/shortcode-templates.md @@@ -1,354 -1,0 +1,354 @@@ +--- +title: Create Your Own Shortcodes +linktitle: Shortcode Templates +description: You can extend Hugo's built-in shortcodes by creating your own using the same templating syntax as that for single and list pages. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [shortcodes,templates] +menu: + docs: + parent: "templates" + weight: 100 +weight: 100 +sections_weight: 100 +draft: false +aliases: [] +toc: true +--- + +Shortcodes are a means to consolidate templating into small, reusable snippets that you can embed directly inside of your content. In this sense, you can think of shortcodes as the intermediary between [page and list templates][templates] and [basic content files][]. + +{{% note %}} +Hugo also ships with built-in shortcodes for common use cases. (See [Content Management: Shortcodes](/content-management/shortcodes/).) +{{% /note %}} + +## Create Custom Shortcodes + +Hugo's built-in shortcodes cover many common, but not all, use cases. Luckily, Hugo provides the ability to easily create custom shortcodes to meet your website's needs. + +{{< youtube Eu4zSaKOY4A >}} + +### File Placement + +To create a shortcode, place an HTML template in the `layouts/shortcodes` directory of your [source organization][]. Consider the file name carefully since the shortcode name will mirror that of the file but without the `.html` extension. For example, `layouts/shortcodes/myshortcode.html` will be called with either `{{}}` or `{{%/* myshortcode /*/%}}` depending on the type of parameters you choose. + +### Shortcode Template Lookup Order + +Shortcode templates have a simple [lookup order][]: + +1. `/layouts/shortcodes/.html` +2. `/themes//layouts/shortcodes/.html` + +### Positional vs Named Parameters + +You can create shortcodes using the following types of parameters: + +* Positional parameters +* Named parameters +* Positional *or* named parameters (i.e, "flexible") + +In shortcodes with positional parameters, the order of the parameters is important. If a shortcode has a single required value (e.g., the `youtube` shortcode below), positional parameters work very well and require less typing from content authors. + +For more complex layouts with multiple or optional parameters, named parameters work best. While less terse, named parameters require less memorization from a content author and can be added in a shortcode declaration in any order. + +Allowing both types of parameters (i.e., a "flexible" shortcode) is useful for complex layouts where you want to set default values that can be easily overridden by users. + +### Access Parameters + +All shortcode parameters can be accessed via the `.Get` method. Whether you pass a key (i.e., string) or a number to the `.Get` method depends on whether you are accessing a named or positional parameter, respectively. + +To access a parameter by name, use the `.Get` method followed by the named parameter as a quoted string: + +``` +{{ .Get "class" }} +``` + +To access a parameter by position, use the `.Get` followed by a numeric position, keeping in mind that positional parameters are zero-indexed: + +``` +{{ .Get 0 }} +``` + +`with` is great when the output depends on a parameter being set: + +``` +{{ with .Get "class"}} class="{{.}}"{{ end }} +``` + +`.Get` can also be used to check if a parameter has been provided. This is +most helpful when the condition depends on either of the values, or both: + +``` +{{ or .Get "title" | .Get "alt" | if }} alt="{{ with .Get "alt"}}{{.}}{{else}}{{.Get "title"}}{{end}}"{{ end }} +``` + +#### `.Inner` + +If a closing shortcode is used, the `.Inner` variable will be populated with all of the content between the opening and closing shortcodes. If a closing shortcode is required, you can check the length of `.Inner` as an indicator of its existence. + +A shortcode with content declared via the `.Inner` variable can also be declared without the inline content and without the closing shortcode by using the self-closing syntax: + +``` +{{}} +``` + +#### `.Params` + +The `.Params` variable in shortcodes contains the list parameters passed to shortcode for more complicated use cases. You can also access higher-scoped parameters with the following logic: + +`$.Params` +: these are the parameters passed directly into the shortcode declaration (e.g., a YouTube video ID) + +`$.Page.Params` +: refers to the page's params; the "page" in this case refers to the content file in which the shortcode is declared (e.g., a `shortcode_color` field in a content's front matter could be accessed via `$.Page.Params.shortcode_color`). + +`$.Page.Site.Params` +: refers to global variables as defined in your [site's configuration file][config]. + +#### `.IsNamedParams` + +The `.IsNamedParams` variable checks whether the shortcode declaration uses named parameters and returns a boolean value. + +For example, you could create an `image` shortcode that can take either a `src` named parameter or the first positional parameter, depending on the preference of the content's author. Let's assume the `image` shortcode is called as follows: + +``` +{{}} +``` + +You could then include the following as part of your shortcode templating: + +``` +{{ if .IsNamedParams }} + +{{ else }} + +{{ end }} +``` + +See the [example Vimeo shortcode][vimeoexample] below for `.IsNamedParams` in action. + +{{% warning %}} +While you can create shortcode templates that accept both positional and named parameters, you *cannot* declare shortcodes in content with a mix of parameter types. Therefore, a shortcode declared like `{{}}` will return an error. +{{% /warning %}} + +You can also use the variable `.Page` to access all the normal [page variables][pagevars]. + +A shortcodes can also be nested. In a nested shortcode, you can access the parent shortcode context with [`.Parent` variable][shortcodesvars]. This can be very useful for inheritance of common shortcode parameters from the root. + +### Checking for Existence + +You can check if a specific shortcode is used on a page by calling `.HasShortcode` in that page template, providing the name of the shortcode. This is sometimes useful when you want to include specific scripts or styles in the header that are only used by that shortcode. + +## Custom Shortcode Examples + +The following are examples of the different types of shortcodes you can create via shortcode template files in `/layouts/shortcodes`. + +### Single-word Example: `year` + +Let's assume you would like to keep mentions of your copyright year current in your content files without having to continually review your markdown. Your goal is to be able to call the shortcode as follows: + +``` +{{}} +``` + +{{< code file="/layouts/shortcodes/year.html" >}} +{{ now.Format "2006" }} +{{< /code >}} + +### Single Positional Example: `youtube` + +Embedded videos are a common addition to markdown content that can quickly become unsightly. The following is the code used by [Hugo's built-in YouTube shortcode][youtubeshortcode]: + +``` +{{}} +``` + +Would load the template at `/layouts/shortcodes/youtube.html`: + +{{< code file="/layouts/shortcodes/youtube.html" >}} +
+ +
+{{< /code >}} + +{{< code file="youtube-embed.html" copy="false" >}} +
+ +
+{{< /code >}} + +### Single Named Example: `image` + +Let's say you want to create your own `img` shortcode rather than use Hugo's built-in [`figure` shortcode][figure]. Your goal is to be able to call the shortcode as follows in your content files: + +{{< code file="content-image.md" >}} +{{}} +{{< /code >}} + +You have created the shortcode at `/layouts/shortcodes/img.html`, which loads the following shortcode template: + +{{< code file="/layouts/shortcodes/img.html" >}} + +
+ {{ with .Get "link"}}{{ end }} + + {{ if .Get "link"}}{{ end }} + {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}} +
{{ if isset .Params "title" }} +

{{ .Get "title" }}

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

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

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

Steve Francia

+
+
+{{< /code >}} + +### Single Flexible Example: `vimeo` + +``` +{{}} +{{}} +``` + +Would load the template found at `/layouts/shortcodes/vimeo.html`: + +{{< code file="/layouts/shortcodes/vimeo.html" >}} +{{ if .IsNamedParams }} +
+ +
+{{ else }} +
+ +
+{{ end }} +{{< /code >}} + +Would be rendered as: + +{{< code file="vimeo-iframes.html" copy="false" >}} +
+ +
+
+ +
+{{< /code >}} + +### Paired Example: `highlight` + +The following is taken from `highlight`, which is a [built-in shortcode][] that ships with Hugo. + +{{< code file="highlight-example.md" >}} +{{}} + + This HTML + +{{}} +{{< /code >}} + +The template for the `highlight` shortcode uses the following code, which is already included in Hugo: + +``` +{{ .Get 0 | highlight .Inner }} +``` + +The rendered output of the HTML example code block will be as follows: + +{{< code file="syntax-highlighted.html" copy="false" >}} +
<html>
 +    <body> This HTML </body>
 +</html>
 +
+{{< /code >}} + +{{% note %}} +The preceding shortcode makes use of a Hugo-specific template function called `highlight`, which uses [Pygments](http://pygments.org) to add syntax highlighting to the example HTML code block. See the [developer tools page on syntax highlighting](/tools/syntax-highlighting/) for more information. +{{% /note %}} + +### Nested Shortcode: Image Gallery + +Hugo's [`.Parent` shortcode variable][parent] returns a boolean value depending on whether the shortcode in question is called within the context of a *parent* shortcode. This provides an inheritance model for common shortcode parameters. + +The following example is contrived but demonstrates the concept. Assume you have a `gallery` shortcode that expects one named `class` parameter: + +{{< code file="layouts/shortcodes/gallery.html" >}} +
+ {{.Inner}} +
+{{< /code >}} + - You also have an `image` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes so that the parent defines the context of each `image`: ++You also have an `img` shortcode with a single named `src` parameter that you want to call inside of `gallery` and other shortcodes, so that the parent defines the context of each `img`: + - {{< code file="layouts/shortcodes/image.html" >}} ++{{< code file="layouts/shortcodes/img.html" >}} +{{- $src := .Get "src" -}} +{{- with .Parent -}} + +{{- else -}} + +{{- end }} +{{< /code >}} + +You can then call your shortcode in your content as follows: + +``` +{{}} + {{}} + {{}} +{{}} +{{}} +``` + - This will output the following HTML. Note how the first two `image` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `image` only uses `src`: ++This will output the following HTML. Note how the first two `img` shortcodes inherit the `class` value of `content-gallery` set with the call to the parent `gallery`, whereas the third `img` only uses `src`: + +``` + + +``` + +## More Shortcode Examples + +More shortcode examples can be found in the [shortcodes directory for spf13.com][spfscs] and the [shortcodes directory for the Hugo docs][docsshortcodes]. + +[basic content files]: /content-management/formats/ "See how Hugo leverages markdown--and other supported formats--to create content for your website." +[built-in shortcode]: /content-management/shortcodes/ +[config]: /getting-started/configuration/ "Learn more about Hugo's built-in configuration variables as well as how to us your site's configuration file to include global key-values that can be used throughout your rendered website." +[Content Management: Shortcodes]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes "Check this section if you are not familiar with the definition of what a shortcode is or if you are unfamiliar with how to use Hugo's built-in shortcodes in your content files." +[source organization]: /getting-started/directory-structure/#directory-structure-explained "Learn how Hugo scaffolds new sites and what it expects to find in each of your directories." +[docsshortcodes]: https://github.com/gohugoio/hugo/tree/master/docs/layouts/shortcodes "See the shortcode source directory for the documentation site you're currently reading." +[figure]: /content-management/shortcodes/#figure +[hugosc]: /content-management/shortcodes/#using-hugo-s-built-in-shortcodes +[lookup order]: /templates/lookup-order/ "See the order in which Hugo traverses your template files to decide where and how to render your content at build time" +[pagevars]: /variables/page/ "See which variables you can leverage in your templating for page vs list templates." +[parent]: /variables/shortcodes/ +[shortcodesvars]: /variables/shortcodes/ "Certain variables are specific to shortcodes, although most .Page variables can be accessed within your shortcode template." +[spfscs]: https://github.com/spf13/spf13.com/tree/master/layouts/shortcodes "See more examples of shortcodes by visiting the shortcode directory of the source for spf13.com, the blog of Hugo's creator, Steve Francia." +[templates]: /templates/ "The templates section of the Hugo docs." +[vimeoexample]: #single-flexible-example-vimeo +[youtubeshortcode]: /content-management/shortcodes/#youtube "See how to use Hugo's built-in YouTube shortcode." diff --cc docs/layouts/shortcodes/gh.html index 0d1a9498,00000000..981f4b83 mode 100644,000000..100644 --- a/docs/layouts/shortcodes/gh.html +++ b/docs/layouts/shortcodes/gh.html @@@ -1,9 -1,0 +1,9 @@@ +{{ range .Params }} + {{ if eq (substr . 0 1) "@" }} + {{ . }} + {{ else if eq (substr . 0 2) "0x" }} - {{ substr . 2 6 }} ++ {{ substr . 2 6 }} + {{ else }} - #{{ . }} ++ #{{ . }} + {{ end }} - {{ end }} ++{{ end }} diff --cc docs/themes/gohugoioTheme/layouts/partials/site-search.html index 291484fd,00000000..cd1fd135 mode 100644,000000..100644 --- a/docs/themes/gohugoioTheme/layouts/partials/site-search.html +++ b/docs/themes/gohugoioTheme/layouts/partials/site-search.html @@@ -1,6 -1,0 +1,6 @@@ + diff --cc docs/themes/gohugoioTheme/src/css/_documentation-styles.css index bf28e8c2,00000000..0ea8e9b7 mode 100644,000000..100644 --- a/docs/themes/gohugoioTheme/src/css/_documentation-styles.css +++ b/docs/themes/gohugoioTheme/src/css/_documentation-styles.css @@@ -1,54 -1,0 +1,54 @@@ +.note, +.warning { + + border-left-width: 4px; + border-left-style: solid; + position: relative; + border-color: var(--primary-color); + + display: block; +} +.note #exclamation-icon, +.warning #exclamation-icon { + + fill: var(--primary-color); + position: absolute; + top: 35%; + left: -12px; + /*background-color: white;*/ +} + + .admonition-content { + display: block; + margin: 0px; + padding: .125em 1em; + /*margin-left: 1em;*/ + margin-top: 2em; + margin-bottom: 2em; + overflow-x: auto; + /*font-size: .9375em;*/ + background-color: var(--black-05); + } + + + .hide-child-menu .child-menu { + display: none; + } + .hide-child-menu:hover .child-menu, + .hide-child-menu:focus .child-menu, + .hide-child-menu:active .child-menu { + display: block; + } + + - /*documentation-copy headings exagerate spacing and size to chunk content */ ++/*documentation-copy headings exaggerate spacing and size to chunk content */ + .documentation-copy h2 { + margin-top: 3em; + &.minor { + font-size: inherit; + margin-top: inherit; + border-bottom: none; + } + } + + diff --cc docs/themes/gohugoioTheme/src/js/anchorforid.js index 5566c0bf,00000000..cb0855d5 mode 100644,000000..100644 --- a/docs/themes/gohugoioTheme/src/js/anchorforid.js +++ b/docs/themes/gohugoioTheme/src/js/anchorforid.js @@@ -1,34 -1,0 +1,34 @@@ +/** +* Anchor for ID BPNY +**/ +var anchorForId = function (id) { + var anchor = document.createElement("a"); + anchor.className = "header-link"; + anchor.href = "#" + id; + anchor.innerHTML = ' '; + return anchor; +}; + +var linkifyAnchors = function (level, containingElement) { + var headers = containingElement.getElementsByTagName("h" + level); + for (var h = 0; h < headers.length; h++) { + var header = headers[h]; + + if (typeof header.id !== "undefined" && header.id !== "") { + header.appendChild(anchorForId(header.id)); + } + } +}; + + +document.onreadystatechange = function () { + if (this.readyState === "complete") { + var contentBlock = document.getElementsByClassName("prose")[0] + if (!contentBlock) { + return; + } - for (var level = 2; level <= 2; level++) { ++ for (var level = 2; level <= 4; level++) { + linkifyAnchors(level, contentBlock); + } + } +}; diff --cc docs/themes/gohugoioTheme/src/readme.md index 0a30b3e0,00000000..db7041a1 mode 100755,000000..100755 --- a/docs/themes/gohugoioTheme/src/readme.md +++ b/docs/themes/gohugoioTheme/src/readme.md @@@ -1,39 -1,0 +1,39 @@@ +## Welcome to the SRC folder for the Gohugo Theme. + +The contents of this folder are used to generate CSS and javascript. You may never have to touch anything here, unless you want to more deeply customize your styles. + +## Tools + +### NPM + - We use [NPM](https://www.npmjs.com/) for package managment The theme's `.gitignore` file should be kept intact to make sure that all files in the `node_modules` folder are not pushed to the repository. ++We use [NPM](https://www.npmjs.com/) for package management The theme's `.gitignore` file should be kept intact to make sure that all files in the `node_modules` folder are not pushed to the repository. + +### Webpack + +We use Webpack to manage our asset pipeline. Arguably, Webpack is overkill for this use-case, but we're using it here because once it's set up (which we've done for you), it's really easy to use. If you want to use an external script, just add it via Yarn, and reference it in main.js. You'll find instructions in the js/main.js file. + +### PostCSS +PostCSS is just CSS. You'll find `postcss.config.js` in the css folder. There you'll find that we're using [`postcss-import`](https://github.com/postcss/postcss-import) which allows us import css files directly from the node_modules folder, [`postcss-cssnext`](http://cssnext.io/features/) which gives us the power to use upcoming CSS features today. If you miss Sass you can find PostCss modules for those capabilities, too. + + +### Tachyons + +This theme uses the [Tachyons CSS Library](http://tachyons.io/). It's about 15kb gzipped, highly modular, and each class is atomic so you never have to worry about overwriting your styles. It's a great library for themes because you can make most all the style changes you need right in your layouts. + +## How to Use + +You'll find the commands to run in `src/package.json`. + +For development, you'll need Node with NPM installed: + +``` +$ cd themes/gohugo-theme/src/ + +$ npm install + +$ npm start + +``` +This will process both the postcss and scripts. + +For production, instead of `npm start`, run `npm run build:production,` which will output minified versions of your files. diff --cc docs/themes/gohugoioTheme/static/dist/app.bundle.js index fc757f71,00000000..6c2fd668 mode 100644,000000..100644 --- a/docs/themes/gohugoioTheme/static/dist/app.bundle.js +++ b/docs/themes/gohugoioTheme/static/dist/app.bundle.js @@@ -1,22 -1,0 +1,22 @@@ - !function(t){function e(r){if(n[r])return n[r].exports;var i=n[r]={i:r,l:!1,exports:{}};return t[r].call(i.exports,i,i.exports,e),i.l=!0,i.exports}var n={};e.m=t,e.c=n,e.i=function(t){return t},e.d=function(t,n,r){e.o(t,n)||Object.defineProperty(t,n,{configurable:!1,enumerable:!0,get:r})},e.n=function(t){var n=t&&t.__esModule?function(){return t.default}:function(){return t};return e.d(n,"a",n),n},e.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},e.p="",e(e.s=10)}([function(t,e,n){"use strict";var r=function(t){var e=document.createElement("a");return e.className="header-link",e.href="#"+t,e.innerHTML=' ',e},i=function(t,e){for(var n=e.getElementsByTagName("h"+t),i=0;i0&&p.parentNode.classList.add("expand")}}catch(t){a=!0,u=t}finally{try{!s&&l.return&&l.return()}finally{if(a)throw u}}}},function(t,e,n){"use strict";n(12)({apiKey:"167e7998590aebda7f9fedcf86bc4a55",indexName:"hugodocs",inputSelector:"#search-input",debug:!0})},function(t,e,n){"use strict";n(13),n(14)},function(t,e,n){"use strict";function r(){for(var t=this.dataset.target.split(" "),e=document.querySelector(".mobilemenu:not(.dn)"),n=document.querySelector(".desktopmenu:not(.dn)"),r=document.querySelector(".desktopmenu:not(.dn)"),i=0;i=0?function(){var t=window.pageYOffset;(t>=i-s||window.innerHeight+t>=document.body.offsetHeight)&&clearInterval(u)}:function(){window.pageYOffset<=(i||0)&&clearInterval(u)};var u=setInterval(a,16)},e=document.querySelectorAll("#TableOfContents ul li a");[].forEach.call(e,function(e){e.addEventListener("click",function(n){n.preventDefault();var r=e.getAttribute("href"),i=document.querySelector(r),o=e.getAttribute("data-speed");i&&t(i,o||500)},!1)})}}()},function(t,e){},function(t,e,n){"use strict";var r=n(9);!function(t){t&&t.__esModule}(r);n(0),n(1),n(2),n(3),n(4),n(5),n(7),n(8),n(6)},function(t,e,n){var r,r;/*! ++!function(t){function e(r){if(n[r])return n[r].exports;var i=n[r]={i:r,l:!1,exports:{}};return t[r].call(i.exports,i,i.exports,e),i.l=!0,i.exports}var n={};e.m=t,e.c=n,e.i=function(t){return t},e.d=function(t,n,r){e.o(t,n)||Object.defineProperty(t,n,{configurable:!1,enumerable:!0,get:r})},e.n=function(t){var n=t&&t.__esModule?function(){return t.default}:function(){return t};return e.d(n,"a",n),n},e.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},e.p="",e(e.s=10)}([function(t,e,n){"use strict";var r=function(t){var e=document.createElement("a");return e.className="header-link",e.href="#"+t,e.innerHTML=' ',e},i=function(t,e){for(var n=e.getElementsByTagName("h"+t),i=0;i0&&p.parentNode.classList.add("expand")}}catch(t){a=!0,u=t}finally{try{!s&&l.return&&l.return()}finally{if(a)throw u}}}},function(t,e,n){"use strict";n(12)({apiKey:"167e7998590aebda7f9fedcf86bc4a55",indexName:"hugodocs",inputSelector:"#search-input",debug:!0})},function(t,e,n){"use strict";n(13),n(14)},function(t,e,n){"use strict";function r(){for(var t=this.dataset.target.split(" "),e=document.querySelector(".mobilemenu:not(.dn)"),n=document.querySelector(".desktopmenu:not(.dn)"),r=document.querySelector(".desktopmenu:not(.dn)"),i=0;i=0?function(){var t=window.pageYOffset;(t>=i-s||window.innerHeight+t>=document.body.offsetHeight)&&clearInterval(u)}:function(){window.pageYOffset<=(i||0)&&clearInterval(u)};var u=setInterval(a,16)},e=document.querySelectorAll("#TableOfContents ul li a");[].forEach.call(e,function(e){e.addEventListener("click",function(n){n.preventDefault();var r=e.getAttribute("href"),i=document.querySelector(r),o=e.getAttribute("data-speed");i&&t(i,o||500)},!1)})}}()},function(t,e){},function(t,e,n){"use strict";var r=n(9);!function(t){t&&t.__esModule}(r);n(0),n(1),n(2),n(3),n(4),n(5),n(7),n(8),n(6)},function(t,e,n){var r,r;/*! + * clipboard.js v1.7.1 + * https://zenorocha.github.io/clipboard.js + * + * Licensed MIT © Zeno Rocha + */ - !function(e){t.exports=e()}(function(){var t;return function t(e,n,i){function o(a,u){if(!n[a]){if(!e[a]){var c="function"==typeof r&&r;if(!u&&c)return r(a,!0);if(s)return s(a,!0);var l=new Error("Cannot find module '"+a+"'");throw l.code="MODULE_NOT_FOUND",l}var h=n[a]={exports:{}};e[a][0].call(h.exports,function(t){var n=e[a][1][t];return o(n||t)},h,h.exports,t,e,n,i)}return n[a].exports}for(var s="function"==typeof r&&r,a=0;a0&&void 0!==arguments[0]?arguments[0]:{};this.action=t.action,this.container=t.container,this.emitter=t.emitter,this.target=t.target,this.text=t.text,this.trigger=t.trigger,this.selectedText=""}},{key:"initSelection",value:function(){this.text?this.selectFake():this.target&&this.selectTarget()}},{key:"selectFake",value:function(){var t=this,e="rtl"==document.documentElement.getAttribute("dir");this.removeFake(),this.fakeHandlerCallback=function(){return t.removeFake()},this.fakeHandler=this.container.addEventListener("click",this.fakeHandlerCallback)||!0,this.fakeElem=document.createElement("textarea"),this.fakeElem.style.fontSize="12pt",this.fakeElem.style.border="0",this.fakeElem.style.padding="0",this.fakeElem.style.margin="0",this.fakeElem.style.position="absolute",this.fakeElem.style[e?"right":"left"]="-9999px";var n=window.pageYOffset||document.documentElement.scrollTop;this.fakeElem.style.top=n+"px",this.fakeElem.setAttribute("readonly",""),this.fakeElem.value=this.text,this.container.appendChild(this.fakeElem),this.selectedText=(0,r.default)(this.fakeElem),this.copyText()}},{key:"removeFake",value:function(){this.fakeHandler&&(this.container.removeEventListener("click",this.fakeHandlerCallback),this.fakeHandler=null,this.fakeHandlerCallback=null),this.fakeElem&&(this.container.removeChild(this.fakeElem),this.fakeElem=null)}},{key:"selectTarget",value:function(){this.selectedText=(0,r.default)(this.target),this.copyText()}},{key:"copyText",value:function(){var t=void 0;try{t=document.execCommand(this.action)}catch(e){t=!1}this.handleResult(t)}},{key:"handleResult",value:function(t){this.emitter.emit(t?"success":"error",{action:this.action,text:this.selectedText,trigger:this.trigger,clearSelection:this.clearSelection.bind(this)})}},{key:"clearSelection",value:function(){this.trigger&&this.trigger.focus(),window.getSelection().removeAllRanges()}},{key:"destroy",value:function(){this.removeFake()}},{key:"action",set:function(){var t=arguments.length>0&&void 0!==arguments[0]?arguments[0]:"copy";if(this._action=t,"copy"!==this._action&&"cut"!==this._action)throw new Error('Invalid "action" value, use either "copy" or "cut"')},get:function(){return this._action}},{key:"target",set:function(t){if(void 0!==t){if(!t||"object"!==(void 0===t?"undefined":i(t))||1!==t.nodeType)throw new Error('Invalid "target" value, use a valid Element');if("copy"===this.action&&t.hasAttribute("disabled"))throw new Error('Invalid "target" attribute. Please use "readonly" instead of "disabled" attribute');if("cut"===this.action&&(t.hasAttribute("readonly")||t.hasAttribute("disabled")))throw new Error('Invalid "target" attribute. You can\'t cut text from elements with "readonly" or "disabled" attributes');this._target=t}},get:function(){return this._target}}]),t}();t.exports=s})},{select:5}],8:[function(e,n,r){!function(i,o){if("function"==typeof t&&t.amd)t(["module","./clipboard-action","tiny-emitter","good-listener"],o);else if(void 0!==r)o(n,e("./clipboard-action"),e("tiny-emitter"),e("good-listener"));else{var s={exports:{}};o(s,i.clipboardAction,i.tinyEmitter,i.goodListener),i.clipboard=s.exports}}(this,function(t,e,n,r){"use strict";function i(t){return t&&t.__esModule?t:{default:t}}function o(t,e){if(!(t instanceof e))throw new TypeError("Cannot call a class as a function")}function s(t,e){if(!t)throw new ReferenceError("this hasn't been initialised - super() hasn't been called");return!e||"object"!=typeof e&&"function"!=typeof e?t:e}function a(t,e){if("function"!=typeof e&&null!==e)throw new TypeError("Super expression must either be null or a function, not "+typeof e);t.prototype=Object.create(e&&e.prototype,{constructor:{value:t,enumerable:!1,writable:!0,configurable:!0}}),e&&(Object.setPrototypeOf?Object.setPrototypeOf(t,e):t.__proto__=e)}function u(t,e){var n="data-clipboard-"+t;if(e.hasAttribute(n))return e.getAttribute(n)}var c=i(e),l=i(n),h=i(r),f="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(t){return typeof t}:function(t){return t&&"function"==typeof Symbol&&t.constructor===Symbol&&t!==Symbol.prototype?"symbol":typeof t},p=function(){function t(t,e){for(var n=0;n0&&void 0!==arguments[0]?arguments[0]:{};this.action="function"==typeof t.action?t.action:this.defaultAction,this.target="function"==typeof t.target?t.target:this.defaultTarget,this.text="function"==typeof t.text?t.text:this.defaultText,this.container="object"===f(t.container)?t.container:document.body}},{key:"listenClick",value:function(t){var e=this;this.listener=(0,h.default)(t,"click",function(t){return e.onClick(t)})}},{key:"onClick",value:function(t){var e=t.delegateTarget||t.currentTarget;this.clipboardAction&&(this.clipboardAction=null),this.clipboardAction=new c.default({action:this.action(e),target:this.target(e),text:this.text(e),container:this.container,trigger:e,emitter:this})}},{key:"defaultAction",value:function(t){return u("action",t)}},{key:"defaultTarget",value:function(t){var e=u("target",t);if(e)return document.querySelector(e)}},{key:"defaultText",value:function(t){return u("text",t)}},{key:"destroy",value:function(){this.listener.destroy(),this.clipboardAction&&(this.clipboardAction.destroy(),this.clipboardAction=null)}}],[{key:"isSupported",value:function(){var t=arguments.length>0&&void 0!==arguments[0]?arguments[0]:["copy","cut"],e="string"==typeof t?[t]:t,n=!!document.queryCommandSupported;return e.forEach(function(t){n=n&&!!document.queryCommandSupported(t)}),n}}]),e}(l.default);t.exports=d})},{"./clipboard-action":7,"good-listener":4,"tiny-emitter":6}]},{},[8])(8)})},function(t,e,n){/*! docsearch 2.3.3 | © Algolia | github.com/algolia/docsearch */ - !function(e,n){t.exports=n()}(0,function(){return function(t){function e(r){if(n[r])return n[r].exports;var i=n[r]={i:r,l:!1,exports:{}};return t[r].call(i.exports,i,i.exports,e),i.l=!0,i.exports}var n={};return e.m=t,e.c=n,e.i=function(t){return t},e.d=function(t,n,r){e.o(t,n)||Object.defineProperty(t,n,{configurable:!1,enumerable:!0,get:r})},e.n=function(t){var n=t&&t.__esModule?function(){return t.default}:function(){return t};return e.d(n,"a",n),n},e.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},e.p="",e(e.s=46)}([function(t,e,n){"use strict";function r(t){return t.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g,"\\$&")}var i=n(1);t.exports={isArray:null,isFunction:null,isObject:null,bind:null,each:null,map:null,mixin:null,isMsie:function(){return!!/(msie|trident)/i.test(navigator.userAgent)&&navigator.userAgent.match(/(msie |rv:)(\d+(.\d+)?)/i)[2]},escapeRegExChars:function(t){return t.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g,"\\$&")},isNumber:function(t){return"number"==typeof t},toStr:function(t){return void 0===t||null===t?"":t+""},cloneDeep:function(t){var e=this.mixin({},t),n=this;return this.each(e,function(t,r){t&&(n.isArray(t)?e[r]=[].concat(t):n.isObject(t)&&(e[r]=n.cloneDeep(t)))}),e},error:function(t){throw new Error(t)},every:function(t,e){var n=!0;return t?(this.each(t,function(r,i){if(!(n=e.call(null,r,i,t)))return!1}),!!n):n},any:function(t,e){var n=!1;return t?(this.each(t,function(r,i){if(e.call(null,r,i,t))return n=!0,!1}),n):n},getUniqueId:function(){var t=0;return function(){return t++}}(),templatify:function(t){if(this.isFunction(t))return t;var e=i.element(t);return"SCRIPT"===e.prop("tagName")?function(){return e.text()}:function(){return String(t)}},defer:function(t){setTimeout(t,0)},noop:function(){},formatPrefix:function(t,e){return e?"":t+"-"},className:function(t,e,n){return(n?"":".")+t+e},escapeHighlightedString:function(t,e,n){e=e||"";var i=document.createElement("div");i.appendChild(document.createTextNode(e)),n=n||"";var o=document.createElement("div");o.appendChild(document.createTextNode(n));var s=document.createElement("div");return s.appendChild(document.createTextNode(t)),s.innerHTML.replace(RegExp(r(i.innerHTML),"g"),e).replace(RegExp(r(o.innerHTML),"g"),n)}}},function(t,e,n){"use strict";t.exports={element:null}},function(t,e){var n=Object.prototype.hasOwnProperty,r=Object.prototype.toString;t.exports=function(t,e,i){if("[object Function]"!==r.call(e))throw new TypeError("iterator must be a function");var o=t.length;if(o===+o)for(var s=0;s was loaded but did not call our provided callback"),JSONPScriptError:i("JSONPScriptError","