From: Bjørn Erik Pedersen Date: Fri, 14 Sep 2018 06:35:23 +0000 (+0200) Subject: Merge commit '13e64d72763bf8d6d92d4cdfc15ed45ee9debfab' X-Git-Tag: v0.49~28 X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=b7ca3e1b3a83ef27bef841c319edb5b377cc4102;p=brevno-suite%2Fhugo Merge commit '13e64d72763bf8d6d92d4cdfc15ed45ee9debfab' --- b7ca3e1b3a83ef27bef841c319edb5b377cc4102 diff --cc docs/content/en/about/hugo-and-gdpr.md index 15352ae7,00000000..e193e183 mode 100644,000000..100644 --- a/docs/content/en/about/hugo-and-gdpr.md +++ b/docs/content/en/about/hugo-and-gdpr.md @@@ -1,134 -1,0 +1,135 @@@ + + +--- +title: Hugo and the General Data Protection Regulation (GDPR) +linktitle: Hugo and GDPR +description: About how to configure your Hugo site to meet the new regulations. +date: 2018-05-25 +layout: single +keywords: ["GDPR", "Privacy", "Data Protection"] +menu: + docs: + parent: "about" + weight: 5 +weight: 5 +sections_weight: 5 +draft: false +aliases: [/privacy/,/gdpr/] +toc: true +--- + + + General Data Protection Regulation ([GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation)) is a regulation in EU law on data protection and privacy for all individuals within the European Union and the European Economic Area. It became enforceable on 25 May 2018. + + **Hugo is a static site generator. By using Hugo you are already standing on very solid ground. Static HTML files on disk are much easier to reason about compared to server and database driven web sites.** + + But even static websites can integrate with external services, so from version `0.41`, Hugo provides a **Privacy Config** that covers the relevant built-in templates. + + Note that: + + * These settings have their defaults setting set to _off_, i.e. how it worked before Hugo `0.41`. You must do your own evaluation of your site and apply the appropriate settings. ++ * These settings work with the [internal templates](/templates/internal/). Some theme may contain custom templates for embedding services like Google Analytics. In that case these options have no effect. + * We will continue this work and improve this further in future Hugo versions. + +## All Privacy Settings + +Below are all privacy settings and their default value. These settings need to be put in your site config (e.g. `config.toml`). + + {{< code-toggle file="config">}} +[privacy] +[privacy.disqus] +disable = false +[privacy.googleAnalytics] +disable = false +respectDoNotTrack = false +anonymizeIP = false +useSessionStorage = false +[privacy.instagram] +disable = false +simple = false +[privacy.twitter] +disable = false +enableDNT = false +simple = false +[privacy.vimeo] +disable = false +simple = false +[privacy.youtube] +disable = false +privacyEnhanced = false +{{< /code-toggle >}} + + +## Disable All Services + +An example Privacy Config that disables all the relevant services in Hugo. With this configuration, the other settings will not matter. + + {{< code-toggle file="config">}} +[privacy] +[privacy.disqus] +disable = true +[privacy.googleAnalytics] +disable = true +[privacy.instagram] +disable = true +[privacy.twitter] +disable = true +[privacy.vimeo] +disable = true +[privacy.youtube] +disable = true +{{< /code-toggle >}} + +## The Privacy Settings Explained + +### GoogleAnalytics + +anonymizeIP +: Enabling this will make it so the users' IP addresses are anonymized within Google Analytics. + +respectDoNotTrack +: Enabling this will make the GA templates respect the "Do Not Track" HTTP header. + +useSessionStorage +: Enabling this will disable the use of Cookies and use Session Storage to Store the GA Client ID. + +### Instagram + +simple +: If simple mode is enabled, a static and no-JS version of the Instagram image card will be built. Note that this only supports image cards and the image itself will be fetched from Instagram's servers. + +**Note:** If you use the _simple mode_ for Instagram and a site styled with Bootstrap 4, you may want to disable the inlines styles provided by Hugo: + + {{< code-toggle file="config">}} +[services] +[services.instagram] +disableInlineCSS = true +{{< /code-toggle >}} + +### Twitter + +enableDNT +: Enabling this for the twitter/tweet shortcode, the tweet and its embedded page on your site are not used for purposes that include personalized suggestions and personalized ads. + +simple +: If simple mode is enabled, a static and no-JS version of a tweet will be built. + + +**Note:** If you use the _simple mode_ for Twitter, you may want to disable the inlines styles provided by Hugo: + + {{< code-toggle file="config">}} +[services] +[services.twitter] +disableInlineCSS = true +{{< /code-toggle >}} + +### YouTube + +privacyEnhanced +: When you turn on privacy-enhanced mode, YouTube won’t store information about visitors on your website unless the user plays the embedded video. + +### Vimeo + +simple +: If simple mode is enabled, the video thumbnail is fetched from Vimeo's servers and it is overlayed with a play button. If the user clicks to play the video, it will open in a new tab directly on Vimeo's website. + diff --cc docs/content/en/content-management/archetypes.md index 904ca8c3,00000000..ff4a2d78 mode 100644,000000..100644 --- a/docs/content/en/content-management/archetypes.md +++ b/docs/content/en/content-management/archetypes.md @@@ -1,75 -1,0 +1,75 @@@ +--- +title: Archetypes +linktitle: Archetypes +description: Archetypes are templates used when creating new content. +date: 2017-02-01 +publishdate: 2017-02-01 +keywords: [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 +--- + +## What are Archetypes? + +**Archetypes** are content template files in the [archetypes directory][] of your project that contain preconfigured [front matter][] and possibly also a content disposition for your website's [content types][]. These will be used when you run `hugo new`. + + +The `hugo new` uses the `content-section` to find the most suitable archetype template in your project. If your project does not contain any archetype files, it will also look in the theme. + +{{< code file="archetype-example.sh" >}} +hugo new posts/my-first-post.md +{{< /code >}} + +The above will create a new content file in `content/posts/my-first-post.md` using the first archetype file found of these: + +1. `archetypes/posts.md` +2. `archetypes/default.md` +3. `themes/my-theme/archetypes/posts.md` +4. `themes/my-theme/archetypes/default.md` + - The last two list items is only applicable if you use a theme and it uses the `my-theme` theme name as an example. ++The last two list items are only applicable if you use a theme and it uses the `my-theme` theme name as an example. + +## Create a New Archetype Template + +A fictional example for the section `newsletter` and the archetype file `archetypes/newsletter.md`. Create a new file in `archetypes/newsletter.md` and open it in a text editor. + +{{< code file="archetypes/newsletter.md" >}} +--- +title: "{{ replace .Name "-" " " | title }}" +date: {{ .Date }} +draft: true +--- + +**Insert Lead paragraph here.** + +## New Cool Posts + +{{ range first 10 ( where .Site.RegularPages "Type" "cool" ) }} +* {{ .Title }} +{{ end }} +{{< /code >}} + +When you create a new newsletter with: + +```bash +hugo new newsletter/the-latest-cool.stuff.md +``` + +It will create a new newsletter type of content file based on the archetype template. + +**Note:** the site will only be built if the `.Site` is in use in the archetype file, and this can be time consuming for big sites. + +The above _newsletter type archetype_ illustrates the possibilities: The full Hugo `.Site` and all of Hugo's template funcs can be used in the archetype file. + + +[archetypes directory]: /getting-started/directory-structure/ +[content types]: /content-management/types/ +[front matter]: /content-management/front-matter/ diff --cc docs/content/en/content-management/comments.md index 268dc4c0,00000000..17914ba2 mode 100644,000000..100644 --- a/docs/content/en/content-management/comments.md +++ b/docs/content/en/content-management/comments.md @@@ -1,85 -1,0 +1,85 @@@ +--- +title: Comments +linktitle: Comments +description: Hugo ships with an internal Disqus template, but this isn't the only commenting system that will work with your new Hugo website. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-09 +keywords: [sections,content,organization] +categories: [project organization, fundamentals] +menu: + docs: + parent: "content-management" + weight: 140 +weight: 140 #rem +draft: false +aliases: [/extras/comments/] +toc: true +--- + +Hugo ships with support for [Disqus](https://disqus.com/), a third-party service that provides comment and community capabilities to websites via JavaScript. + +Your theme may already support Disqus, but if not, it is easy to add to your templates via [Hugo's built-in Disqus partial][disquspartial]. + +## Add Disqus + +Hugo comes with all the code you need to load Disqus into your templates. Before adding Disqus to your site, you'll need to [set up an account][disqussetup]. + +### Configure Disqus + +Disqus comments require you set a single value in your [site's configuration file][configuration] like so: + +{{< code-toggle copy="false" >}} +disqusShortname = "yourdiscussshortname" +{{}} + +For many websites, this is enough configuration. However, you also have the option to set the following in the [front matter][] of a single content file: + +* `disqus_identifier` +* `disqus_title` +* `disqus_url` + +### Render Hugo's Built-in Disqus Partial Template + +Disqus has its own [internal template](https://gohugo.io/templates/internal/#disqus) available, to render it add the following code where you want comments to appear: + +``` +{{ template "_internal/disqus.html" . }} +``` + +## Comments Alternatives + +There are a few alternatives to commenting on static sites for those who do not want to use Disqus: + +* [Static Man](https://staticman.net/) +* [Talkyard](https://www.talkyard.io/blog-comments) (Open source, & serverless hosting) +* [txtpen](https://txtpen.github.io/hn/) +* [IntenseDebate](http://intensedebate.com/) +* [Graph Comment][] +* [Muut](http://muut.com/) +* [isso](http://posativ.org/isso/) (Self-hosted, Python) + * [Tutorial on Implementing Isso with Hugo][issotutorial] - ++* [Utterances](https://utteranc.es/) (Open source, Github comments widget built on Github issues) + + + + + + +[configuration]: /getting-started/configuration/ +[disquspartial]: /templates/partials/#disqus +[disqussetup]: https://disqus.com/profile/signup/ +[forum]: https://discourse.gohugo.io +[front matter]: /content-management/front-matter/ +[Graph Comment]: https://graphcomment.com/ +[kaijuissue]: https://github.com/spf13/kaiju/issues/new +[issotutorial]: https://stiobhart.net/2017-02-24-isso-comments/ +[partials]: /templates/partials/ +[MongoDB]: https://www.mongodb.com/ +[tweet]: https://twitter.com/spf13 diff --cc docs/content/en/content-management/formats.md index ab9fdd78,00000000..f7a466c3 mode 100644,000000..100644 --- a/docs/content/en/content-management/formats.md +++ b/docs/content/en/content-management/formats.md @@@ -1,251 -1,0 +1,251 @@@ +--- +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] +keywords: [markdown,asciidoc,mmark,pandoc,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/en/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: + +``` + +``` + +#### 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` shortcode][hlsc], and syntax highlights those code blocks natively using *Chroma*. Users also have an option to use *Pygments* instead. See the [Syntax Highlighting][hl] section for details. + +## 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 +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 a new concept called _external helpers_. It means that you can write your content using [Asciidoc][ascii], [reStructuredText][rest], or [pandoc]. 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. + +Hugo passes reasonable default arguments to these external helpers by default: + +- `asciidoc`: `--no-header-footer --safe -` +- `asciidoctor`: `--no-header-footer --safe --trace -` +- `rst2html`: `--leave-comments --initial-header-level=2` +- `pandoc`: `--mathjax` + +{{% 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] +* [The Markdown Guide, Matt Cone][mdguide] + +[`emojify` function]: /functions/emojify/ +[ascii]: http://asciidoctor.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]: /content-management/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 +[mdguide]: https://www.markdownguide.org/ +[mdtutorial]: http://www.markdowntutorial.com/ - [Miek Gieben's website]: https://miek.nl/2016/March/05/mmark-syntax-document/ ++[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/ +[pandoc]: http://www.pandoc.org/ +[Pygments]: http://pygments.org/ +[rest]: http://docutils.sourceforge.net/rst.html +[sc]: /content-management/shortcodes/ +[sct]: /templates/shortcode-templates/ diff --cc docs/content/en/content-management/menus.md index 4278b03b,00000000..bc48c82e mode 100644,000000..100644 --- a/docs/content/en/content-management/menus.md +++ b/docs/content/en/content-management/menus.md @@@ -1,122 -1,0 +1,123 @@@ +--- +title: Menus +linktitle: Menus +description: Hugo has a simple yet powerful menu system. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-31 +categories: [content management] +keywords: [menus] +draft: false +menu: + docs: + parent: "content-management" + weight: 120 +weight: 120 #rem +aliases: [/extras/menus/] +toc: true +--- + +{{% note "Lazy Blogger"%}} +If all you want is a simple menu for your sections, see the ["Section Menu for Lazy Bloggers" in Menu Templates](/templates/menu-templates/#section-menu-for-lazy-bloggers). +{{% /note %}} + +You can do this: + +* Place content in one or many menus +* Handle nested menus with unlimited depth +* Create menu entries without being attached to any content +* Distinguish active element (and active branch) + +## What is a Menu in Hugo? + +A **menu** is a named array of menu entries accessible by name via the [`.Site.Menus` site variable][sitevars]. For example, you can access your site's `main` menu via `.Site.Menus.main`. + +{{% note "Menus on Multilingual Sites" %}} +If you make use of the [multilingual feature](/content-management/multilingual/), you can define language-independent menus. +{{% /note %}} + +See the [Menu Entry Properties][me-props] for all the variables and functions related to a menu entry. + +## Add content to menus + +Hugo allows you to add content to a menu via the content's [front matter](/content-management/front-matter/). + +### Simple + +If all you need to do is add an entry to a menu, the simple form works well. + +#### A Single Menu + +``` +--- +menu: "main" +--- +``` + +#### Multiple Menus + +``` +--- +menu: ["main", "footer"] +--- +``` + +#### Advanced + + +``` +--- +menu: + docs: + parent: 'extras' + weight: 20 +--- +``` + +## Add Non-content Entries to a Menu + +You can also add entries to menus that aren’t attached to a piece of content. This takes place in your Hugo project's [`config` file][config]. + +Here’s an example snippet pulled from a configuration file: + - {{< code-toggle file="config.toml" >}} ++{{< code-toggle file="config" >}} +[[menu.main]] + name = "about hugo" + pre = "" + weight = -110 + identifier = "about" + url = "/about/" +[[menu.main]] + name = "getting started" + pre = "" ++ post = "New!" + weight = -100 + url = "/getting-started/" +{{< /code-toggle >}} + +{{% note %}} +The URLs must be relative to the context root. If the `baseURL` is `https://example.com/mysite/`, then the URLs in the menu must not include the context root `mysite`. Using an absolute URL will override the baseURL. If the value used for `URL` in the above example is `https://subdomain.example.com/`, the output will be `https://subdomain.example.com`. +{{% /note %}} + +## Nesting + +All nesting of content is done via the `parent` field. + +The parent of an entry should be the identifier of another entry. The identifier should be unique (within a menu). + +The following order is used to determine an Identifier: + +`.Name > .LinkTitle > .Title` + +This means that `.Title` will be used unless `.LinkTitle` is present, etc. In practice, `.Name` and `.Identifier` are only used to structure relationships and therefore never displayed. + +In this example, the top level of the menu is defined in your [site `config` file][config]). All content entries are attached to one of these entries via the `.Parent` field. + +## Render Menus + +See [Menu Templates](/templates/menu-templates/) for information on how to render your site menus within your templates. + +[config]: /getting-started/configuration/ +[multilingual]: /content-management/multilingual/ +[sitevars]: /variables/ +[me-props]: /variables/menus/ diff --cc docs/content/en/content-management/related.md index 9a4c77d4,00000000..636e9597 mode 100644,000000..100644 --- a/docs/content/en/content-management/related.md +++ b/docs/content/en/content-management/related.md @@@ -1,143 -1,0 +1,135 @@@ +--- +title: Related Content +description: List related content in "See Also" sections. +date: 2017-09-05 +categories: [content management] +keywords: [content] +menu: + docs: + parent: "content-management" + weight: 40 +weight: 30 +draft: false +aliases: [/content/related/,/related/] +toc: true +--- + - {{% note %}} - We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock). - {{% /note %}} ++ ++Hugo uses a set of factors to identify a page's related content based on Front Matter parameters. This can be tuned to the desired set of indices and parameters or left to Hugo's default [Related Content configuration](#configure-related-content). + +## List Related Content + - To list up to 5 related pages is as simple as including something similar to this partial in your single page template: ++ ++To list up to 5 related pages (which share the same _date_ or _keyword_ parameters) is as simple as including something similar to this partial in your single page template: + +{{< code file="layouts/partials/related.html" >}} +{{ $related := .Site.RegularPages.Related . | first 5 }} +{{ with $related }} +

