hugo/docs/content/hosting-and-deployment/hosting-on-netlify.md

156 lines
7.7 KiB
Markdown
Raw Normal View History

---
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 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 a typical modal you've seen through other application that use GitHub 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.
### Build with a Specific Hugo Version
Setting the build command to `hugo` will build your site according to the current default Hugo version used by Netlify. You can see the full list of [available Hugo versions in Netlify's Docker file][hugoversions].
Squashed 'docs/' changes from f887bd7b..1d052b16 1d052b16 Update hosting-on-netlify.md 28b96bec Remove double brackets in Netlify hosting tutorial 373ed38b Update deployment instructions from hugo > 0.20 on Netlify 1bbb41ca Generate static assets on deploy in Nanobox tutorial 816d207f Add missing backtick in templates/views.md bf88e772 Add nanobox as a deployment option 9c37b4cc Change config's syntax order matching description d3cb05a7 Fix wrongly named default value of publishDir 4be85c54 Add link to showcase a theme setup via config file 46837195 Init and update of submodules in .gitlab-ci.yml 9e7c2827 Add CSS lang argument to code block 85aad56e Abstract the type in the lookup order 4e1e43e9 Fix broken Pygments url 65b4e79b Correct GitLab project pipelines URL 94af72b5 Fix .Data.Terms usage in taxonomy template example eb371e52 functions: Fix lang.NumFmt docs a745cd6c Fix layouts' folder name in template primer e181e637 Correct typo on GitHub pages guide (#151) 28698500 Remove HTML special chars from Windows install example 96b1f5b5 Remove not needed escape slashes in urls.md 2e05043f Add upgrade instructions using homebrew 2a14624d Fix alias in countrunes.md 5e26bb97 Update docker image for build/publish 01424887 List the internal templates a3ef5be9 Remove string concatenation from add (math) sample 43d12b44 Fix typo 89bafa49 Change to Asciidoc URI 4e14071e Removes an extra bracket (>) in single-page-templates.md 0938e423 Fix typo in http2 server push blog fac55121 Fix typo in deployment with rsync tutorial git-subtree-dir: docs git-subtree-split: 1d052b16a1290ada12f1e28c7c0c373f86741071
2017-09-05 12:09:40 -04:00
If you want to tell Netlify to build with a specific version (hugo <= 0.20), you can append an underscore followed by the version number to the build command:
```
hugo_0.19
```
Your simple configuration should now look similar to the following:
![Screenshot of 3-step, basic continuous deployment setup with a new Hugo site on Netlify](/images/hosting-and-deployment/hosting-on-netlify/netlify-create-new-site-step-3.jpg)
Squashed 'docs/' changes from f887bd7b..1d052b16 1d052b16 Update hosting-on-netlify.md 28b96bec Remove double brackets in Netlify hosting tutorial 373ed38b Update deployment instructions from hugo > 0.20 on Netlify 1bbb41ca Generate static assets on deploy in Nanobox tutorial 816d207f Add missing backtick in templates/views.md bf88e772 Add nanobox as a deployment option 9c37b4cc Change config's syntax order matching description d3cb05a7 Fix wrongly named default value of publishDir 4be85c54 Add link to showcase a theme setup via config file 46837195 Init and update of submodules in .gitlab-ci.yml 9e7c2827 Add CSS lang argument to code block 85aad56e Abstract the type in the lookup order 4e1e43e9 Fix broken Pygments url 65b4e79b Correct GitLab project pipelines URL 94af72b5 Fix .Data.Terms usage in taxonomy template example eb371e52 functions: Fix lang.NumFmt docs a745cd6c Fix layouts' folder name in template primer e181e637 Correct typo on GitHub pages guide (#151) 28698500 Remove HTML special chars from Windows install example 96b1f5b5 Remove not needed escape slashes in urls.md 2e05043f Add upgrade instructions using homebrew 2a14624d Fix alias in countrunes.md 5e26bb97 Update docker image for build/publish 01424887 List the internal templates a3ef5be9 Remove string concatenation from add (math) sample 43d12b44 Fix typo 89bafa49 Change to Asciidoc URI 4e14071e Removes an extra bracket (>) in single-page-templates.md 0938e423 Fix typo in http2 server push blog fac55121 Fix typo in deployment with rsync tutorial git-subtree-dir: docs git-subtree-split: 1d052b16a1290ada12f1e28c7c0c373f86741071
2017-09-05 12:09:40 -04:00
For version hugo > 0.20 you have to [specify version hugo for testing and production](https://www.netlify.com/blog/2017/04/11/netlify-plus-hugo-0.20-and-beyond/) 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.26"
```
For testing:
```
[context.deploy-preview.environment]
HUGO_VERSION = "0.26"
```
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.
## 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/<THEMECREATOR>/<THEMENAME>
```
Squashed 'docs/' changes from e65df1059..a042b67b5 a042b67b5 Update installation instructions for Fedora, CentOS, Red Hat e99dcb0b5 Document `:sections` placeholder for permalinks f33c88a27 Fix and clarify documentation about Blackfriday extensions (mask) 5cab109c2 Add .Page.File documentation 62df7bb80 Add .Page.CurrentSection and .Page.Sections documentation 60b4414de Add .Page.Dir documentation 22038d1a8 shortcode-templates.md: Update year example 850d5ca41 Add note about theme versions in hosting-on-netlify.md 0509b8055 Update permalink example URL c68d61d3a Mention the available 'width' argument in 'figure' shortcode ed83b483a Update Nanobox deployment tutorial a7422f35d shortcode-templates.md: Remove stray period af2905fe4 Fix order of releases in news section 19d3ea064 Bump to 0.30.2 bbfa10343 Merge branch 'next' 36ed7cbe4 releaser: Prepare repository for 0.31-DEV f689770f6 releaser: Add release notes to /docs for release of 0.30.2 0045e712a releaser: Bump versions for release of 0.30.2 a9efc3bbd Add slug to 0.30.1 relnotes 9cf47a4a1 Release 0.30.1 1fa0bb23d releaser: Prepare repository for 0.31-DEV 5582208b6 releaser: Add release notes to /docs for release of 0.30.1 09693d155 releaser: Bump versions for release of 0.30.1 58adf5d0d Merge commit '325009c3fd4ac90021897b7e3e025c14e70ce162' 4ef5dcb9b releaser: Prepare repository for 0.31-DEV 02938a788 releaser: Add release notes to /docs for release of 0.30.1 7cfd01fc6 releaser: Bump versions for release of 0.30.1 db3a68e24 Fix typo 95a5d8b46 Fix format of summaryLength in TOML example config 2ad649a92 Make terms in taxonomy examples more coherent 1fac1e662 Make a link specifically point to Pygments HTML Formatter docs 11ae6be03 Fix minor typos in v0.30 release notes git-subtree-dir: docs git-subtree-split: a042b67b5b8834ee8292849708cba724f5d6644e
2017-11-17 07:46:40 -05:00
It is recommended to only use stable versions of a theme (if its 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/<theme>
git tag
# exit with q
```
You can checkout a specific version as follows:
```
git checkout tags/<version-name>
```
## 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#L166
[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