See Also

+ +{{ end }} +{{< /code >}} + ++### Methods + - {{% note %}} - Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. - {{% /note %}} ++Here is the list of "Related" methods available on a page collection such `.RegularPages`. + - The full set of methods available on the page lists can be seen in this Go interface: ++#### .Related PAGE ++Returns a collection of pages related the given one. + - ```go - // A PageGenealogist finds related pages in a page collection. This interface is implemented - // by Pages and PageGroup, which makes it available as `{{ .RegularPages.Related . }}` etc. - type PageGenealogist interface { ++``` ++{{ $related := .RegularPages.Related . }} ++``` + - // Template example: - // {{ $related := .RegularPages.Related . }} - Related(doc related.Document) (Pages, error) ++#### .RelatedIndices PAGE INDICE1 [INDICE2 ...] ++Returns a collection of pages related to a given one restricted to a list of indices. + - // Template example: - // {{ $related := .RegularPages.RelatedIndices . "tags" "date" }} - RelatedIndices(doc related.Document, indices ...interface{}) (Pages, error) ++``` ++{{ $related := .RegularPages.RelatedIndices . "tags" "date" }} ++``` ++ ++#### .RelatedTo KEYVALS [KEYVALS2 ...] ++Returns a collection of pages related together by a set of indices and their match. + - // Template example: - // {{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }} - RelatedTo(args ...types.KeyValues) (Pages, error) - } ++In order to build those set and pass them as argument, one must use the `keyVals` function where the first agrument would be the `indice` and the consective ones its potential `matches`. ++ ++``` ++{{ $related := .RegularPages.RelatedTo ( keyVals "tags" "hugo" "rocks") ( keyVals "date" .Date ) }} +``` ++ ++{{% note %}} ++Read [this blog article](https://regisphilibert.com/blog/2018/04/hugo-optmized-relashionships-with-related-content/) for a great explanation of more advanced usage of this feature. ++{{% /note %}} ++ +## Configure Related Content +Hugo provides a sensible default configuration of Related Content, but you can fine-tune this in your configuration, on the global or language level if needed. + ++### Default configuration ++ ++Without any `related` configuration set on the project, Hugo's Related Content methods will use the following. ++ ++```yaml ++related: ++ threshold: 80 ++ includeNewer: false ++ toLower: false ++ indices: ++ - name: keywords ++ weight: 100 ++ - name: date ++ weight: 10 ++``` ++ ++Custom configuration should be set using the same syntax. ++ +{{% note %}} +If you add a `related` config section, you need to add a complete configuration. It is not possible to just set, say, `includeNewer` and use the rest from the Hugo defaults. +{{% /note %}} + - Below is a sample `config.toml` section: - - ``` - [related] - - # Only include matches with rank >= threshold. This is a normalized rank between 0 and 100. - threshold = 80 - - # To get stable "See also" sections we, by default, exclude newer related pages. - includeNewer = false - - # Will lower case keywords in both queries and in the indexes. - toLower = false - - [[related.indices]] - name = "keywords" - weight = 150 - [[related.indices]] - name = "author" - toLower = true - weight = 30 - [[related.indices]] - name = "tags" - weight = 100 - [[related.indices]] - name = "date" - weight = 10 - pattern = "2006" - ``` +### Top Level Config Options + +threshold +: A value between 0-100. Lower value will give more, but maybe not so relevant, matches. + +includeNewer +: Set to true to include **pages newer than the current page** in the related content listing. This will mean that the output for older posts may change as new related content gets added. + +toLower +: Set to true to lower case keywords in both the indexes and the queries. This may give more accurate results at a slight performance penalty. Note that this can also be set per index. + +### Config Options per Index + +name +: The index name. This value maps directly to a page param. Hugo supports string values (`author` in the example) and lists (`tags`, `keywords` etc.) and time and date objects. + +weight +: An integer weight that indicates _how important_ this parameter is relative to the other parameters. It can be 0, which has the effect of turning this index off, or even negative. Test with different values to see what fits your content best. + +pattern +: This is currently only relevant for dates. When listing related content, we may want to list content that is also close in time. Setting "2006" (default value for date indexes) as the pattern for a date index will add weight to pages published in the same year. For busier blogs, "200601" (year and month) may be a better default. + +toLower +: See above. + +## Performance Considerations + +**Fast is Hugo's middle name** and we would not have released this feature had it not been blistering fast. + +This feature has been in the back log and requested by many for a long time. The development got this recent kick start from this Twitter thread: + +{{< tweet 898398437527363585 >}} + +Scott S. Lowe removed the "Related Content" section built using the `intersect` template function on tags, and the build time dropped from 30 seconds to less than 2 seconds on his 1700 content page sized blog. + +He should now be able to add an improved version of that "Related Content" section without giving up the fast live-reloads. But it's worth noting that: + +* If you don't use any of the `Related` methods, you will not use the Relate Content feature, and performance will be the same as before. +* Calling `.RegularPages.Related` etc. will create one inverted index, also sometimes named posting list, that will be reused for any lookups in that same page collection. Doing that in addition to, as an example, calling `.Pages.Related` will work as expected, but will create one additional inverted index. This should still be very fast, but worth having in mind, especially for bigger sites. + - - - - - - ++{{% note %}} ++We currently do not index **Page content**. We thought we would release something that will make most people happy before we start solving [Sherlock's last case](https://github.com/joearms/sherlock). ++{{% /note %}} diff --cc docs/content/en/content-management/summaries.md index 0f893937,00000000..63d64aa3 mode 100644,000000..100644 --- a/docs/content/en/content-management/summaries.md +++ b/docs/content/en/content-management/summaries.md @@@ -1,81 -1,0 +1,89 @@@ +--- +title: Content Summaries +linktitle: Summaries +description: Hugo generates summaries of your content. +date: 2017-01-10 +publishdate: 2017-01-10 +lastmod: 2017-01-10 +categories: [content management] +keywords: [summaries,abstracts,read more] +menu: + docs: + parent: "content-management" + weight: 90 +weight: 90 #rem +draft: false +aliases: [/content/summaries/,/content-management/content-summaries/] +toc: true +--- + +With the use of the `.Summary` [page variable][pagevariables], Hugo generates summaries of content to use as a short version in summary views. + +## Summary Splitting Options + - * Hugo-defined Summary Split - * User-defined Summary Split ++* Automatic Summary Split ++* Manual Summary Split + +It is natural to accompany the summary with links to the original content, and a common design pattern is to see this link in the form of a "Read More ..." button. See the `.RelPermalink`, `.Permalink`, and `.Truncated` [page variables][pagevariables]. + - ### Hugo-defined: Automatic Summary Splitting ++### Automatic Summary Splitting + - By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. Taking the Hugo-defined approach to summaries may save time, but it has pros and cons: ++By default, Hugo automatically takes the first 70 words of your content as its summary and stores it into the `.Summary` page variable for use in your templates. You may customize the summary length by setting `summaryLength` in your [site configuration](/getting-started/configuration/). + - * **Pros:** Automatic, no additional work on your part. - * **Cons:** All HTML tags are stripped from the summary, and the first 70 words, whether they belong to a heading or to different paragraphs, are all put into one paragraph. ++{{% note %}} ++You can customize how HTML tags in the summary are loaded using functions such as `plainify` and `safeHTML`. ++{{% /note %}} + +{{% note %}} - The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive white space characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in you [site configuration](/getting-started/configuration/). ++The Hugo-defined summaries are set to use word count calculated by splitting the text by one or more consecutive whitespace characters. If you are creating content in a `CJK` language and want to use Hugo's automatic summary splitting, set `hasCJKLanguage` to `true` in your [site configuration](/getting-started/configuration/). +{{% /note %}} + - ### User-defined: Manual Summary Splitting ++### Manual Summary Splitting ++ ++Alternatively, you may add the <!--more--> summary divider where you want to split the article. + - Alternatively, you may add the <!--more--> summary divider where you want to split the article. For [org content][org], use `# more` where you want to split the article. Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact. ++For [Org mode content][org], use `# more` where you want to split the article. ++ ++Content that comes before the summary divider will be used as that content's summary and stored in the `.Summary` page variable with all HTML formatting intact. + +{{% note "Summary Divider"%}} +The concept of a *summary divider* is not unique to Hugo. It is also called the "more tag" or "excerpt separator" in other literature. +{{% /note %}} + - * Pros: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved. - * Cons: Extra work for content authors, since they need to remember to type <!--more--> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/). ++Pros ++: Freedom, precision, and improved rendering. All HTML tags and formatting are preserved. ++ ++Cons ++: Extra work for content authors, since they need to remember to type <!--more--> (or `# more` for [org content][org]) in each content file. This can be automated by adding the summary divider below the front matter of an [archetype](/content-management/archetypes/). + +{{% warning "Be Precise with the Summary Divider" %}} +Be careful to enter <!--more--> exactly; i.e., all lowercase and with no whitespace. +{{% /warning %}} + +## Example: First 10 Articles with Summaries + +You can show content summaries with the following code. You could use the following snippet, for example, in a [section template][]. + +{{< code file="page-list-with-summaries.html" >}} +{{ range first 10 .Pages }} + +{{ end }} +{{< /code >}} + +Note how the `.Truncated` boolean valuable may be used to hide the "Read More..." link when the content is not truncated; i.e., when the summary contains the entire article. + +[org]: /content-management/formats/ +[pagevariables]: /variables/page/ +[section template]: /templates/section-templates/ diff --cc docs/content/en/contribute/development.md index be2ca4a2,00000000..e9e1cd10 mode 100644,000000..100644 --- a/docs/content/en/contribute/development.md +++ b/docs/content/en/contribute/development.md @@@ -1,416 -1,0 +1,415 @@@ +--- +title: Contribute to Hugo Development +linktitle: Development +description: Hugo relies heavily on contributions from the open source community. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [contribute] +keywords: [dev,open source] +authors: [digitalcraftsman] +menu: + docs: + parent: "contribute" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false - aliases: [/contribute/development/] +toc: true +--- + +## Introduction + +Hugo is an open-source project and lives by the work of its [contributors][]. There are plenty of [open issues][issues], and we need your help to make Hugo even more awesome. You don't need to be a Go guru to contribute to the project's development. + +## Assumptions + +This contribution guide takes a step-by-step approach in hopes of helping newcomers. Therefore, we only assume the following: + +* You are new to Git or open-source projects in general +* You are a fan of Hugo and enthusiastic about contributing to the project + +{{% note "Additional Questions?" %}} +If you're struggling at any point in this contribution guide, reach out to the Hugo community in [Hugo's Discussion forum](https://discourse.gohugo.io). +{{% /note %}} + +## Install Go + +The installation of Go should take only a few minutes. You have more than one option to get Go up and running on your machine. + +If you are having trouble following the installation guides for Go, check out [Go Bootcamp, which contains setups for every platform][gobootcamp] or reach out to the Hugo community in the [Hugo Discussion Forums][forums]. + +### Install Go From Source + +[Download the latest stable version of Go][godl] and follow the official [Go installation guide][goinstall]. + +Once you're finished installing Go, let's confirm everything is working correctly. Open a terminal---or command line under Windows--and type the following: + +``` +go version +``` + +You should see something similar to the following written to the console. Note that the version here reflects the most recent version of Go as of the last update for this page: + +``` +go version go1.8 darwin/amd64 +``` + +Next, make sure that you set up your `GOPATH` [as described in the installation guide][setupgopath]. + +You can print the `GOPATH` with `echo $GOPATH`. You should see a non-empty string containing a valid path to your Go workspace; for example: + +``` +/Users//Code/go +``` + +### Install Go with Homebrew + +If you are a MacOS user and have [Homebrew](https://brew.sh/) installed on your machine, installing Go is as simple as the following command: + +{{< code file="install-go.sh" >}} +brew install go +{{< /code >}} + +### Install Go via GVM + +More experienced users can use the [Go Version Manager][gvm] (GVM). GVM allows you to switch between different Go versions *on the same machine*. If you're a beginner, you probably don't need this feature. However, GVM makes it easy to upgrade to a new released Go version with just a few commands. + +GVM comes in especially handy if you follow the development of Hugo over a longer period of time. Future versions of Hugo will usually be compiled with the latest version of Go. Sooner or later, you will have to upgrade if you want to keep up. + +## Create a GitHub Account + +If you're going to contribute code, you'll need to have an account on GitHub. Go to [www.github.com/join](https://github.com/join) and set up a personal account. + +## Install Git on Your System + +You will need to have Git installed on your computer to contribute to Hugo development. Teaching Git is outside the scope of the Hugo docs, but if you're looking for an excellent reference to learn the basics of Git, we recommend the [Git book][gitbook] if you are not sure where to begin. We will include short explainations of the Git commands in this document. + +Git is a [version control system](https://en.wikipedia.org/wiki/Version_control) to track the changes of source code. Hugo depends on smaller third-party packages that are used to extend the functionality. We use them because we don't want to reinvent the wheel. + +Go ships with a sub-command called `get` that will download these packages for us when we setup our working environment. The source code of the packages is tracked with Git. `get` will interact with the Git servers of the package hosters in order to fetch all dependencies. + +Move back to the terminal and check if Git is already installed. Type in `git version` and press enter. You can skip the rest of this section if the command returned a version number. Otherwise [download](https://git-scm.com/downloads) the latest version of Git and follow this [installation guide](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). + +Finally, check again with `git version` if Git was installed successfully. + +### Git Graphical Front Ends + +There are several [GUI clients](https://git-scm.com/downloads/guis) that help you to operate Git. Not all are available for all operating systems and maybe differ in their usage. Because of this we will document how to use the command line, since the commands are the same everywhere. + +### Install Hub on Your System (Optional) + +Hub is a great tool for working with GitHub. The main site for it is [hub.github.com](https://hub.github.com/). Feel free to install this little Git wrapper. + +On a Mac, you can install [Hub](https://github.com/github/hub) using [Homebrew](https://brew.sh): + +``` +brew install hub +``` + +Now we'll create an [alias in Bash](http://tldp.org/LDP/abs/html/aliases.html) so that typing `git` actually runs `Hub`: + +``` +echo "alias git='hub'" >> ~/.bash_profile +``` + +Confirm the installation: + +``` +git version 2.6.3 +hub version 2.2.2 +``` + +## Set up your working copy + +You set up the working copy of the repository locally on your computer. Your local copy of the files is what you'll edit, compile, and end up pushing back to GitHub. The main steps are cloning the repository and creating your fork as a remote. + +### Clone the repository + +We assume that you've set up your `GOPATH` (see the section above if you're unsure about this). You should now copy the Hugo repository down to your computer. You'll hear this called "clone the repo". GitHub's [help pages](https://help.github.com/articles/cloning-a-repository/) give us a short explanation: + +> When you create a repository on GitHub, it exists as a remote repository. You can create a local clone of your repository on your computer and sync between the two locations. + +We're going to clone the [master Hugo repository](https://github.com/gohugoio/hugo). That seems counter-intuitive, since you won't have commit rights on it. But it's required for the Go workflow. You'll work on a copy of the master and push your changes to your own repository on GitHub. + +So, let's clone that master repository: + +``` +go get -v -u github.com/gohugoio/hugo +``` + +Hugo relies on [Testify](https://github.com/stretchr/testify) for testing Go code. If you don't already have it, get the Testify testing tools: + +``` +go get github.com/stretchr/testify +``` + +### Fork the repository + +If you're not familiar with this term, GitHub's [help pages](https://help.github.com/articles/fork-a-repo/) provide again a simple explanation: + +> A fork is a copy of a repository. Forking a repository allows you to freely experiment with changes without affecting the original project. + +#### Fork by hand + +Open the [Hugo repository](https://github.com/gohugoio/hugo) on GitHub and click on the "Fork" button in the top right. + +![Fork button](/images/contribute/development/forking-a-repository.png) + +Now open your fork repository on GitHub and copy the remote url of your fork. You can choose between HTTPS and SSH as protocol that Git should use for the following operations. HTTPS works always [if you're not sure](https://help.github.com/articles/which-remote-url-should-i-use/). + +![Copy remote url](/images/contribute/development/copy-remote-url.png) + +Switch back to the terminal and move into the directory of the cloned master repository from the last step. + +``` +cd $GOPATH/src/github.com/gohugoio/hugo +``` + +Now Git needs to know that our fork exists by adding the copied remote url: + +``` +git remote add +``` + +#### Fork with Hub + +Alternatively, you can use the Git wrapper Hub. Hub makes forking a repository easy: + +``` +git fork +``` + +That command will log in to GitHub using your account, create a fork of the repository that you're currently working in, and add it as a remote to your working copy. + +#### Trust, but verify + +Let's check if everything went right by listing all known remotes: + +``` +git remote -v +``` + +The output should look similar: + +``` +digitalcraftsman git@github.com:digitalcraftsman/hugo.git (fetch) +digitalcraftsman git@github.com:digitalcraftsman/hugo.git (push) +origin https://github.com/gohugoio/hugo (fetch) +origin https://github.com/gohugoio/hugo (push) +``` + +## The Hugo Git Contribution Workflow + +### Create a new branch + +You should never develop against the "master" branch. The development team will not accept a pull request against that branch. Instead, create a descriptive named branch and work on it. + +First, you should always pull the latest changes from the master repository: + +``` +git checkout master +git pull +``` + +Now we can create a new branch for your additions: + +``` +git checkout -b +``` + +You can check on which branch you are with `git branch`. You should see a list of all local branches. The current branch is indicated with a little asterisk. + +### Contribute to Documentation + +Perhaps you want to start contributing to the Hugo docs. If so, you can ignore most of the following steps and focus on the `/docs` directory within your newly cloned repository. You can change directories into the Hugo docs using `cd docs`. + +You can start Hugo's built-in server via `hugo server`. Browse the documentation by entering [http://localhost:1313](http://localhost:1313) in the address bar of your browser. The server automatically updates the page whenever you change content. + +We have developed a [separate Hugo documentation contribution guide][docscontrib] for more information on how the Hugo docs are built, organized, and improved by the generosity of people like you. + +### Build Hugo + +While making changes in the codebase it's a good idea to build the binary to test them: + +``` +go build -o hugo main.go +``` + +### Test +Sometimes changes on the codebase can cause unintended side effects. Or they don't work as expected. Most functions have their own test cases. You can find them in files ending with `_test.go`. + +Make sure the commands `go test ./...` passes, and `go build` completes. + +### Formatting +The Go code styleguide maybe is opinionated but it ensures that the codebase looks the same, regardless who wrote the code. Go comes with its own formatting tool. Let's apply the styleguide to our addtions: + +``` +go fmt ./... +``` + +Once you made your additions commit your changes. Make sure that you follow our [code contribution guidelines](https://github.com/gohugoio/hugo/blob/master/CONTRIBUTING.md): + +``` +# Add all changed files +git add --all +git commit --message "YOUR COMMIT MESSAGE" +``` + +The commit message should describe what the commit does (e.g. add feature XYZ), not how it is done. + +### Modify commits + +You noticed some commit messages don't fulfill the code contribution guidelines or you just forget something to add some files? No problem. Git provides the necessary tools to fix such problems. The next two methods cover all common cases. + +If you are unsure what a command does leave the commit as it is. We can fix your commits later in the pull request. + +#### Modify the last commit + +Let's say you want to modify the last commit message. Run the following command and replace the current message: + +``` +git commit --amend -m"YOUR NEW COMMIT MESSAGE" +``` + +Take a look at the commit log to see the change: + +``` +git log +# Exit with q +``` + +After making the last commit you may have forgot something. There is no need to create a new commit. Just add the latest changes and merge them into the intended commit: + +``` +git add --all +git commit --amend +``` + +#### Modify multiple commits + +{{% warning "Be Careful Modifying Multiple Commits"%}} +Modifications such as those described in this section can have serious unintended consequences. Skip this section if you're not sure! +{{% /warning %}} + +This is a bit more advanced. Git allows you to [rebase](https://git-scm.com/docs/git-rebase) commits interactively. In other words: it allows you to rewrite the commit history. + +``` +git rebase --interactive @~6 +``` + +The `6` at the end of the command represents the number of commits that should be modified. An editor should open and present a list of last six commit messages: + +``` +pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick aaee038 tpl: Sort the smoke tests +pick f0dbf2c tpl: Add the other test case for hasPrefix +pick 911c35b Add "How to contribute to Hugo" tutorial +pick 33c8973 Begin workflow +pick 3502f2e Refactoring and typo fixes +``` + +In the case above we should merge the last to commits in the commit of this tutorial (`Add "How to contribute to Hugo" tutorial`). You can "squash" commits, i.e. merge two or more commits into a single one. + +All operations are written before the commit message. Replace "pick" with an operation. In this case `squash` or `s` for short: + +``` +pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick aaee038 tpl: Sort the smoke tests +pick f0dbf2c tpl: Add the other test case for hasPrefix +pick 911c35b Add "How to contribute to Hugo" tutorial +squash 33c8973 Begin workflow +squash 3502f2e Refactoring and typo fixes +``` + +We also want to rewrite the commits message of the third last commit. We forgot "docs:" as prefix according to the code contribution guidelines. The operation to rewrite a commit is called `reword` (or `r` as shortcut). + +You should end up with a similar setup: + +``` +pick 80d02a1 tpl: Add hasPrefix to the template funcs' "smoke test" +pick aaee038 tpl: Sort the smoke tests +pick f0dbf2c tpl: Add the other test case for hasPrefix +reword 911c35b Add "How to contribute to Hugo" tutorial +squash 33c8973 Begin workflow +squash 3502f2e Refactoring and typo fixes +``` + +Close the editor. It should open again with a new tab. A text is instructing you to define a new commit message for the last two commits that should be merged (aka "squashed"). Save the file with CTRL+S and close the editor again. + +A last time a new tab opens. Enter a new commit message and save again. Your terminal should contain a status message. Hopefully this one: + +``` +Successfully rebased and updated refs/heads/. +``` + +Check the commit log if everything looks as expected. Should an error occur you can abort this rebase with `git rebase --abort`. + +### Push commits + +To push our commits to the fork on GitHub we need to specify a destination. A destination is defined by the remote and a branch name. Earlier, the defined that the remote url of our fork is the same as our GitHub handle, in my case `digitalcraftsman`. The branch should have the same as our local one. This makes it easy to identify corresponding branches. + +``` +git push --set-upstream +``` + +Now Git knows the destination. Next time when you to push commits you just need to enter `git push`. + +If you modified your commit history in the last step GitHub will reject your try to push. This is a safety-feature because the commit history isn't the same and new commits can't be appended as usual. You can enforce this push explicitly with `git push --force`. + +## Open a pull request + +We made a lot of progress. Good work. In this step we finally open a pull request to submit our additions. Open the [Hugo master repository](https://github.com/gohugoio/hugo/) on GitHub in your browser. + +You should find a green button labeled with "New pull request". But GitHub is clever and probably suggests you a pull request like in the beige box below: + +![Open a pull request](/images/contribute/development/open-pull-request.png) + +The new page summaries the most important information of your pull request. Scroll down and you find the additions of all your commits. Make sure everything looks as expected and click on "Create pull request". + +### Accept the contributor license agreement + +Last but not least you should accept the contributor license agreement (CLA). A new comment should be added automatically to your pull request. Click on the yellow badge, accept the agreement and authenticate yourself with your GitHub account. It just takes a few clicks and only needs to be done once. + +![Accept the CLA](/images/contribute/development/accept-cla.png) + +### Automatic builds + +We use the [Travis CI loop](https://travis-ci.org/gohugoio/hugo) (Linux and OS X) and [AppVeyor](https://ci.appveyor.com/project/gohugoio/hugo/branch/master) (Windows) to compile Hugo with your additions. This should ensure that everything works as expected before merging your pull request. This in most cases only relevant if you made changes to the codebase of Hugo. + +![Automic builds and their status](/images/contribute/development/ci-errors.png) + +Above you can see that Travis wasn't able to compile the changes in this pull request. Click on "Details" and try to investigate why the build failed. But it doesn't have to be your fault. Mostly, the `master` branch that we used as foundation for your pull request should build without problems. + +If you have questions, leave a comment in the pull request. We are willing to assist you. + +## Where to start? + +Thank you for reading through this contribution guide. Hopefully, we will see you again soon on GitHub. There are plenty of [open issues][issues] for you to help with. + +Feel free to [open an issue][newissue] if you think you found a bug or you have a new idea to improve Hugo. We are happy to hear from you. + +## Additional References for Learning Git and Go + +* [Codecademy's Free "Learn Git" Course][codecademy] (Free) +* [Code School and GitHub's "Try Git" Tutorial][trygit] (Free) +* [The Git Book][gitbook] (Free) +* [Go Bootcamp][gobootcamp] +* [GitHub Pull Request Tutorial, Thinkful][thinkful] + + +[codecademy]: https://www.codecademy.com/learn/learn-git +[contributors]: https://github.com/gohugoio/hugo/graphs/contributors +[docscontrib]: /contribute/documentation/ +[forums]: https://discourse.gohugo.io +[gitbook]: https://git-scm.com/ +[gobootcamp]: http://www.golangbootcamp.com/book/get_setup +[godl]: https://golang.org/dl/ +[goinstall]: https://golang.org/doc/install +[gvm]: https://github.com/moovweb/gvm +[issues]: https://github.com/gohugoio/hugo/issues +[newissue]: https://github.com/gohugoio/hugo/issues/new +[releases]: /getting-started/ +[setupgopath]: https://golang.org/doc/code.html#Workspaces +[thinkful]: https://www.thinkful.com/learn/github-pull-request-tutorial/ +[trygit]: https://try.github.io/levels/1/challenges/1 diff --cc docs/content/en/contribute/documentation.md index e8603d43,00000000..7b198a4c mode 100644,000000..100644 --- a/docs/content/en/contribute/documentation.md +++ b/docs/content/en/contribute/documentation.md @@@ -1,336 -1,0 +1,333 @@@ +--- +title: Contribute to the Hugo Docs +linktitle: Documentation +description: Documentation is an integral part of any open source project. The Hugo docs are as much a work in progress as the source it attempts to cover. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [contribute] +keywords: [docs,documentation,community, contribute] +menu: + docs: + parent: "contribute" + weight: 20 +weight: 20 +sections_weight: 20 +draft: false +aliases: [/contribute/docs/] +toc: true +--- + +## Create Your Fork + +It's best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you've created a fork of [hugoDocs](https://github.com/gohugoio/hugoDocs) on GitHub and cloned the repository locally on your machine. For more information, you can see [GitHub's documentation on "forking"][ghforking] or follow along with [Hugo's development contribution guide][hugodev]. + +You can then create a separate branch for your additions. Be sure to choose a descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase: + +``` +git checkout -b jon-doe-showcase-addition +``` + +## Add New Content + +The Hugo docs make heavy use of Hugo's [archetypes][] feature. All content sections in Hugo documentation have an assigned archetype. + +Adding new content to the Hugo docs follows the same pattern, regardless of the content section: + +``` +hugo new /.md +``` + +### Add a New Function + +Once you have cloned the Hugo repository, you can create a new function via the following command. Keep the file name lowercase. + +``` +hugo new functions/newfunction.md +``` + +The archetype for `functions` according to the Hugo docs is as follows: + +{{< code file="archetypes/functions.md" >}} +{{< readfile file="/archetypes/functions.md">}} +{{< /code >}} + +#### New Function Required Fields + +Here is a review of the front matter fields automatically generated for you using `hugo new functions/*`: + +***`title`*** +: this will be auto-populated in all lowercase when you use `hugo new` generator. + +***`linktitle`*** +: the function's actual casing (e.g., `replaceRE` rather than `replacere`). + +***`description`*** +: a brief description used to populate the [Functions Quick Reference](/functions/). + +`categories` +: currently auto-populated with 'functions` for future-proofing and portability reasons only; ignore this field. + +`tags` +: only if you think it will help end users find other related functions + +`signature` +: this is a signature/syntax definition for calling the function (e.g., `apply SEQUENCE FUNCTION [PARAM...]`). + +`workson` +: acceptable values include `lists`,`taxonomies`, `terms`, `groups`, and `files`. + +`hugoversion` +: the version of Hugo that will ship with this new function. + +`relatedfuncs` +: other [templating functions][] you feel are related to your new function to help fellow Hugo users. + +`{{.Content}}` +: an extended description of the new function; examples are not only welcomed but encouraged. + +In the body of your function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs [`code` shortcode](#adding-code-blocks). If you are unable to add examples but would like to solicit help from the Hugo community, add `needsexample: true` to your front matter. + +## Add Code Blocks + +Code blocks are crucial for providing examples of Hugo's new features to end users of the Hugo docs. Whenever possible, create examples that you think Hugo users will be able to implement in their own projects. + +### Standard Syntax + - Across all pages on the Hugo docs, the typical triple-back-tick markdown syntax is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard GitHub-flavored markdown. The Hugo docs use a version of [highlight.js](https://highlightjs.org/) with a specific set of languages. ++Across many pages on the Hugo docs, the typical triple-back-tick markdown syntax (```` ``` ````) is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard GitHub-flavored markdown. The Hugo docs use a version of [highlight.js](https://highlightjs.org/) with a specific set of languages. + +Your options for languages are `xml`/`html`, `go`/`golang`, `md`/`markdown`/`mkd`, `handlebars`, `apache`, `toml`, `yaml`, `json`, `css`, `asciidoc`, `ruby`, `powershell`/`ps`, `scss`, `sh`/`zsh`/`bash`/`git`, `http`/`https`, and `javascript`/`js`. + - ``` ++```` +``` +

Hello world!

+``` - ``` ++```` + +### Code Block Shortcode + +The Hugo documentation comes with a very robust shortcode for adding interactive code blocks. + +{{% note %}} +With the `code` shortcodes, *you must include triple back ticks and a language declaration*. This was done by design so that the shortcode wrappers were easily added to legacy documentation and will be that much easier to remove if needed in future versions of the Hugo docs. +{{% /note %}} + +### `code` + +`code` is the Hugo docs shortcode you'll use most often. `code` requires has only one named parameter: `file`. Here is the pattern: + +``` +{{%/* code file="smart/file/name/with/path.html" download="download.html" copy="true" */%}} - ``` +A whole bunch of coding going on up in here! - ``` +{{%/* /code */%}} +``` + +The following are the arguments passed into `code`: + ++ +***`file`*** +: the only *required* argument. `file` is needed for styling but also plays an important role in helping users create a mental model around Hugo's directory structure. Visually, this will be displayed as text in the top left of the code block. + +`download` +: if omitted, this will have no effect on the rendered shortcode. When a value is added to `download`, it's used as the filename for a downloadable version of the code block. + +`copy` +: a copy button is added automatically to all `code` shortcodes. If you want to keep the filename and styling of `code` but don't want to encourage readers to copy the code (e.g., a "Do not do" snippet in a tutorial), use `copy="false"`. + +#### Example `code` Input + +This example HTML code block tells Hugo users the following: + +1. This file *could* live in `layouts/_default`, as demonstrated by `layouts/_default/single.html` as the value for `file`. +2. This snippet is complete enough to be downloaded and implemented in a Hugo project, as demonstrated by `download="single.html"`. + +``` +{{}} +{{ define "main" }} +
+
+
+

{{.Title}}

+ {{with .Params.subtitle}} + {{.}} +
+
+ {{.Content}} +
+ +
+
+{{ end }} +{{}} +``` + +##### Example 'code' Display + +The output of this example will render to the Hugo docs as follows: + +{{< code file="layouts/_default/single.html" download="single.html" >}} +{{ define "main" }} +
+
+
+

{{.Title}}

+ {{with .Params.subtitle}} + {{.}} +
+
+ {{.Content}} +
+ +
+
+{{ end }} +{{< /code >}} + + + +## Blockquotes + +Blockquotes can be added to the Hugo documentation using [typical Markdown blockquote syntax][bqsyntax]: + +``` +> Without the threat of punishment, there is no joy in flight. +``` + +The preceding blockquote will render as follows in the Hugo docs: + +> Without the threat of punishment, there is no joy in flight. + +However, you can add a quick and easy `` element (added on the client via JavaScript) by separating your main blockquote and the citation with a hyphen with a single space on each side: + +``` +> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe) +``` + +Which will render as follows in the Hugo docs: + +> Without the threat of punishment, there is no joy in flight. - [Kobo Abe][abe] + +{{% note "Blockquotes `!=` Admonitions" %}} +Previous versions of Hugo documentation used blockquotes to draw attention to text. This is *not* the [intended semantic use of `
`](http://html5doctor.com/cite-and-blockquote-reloaded/). Use blockquotes when quoting. To note or warn your user of specific information, use the admonition shortcodes that follow. +{{% /note %}} + +## Admonitions + +**Admonitions** are common in technical documentation. The most popular is that seen in [reStructuredText Directives][sourceforge]. From the SourceForge documentation: + +> Admonitions are specially marked "topics" that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - [SourceForge][sourceforge] + +The Hugo docs contain three admonitions: `note`, `tip`, and `warning`. + +### `note` Admonition + +Use the `note` shortcode when you want to draw attention to information subtly. `note` is intended to be less of an interruption in content than is `warning`. + +#### Example `note` Input + +{{< code file="note-with-heading.md" >}} +{{%/* note */%}} +Here is a piece of information I would like to draw your **attention** to. +{{%/* /note */%}} +{{< /code >}} + +#### Example `note` Output + +{{< output file="note-with-heading.html" >}} +{{% note %}} +Here is a piece of information I would like to draw your **attention** to. +{{% /note %}} +{{< /output >}} + +#### Example `note` Display + +{{% note %}} +Here is a piece of information I would like to draw your **attention** to. +{{% /note %}} + +### `tip` Admonition + +Use the `tip` shortcode when you want to give the reader advice. `tip`, like `note`, is intended to be less of an interruption in content than is `warning`. + +#### Example `tip` Input + +{{< code file="using-tip.md" >}} +{{%/* tip */%}} +Here's a bit of advice to improve your productivity with Hugo. +{{%/* /tip */%}} +{{< /code >}} + +#### Example `tip` Output + +{{< output file="tip-output.html" >}} +{{% tip %}} +Here's a bit of advice to improve your productivity with Hugo. +{{% /tip %}} +{{< /output >}} + +#### Example `tip` Display + +{{% tip %}} +Here's a bit of advice to improve your productivity with Hugo. +{{% /tip %}} + +### `warning` Admonition + +Use the `warning` shortcode when you want to draw the user's attention to something important. A good usage example is for articulating breaking changes in Hugo versions, known bugs, or templating "gotchas." + +#### Example `warning` Input + +{{< code file="warning-admonition-input.md" >}} +{{%/* warning */%}} +This is a warning, which should be reserved for *important* information like breaking changes. +{{%/* /warning */%}} +{{< /code >}} + +#### Example `warning` Output + +{{< output file="warning-admonition-output.html" >}} +{{% warning %}} +This is a warning, which should be reserved for *important* information like breaking changes. +{{% /warning %}} +{{< /output >}} + +#### Example `warning` Display + +{{% warning %}} +This is a warning, which should be reserved for *important* information like breaking changes. +{{% /warning %}} + +{{% note "Pull Requests and Branches" %}} +Similar to [contributing to Hugo development](/contribute/development/), the Hugo team expects you to create a separate branch/fork when you make your contributions to the Hugo docs. +{{% /note %}} + +[abe]: https://en.wikipedia.org/wiki/Kobo_Abe +[archetypes]: /content-management/archetypes/ +[bqsyntax]: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#blockquotes +[charcount]: http://www.lettercount.com/ +[`docs/static/images/showcase/`]: https://github.com/gohugoio/hugo/tree/master/docs/static/images/showcase/ +[ghforking]: https://help.github.com/articles/fork-a-repo/ +[hugodev]: /contribute/development/ +[shortcodeparams]: content-management/shortcodes/#shortcodes-without-markdown +[sourceforge]: http://docutils.sourceforge.net/docs/ref/rst/directives.html#admonitions +[templating function]: /functions/ diff --cc docs/content/en/functions/GetPage.md index 2d9de4d7,00000000..366d1f09 mode 100644,000000..100644 --- a/docs/content/en/functions/GetPage.md +++ b/docs/content/en/functions/GetPage.md @@@ -1,89 -1,0 +1,89 @@@ +--- +title: .GetPage +description: "Gets a `Page` of a given `path`." +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [sections,lists,indexes] +signature: [".GetPage PATH"] +workson: [] +hugoversion: +relatedfuncs: [] +deprecated: false +aliases: [] +--- + +`.GetPage` returns a page of a given `path`. Both `Site` and `Page` implements this method. The `Page` variant will, if given a relative path -- i.e. a path without a leading `/` -- try look for the page relative to the current page. + +{{% note %}} +**Note:** We overhauled and simplified the `.GetPage` API in Hugo 0.45. Before that you needed to provide a `Kind` attribute in addition to the path, e.g. `{{ .Site.GetPage "section" "blog" }}`. This will still work, but is now superflous. +{{% /note %}} + + +```go-html-template +{{ with .Site.GetPage "/blog" }}{{ .Title }}{{ end }} +``` + +This method wil return `nil` when no page could be found, so the above will not print anything if the blog section is not found. + - To fund a regular page in the blog section:: ++To find a regular page in the blog section:: + +```go-html-template +{{ with .Site.GetPage "/blog/my-post.md" }}{{ .Title }}{{ end }} +``` + +And since `Page` also provides a `.GetPage` method, the above is the same as: + +```go-html-template +{{ with .Site.GetPage "/blog" }} +{{ with .GetPage "my-post.md" }}{{ .Title }}{{ end }} +{{ end }} +``` + +## .GetPage and Multilingual Sites + +The previous examples have used the full content filename to lookup the post. Depending on how you have organized your content (whether you have the language code in the file name or not, e.g. `my-post.en.md`), you may want to do the lookup without extension. This will get you the current language's version of the page: + +```go-html-template +{{ with .Site.GetPage "/blog/my-post" }}{{ .Title }}{{ end }} +``` + +## .GetPage Example + +This code snippet---in the form of a [partial template][partials]---allows you to do the following: + +1. Grab the index object of your `tags` [taxonomy][]. +2. Assign this object to a variable, `$t` +3. Sort the terms associated with the taxonomy by popularity. +4. Grab the top two most popular terms in the taxonomy (i.e., the two most popular tags assigned to content. + +{{< code file="grab-top-two-tags.html" >}} +
    +{{ $t := .Site.GetPage "/tags" }} +{{ range first 2 $t.Data.Terms.ByCount }} +
  • {{ . }}
    • +{{ end }} +
+{{< /code >}} + +## `.GetPage` on Page Bundles + +If the page retrieved by `.GetPage` is a [Leaf Bundle][leaf_bundle], and you +need to get the nested _**page** resources_ in that, you will need to use the +methods in `.Resources` as explained in the [Page Resources][page_resources] +section. + +See the [Headless Bundle][headless_bundle] documentation for an example. + + +[partials]: /templates/partials/ +[taxonomy]: /content-management/taxonomies/ +[page_kinds]: /templates/section-templates/#page-kinds +[leaf_bundle]: /content-management/page-bundles/#leaf-bundles +[headless_bundle]: /content-management/page-bundles/#headless-bundle +[page_resources]: /content-management/page-resources/ diff --cc docs/content/en/functions/default.md index 1b5a9fb6,00000000..18f7b7d3 mode 100644,000000..100644 --- a/docs/content/en/functions/default.md +++ b/docs/content/en/functions/default.md @@@ -1,93 -1,0 +1,93 @@@ +--- +title: default +description: Allows setting a default value that can be returned if a first value is not set. +qref: "Returns a default value if a value is not set when checked." +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +keywords: [defaults] +categories: [functions] +menu: + docs: + parent: "functions" +toc: +signature: ["default DEFAULT INPUT"] +workson: [] +hugoversion: +relatedfuncs: [] +deprecated: false +draft: false +aliases: [] +needsexamples: false +--- + - `default` checks whether a given value is set and returns a default value if it is not. *Set* in this context means different things depending on date type: ++`default` checks whether a given value is set and returns a default value if it is not. *Set* in this context means different things depending on the data type: + +* non-zero for numeric types and times +* non-zero length for strings, arrays, slices, and maps +* any boolean or struct value +* non-nil for any other types + +`default` function examples reference the following content page: + +{{< code file="content/posts/default-function-example.md" >}} +--- +title: Sane Defaults +seo_title: +date: 2017-02-18 +font: +oldparam: The default function helps make your templating DRYer. +newparam: +--- +{{< /code >}} + +`default` can be written in more than one way: + +``` +{{ index .Params "font" | default "Roboto" }} +{{ default "Roboto" (index .Params "font") }} +``` + +Both of the above `default` function calls return `Roboto`. + +A `default` value, however, does not need to be hard coded like the previous example. The `default` value can be a variable or pulled directly from the front matter using dot notation: + +{{< code file="variable-as-default-value.html" nocopy="true" >}} +{{$old := .Params.oldparam }} +

{{ .Params.newparam | default $old }}

+{{< /code >}} + +Which would return: + +``` +

The default function helps make your templating DRYer.

+``` + +And then using dot notation + +{{< code file="dot-notation-default-value.html" >}} +{{ .Params.seo_title | default .Title }} +{{< /code >}} + +Which would return + +{{< output file="dot-notation-default-return-value.html" >}} +Sane Defaults +{{< /output >}} + +The following have equivalent return values but are far less terse. This demonstrates the utility of `default`: + +Using `if`: + +{{< code file="if-instead-of-default.html" nocopy="true" >}} +{{if .Params.seo_title}}{{.Params.seo_title}}{{else}}{{.Title}}{{end}} +=> Sane Defaults +{{< /code >}} + +Using `with`: + +{{< code file="with-instead-of-default.html" nocopy="true" >}} +{{with .Params.seo_title}}{{.}}{{else}}{{.Title}}{{end}} +=> Sane Defaults +{{< /code >}} diff --cc docs/content/en/functions/intersect.md index a607ff21,00000000..6d2efacb mode 100644,000000..100644 --- a/docs/content/en/functions/intersect.md +++ b/docs/content/en/functions/intersect.md @@@ -1,56 -1,0 +1,36 @@@ +--- +title: intersect +linktitle: intersect +description: Returns the common elements of two arrays or slices. +godocref: +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [functions] +menu: + docs: + parent: "functions" +keywords: [] +signature: ["intersect SET1 SET2"] +workson: [] +hugoversion: +relatedfuncs: [] +deprecated: false +aliases: [] +--- + - The elements supported are strings, integers, and floats (only float64). - - A useful example of `intersect` functionality is a "related posts" block. `isset` allows us to create a list of links to other posts that have tags that intersect with the tags in the current post. - - The following is an example of a "related posts" [partial template][partials] that could be added to a [single page template][single]: - - {{< code file="layouts/partials/related-posts.html" download="related-posts.html" >}} -
    - {{ $page_link := .Permalink }} - {{ $tags := .Params.tags }} - {{ range .Site.Pages }} - {{ $page := . }} - {{ $has_common_tags := intersect $tags .Params.tags | len | lt 0 }} - {{ if and $has_common_tags (ne $page_link $page.Permalink) }} -
  • {{ $page.Title }}
    • - {{ end }} - {{ end }} -
- {{< /code >}} - - This is also very useful to use as `AND` filters when combined with where: ++An useful example is to use it as `AND` filters when combined with where: + +``` +{{ $pages := where .Site.RegularPages "Type" "not in" (slice "page" "about") }} +{{ $pages := $pages | union (where .Site.RegularPages "Params.pinned" true) }} +{{ $pages := $pages | intersect (where .Site.RegularPages "Params.images" "!=" nil) }} +``` + +The above fetches regular pages not of `page` or `about` type unless they are pinned. And finally, we exclude all pages with no `images` set in Page params. + +See [union](/functions/union) for `OR`. + + +[partials]: /templates/partials/ +[single]: /templates/single-page-templates/ diff --cc docs/content/en/functions/os.Stat.md index 00000000,00000000..1e878d89 new file mode 100644 --- /dev/null +++ b/docs/content/en/functions/os.Stat.md @@@ -1,0 -1,0 +1,33 @@@ ++--- ++title: os.Stat ++description: Gets a file information of a given path. ++godocref: ++date: 2018-08-07 ++publishdate: 2018-08-07 ++lastmod: 2018-08-07 ++categories: [functions] ++menu: ++ docs: ++ parent: "functions" ++keywords: [files] ++signature: ["os.Stat PATH"] ++workson: [] ++hugoversion: ++relatedfuncs: [readDir] ++deprecated: false ++aliases: [] ++--- ++ ++If your current project working directory has a single file named `README.txt` (30 bytes): ++``` ++{{ $stat := os.Stat "README.txt" }} ++{{ $stat.Name }} → "README.txt" ++{{ $stat.Size }} → 30 ++``` ++ ++Function [`os.Stat`][Stat] returns [`os.FileInfo`][osfileinfo]. ++For further information of `os.FileInfo`, see [golang page][osfileinfo]. ++ ++ ++[Stat]: /functions/os.Stat/ ++[osfileinfo]: https://golang.org/pkg/os/#FileInfo diff --cc docs/content/en/getting-started/installing.md index deb2605b,00000000..ccf96317 mode 100644,000000..100644 --- a/docs/content/en/getting-started/installing.md +++ b/docs/content/en/getting-started/installing.md @@@ -1,514 -1,0 +1,522 @@@ +--- +title: Install Hugo +linktitle: Install Hugo +description: Install Hugo on macOS, Windows, Linux, OpenBSD, FreeBSD, and on any machine where the Go compiler tool chain can run. +date: 2016-11-01 +publishdate: 2016-11-01 +lastmod: 2018-01-02 +categories: [getting started,fundamentals] +authors: ["Michael Henderson"] +keywords: [install,pc,windows,linux,macos,binary,tarball] +menu: + docs: + parent: "getting-started" + weight: 30 +weight: 30 +sections_weight: 30 +draft: false +aliases: [/tutorials/installing-on-windows/,/tutorials/installing-on-mac/,/overview/installing/,/getting-started/install,/install/] +toc: true +--- + + +{{% note %}} +There is lots of talk about "Hugo being written in Go", but you don't need to install Go to enjoy Hugo. Just grab a precompiled binary! +{{% /note %}} + +Hugo is written in [Go](https://golang.org/) with support for multiple platforms. The latest release can be found at [Hugo Releases][releases]. + +Hugo currently provides pre-built binaries for the following: + +* macOS (Darwin) for x64, i386, and ARM architectures +* Windows +* Linux +* OpenBSD +* FreeBSD + +Hugo may also be compiled from source wherever the Go toolchain can run; e.g., on other operating systems such as DragonFly BSD, OpenBSD, Plan 9, Solaris, and others. See for the full set of supported combinations of target operating systems and compilation architectures. + +## Quick Install + +### Binary (Cross-platform) + +Download the appropriate version for your platform from [Hugo Releases][releases]. Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account. + +Ideally, you should install it somewhere in your `PATH` for easy use. `/usr/local/bin` is the most probable location. + +### Homebrew (macOS) + +If you are on macOS and using [Homebrew][brew], you can install Hugo with the following one-liner: + +{{< code file="install-with-homebrew.sh" >}} +brew install hugo +{{< /code >}} + +For more detailed explanations, read the installation guides that follow for installing on macOS and Windows. + +### Chocolatey (Windows) + +If you are on a Windows machine and use [Chocolatey][] for package management, you can install Hugo with the following one-liner: + +{{< code file="install-with-chocolatey.ps1" >}} +choco install hugo -confirm +{{< /code >}} + +### Scoop (Windows) + +If you are on a Windows machine and use [Scoop][] for package management, you can install Hugo with the following one-liner: + +```bash +scoop install hugo +``` + +### Source + +#### Prerequisite Tools + +* [Git][installgit] +* [Go (latest or previous version)][installgo] + +#### Vendored Dependencies + +Hugo uses [dep][] to vendor dependencies, but we don't commit the vendored packages themselves to the Hugo git repository. Therefore, a simple `go get` is *not* supported because the command is not vendor aware. + +The simplest way is to use [mage][] (a Make alternative for Go projects.) + +#### Fetch from GitHub + +{{< code file="from-gh.sh" >}} +go get github.com/magefile/mage +go get -d github.com/gohugoio/hugo +cd ${GOPATH:-$HOME/go}/src/github.com/gohugoio/hugo +mage vendor +HUGO_BUILD_TAGS=extended mage install +{{< /code >}} + +Remove `HUGO_BUILD_TAGS=extended` if you do not want Sass/SCSS support. + +{{% note %}} +If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`. +{{% /note %}} + +## macOS + +### Assumptions + +1. You know how to open the macOS terminal. +2. You're running a modern 64-bit Mac. +3. You will use `~/Sites` as the starting point for your site. (`~/Sites` is used for example purposes. If you are familiar enough with the command line and file system, you should have no issues following along with the instructions.) + +### Pick Your Method + +There are three ways to install Hugo on your Mac + +1. The [Homebrew][brew] `brew` utility +2. Distribution (i.e., tarball) +3. Building from Source + +There is no "best" way to install Hugo on your Mac. You should use the method that works best for your use case. + +#### Pros and Cons + +There are pros and cons to each of the aforementioned methods: + +1. **Homebrew.** Homebrew is the simplest method and will require the least amount of work to maintain. The drawbacks aren't severe. The default package will be for the most recent release, so it will not have bug fixes until the next release (i.e., unless you install it with the `--HEAD` option). Hugo `brew` releases may lag a few days behind because it has to be coordinated with another team. Nevertheless, `brew` is the recommended installation method if you want to work from a stable, widely used source. Brew works well and is easy to update. + +2. **Tarball.** Downloading and installing from the tarball is also easy, although it requires a few more command line skills than does Homebrew. Updates are easy as well: you just repeat the process with the new binary. This gives you the flexibility to have multiple versions on your computer. If you don't want to use `brew`, then the tarball/binary is a good choice. + +3. **Building from Source.** Building from source is the most work. The advantage of building from source is that you don't have to wait for a release to add features or bug fixes. The disadvantage is that you need to spend more time managing the setup, which is manageable but requires more time than the preceding two options. + +{{% note %}} +Since building from source is appealing to more seasoned command line users, this guide will focus more on installing Hugo via Homebrew and Tarball. +{{% /note %}} + +### Install Hugo with Brew + +{{< youtube WvhCGlLcrF8 >}} + +#### Step 1: Install `brew` if you haven't already + +Go to the `brew` website, , and follow the directions there. The most important step is the installation from the command line: + +{{< code file="install-brew.sh" >}} +ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" +{{< /code >}} + +#### Step 2: Run the `brew` Command to Install `hugo` + +Installing Hugo using `brew` is as easy as the following: + +{{< code file="install-brew.sh" >}} +brew install hugo +{{< /code >}} + +If Homebrew is working properly, you should see something similar to the following: + +``` +==> Downloading https://homebrew.bintray.com/bottles/hugo-0.21.sierra.bottle.tar.gz +######################################################################### 100.0% +==> Pouring hugo-0.21.sierra.bottle.tar.gz +🍺 /usr/local/Cellar/hugo/0.21: 32 files, 17.4MB +``` + +{{% note "Installing the Latest Hugo with Brew" %}} +Replace `brew install hugo` with `brew install hugo --HEAD` if you want the absolute latest in-development version. +{{% /note %}} + +`brew` should have updated your path to include Hugo. You can confirm by opening a new terminal window and running a few commands: + +``` +$ # show the location of the hugo executable +which hugo +/usr/local/bin/hugo + +# show the installed version +ls -l $( which hugo ) +lrwxr-xr-x 1 mdhender admin 30 Mar 28 22:19 /usr/local/bin/hugo -> ../Cellar/hugo/0.13_1/bin/hugo + +# verify that hugo runs correctly +hugo version +Hugo Static Site Generator v0.13 BuildDate: 2015-03-09T21:34:47-05:00 +``` + +### Install Hugo from Tarball + +#### Step 1: Decide on the location + +When installing from the tarball, you have to decide if you're going to install the binary in `/usr/local/bin` or in your home directory. There are three camps on this: + +1. Install it in `/usr/local/bin` so that all the users on your system have access to it. This is a good idea because it's a fairly standard place for executables. The downside is that you may need elevated privileges to put software into that location. Also, if there are multiple users on your system, they will all run the same version. Sometimes this can be an issue if you want to try out a new release. + +2. Install it in `~/bin` so that only you can execute it. This is a good idea because it's easy to do, easy to maintain, and doesn't require elevated privileges. The downside is that only you can run Hugo. If there are other users on your site, they have to maintain their own copies. That can lead to people running different versions. Of course, this does make it easier for you to experiment with different releases. + +3. Install it in your `Sites` directory. This is not a bad idea if you have only one site that you're building. It keeps every thing in a single place. If you want to try out new releases, you can make a copy of the entire site and update the Hugo executable. + +All three locations will work for you. In the interest of brevity, this guide focuses on option #2. + +#### Step 2: Download the Tarball + +1. Open in your browser. + +2. Find the current release by scrolling down and looking for the green tag that reads "Latest Release." + +3. Download the current tarball for the Mac. The name will be something like `hugo_X.Y_osx-64bit.tgz`, where `X.YY` is the release number. + +4. By default, the tarball will be saved to your `~/Downloads` directory. If you choose to use a different location, you'll need to change that in the following steps. + +#### Step 3: Confirm your download + +Verify that the tarball wasn't corrupted during the download: + +``` +tar tvf ~/Downloads/hugo_X.Y_osx-64bit.tgz +-rwxrwxrwx 0 0 0 0 Feb 22 04:02 hugo_X.Y_osx-64bit/hugo_X.Y_osx-64bit.tgz +-rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_X.Y_osx-64bit/README.md +-rwxrwxrwx 0 0 0 0 Jan 30 18:48 hugo_X.Y_osx-64bit/LICENSE.md +``` + +The `.md` files are documentation for Hugo. The other file is the executable. + +#### Step 4: Install Into Your `bin` Directory + +``` +# create the directory if needed +mkdir -p ~/bin + +# make it the working directory +cd ~/bin + +# extract the tarball +tar -xvzf ~/Downloads/hugo_X.Y_osx-64bit.tgz +Archive: hugo_X.Y_osx-64bit.tgz + x ./ + x ./hugo + x ./LICENSE.md + x ./README.md + +# verify that it runs +./hugo version +Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30-06:00 +``` + +You may need to add your bin directory to your `PATH` variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything. + +``` +# check if hugo is in the path +which hugo +/Users/USERNAME/bin/hugo +``` + +If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor: + +``` +nano ~/.bash_profile +``` + +Add a line to update your `PATH` variable: + +``` +export PATH=$PATH:$HOME/bin +``` + +Then save the file by pressing Control-X, then Y to save the file and return to the prompt. + +Close the terminal and open a new terminal to pick up the changes to your profile. Verify your success by running the `which hugo` command again. + +You've successfully installed Hugo. + +### Build from Source on Mac + +If you want to compile Hugo yourself, you'll need to install Go (aka Golang). You can [install Go directly from the Go website](https://golang.org/dl/) or via Homebrew using the following command: + +``` +brew install go +``` + +#### Step 1: Get the Source + +If you want to compile a specific version of Hugo, go to and download the source code for the version of your choice. If you want to compile Hugo with all the latest changes (which might include bugs), clone the Hugo repository: + +``` +git clone https://github.com/gohugoio/hugo +``` + +{{% warning "Sometimes \"Latest\" = \"Bugs\""%}} +Cloning the Hugo repository directly means taking the good with the bad. By using the bleeding-edge version of Hugo, you make your development susceptible to the latest features, as well as the latest bugs. Your feedback is appreciated. If you find a bug in the latest release, [please create an issue on GitHub](https://github.com/gohugoio/hugo/issues/new). +{{% /warning %}} + +#### Step 2: Compiling + +Make the directory containing the source your working directory and then fetch Hugo's dependencies: + +``` +mkdir -p src/github.com/gohugoio +ln -sf $(pwd) src/github.com/gohugoio/hugo + +# set the build path for Go +export GOPATH=$(pwd) + +go get +``` + +This will fetch the absolute latest version of the dependencies. If Hugo fails to build, it may be the result of a dependency's author introducing a breaking change. + +Once you have properly configured your directory, you can compile Hugo using the following command: + +``` +go build -o hugo main.go +``` + +Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo. + +## Windows + +The following aims to be a complete guide to installing Hugo on your Windows PC. + +{{< youtube G7umPCU-8xc >}} + +### Assumptions + +1. You will use `C:\Hugo\Sites` as the starting point for your new project. +2. You will use `C:\Hugo\bin` to store executable files. + +### Set up Your Directories + +You'll need a place to store the Hugo executable, your [content][], and the generated Hugo website: + +1. Open Windows Explorer. +2. Create a new folder: `C:\Hugo`, assuming you want Hugo on your C drive, although this can go anywhere +3. Create a subfolder in the Hugo folder: `C:\Hugo\bin` +4. Create another subfolder in Hugo: `C:\Hugo\Sites` + +### Technical Users + +1. Download the latest zipped Hugo executable from [Hugo Releases][releases]. +2. Extract all contents to your `..\Hugo\bin` folder. +3. The `hugo` executable will be named as `hugo_hugo-version_platform_arch.exe`. Rename the executable to `hugo.exe` for ease of use. +4. In PowerShell or your preferred CLI, add the `hugo.exe` executable to your PATH by navigating to `C:\Hugo\bin` (or the location of your hugo.exe file) and use the command `set PATH=%PATH%;C:\Hugo\bin`. If the `hugo` command does not work after a reboot, you may have to run the command prompt as administrator. + +### Less-technical Users + +1. Go to the [Hugo Releases][releases] page. +2. The latest release is announced on top. Scroll to the bottom of the release announcement to see the downloads. They're all ZIP files. +3. Find the Windows files near the bottom (they're in alphabetical order, so Windows is last) – download either the 32-bit or 64-bit file depending on whether you have 32-bit or 64-bit Windows. (If you don't know, [see here](https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx).) +4. Move the ZIP file into your `C:\Hugo\bin` folder. +5. Double-click on the ZIP file and extract its contents. Be sure to extract the contents into the same `C:\Hugo\bin` folder – Windows will do this by default unless you tell it to extract somewhere else. - 6. You should now have three new files: hugo executable (e.g. `hugo_0.18_windows_amd64.exe`), `license.md`, and `readme.md`. (You can delete the ZIP download now.) Rename that hugo executable (`hugo_hugo-version_platform_arch.exe`) to `hugo.exe` for ease of use. ++6. You should now have three new files: The hugo executable (`hugo.exe`), `LICENSE`, and `README.md`. + +Now you need to add Hugo to your Windows PATH settings: + +#### For Windows 10 Users: + +* Right click on the **Start** button. +* Click on **System**. +* Click on **Advanced System Settings** on the left. +* Click on the **Environment Variables...** button on the bottom. +* In the User variables section, find the row that starts with PATH (PATH will be all caps). +* Double-click on **PATH**. +* Click the **New...** button. +* Type in the folder where `hugo.exe` was extracted, which is `C:\Hugo\bin` if you went by the instructions above. *The PATH entry should be the folder where Hugo lives and not the binary.* Press Enter when you're done typing. +* Click OK at every window to exit. + +{{% note "Path Editor in Windows 10"%}} +The path editor in Windows 10 was added in the large [November 2015 Update](https://blogs.windows.com/windowsexperience/2015/11/12/first-major-update-for-windows-10-available-today/). You'll need to have that or a later update installed for the above steps to work. You can see what Windows 10 build you have by clicking on the  Start button → Settings → System → About. See [here](https://www.howtogeek.com/236195/how-to-find-out-which-build-and-version-of-windows-10-you-have/) for more.) +{{% /note %}} + +#### For Windows 7 and 8.x users: + +Windows 7 and 8.1 do not include the easy path editor included in Windows 10, so non-technical users on those platforms are advised to install a free third-party path editor like [Windows Environment Variables Editor][Windows Environment Variables Editor] or [Path Editor](https://patheditor2.codeplex.com/). + +### Verify the Executable + +Run a few commands to verify that the executable is ready to run, and then build a sample site to get started. + +#### 1. Open a Command Prompt + +At the prompt, type `hugo help` and press the Enter key. You should see output that starts with: + +``` +hugo is the main command, used to build your Hugo site. + +Hugo is a Fast and Flexible Static Site Generator +built with love by spf13 and friends in Go. + +Complete documentation is available at https://gohugo.io/. +``` + +If you do, then the installation is complete. If you don't, double-check the path that you placed the `hugo.exe` file in and that you typed that path correctly when you added it to your `PATH` variable. If you're still not getting the output, search the [Hugo discussion forum][forum] to see if others have already figured out our problem. If not, add a note---in the "Support" category---and be sure to include your command and the output. + +At the prompt, change your directory to the `Sites` directory. + +``` +C:\Program Files> cd C:\Hugo\Sites +C:\Hugo\Sites> +``` + +#### 2. Run the Command + +Run the command to generate a new site. I'm using `example.com` as the name of the site. + +``` +C:\Hugo\Sites> hugo new site example.com +``` + +You should now have a directory at `C:\Hugo\Sites\example.com`. Change into that directory and list the contents. You should get output similar to the following: + +``` +C:\Hugo\Sites> cd example.com +C:\Hugo\Sites\example.com> dir +Directory of C:\hugo\sites\example.com + +04/13/2015 10:44 PM . +04/13/2015 10:44 PM .. +04/13/2015 10:44 PM archetypes +04/13/2015 10:44 PM 83 config.toml +04/13/2015 10:44 PM content +04/13/2015 10:44 PM data +04/13/2015 10:44 PM layouts +04/13/2015 10:44 PM static + 1 File(s) 83 bytes + 7 Dir(s) 6,273,331,200 bytes free +``` + +### Troubleshoot Windows Installation + +[@dhersam][] has created a nice video on common issues: + +{{< youtube c8fJIRNChmU >}} + +## Linux + +### Snap Package + +In any of the [Linux distributions that support snaps][snaps], you may install install the "extended" Sass/SCSS version with this command: + + snap install hugo --channel=extended + +To install the non-extended version without Sass/SCSS support: + + snap install hugo + +To switch between the two, use either `snap refresh hugo --channel=extended` or `snap refresh hugo --channel=stable`. + +{{% note %}} +Hugo-as-a-snap can write only inside the user’s `$HOME` directory---and gvfs-mounted directories owned by the user---because of Snaps’ confinement and security model. More information is also available [in this related GitHub issue](https://github.com/gohugoio/hugo/issues/3143). Use ```sudo snap install hugo --classic``` to disable the default security model if you want hugo to be able to have write access in other paths besides the user’s `$HOME` directory. +{{% /note %}} + +### Debian and Ubuntu + +[@anthonyfok](https://github.com/anthonyfok) and friends in the [Debian Go Packaging Team](https://go-team.pages.debian.net/) maintains an official hugo [Debian package](https://packages.debian.org/hugo) which is shared with [Ubuntu](https://packages.ubuntu.com/hugo) and is installable via `apt-get`: + + sudo apt-get install hugo + +This installs the "extended" Sass/SCSS version. + +### Arch Linux + +You can also install Hugo from the Arch Linux [community](https://www.archlinux.org/packages/community/x86_64/hugo/) repository. Applies also to derivatives such as Manjaro. + +``` +sudo pacman -Syu hugo +``` + +### Fedora, Red Hat and CentOS + +Fedora maintains an [official package for Hugo](https://apps.fedoraproject.org/packages/hugo) which may be installed with: + + sudo dnf install hugo + +For the latest version, the Hugo package maintained by [@daftaupe](https://github.com/daftaupe) at Fedora Copr is recommended: + +* + +See the [related discussion in the Hugo forums][redhatforum]. + ++### Solus ++ ++Solus includes Hugo in its package repository, it may be installed with: ++ ++``` ++sudo eopkg install hugo ++``` ++ +## OpenBSD + +OpenBSD provides a package for Hugo via `pkg_add`: + + doas pkg_add hugo + + +## Upgrade Hugo + +Upgrading Hugo is as easy as downloading and replacing the executable you’ve placed in your `PATH` or run `brew upgrade hugo` if using Homebrew. + +## Install Pygments (Optional) + +The Hugo executable has one *optional* external dependency for source code highlighting ([Pygments][pygments]). + +If you want to have source code highlighting using the [highlight shortcode][], you need to install the Python-based Pygments program. The procedure is outlined on the [Pygments homepage][pygments]. + +## Next Steps + +Now that you've installed Hugo, read the [Quick Start guide][quickstart] and explore the rest of the documentation. If you have questions, ask the Hugo community directly by visiting the [Hugo Discussion Forum][forum]. + +[brew]: https://brew.sh/ +[Chocolatey]: https://chocolatey.org/ +[content]: /content-management/ +[@dhersam]: https://github.com/dhersam +[forum]: https://discourse.gohugo.io +[mage]: https://github.com/magefile/mage +[dep]: https://github.com/golang/dep +[highlight shortcode]: /content-management/shortcodes/#highlight +[installgit]: http://git-scm.com/ +[installgo]: https://golang.org/dl/ +[Path Editor]: https://patheditor2.codeplex.com/ +[pygments]: http://pygments.org +[quickstart]: /getting-started/quick-start/ +[redhatforum]: https://discourse.gohugo.io/t/solved-fedora-copr-repository-out-of-service/2491 +[releases]: https://github.com/gohugoio/hugo/releases +[Scoop]: https://scoop.sh/ +[snaps]: http://snapcraft.io/docs/core/install +[windowsarch]: https://esupport.trendmicro.com/en-us/home/pages/technical-support/1038680.aspx +[Windows Environment Variables Editor]: http://eveditor.com/ diff --cc docs/content/en/hosting-and-deployment/hosting-on-netlify.md index f2820a8d,00000000..01ca42f4 mode 100644,000000..100644 --- a/docs/content/en/hosting-and-deployment/hosting-on-netlify.md +++ b/docs/content/en/hosting-and-deployment/hosting-on-netlify.md @@@ -1,153 -1,0 +1,153 @@@ +--- +title: Host on Netlify +linktitle: Host on Netlify +description: Netlify can host your Hugo site with CDN, continuous deployment, 1-click HTTPS, an admin GUI, and its own CLI. +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-03-11 +categories: [hosting and deployment] +keywords: [netlify,hosting,deployment] +authors: [Ryan Watters, Seth MacLeod] +menu: + docs: + parent: "hosting-and-deployment" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [] +toc: true +--- + +[Netlify][netlify] provides continuous deployment services, global CDN, ultra-fast DNS, atomic deploys, instant cache invalidation, one-click SSL, a browser-based interface, a CLI, and many other features for managing your Hugo website. + +## Assumptions + +* You have an account with GitHub, GitLab, or Bitbucket. - * You have completed the [Quick Start][] or have Hugo website you are ready to deploy and share with the world. ++* You have completed the [Quick Start][] or have a Hugo website you are ready to deploy and share with the world. +* You do not already have a Netlify account. + +## Create a Netlify account + +Go to [app.netlify.com][] and select your preferred signup method. This will likely be a hosted Git provider, although you also have the option to sign up with an email address. + +The following examples use GitHub, but other git providers will follow a similar process. + +![Screenshot of the homepage for app.netlify.com, containing links to the most popular hosted git solutions.](/images/hosting-and-deployment/hosting-on-netlify/netlify-signup.jpg) + +Selecting GitHub will bring up an authorization modal for authentication. Select "Authorize application." + +![Screenshot of the authorization popup for Netlify and GitHub.](/images/hosting-and-deployment/hosting-on-netlify/netlify-first-authorize.jpg) + +## Create a New Site with Continuous Deployment + +You're now already a Netlify member and should be brought to your new dashboard. Select "New site from git." + +![Screenshot of the blank Netlify admin panel with no sites and highlighted 'add new site' button'](/images/hosting-and-deployment/hosting-on-netlify/netlify-add-new-site.jpg) + +Netlify will then start walking you through the steps necessary for continuous deployment. First, you'll need to select your git provider again, but this time you are giving Netlify added permissions to your repositories. + +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-1.jpg) + +And then again with the GitHub authorization modal: + +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-authorize-added-permissions.jpg) + +Select the repo you want to use for continuous deployment. If you have a large number of repositories, you can filter through them in real time using repo search: + +![Screenshot of step 1 of create a new site for Netlify: selecting the git provider](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-2.jpg) + +Once selected, you'll be brought to a screen for basic setup. Here you can select the branch you wanted published, your [build command][], and your publish (i.e. deploy) directory. The publish directory should mirror that of what you've set in your [site configuration][config], the default of which is `public`. The following steps assume you are publishing from the `master` branch. + - ## Configure Hugo Version in Netlify ++## Configure Hugo Version in Netlify + +You can [set Hugo version](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for your environments in `netlify.toml` file or set `HUGO_VERSION` as a build environment variable in the Netlify console. + +For production: + +``` +[context.production.environment] + HUGO_VERSION = "0.36" +``` + +For testing: + +``` +[context.deploy-preview.environment] + HUGO_VERSION = "0.36" +``` + +The Netlify configuration file can be a little hard to understand and get right for the different environment, and you may get some inspiration and tips from this site's `netlify.toml`: + +{{< code file="netlify.toml" nocode="true" >}} - {{< readfile file="netlify.toml" highlight="toml" >}} ++{{< readfile file="netlify.toml" highlight="toml" >}} +{{< /code >}} + +## Build and Deploy Site + +In the Netlify console, selecting "Deploy site" will immediately take you to a terminal for your build:. + +![Animated gif of deploying a site to Netlify, including the terminal read out for the build.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploying-site.gif) + +Once the build is finished---this should only take a few seconds--you should now see a "Hero Card" at the top of your screen letting you know the deployment is successful. The Hero Card is the first element that you see in most pages. It allows you to see a quick summary of the page and gives access to the most common/pertinent actions and information. You'll see that the URL is automatically generated by Netlify. You can update the URL in "Settings." + +![Screenshot of successful deploy badge at the top of a deployments screen from within the Netlify admin.](/images/hosting-and-deployment/hosting-on-netlify/netlify-deploy-published.jpg) + +![Screenshot of homepage to https://hugo-netlify-example.netlify.com, which is mostly dummy text](/images/hosting-and-deployment/hosting-on-netlify/netlify-live-site.jpg) + +[Visit the live site][visit]. + +Now every time you push changes to your hosted git repository, Netlify will rebuild and redeploy your site. + +See [this blog post](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) for more details about how Netlify handles Hugo versions. + +## Use Hugo Themes with Netlify + +The [`git clone` method for installing themes][installthemes] is not supported by Netlify. If you were to use `git clone`, it would require you to recursively remove the `.git` subdirectory from the theme folder and would therefore prevent compatibility with future versions of the theme. + +A *better* approach is to install a theme as a proper git submodule. You can [read the GitHub documentation for submodules][ghsm] or those found on [Git's website][gitsm] for more information, but the command is similar to that of `git clone`: + +``` +cd themes +git submodule add https://github.com// +``` + +It is recommended to only use stable versions of a theme (if it’s versioned) and always check the changelog. This can be done by checking out a specific release within the theme's directory. + +Switch to the theme's directory and list all available versions: + +``` +cd themes/ +git tag +# exit with q +``` + +You can checkout a specific version as follows: + +``` +git checkout tags/ +``` + +## Next Steps + +You now have a live website served over https, distributed through CDN, and configured for continuous deployment. Dig deeper into the Netlify documentation: + +1. [Using a Custom Domain][] +2. [Setting up HTTPS on Custom Domains][httpscustom] +3. [Redirects and Rewrite Rules][] + + +[app.netlify.com]: https://app.netlify.com +[build command]: /getting-started/usage/#the-hugo-command +[config]: /getting-started/configuration/ +[ghsm]: https://github.com/blog/2104-working-with-submodules +[gitsm]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[httpscustom]: https://www.netlify.com/docs/ssl/ +[hugoversions]: https://github.com/netlify/build-image/blob/master/Dockerfile#L216 +[installthemes]: /themes/installing/ +[netlify]: https://www.netlify.com/ +[netlifysignup]: https://app.netlify.com/signup +[Quick Start]: /getting-started/quick-start/ +[Redirects and Rewrite Rules]: https://www.netlify.com/docs/redirects/ +[Using a Custom Domain]: https://www.netlify.com/docs/custom-domains/ +[visit]: https://hugo-netlify-example.netlify.com diff --cc docs/content/en/hugo-pipes/postcss.md index a0ecc6d3,00000000..a0a67379 mode 100755,000000..100755 --- a/docs/content/en/hugo-pipes/postcss.md +++ b/docs/content/en/hugo-pipes/postcss.md @@@ -1,56 -1,0 +1,58 @@@ +--- +title: PostCSS +description: Hugo Pipes can process CSS files with PostCSS. +date: 2018-07-14 +publishdate: 2018-07-14 +lastmod: 2018-07-14 +categories: [asset management] +keywords: [] +menu: + docs: + parent: "pipes" + weight: 40 +weight: 40 +sections_weight: 40 +draft: false +--- + + +Any asset file can be processed using `resources.PostCSS` which takes for argument the resource object and a slice of options listed below. + +The resource will be processed using the project's or theme's own `postcss.config.js` or any file set with the `config` option. + + +```go-html-template +{{ $css := resources.Get "css/main.css" }} +{{ $style := $css | resources.PostCSS }} +``` + +{{% note %}} - Hugo Pipe's PostCSS requires `postcss-cli` javascript package to be installed on the environement along with any PostCSS plugin used. ++Hugo Pipe's PostCSS requires the `postcss-cli` JavaScript package to be installed in the environment (`npm install -g postcss-cli`) along with any PostCSS plugin(s) used (e.g., `npm install -g autoprefixer`). ++ ++If you are using the Hugo Snap package, PostCSS and plugin(s) need to be installed locally within your Hugo site directory, e.g., `npm install postcss-cli` without the `-g` flag. +{{% /note %}} +### Options + +config [string] +: Path to the PostCSS configuration file + +noMap [bool] +: Default is `true`. Disable the default inline sourcemaps + +_If no configuration file is used:_ + +use [string] +: List of PostCSS plugins to use + +parser [string] +: Custom PostCSS parser + +stringifier [string] +: Custom PostCSS stringifier + +syntax [string] +: Custom postcss syntax + +```go-html-template +{{ $style := resources.Get "css/main.css" | resources.PostCSS (dict "config" "customPostCSS.js" "noMap" true) }} +``` diff --cc docs/content/en/hugo-pipes/scss-sass.md index baed2b4d,00000000..489d16e7 mode 100755,000000..100755 --- a/docs/content/en/hugo-pipes/scss-sass.md +++ b/docs/content/en/hugo-pipes/scss-sass.md @@@ -1,45 -1,0 +1,49 @@@ +--- +title: SASS / SCSS +description: Hugo Pipes allows the processing of SASS and SCSS files. +date: 2018-07-14 +publishdate: 2018-07-14 +lastmod: 2018-07-14 +categories: [asset management] +keywords: [] +menu: + docs: + parent: "pipes" + weight: 30 +weight: 02 +sections_weight: 02 +draft: false +--- + + +Any SASS or SCSS file can be transformed into a CSS file using `resources.ToCSS` which takes two arguments, the resource object and a map of options listed below. + +```go-html-template +{{ $sass := resources.Get "sass/main.scss" }} +{{ $style := $sass | resources.ToCSS }} +``` + +### Options +targetPath [string] +: If not set, the resource's target path will be the asset file original path with its extension replaced by `.css`. + +outputStyle [string] +: Default is `nested`. Other available output styles are `expanded`, `compact` and `compressed`. + +precision [int] +: Precision of floating point math. + +enableSourceMap [bool] +: When enabled, a source map will be generated. + +includePaths [string slice] +: Additional SCSS/SASS include paths. Paths must be relative to the project directory. + +```go-html-template +{{ $options := (dict "targetPath" "style.css" "outputStyle" "compressed" "enableSourceMap" true "includePaths" (slice "node_modules/myscss")) }} +{{ $style := resources.Get "sass/main.scss" | resources.ToCSS $options }} +``` ++ ++{{% note %}} ++Setting `outputStyle` to `compressed` will handle SASS/SCSS files minification better than the more generic [`resources.Minify`]({{< ref "minification">}}). ++{{% /note %}} diff --cc docs/content/en/news/0.47-relnotes/featured-hugo-47-poster.png index 00000000,00000000..60192296 new file mode 100644 Binary files differ diff --cc docs/content/en/news/0.47-relnotes/index.md index 8e12a472,00000000..79d15ec6 mode 100644,000000..100644 --- a/docs/content/en/news/0.47-relnotes/index.md +++ b/docs/content/en/news/0.47-relnotes/index.md @@@ -1,79 -1,0 +1,79 @@@ + +--- +date: 2018-08-17 - title: "0.47" - description: "0.47" ++title: "Output Minification, Live-Reload Fixes and More" ++description: "Hugo 0.47: Adds minification of rendered output, but is mostly a massive bug fix release." +categories: ["Releases"] +--- + - Hugo `0.47` is named **Hugo Reloaded**. It adds minification support for the final rendered output (run `hugo --minify`), but it is mostly a bug fix release. And most notably, it fixes a set of issues with live-reloading/partial rebuilds when running `hugo server`. Working with bundles should now be a more pleasant experience, to pick one example. ++Hugo `0.47` is named **Hugo Reloaded**. It adds minification support for the final rendered output (run `hugo --minify`), but it is mostly a bug fix release. And most notably, it fixes a set of issues with live-reloading/partial rebuilds when running `hugo server`. Working with bundles should now be a more pleasant experience, to pick one example. + +This release represents **35 contributions by 6 contributors** to the main Hugo code base. +[@bep](https://github.com/bep) leads the Hugo development with a significant amount of contributions, but also a big shoutout to [@satotake](https://github.com/satotake), [@anthonyfok](https://github.com/anthonyfok), and [@coliff](https://github.com/coliff) for their ongoing contributions. + +And a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) and [@onedrawingperday](https://github.com/onedrawingperday) for their relentless work on keeping the themes site in pristine condition and to [@kaushalmodi](https://github.com/kaushalmodi) for his great work on the documentation site. + +Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs), +which has received **21 contributions by 10 contributors**. A special thanks to [@bep](https://github.com/bep), [@aapeliv](https://github.com/aapeliv), [@regisphilibert](https://github.com/regisphilibert), and [@brentybh](https://github.com/brentybh) for their work on the documentation site. + + +Hugo now has: + +* 27980+ [stars](https://github.com/gohugoio/hugo/stargazers) +* 442+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors) +* 251+ [themes](http://themes.gohugo.io/) + +## Enhancements + +### Templates + +* Suppress blank lines from opengraph internal template [c09ee78f](https://github.com/gohugoio/hugo/commit/c09ee78fd235599d3fb794110cd75c024d80cfca) [@anthonyfok](https://github.com/anthonyfok) +* Add MIME type to embedded JS [755d1ffe](https://github.com/gohugoio/hugo/commit/755d1ffe7a22d8ad83485240ff78cf25d501602f) [@bep](https://github.com/bep) [#5042](https://github.com/gohugoio/hugo/issues/5042) +* Add `os.Stat` template function [d7112085](https://github.com/gohugoio/hugo/commit/d71120852a8e14d0ea4d24de269fce041ef7b666) [@satotake](https://github.com/satotake) + +### Output + +* Add support for minification of final output [789ef8c6](https://github.com/gohugoio/hugo/commit/789ef8c639e4621abd36da530bcb5942ac9297da) [@bep](https://github.com/bep) [#1251](https://github.com/gohugoio/hugo/issues/1251) + +### Other + +* Regenerate CLI docs [4a16b5f4](https://github.com/gohugoio/hugo/commit/4a16b5f4b0adbb31fee611c378de9d5526de2f86) [@bep](https://github.com/bep) +* Include theme name in version mismatch error [e5052f4e](https://github.com/gohugoio/hugo/commit/e5052f4e09b6df590cddf2f8bc2c834fd3af3082) [@bep](https://github.com/bep) [#5044](https://github.com/gohugoio/hugo/issues/5044) +* Make the JS minifier matcher less specific [c81fbf46](https://github.com/gohugoio/hugo/commit/c81fbf4625ae7cc7dd3a7a526331ddfdf5237cc6) [@bep](https://github.com/bep) [#5073](https://github.com/gohugoio/hugo/issues/5073) +* Close file when done [f6ae436c](https://github.com/gohugoio/hugo/commit/f6ae436c5878bafeafa0bb2646a2c9b32c9b4380) [@bep](https://github.com/bep) [#5062](https://github.com/gohugoio/hugo/issues/5062) +* https links to 3rd party sites [c2a67413](https://github.com/gohugoio/hugo/commit/c2a6741394bc609a663522b245d3d75f0ad17da4) [@coliff](https://github.com/coliff) +* Update alias.go [06bd0136](https://github.com/gohugoio/hugo/commit/06bd0136419ebd6727635716c7023494cc5a8257) [@coliff](https://github.com/coliff) +* Remove test debug [fb3cb05c](https://github.com/gohugoio/hugo/commit/fb3cb05cc3dfc50370449f622fb0130ba7e0ced2) [@bep](https://github.com/bep) +* Update dependencies [d07882df](https://github.com/gohugoio/hugo/commit/d07882dfb76a65cce79aaa6f27df71279cd30600) [@bep](https://github.com/bep) +* Update Chroma [7f535671](https://github.com/gohugoio/hugo/commit/7f5356717d14079432365974e1424fc4ff5987c9) [@bep](https://github.com/bep) [#5025](https://github.com/gohugoio/hugo/issues/5025) +* Remove alias of os.Stat [71931b30](https://github.com/gohugoio/hugo/commit/71931b30b1813b146aaa60f5cdab16c0f9ebebdb) [@satotake](https://github.com/satotake) +* Renmae FileStat Stat [d40116e5](https://github.com/gohugoio/hugo/commit/d40116e5f941e4734ed3bed69dce8ffe11fc76b2) [@satotake](https://github.com/satotake) +* Reduce allocation in the benchmark itself [a6b1eb1e](https://github.com/gohugoio/hugo/commit/a6b1eb1e9150aa5c1c86fe7424cc4167d6f59a5a) [@bep](https://github.com/bep) +* Simplify the 0 transformer case [27110133](https://github.com/gohugoio/hugo/commit/27110133ffca05feae2e11a9ff28a9a00f613350) [@bep](https://github.com/bep) + +## Fixes + +### Templates + +* Fix compiling Amber templates that import other templates [37438757](https://github.com/gohugoio/hugo/commit/37438757788d279c839506d54f460b2ab37db164) [@Stebalien](https://github.com/Stebalien) +* Reimplement the ".Params tolower" template transformer [5c538491](https://github.com/gohugoio/hugo/commit/5c5384916e8f954f3ea66148ecceb3732584588e) [@bep](https://github.com/bep) [#5068](https://github.com/gohugoio/hugo/issues/5068) + +### Output + +* Fix Resource output in multihost setups [78f8475a](https://github.com/gohugoio/hugo/commit/78f8475a054a6277d37f13329afd240b00dc9408) [@bep](https://github.com/bep) [#5058](https://github.com/gohugoio/hugo/issues/5058) + +### Core + +* Force render of any changed page, even in Fast Render Mode [22475460](https://github.com/gohugoio/hugo/commit/2247546017c00201d2ce1232dd5303295451f1cc) [@bep](https://github.com/bep) [#5083](https://github.com/gohugoio/hugo/issues/5083) +* Add configFile(s) back to the watch list after REMOVE event [abc54080](https://github.com/gohugoio/hugo/commit/abc54080ec8c43e8989c081d934b59f0c9570c0b) [@anthonyfok](https://github.com/anthonyfok) [#4701](https://github.com/gohugoio/hugo/issues/4701) +* Gracefully handle typos in server config when running the server [a655e00d](https://github.com/gohugoio/hugo/commit/a655e00d702dbc20b3961b131b33ab21841b043d) [@bep](https://github.com/bep) [#5081](https://github.com/gohugoio/hugo/issues/5081) +* Fix shortcode output wrapped in p [78c99463](https://github.com/gohugoio/hugo/commit/78c99463fdd45c91af9933528d12d36a86dc6482) [@gllera](https://github.com/gllera) [#1642](https://github.com/gohugoio/hugo/issues/1642) +* Adjust tests for shortcode p-issue [baa62d0a](https://github.com/gohugoio/hugo/commit/baa62d0abbbf24a17d0aa800a4bb217f026c49ad) [@bep](https://github.com/bep) [#1642](https://github.com/gohugoio/hugo/issues/1642) +* Fix image cache-clearing for sub-languages [9d973004](https://github.com/gohugoio/hugo/commit/9d973004f5379cff2adda489566fe40683553c4c) [@bep](https://github.com/bep) [#5084](https://github.com/gohugoio/hugo/issues/5084) +* Fix error when deleting a bundle in server mode [0a88741f](https://github.com/gohugoio/hugo/commit/0a88741fe85f4f7aedc02ed748dfeb8ccc073dbf) [@bep](https://github.com/bep) [#5077](https://github.com/gohugoio/hugo/issues/5077) +* Fix Related when called from shortcode [0dd06bda](https://github.com/gohugoio/hugo/commit/0dd06bdac008aa81ec2e8f29ad8110dac0227011) [@bep](https://github.com/bep) [#5071](https://github.com/gohugoio/hugo/issues/5071) +* Use the interface value when doing Related search [a6f199f7](https://github.com/gohugoio/hugo/commit/a6f199f7a640161333608b4a843d701f7e182829) [@bep](https://github.com/bep) [#5071](https://github.com/gohugoio/hugo/issues/5071) +* Fix GitInfo when multiple content dirs [2182ecfd](https://github.com/gohugoio/hugo/commit/2182ecfd34a24521bf0e3c939627a55327eb1e19) [@bep](https://github.com/bep) [#5054](https://github.com/gohugoio/hugo/issues/5054) +* Add multiple content dirs to GitInfo test site [e85833d8](https://github.com/gohugoio/hugo/commit/e85833d868a902840c5ed1c90713256153b2548b) [@bep](https://github.com/bep) [#5054](https://github.com/gohugoio/hugo/issues/5054) +* Fix "adding a bundle" in server mode [d139a037](https://github.com/gohugoio/hugo/commit/d139a037d98e4b388687eecb7831758412247c58) [@bep](https://github.com/bep) [#5075](https://github.com/gohugoio/hugo/issues/5075) +* Fix typo [c362634b](https://github.com/gohugoio/hugo/commit/c362634b7d8802ea81b0b4341c800a9f78f7cd7c) [@satotake](https://github.com/satotake) diff --cc docs/content/en/news/0.47.1-relnotes/index.md index fc82642b,00000000..d35b0fad mode 100644,000000..100644 --- a/docs/content/en/news/0.47.1-relnotes/index.md +++ b/docs/content/en/news/0.47.1-relnotes/index.md @@@ -1,30 -1,0 +1,30 @@@ + +--- +date: 2018-08-20 - title: "0.47.1" - description: "0.47.1" ++title: "Two Bug Fixes" ++description: "Hugo 0.47.1: Two Bug Fixes" +categories: ["Releases"] +images: +- images/blog/hugo-bug-poster.png + +--- + + This is a bug-fix release with two fixes. + +# Fixes + +* Fix .Site.Params case regression [fdff0d3a](https://github.com/gohugoio/hugo/commit/fdff0d3af4670f7079e539fef4b92af2a866d02d) [@bep](https://github.com/bep) [#5094](https://github.com/gohugoio/hugo/issues/5094) +* Do not strip IE conditional statements [5a0ee2b9](https://github.com/gohugoio/hugo/commit/5a0ee2b934e38d596da0f9742361f81c1221e3d5) [@bep](https://github.com/bep) [#5089](https://github.com/gohugoio/hugo/issues/5089) + +## Updates to Linux Snap build + +* Remove unused files from Git, Perl, etc. [834617f9](https://github.com/gohugoio/hugo/commit/834617f9f8d870643b2631fe607471c8e2ef2f47) [@anthonyfok](https://github.com/anthonyfok) +* Add nodejs to allow PostCSS to work [ef20ec1f](https://github.com/gohugoio/hugo/commit/ef20ec1fbaa8f5841b3fbe18978d4d8c19d8fc53) [@anthonyfok](https://github.com/anthonyfok) + + + + + + + + diff --cc docs/content/en/news/0.48-relnotes/featured-hugo-48-poster.png index 00000000,00000000..7adb0d22 new file mode 100644 Binary files differ diff --cc docs/content/en/news/0.48-relnotes/index.md index e5dbb67d,00000000..92c765f2 mode 100644,000000..100644 --- a/docs/content/en/news/0.48-relnotes/index.md +++ b/docs/content/en/news/0.48-relnotes/index.md @@@ -1,57 -1,0 +1,57 @@@ + +--- +date: 2018-08-29 - title: "0.48" - description: "0.48" ++title: "This One Goes to 11!" ++description: "With Go 1.11, Hugo finally gets support for variable overwrites in templates!" +categories: ["Releases"] +--- + - Hugo `0.48` is built with the brand new Go 1.11. On the technical side this means that Hugo now uses [Go Modules](https://github.com/golang/go/wiki/Modules) for the build. The big new functional thing in Go 1.11 for Hugo is added support for [variable overwrites](https://github.com/golang/go/issues/10608). This means that you can now do: ++Hugo `0.48` is built with the brand new Go 1.11. On the technical side this means that Hugo now uses [Go Modules](https://github.com/golang/go/wiki/Modules) for the build. The big new functional thing in Go 1.11 for Hugo is added support for [variable overwrites](https://github.com/golang/go/issues/10608). This means that you can now do this and get the expected result: + - ``` ++```go-html-template +{{ $var := "Hugo Page" }} +{{ if .IsHome }} - {{ $var = "Hugo Home" }} ++ {{ $var = "Hugo Home" }} +{{ end }} +Var is {{ $var }} +``` + +The above may look obvious, but has not been possible until now. In Hugo we have had `.Scratch` as a workaround for this, but Go 1.11 will help clean up a lot of templates. + +This release represents **23 contributions by 5 contributors** to the main Hugo code base. [@bep](https://github.com/bep) leads the Hugo development with a significant amount of contributions, but also a big shoutout to [@anthonyfok](https://github.com/anthonyfok), [@vsopvsop](https://github.com/vsopvsop), and [@moorereason](https://github.com/moorereason) for their ongoing contributions. And a big thanks to [@digitalcraftsman](https://github.com/digitalcraftsman) for his relentless work on keeping the themes site in pristine condition and to [@kaushalmodi](https://github.com/kaushalmodi) for his great work on the documentation site. + +Many have also been busy writing and fixing the documentation in [hugoDocs](https://github.com/gohugoio/hugoDocs), +which has received **15 contributions by 12 contributors**. A special thanks to [@bep](https://github.com/bep), [@kaushalmodi](https://github.com/kaushalmodi), [@regisphilibert](https://github.com/regisphilibert), and [@anthonyfok](https://github.com/anthonyfok) for their work on the documentation site. + + +Hugo now has: + +* 28275+ [stars](https://github.com/gohugoio/hugo/stargazers) +* 441+ [contributors](https://github.com/gohugoio/hugo/graphs/contributors) +* 252+ [themes](http://themes.gohugo.io/) + +## Enhancements + +* Add a test for template variable overwrite [0c8a4154](https://github.com/gohugoio/hugo/commit/0c8a4154838e32a33d34202fd4fa0187aa502190) [@bep](https://github.com/bep) +* Include language code in REF_NOT_FOUND errors [94d0e79d](https://github.com/gohugoio/hugo/commit/94d0e79d33994b9a9d26a4d020500acdcc71e58c) [@bep](https://github.com/bep) [#5110](https://github.com/gohugoio/hugo/issues/5110) +* Improve minifier MIME type resolution [ebb56e8b](https://github.com/gohugoio/hugo/commit/ebb56e8bdbfaf4f955326017e40b2805850871e9) [@bep](https://github.com/bep) [#5093](https://github.com/gohugoio/hugo/issues/5093) +* Update to Go 1.11 [6b9934a2](https://github.com/gohugoio/hugo/commit/6b9934a26615ea614b1774770532cae9762a58d3) [@bep](https://github.com/bep) [#5115](https://github.com/gohugoio/hugo/issues/5115) +* Set GO111MODULE=on for mage install [c7f05779](https://github.com/gohugoio/hugo/commit/c7f057797ca7bfc781d5a2bbf181bb52360f160f) [@bep](https://github.com/bep) [#5115](https://github.com/gohugoio/hugo/issues/5115) +* Add instruction to install PostCSS when missing [08d14113](https://github.com/gohugoio/hugo/commit/08d14113b60ff70ffe922e8098e289b099a70e0f) [@anthonyfok](https://github.com/anthonyfok) [#5111](https://github.com/gohugoio/hugo/issues/5111) +* Update snapcraft build config to Go 1.11 [94d6d678](https://github.com/gohugoio/hugo/commit/94d6d6780fac78e9ed5ed58ecdb9821ad8f0f27c) [@bep](https://github.com/bep) [#5115](https://github.com/gohugoio/hugo/issues/5115) +* Use Go 1.11 modules with Mage [45c9c45d](https://github.com/gohugoio/hugo/commit/45c9c45d1d0d99443fa6bb524a1265fa9ba95e0e) [@bep](https://github.com/bep) [#5115](https://github.com/gohugoio/hugo/issues/5115) +* Add go.mod [fce32c07](https://github.com/gohugoio/hugo/commit/fce32c07fb80e9929bc2660cf1e681e93009d24b) [@bep](https://github.com/bep) [#5115](https://github.com/gohugoio/hugo/issues/5115) +* Update Travis to Go 1.11 and Go 1.10.4 [d32ff16f](https://github.com/gohugoio/hugo/commit/d32ff16fd61f55874e81d73759afa099b8bdcb57) [@bep](https://github.com/bep) [#5115](https://github.com/gohugoio/hugo/issues/5115) +* Skip installing postcss due to failure on build server [66f688f7](https://github.com/gohugoio/hugo/commit/66f688f7120560ca787c1a23e3e7fbc3aa617956) [@anthonyfok](https://github.com/anthonyfok) + +## Fixes + +* Keep end tags [e6eda2a3](https://github.com/gohugoio/hugo/commit/e6eda2a370aa1184e0afaf12e95dbd6f8b63ace5) [@vsopvsop](https://github.com/vsopvsop) +* Fix permissions when creating new folders [f4675fa0](https://github.com/gohugoio/hugo/commit/f4675fa0f0fae2358adfaea49e8da824ee094495) [@bep](https://github.com/bep) [#5128](https://github.com/gohugoio/hugo/issues/5128) +* Fix handling of taxonomy terms containing slashes [fff13253](https://github.com/gohugoio/hugo/commit/fff132537b4094221f4f099e2251f3cda613060f) [@moorereason](https://github.com/moorereason) [#4090](https://github.com/gohugoio/hugo/issues/4090) +* Fix build on armv7 [8999de19](https://github.com/gohugoio/hugo/commit/8999de193c18b7aa07b44e5b7d9f443a8572e117) [@caarlos0](https://github.com/caarlos0) [#5101](https://github.com/gohugoio/hugo/issues/5101) + + + + + diff --cc docs/content/en/showcase/over/bio.md index 00000000,00000000..415668f9 new file mode 100644 --- /dev/null +++ b/docs/content/en/showcase/over/bio.md @@@ -1,0 -1,0 +1,5 @@@ ++The site is built by: ++ ++* [Lauren Waller](https://twitter.com/waller_texas) ++* [Wayne Ashley Berry](https://twitter.com/waynethebrain) ++ diff --cc docs/content/en/showcase/over/featured-over.png index 00000000,00000000..726d9873 new file mode 100644 Binary files differ diff --cc docs/content/en/showcase/over/index.md index 00000000,00000000..9640198d new file mode 100644 --- /dev/null +++ b/docs/content/en/showcase/over/index.md @@@ -1,0 -1,0 +1,17 @@@ ++--- ++title: Over ++date: 2018-09-12 ++description: "Showcase: \"People from all disciplines contribute to our website; Hugo’s single static binary makes that possible.\"" ++siteURL: https://madewithover.com/ ++ ++--- ++ ++At Over we're into creativity, and technology should not get in the way. We want it to be easy for everyone to create, and Hugo does the same for us. That's one of the reasons many of us are fond of using it. ++ ++People from all disciplines contribute to our website, be it legal documentation, layout and design, recruiting, marketing and of course… engineering. Hugo allows us to do this with as little friction as possible. A lot of this comes down to Hugo being distributed as a single static binary. Copy, paste, run... and you're up and running! ++ ++We use [Wercker](https://www.wercker.com/) for continuous integration and deployments, [GitHub](https://github.com/) for contributing to and writing markdown and [Firebase](https://firebase.google.com/docs/hosting/) for hosting. ++ ++This infrastructure takes all the pressure off our engineers, anyone can contribute to our website. Anyone else can review the changes, and of course anyone with permission can deploy those approved changes as well! ++ ++We're busy working on a few new features for our website, and Hugo continues to deliver above and beyond. We're so happy with the choice we made to use Hugo and to us it has become the de-facto static site generator. diff --cc docs/content/en/templates/404.md index eba2d95d,00000000..c6bea191 mode 100644,000000..100644 --- a/docs/content/en/templates/404.md +++ b/docs/content/en/templates/404.md @@@ -1,61 -1,0 +1,62 @@@ +--- +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: [] +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 `.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. ++* Amazon CloudFont. You can specify the page in the Error Pages section in the CloudFont Console. [Details here](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/custom-error-pages.html) +* Caddy Server. Using `errors { 404 /404.html }`. [Details here](https://caddyserver.com/docs/errors) + +{{% 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/en/templates/files.md index 6e6f3ec4,00000000..4969a4f3 mode 100644,000000..100644 --- a/docs/content/en/templates/files.md +++ b/docs/content/en/templates/files.md @@@ -1,115 -1,0 +1,115 @@@ +--- +title: Local File Templates +linktitle: Local File Templates +description: Hugo's `readerDir` and `readFile` functions make it easy to traverse your project's directory structure and write file contents to your templates. +godocref: https://golang.org/pkg/os/#FileInfo +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-01 +categories: [templates] +keywords: [files,directories] +menu: + docs: + parent: "templates" + weight: 110 +weight: 110 +sections_weight: 110 +draft: false +aliases: [/extras/localfiles/,/templates/local-files/] +toc: true +--- + +## Traverse Local Files + +With Hugo's [`readDir`][readDir] and [`readFile`][readFile] template functions, you can traverse your website's files on your server. + +## Use `readDir` + +The [`readDir` function][readDir] returns an array of [`os.FileInfo`][osfileinfo]. It takes the file's `path` as a single string argument. This path can be to any directory of your website (i.e., as found on your server's file system). + +Whether the path is absolute or relative does not matter because---at least for `readDir`---the root of your website (typically `./public/`) in effect becomes both: + +1. The file system root +2. The current working directory + +### `readDir` Example: List Directory Files + +This shortcode creates a link to each of the files in a directory---display as the file's basename---along with the file's size in bytes. + +{{< code file="layouts/shortcodes/directoryindex.html" download="directoryindex.html" >}} +{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/directoryindex.html" >}} +{{< /code >}} + +You can then call the shortcode as follows inside of your content's markup: + +``` +{{}} +``` + +The above shortcode [is part of the code for the Hugo docs][dirindex]. Here it lists this site's CSS files: + +{{< directoryindex path="/themes/gohugoioTheme/static/dist" pathURL="/css" >}} + +{{% note "Slashes are Important" %}} +The initial slash `/` in `pathURL` is important in the `directoryindex` shortcode. Otherwise, `pathURL` becomes relative to the current web page. +{{% /note %}} + +## Use `readFile` + +The [`readfile` function][readFile] reads a file from disk and converts it into a string to be manipulated by other Hugo functions or added as-is. `readFile` takes the file, including path, as an argument passed to the function. + +To use the `readFile` function in your templates, make sure the path is relative to your *Hugo project's root directory*: + +``` +{{ readFile "/content/templates/local-file-templates" }} +``` + +### `readFile` Example: Add a Project File to Content + +As `readFile` is a function, it is only available to you in your templates and not your content. However, we can create a simple [shortcode template][sct] that calls `readFile`, passes the first argument through the function, and then allows an optional second argument to send the file through the Blackfriday markdown processor. The pattern for adding this shortcode to your content will be as follows: + +``` +{{}} +``` + +{{% warning %}} +If you are going to create [custom shortcodes](/templates/shortcode-templates/) with `readFile` for a theme, note that usage of the shortcode will refer to the project root and *not* your `themes` directory. +{{% /warning %}} + +Here is the templating for our new `readfile` shortcode: + +{{< code file="layouts/shortcodes/readfile.html" download="readfile.html" >}} +{{< readfile file="/themes/gohugoioTheme/layouts/shortcodes/readfile.html">}} +{{< /code >}} + +This `readfile` shortcode is [also part of the Hugo docs][readfilesource]. So is [`testing.txt`][testfile], which we will call in this example by passing it into our new `readfile` shortcode as follows: + +``` +{{}} +``` + +The output "string" for this shortcode declaration will be the following: + +``` +{{< readfile file="/content/en/readfiles/testing.txt" >}} +``` + +However, if we want Hugo to pass this string through Blackfriday, we should add the `markdown="true"` optional parameter: + +``` +{{}} +``` + +And here is the result as [called directly in the Hugo docs][] and rendered for display: + +{{< readfile file="/content/en/readfiles/testing.txt" markdown="true">}} + - [called directly in the Hugo docs]: https://github.com/gohugoio/hugo/blob/master/docs/content/templates/files.md ++[called directly in the Hugo docs]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/templates/files.md +[dirindex]: https://github.com/gohugoio/hugo/blob/master/docs/layouts/shortcodes/directoryindex.html +[osfileinfo]: https://golang.org/pkg/os/#FileInfo +[readDir]: /functions/readdir/ +[readFile]: /functions/readfile/ +[sc]: /content-management/shortcodes/ +[sct]: /templates/shortcode-templates/ - [readfilesource]: https://github.com/gohugoio/hugo/blob/master/ - [testfile]: https://github.com/gohugoio/hugo/blob/master/docs/testfile ++[readfilesource]: https://github.com/gohugoio/hugoDocs/blob/master/layouts/shortcodes/readfile.html ++[testfile]: https://github.com/gohugoio/hugoDocs/blob/master/content/en/readfiles/testing.txt diff --cc docs/content/en/templates/introduction.md index 0b9ad051,00000000..1e1778eb mode 100644,000000..100644 --- a/docs/content/en/templates/introduction.md +++ b/docs/content/en/templates/introduction.md @@@ -1,541 -1,0 +1,652 @@@ +--- +title: Introduction to Hugo Templating +linktitle: Introduction +description: Hugo uses Go's `html/template` and `text/template` libraries as the basis for the templating. +godocref: https://golang.org/pkg/html/template/ +date: 2017-02-01 +publishdate: 2017-02-01 +lastmod: 2017-02-25 +categories: [templates,fundamentals] +keywords: [go] +menu: + docs: + parent: "templates" + weight: 10 +weight: 10 +sections_weight: 10 +draft: false +aliases: [/layouts/introduction/,/layout/introduction/, /templates/go-templates/] +toc: true +--- + +{{% note %}} - The following is only a primer on Go templates. For an in-depth look into Go templates, check the official [Go docs](http://golang.org/pkg/html/template/). ++The following is only a primer on Go Templates. For an in-depth look into Go Templates, check the official [Go docs](http://golang.org/pkg/html/template/). +{{% /note %}} + - Go templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. ++Go Templates provide an extremely simple template language that adheres to the belief that only the most basic of logic belongs in the template or view layer. + +{{< youtube gnJbPO-GFIw >}} + +## Basic Syntax + - Go templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go template variables and functions are accessible within `{{ }}`. ++Go Templates are HTML files with the addition of [variables][variables] and [functions][functions]. Go Template variables and functions are accessible within `{{ }}`. + +### Access a Predefined Variable + - ``` - {{ foo }} ++A _predefined variable_ could be a variable already existing in the ++current scope (like the `.Title` example in the [Variables]({{< relref ++"#variables" >}}) section below) or a custom variable (like the ++`$address` example in that same section). ++ ++ ++```go-html-template ++{{ .Title }} ++{{ $address }} +``` + - Parameters for functions are separated using spaces. The following example calls the `add` function with inputs of `1` and `2`: ++Parameters for functions are separated using spaces. The general syntax is: + +``` ++{{ FUNCTION ARG1 ARG2 .. }} ++``` ++ ++The following example calls the `add` function with inputs of `1` and `2`: ++ ++```go-html-template +{{ add 1 2 }} +``` + +#### Methods and Fields are Accessed via dot Notation + +Accessing the Page Parameter `bar` defined in a piece of content's [front matter][]. + - ``` ++```go-html-template +{{ .Params.bar }} +``` + +#### Parentheses Can be Used to Group Items Together + - ``` ++```go-html-template +{{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} +``` + - ## Variables ++## Variables {#variables} + - Each Go template gets a data object. In Hugo, each template is passed a `Page`. See [variables][] for more information. ++Each Go Template gets a data object. In Hugo, each template is passed ++a `Page`. In the below example, `.Title` is one of the elements ++accessible in that [`Page` variable][pagevars]. + - This is how you access a `Page` variable from a template: ++With the `Page` being the default scope of a template, the `Title` ++element in current scope (`.` -- "the **dot**") is accessible simply ++by the dot-prefix (`.Title`): + - ``` ++```go-html-template +{{ .Title }} +``` + +Values can also be stored in custom variables and referenced later: + - ``` - {{ $address := "123 Main St."}} ++{{% note %}} ++The custom variables need to be prefixed with `$`. ++{{% /note %}} ++ ++```go-html-template ++{{ $address := "123 Main St." }} +{{ $address }} +``` + +{{% warning %}} - Variables defined inside `if` conditionals and similar are not visible on the outside. See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). ++For Hugo v0.47 and older versions, variables defined inside `if` ++conditionals and similar are not visible on the outside. ++See [https://github.com/golang/go/issues/10608](https://github.com/golang/go/issues/10608). + +Hugo has created a workaround for this issue in [Scratch](/functions/scratch). - +{{% /warning %}} + ++For **Hugo v0.48** and newer, variables can be re-defined using the ++new `=` operator (new in Go 1.11). ++ ++Below example will work only in these newer Hugo versions. The example ++prints "Var is Hugo Home" on the home page, and "Var is Hugo Page" on ++all other pages: ++ ++```go-html-template ++{{ $var := "Hugo Page" }} ++{{ if .IsHome }} ++ {{ $var = "Hugo Home" }} ++{{ end }} ++Var is {{ $var }} ++``` ++ +## Functions + - Go templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. ++Go Templates only ship with a few basic functions but also provide a mechanism for applications to extend the original set. + +[Hugo template functions][functions] provide additional functionality specific to building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling Hugo. + +### Example 1: Adding Numbers + - ``` ++```go-html-template +{{ add 1 2 }} - => 3 ++ +``` + +### Example 2: Comparing Numbers + - ``` ++```go-html-template +{{ lt 1 2 }} - => true (i.e., since 1 is less than 2) ++ +``` + - Note that both examples make use of Go template's [math functions][]. ++Note that both examples make use of Go Template's [math functions][]. + +{{% note "Additional Boolean Operators" %}} - There are more boolean operators than those listed in the Hugo docs in the [Go template documentation](http://golang.org/pkg/text/template/#hdr-Functions). ++There are more boolean operators than those listed in the Hugo docs in the [Go Template documentation](http://golang.org/pkg/text/template/#hdr-Functions). +{{% /note %}} + +## Includes + +When including another template, you will need to pass it the data that it would +need to access. + +{{% note %}} +To pass along the current context, please remember to include a trailing **dot**. +{{% /note %}} + +The templates location will always be starting at the `layouts/` directory +within Hugo. + +### Partial + +The [`partial`][partials] function is used to include *partial* templates using +the syntax `{{ partial "/." . }}`. + - Example: ++Example of including a `layouts/partials/header.html` partial: + - ``` ++```go-html-template +{{ partial "header.html" . }} +``` + +### Template + - The `template` function was used to include *partial* templates in much older - Hugo versions. Now it is still useful for calling [*internal* - templates][internal_templates]: ++The `template` function was used to include *partial* templates ++in much older Hugo versions. Now it useful only for calling ++[*internal* templates][internal_templates]. The syntax is `{{ template ++"_internal/