mirror of
https://github.com/gohugoio/hugo.git
synced 2024-05-11 05:54:58 +00:00
Bjørn Erik Pedersen
23
docs/content/getting-started/_index.md
Normal file
23
docs/content/getting-started/_index.md
Normal file
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: Getting Started
|
||||
linktitle: Getting Started Overview
|
||||
description: Quick start and guides for installing Hugo on your preferred operating system.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [getting started]
|
||||
#tags: [usage,docs]
|
||||
menu:
|
||||
docs:
|
||||
parent: "getting-started"
|
||||
weight: 1
|
||||
weight: 0001 #rem
|
||||
draft: false
|
||||
aliases: [/overview/introduction/]
|
||||
toc: false
|
||||
---
|
||||
|
||||
If this is your first time using Hugo and you've [already installed Hugo on your machine][installed], we recommend the [quick start][].
|
||||
|
||||
[installed]: /getting-started/installing/
|
||||
[quick start]: /getting-started/quick-start/
|
||||
401
docs/content/getting-started/configuration.md
Normal file
401
docs/content/getting-started/configuration.md
Normal file
@@ -0,0 +1,401 @@
|
||||
---
|
||||
title: Configuring Hugo
|
||||
linktitle: Configuration
|
||||
description: Often the default settings are good enough, but the config file can provide highly granular control over how your site is rendered.
|
||||
date: 2013-07-01
|
||||
publishdate: 2017-01-02
|
||||
lastmod: 2017-03-05
|
||||
categories: [getting started,fundamentals]
|
||||
#tags: [configuration,toml,yaml,json]
|
||||
menu:
|
||||
docs:
|
||||
parent: "getting-started"
|
||||
weight: 60
|
||||
weight: 60
|
||||
sections_weight: 60
|
||||
draft: false
|
||||
aliases: [/overview/source-directory/,/overview/configuration/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
The [directory structure][] of a Hugo website—or more precisely, the source organization of files containing the website's content and templates—provides most of the configuration information that Hugo needs in order to generate a finished website.
|
||||
|
||||
Because of Hugo's sensible defaults, many websites may not need a configuration file. Hugo is designed to recognize certain typical usage patterns.
|
||||
|
||||
## Configuration Lookup Order
|
||||
|
||||
Similar to the template [lookup order][], Hugo has a default set of rules for searching for a configuration file in the root of your website's source directory as a default behavior:
|
||||
|
||||
1. `./config.toml`
|
||||
2. `./config.yaml`
|
||||
3. `./config.json`
|
||||
|
||||
In your `config` file, you can direct Hugo as to how you want your website rendered, control your website's menus, and arbitrarily define site-wide parameters specific to your project.
|
||||
|
||||
## YAML Configuration
|
||||
|
||||
The following is a typical example of a YAML configuration file. Note the document opens with 3 hyphens and closes with 3 periods. The values nested under `params:` will populate the [`.Site.Params`][] variable for use in [templates][]:
|
||||
|
||||
{{% code file="config.yml"%}}
|
||||
```yaml
|
||||
---
|
||||
baseURL: "https://yoursite.example.com/"
|
||||
title: "My Hugo Site"
|
||||
footnoteReturnLinkContents: "↩"
|
||||
permalinks:
|
||||
post: /:year/:month/:title/
|
||||
params:
|
||||
Subtitle: "Hugo is Absurdly Fast!"
|
||||
AuthorName: "Jon Doe"
|
||||
GitHubUser: "spf13"
|
||||
ListOfFoo:
|
||||
- "foo1"
|
||||
- "foo2"
|
||||
SidebarRecentLimit: 5
|
||||
...
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
### All Variables, YAML
|
||||
|
||||
The following is the full list of Hugo-defined variables in an example YAML file. The values provided in this example represent the default values used by Hugo.
|
||||
|
||||
{{% code file="config.yml" download="config.yml" %}}
|
||||
```yaml
|
||||
---
|
||||
archetypeDir: "archetypes"
|
||||
# hostname (and path) to the root, e.g. http://spf13.com/
|
||||
baseURL: ""
|
||||
# include content marked as draft
|
||||
buildDrafts: false
|
||||
# include content with publishdate in the future
|
||||
buildFuture: false
|
||||
# include content already expired
|
||||
buildExpired: false
|
||||
# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs. See the "URL Management" page
|
||||
relativeURLs: false
|
||||
canonifyURLs: false
|
||||
# config file (default is path/config.yaml|json|toml)
|
||||
config: "config.toml"
|
||||
contentDir: "content"
|
||||
dataDir: "data"
|
||||
defaultExtension: "html"
|
||||
defaultLayout: "post"
|
||||
# Missing translations will default to this content language
|
||||
defaultContentLanguage: "en"
|
||||
# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
|
||||
defaultContentLanguageInSubdir: false
|
||||
disableLiveReload: false
|
||||
# Do not build RSS files
|
||||
disableRSS: false
|
||||
# Do not build Sitemap file
|
||||
disableSitemap: false
|
||||
# Enable GitInfo feature
|
||||
enableGitInfo: false
|
||||
# Build robots.txt file
|
||||
enableRobotsTXT: false
|
||||
# Do not render 404 page
|
||||
disable404: false
|
||||
# Do not inject generator meta tag on homepage
|
||||
disableHugoGeneratorInject: false
|
||||
# Allows you to disable all page types and will render nothing related to 'kind';
|
||||
# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"
|
||||
disableKinds: []
|
||||
# Do not make the url/path to lowercase
|
||||
disablePathToLower: false ""
|
||||
# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com
|
||||
enableEmoji: false
|
||||
# Show a placeholder instead of the default value or an empty string if a translation is missing
|
||||
enableMissingTranslationPlaceholders: false
|
||||
footnoteAnchorPrefix: ""
|
||||
footnoteReturnLinkContents: ""
|
||||
# google analytics tracking id
|
||||
googleAnalytics: ""
|
||||
# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage)
|
||||
hasCJKLanguage: false
|
||||
languageCode: ""
|
||||
layoutDir: "layouts"
|
||||
# Enable Logging
|
||||
log: false
|
||||
# Log File path (if set, logging enabled automatically)
|
||||
logFile: ""
|
||||
# "toml","yaml", or "json"
|
||||
metaDataFormat: "toml"
|
||||
newContentEditor: ""
|
||||
# Don't sync permission mode of files
|
||||
noChmod: false
|
||||
# Don't sync modification time of files
|
||||
noTimes: false
|
||||
# Pagination
|
||||
paginate: 10
|
||||
paginatePath: "page"
|
||||
# See "content-management/permalinks"
|
||||
permalinks:
|
||||
# Pluralize titles in lists using inflect
|
||||
pluralizeListTitles: true
|
||||
# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
|
||||
preserveTaxonomyNames: false
|
||||
# filesystem path to write files to
|
||||
publishDir: "public"
|
||||
# enables syntax guessing for code fences without specified language
|
||||
pygmentsCodeFencesGuessSyntax: false
|
||||
# color-codes for highlighting derived from this style
|
||||
pygmentsStyle: "monokai"
|
||||
# true use pygments-css or false will color code directly
|
||||
pygmentsUseClasses: false
|
||||
# maximum number of items in the RSS feed
|
||||
rssLimit: 15
|
||||
# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info
|
||||
SectionPagesMenu: ""
|
||||
# default sitemap configuration map
|
||||
sitemap:
|
||||
# filesystem path to read files relative from
|
||||
source: ""
|
||||
staticDir: "static"
|
||||
# display memory and timing of different steps of the program
|
||||
stepAnalysis: false
|
||||
# theme to use (located by default in /themes/THEMENAME/)
|
||||
themesDir: "themes"
|
||||
theme: ""
|
||||
title: ""
|
||||
# if true, use /filename.html instead of /filename/
|
||||
uglyURLs: false
|
||||
# verbose output
|
||||
verbose: false
|
||||
# verbose logging
|
||||
verboseLog: false
|
||||
# watch filesystem for changes and recreate as needed
|
||||
watch: true
|
||||
taxonomies:
|
||||
- category: "categories"
|
||||
- tag: "tags"
|
||||
---
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
## TOML Configuration
|
||||
|
||||
The following is an example of a TOML configuration file. The values under `[params]` will populate the `.Site.Params` variable for use in [templates][]:
|
||||
|
||||
```toml
|
||||
contentDir = "content"
|
||||
layoutDir = "layouts"
|
||||
publishDir = "public"
|
||||
buildDrafts = false
|
||||
baseURL = "https://yoursite.example.com/"
|
||||
canonifyURLs = true
|
||||
title = "My Hugo Site"
|
||||
|
||||
[taxonomies]
|
||||
category = "categories"
|
||||
tag = "tags"
|
||||
|
||||
[params]
|
||||
subtitle = "Hugo is Absurdly Fast!"
|
||||
author = "John Doe"
|
||||
```
|
||||
|
||||
### All Variables, TOML
|
||||
|
||||
The following is the full list of Hugo-defined variables in an example TOML file. The values provided in this example represent the default values used by Hugo.
|
||||
|
||||
{{% code file="config.toml" download="config.toml"%}}
|
||||
```toml
|
||||
+++
|
||||
archetypeDir = "archetypes"
|
||||
# hostname (and path) to the root, e.g. http://spf13.com/
|
||||
baseURL = ""
|
||||
# include content marked as draft
|
||||
buildDrafts = false
|
||||
# include content with publishdate in the future
|
||||
buildFuture = false
|
||||
# include content already expired
|
||||
buildExpired = false
|
||||
# enable this to make all relative URLs relative to content root. Note that this does not affect absolute URLs.
|
||||
relativeURLs = false
|
||||
canonifyURLs = false
|
||||
# config file (default is path/config.yaml|json|toml)
|
||||
config = "config.toml"
|
||||
contentDir = "content"
|
||||
dataDir = "data"
|
||||
defaultExtension = "html"
|
||||
defaultLayout = "post"
|
||||
# Missing translations will default to this content language
|
||||
defaultContentLanguage = "en"
|
||||
# Renders the default content language in subdir, e.g. /en/. The root directory / will redirect to /en/
|
||||
defaultContentLanguageInSubdir = false
|
||||
disableLiveReload = false
|
||||
# Do not build RSS files
|
||||
disableRSS = false
|
||||
# Do not build Sitemap file
|
||||
disableSitemap = false
|
||||
# Enable GitInfo feature
|
||||
enableGitInfo = false
|
||||
# Build robots.txt file
|
||||
enableRobotsTXT = false
|
||||
# Do not render 404 page
|
||||
disable404 = false
|
||||
# Do not inject generator meta tag on homepage
|
||||
disableHugoGeneratorInject = false
|
||||
# Allows you to disable all page types and will render nothing related to 'kind';
|
||||
# values = "page", "home", "section", "taxonomy", "taxonomyTerm", "RSS", "sitemap", "robotsTXT", "404"
|
||||
disableKinds = []
|
||||
# Do not make the url/path to lowercase
|
||||
disablePathToLower = false
|
||||
# Enable Emoji emoticons support for page content; see emoji-cheat-sheet.com
|
||||
enableEmoji = false
|
||||
# Show a placeholder instead of the default value or an empty string if a translation is missing
|
||||
enableMissingTranslationPlaceholders = false
|
||||
footnoteAnchorPrefix = ""
|
||||
footnoteReturnLinkContents = ""
|
||||
# google analytics tracking id
|
||||
googleAnalytics = ""
|
||||
# if true, auto-detect Chinese/Japanese/Korean Languages in the content. (.Summary and .WordCount can work properly in CJKLanguage)
|
||||
hasCJKLanguage = false
|
||||
languageCode = ""
|
||||
layoutDir = "layouts"
|
||||
# Enable Logging
|
||||
log = false
|
||||
# Log File path (if set, logging enabled automatically)
|
||||
logFile =
|
||||
# maximum number of items in the RSS feed
|
||||
rssLimit = 15
|
||||
# "toml","yaml", or "json"
|
||||
metaDataFormat = "toml"
|
||||
newContentEditor = ""
|
||||
# Don't sync permission mode of files
|
||||
noChmod = false
|
||||
# Don't sync modification time of files
|
||||
noTimes = false
|
||||
# Pagination
|
||||
paginate = 10
|
||||
paginatePath = "page"
|
||||
# See "content-management/permalinks"
|
||||
permalinks =
|
||||
# Pluralize titles in lists using inflect
|
||||
pluralizeListTitles = true
|
||||
# Preserve special characters in taxonomy names ("Gérard Depardieu" vs "Gerard Depardieu")
|
||||
preserveTaxonomyNames = false
|
||||
# filesystem path to write files to
|
||||
publishDir = "public"
|
||||
# enables syntax guessing for code fences without specified language
|
||||
pygmentsCodeFencesGuessSyntax = false
|
||||
# color-codes for highlighting derived from this style
|
||||
pygmentsStyle = "monokai"
|
||||
# true: use pygments-css or false: color-codes directly
|
||||
pygmentsUseClasses = false
|
||||
# see "Section Menu for Lazy Bloggers", /templates/menu-templates for more info
|
||||
SectionPagesMenu =
|
||||
# default sitemap configuration map
|
||||
sitemap =
|
||||
# filesystem path to read files relative from
|
||||
source = ""
|
||||
staticDir = "static"
|
||||
# display memory and timing of different steps of the program
|
||||
stepAnalysis = false
|
||||
# theme to use (located by default in /themes/THEMENAME/)
|
||||
themesDir = "themes"
|
||||
theme = ""
|
||||
title = ""
|
||||
# if true, use /filename.html instead of /filename/
|
||||
uglyURLs = false
|
||||
# verbose output
|
||||
verbose = false
|
||||
# verbose logging
|
||||
verboseLog = false
|
||||
# watch filesystem for changes and recreate as needed
|
||||
watch = true
|
||||
[taxonomies]
|
||||
category = "categories"
|
||||
tag = "tags"
|
||||
+++
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
{{% note %}}
|
||||
If you are developing your site on a \*nix machine, here is a handy shortcut for finding a configuration option from the command line:
|
||||
```bash
|
||||
~/sites/yourhugosite
|
||||
hugo config | grep emoji
|
||||
enableemoji: true
|
||||
```
|
||||
{{% /note %}}
|
||||
|
||||
## Environmental Variables
|
||||
|
||||
In addition to the 3 config options already mentioned, configuration key-values can be defined through operating system environment variables.
|
||||
|
||||
For example, the following command will effectively set a website's title on Unix-like systems:
|
||||
|
||||
```bash
|
||||
$ env HUGO_TITLE="Some Title" hugo
|
||||
```
|
||||
|
||||
{{% note "Setting Environment Variables" %}}
|
||||
Names must be prefixed with `HUGO_` and the configuration key must be set in uppercase when setting operating system environment variables.
|
||||
{{% /note %}}
|
||||
|
||||
## Ignore Files When Rendering
|
||||
|
||||
The following statement inside `./config.toml` will cause Hugo to ignore files ending with `.foo` and `.boo` when rendering:
|
||||
|
||||
```toml
|
||||
ignoreFiles = [ "\\.foo$", "\\.boo$" ]
|
||||
```
|
||||
|
||||
The above is a list of regular expressions. Note that the backslash (`\`) character is escaped in this example to keep TOML happy.
|
||||
|
||||
## Configure Blackfriday
|
||||
|
||||
[Blackfriday](https://github.com/russross/blackfriday) is Hugo's built-in Markdown rendering engine.
|
||||
|
||||
Hugo typically configures Blackfriday with sane default values that should fit most use cases reasonably well.
|
||||
|
||||
However, if you have specific needs with respect to Markdown, Hugo exposes some of its Blackfriday behavior options for you to alter. The following table lists these Hugo options, paired with the corresponding flags from Blackfriday's source code ( [html.go](https://github.com/russross/blackfriday/blob/master/html.go) and [markdown.go](https://github.com/russross/blackfriday/blob/master/markdown.go)).
|
||||
|
||||
{{< readfile file="/content/readfiles/bfconfig.md" markdown="true" >}}
|
||||
|
||||
{{% note %}}
|
||||
1. Blackfriday flags are *case sensitive* as of Hugo v0.15.
|
||||
2. Blackfriday flags must be grouped under the `blackfriday` key and can be set on both the site level *and* the page level. Any setting on a page will override its respective site setting.
|
||||
{{% /note %}}
|
||||
|
||||
{{% code file="bf-config.toml" %}}
|
||||
```toml
|
||||
[blackfriday]
|
||||
angledQuotes = true
|
||||
fractions = false
|
||||
plainIDAnchors = true
|
||||
extensions = ["hardLineBreak"]
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
{{% code file="bf-config.yml" %}}
|
||||
```yaml
|
||||
blackfriday:
|
||||
angledQuotes: true
|
||||
fractions: false
|
||||
plainIDAnchors: true
|
||||
extensions:
|
||||
- hardLineBreak
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
## Configure Additional Output Formats
|
||||
|
||||
Hugo v0.20 introduced the ability to render your content to multiple output formats (e.g., to JSON, AMP html, or CSV). See [Output Formats][] for information on how to add these values to your Hugo project's configuration file.
|
||||
|
||||
## Configuration Format Specs
|
||||
|
||||
* [TOML Spec][toml]
|
||||
* [YAML Spec][yaml]
|
||||
* [JSON Spec][json]
|
||||
|
||||
[`.Site.Params`]: /variables/site/
|
||||
[directory structure]: /getting-started/directory-structure
|
||||
[json]: /documents/ecma-404-json-spec.pdf
|
||||
[lookup order]: /templates/lookup-order/
|
||||
[Output Formats]: /templates/output-formats/
|
||||
[templates]: /templates/
|
||||
[toml]: https://github.com/toml-lang/toml
|
||||
[yaml]: http://yaml.org/spec/
|
||||
82
docs/content/getting-started/directory-structure.md
Normal file
82
docs/content/getting-started/directory-structure.md
Normal file
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: Directory Structure
|
||||
linktitle: Directory Structure
|
||||
description: Hugo's CLI scaffolds a project directory structure and then takes that single directory and uses it as the input to create a complete website.
|
||||
date: 2017-01-02
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-03-09
|
||||
categories: [getting started,fundamentals]
|
||||
#tags: [source, organization, directories]
|
||||
menu:
|
||||
docs:
|
||||
parent: "getting-started"
|
||||
weight: 50
|
||||
weight: 50
|
||||
sections_weight: 50
|
||||
draft: false
|
||||
aliases: [/overview/source-directory/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
## New Site Scaffolding
|
||||
|
||||
Running the `hugo new site` generator from the command line will create a directory structure with the following elements:
|
||||
|
||||
```bash
|
||||
.
|
||||
├── archetypes
|
||||
├── config.toml
|
||||
├── content
|
||||
├── data
|
||||
├── layouts
|
||||
├── static
|
||||
└── themes
|
||||
```
|
||||
|
||||
|
||||
## Directory Structure Explained
|
||||
|
||||
The following is a high-level overview of each of the directories with links to each of their respective sections with in the Hugo docs.
|
||||
|
||||
[`archetypes`](/content-management/archetypes/)
|
||||
: You can create new content files in Hugo using the `hugo new` command.
|
||||
By default, hugo will create new content files with at least `date`, `title` (inferred from the file name), and `draft = true`. This saves time and promotes consistency for sites using multiple content types. You can create your own [archetypes][] with custom preconfigured front matter fields as well.
|
||||
|
||||
[`config.toml`](/getting-started/configuration/)
|
||||
: Every Hugo project should have a configuration file in TOML, YAML, or JSON format at the root. Many sites may need little to no configuration, but Hugo ships with a large number of [configuration directives][] for more granular directions on how you want Hugo to build your website.
|
||||
|
||||
[`content`][]
|
||||
: All content for your website will live inside this directory. Each top-level folder in Hugo is considered a [content section][]. For example, if your site has three main sections---`blog`, `articles`, and `tutorials`---you will have three directories at `content/blog`, `content/articles`, and `content/tutorials`. Hugo uses sections to assign default [content types][].
|
||||
|
||||
[`data`](/templates/data-templates/)
|
||||
: This directory is used to store configuration files that can be
|
||||
used by Hugo when generating your website. You can write these files in YAML, JSON, or TOML format. In addition to the files you add to this folder, you can also create [data templates][] that pull from dynamic content.
|
||||
|
||||
[`layouts`][]
|
||||
: Stores templates in the form of `.html` files that specify how views of your content will be rendered into a static website. Templates include [list pages][lists], your [homepage][], [taxonomy templates][], [partials][], [single page templates][singles], and more.
|
||||
|
||||
`static`
|
||||
: stores all the static content for your future website: images, CSS, JavaScript, etc. When Hugo builds your site, all assets inside your static directory are copied over as-is. A good example of using the `static` folder is for [verifying site ownership on Google Search Console][searchconsole], where you want Hugo to copy over a complete HTML file without modifying its content.
|
||||
|
||||
{{% note %}}
|
||||
Hugo does not currently ship with an asset pipeline ([#3207](https://github.com/gohugoio/hugo/issues/3207)). You can solicit support from the community in the [Hugo forums](https://discourse.gohugo.io) or check out a few of the [Hugo starter kits](/tools/starter-kits/) for examples of how Hugo developers are managing static assets.
|
||||
{{% /note %}}
|
||||
|
||||
|
||||
[archetypes]: /content-management/archetypes/
|
||||
[configuration directives]: /getting-started/configuration/#all-variables-yaml
|
||||
[`content`]: /content-management/organization/
|
||||
[content section]: /content-management/sections/
|
||||
[content types]: /content-management/types/
|
||||
[data templates]: /templates/data-templates/
|
||||
[homepage]: /templates/homepage/
|
||||
[`layouts`]: /templates/
|
||||
[lists]: /templates/list/
|
||||
[pagevars]: /variables/page/
|
||||
[partials]: /templates/partials/
|
||||
[searchconsole]: https://support.google.com/analytics/answer/1142414?hl=en
|
||||
[singles]: /templates/single-page-templates/
|
||||
[starters]: /tools/starter-kits/
|
||||
[taxonomies]: /content-management/taxonomies/
|
||||
[taxonomy templates]: /templates/taxonomy-templates/
|
||||
[types]: /content-management/types/
|
||||
502
docs/content/getting-started/installing.md
Normal file
502
docs/content/getting-started/installing.md
Normal file
@@ -0,0 +1,502 @@
|
||||
---
|
||||
title: Install Hugo
|
||||
linktitle: Install Hugo
|
||||
description: Install Hugo on macOS, Windows, Linux, FreeBSD, and on any machine where the Go compiler tool chain can run.
|
||||
date: 2016-11-01
|
||||
publishdate: 2016-11-01
|
||||
lastmod: 2017-02-20
|
||||
categories: [getting started,fundamentals]
|
||||
authors: ["Michael Henderson"]
|
||||
#tags: [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:
|
||||
|
||||
* <i class="icon-apple"></i> macOS (Darwin) for x64, i386, and ARM architectures
|
||||
* <i class="icon-windows"></i> Windows
|
||||
* <i class="icon-linux"></i> Linux
|
||||
* <i class="icon-freebsd"></i> FreeBSD
|
||||
|
||||
Hugo may also be compiled from source wherever the Go compiler tool chain can run; e.g., on other operating systems such as DragonFly BSD, OpenBSD, Plan 9, Solaris, and others. See <https://golang.org/doc/install/source> 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" %}}
|
||||
```bash
|
||||
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" %}}
|
||||
```powershell
|
||||
choco install hugo -confirm
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
### Source
|
||||
|
||||
#### Prerequisite Tools
|
||||
|
||||
* [Git][installgit]
|
||||
* [Go 1.5+][installgo]
|
||||
* [govendor][]
|
||||
|
||||
#### Vendored Dependencies
|
||||
|
||||
Hugo uses [govendor][] 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. *You must use `govendor` to fetch Hugo's dependencies.*
|
||||
|
||||
#### Fetch from GitHub
|
||||
|
||||
{{% code file="from-gh.sh" %}}
|
||||
```sh
|
||||
go get github.com/kardianos/govendor
|
||||
govendor get github.com/gohugoio/hugo
|
||||
go install github.com/gohugoio/hugo
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
`govendor get` will fetch Hugo and all its dependent libraries to `$GOPATH/src/github.com/gohugoio/hugo`, and `go install` compiles everything into a final `hugo` (or `hugo.exe`) executable inside `$GOPATH/bin/`.
|
||||
|
||||
{{% note %}}
|
||||
If you are a Windows user, substitute the `$HOME` environment variable above with `%USERPROFILE%`.
|
||||
{{% /note %}}
|
||||
|
||||
## <i class="icon-apple"></i>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
|
||||
|
||||
#### Step 1: Install `brew` if you haven't already
|
||||
|
||||
Go to the `brew` website, <https://brew.sh/>, and follow the directions there. The most important step is the installation from the command line:
|
||||
|
||||
{{% code file="install-brew.sh" %}}
|
||||
```bash
|
||||
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" %}}
|
||||
```bash
|
||||
brew install hugo
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
If Homebrew is working properly, you should see something similar to the following:
|
||||
|
||||
```sh
|
||||
==> 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:
|
||||
|
||||
```bash
|
||||
$ # 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 <https://github.com/gohugoio/hugo/releases> 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:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
nano ~/.bash_profile
|
||||
```
|
||||
|
||||
Add a line to update your `PATH` variable:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
brew install go
|
||||
```
|
||||
|
||||
#### Step 1: Get the Source
|
||||
|
||||
If you want to compile a specific version of Hugo, go to <https://github.com/gohugoio/hugo/releases> 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
go build -o hugo main.go
|
||||
```
|
||||
|
||||
Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo.
|
||||
|
||||
## <i class="icon-windows"></i>Windows
|
||||
|
||||
The following aims to be a complete guide to installing Hugo on your Windows PC.
|
||||
|
||||
### 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.
|
||||
|
||||
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 <kbd>Enter</kbd> 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 <i class="fa fa-windows"></i> 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 <kbd>Enter</kbd> key. You should see output that starts with:
|
||||
|
||||
```powershell
|
||||
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.
|
||||
|
||||
```powershell
|
||||
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.
|
||||
|
||||
```powershell
|
||||
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:
|
||||
|
||||
```powershell
|
||||
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 <DIR> .
|
||||
04/13/2015 10:44 PM <DIR> ..
|
||||
04/13/2015 10:44 PM <DIR> archetypes
|
||||
04/13/2015 10:44 PM 83 config.toml
|
||||
04/13/2015 10:44 PM <DIR> content
|
||||
04/13/2015 10:44 PM <DIR> data
|
||||
04/13/2015 10:44 PM <DIR> layouts
|
||||
04/13/2015 10:44 PM <DIR> 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 >}}
|
||||
|
||||
## <i class="icon-linux"></i>Linux
|
||||
|
||||
### Debian and Ubuntu
|
||||
|
||||
In any of the [Linux distributions that support snaps](https://snapcraft.io/docs/core/install):
|
||||
|
||||
```sh
|
||||
sudo apt install hugo
|
||||
```
|
||||
|
||||
#### Pros
|
||||
|
||||
* Native Debian/Ubuntu package maintained by Debian Developers
|
||||
* Pre-installed bash completion script and `man` pages
|
||||
|
||||
#### Cons
|
||||
|
||||
* Might not be the latest version, especially if you are using an older, stable version (e.g., Ubuntu 16.04 LTS). Until backports and PPA are available, you may consider installing the Hugo snap package to get the latest version of Hugo, as described below.
|
||||
|
||||
### Arch
|
||||
|
||||
You can also install Hugo from the [Arch user repository](https://aur.archlinux.org/) on Arch Linux or derivatives such as Manjaro.
|
||||
|
||||
Be aware that Hugo is built from source. This means that additional tools like [Git](https://git-scm.com) and [Go](https://golang.org/doc/install) will be installed as well.
|
||||
|
||||
```bash
|
||||
sudo pacman -S yaourt
|
||||
yaourt -S hugo
|
||||
```
|
||||
|
||||
### Fedora, CentOS, and Red Hat
|
||||
|
||||
* <https://copr.fedorainfracloud.org/coprs/spf13/Hugo/> (updated to Hugo v0.16)
|
||||
* <https://copr.fedorainfracloud.org/coprs/daftaupe/hugo/> (updated to Hugo v0.22); usually released a few days after the official Hugo release.
|
||||
|
||||
See the [related discussion in the Hugo forums][redhatforum].
|
||||
|
||||
### Snap Package
|
||||
|
||||
In any of the [Linux distributions that support snaps][snaps]:
|
||||
|
||||
```bash
|
||||
snap install hugo
|
||||
```
|
||||
|
||||
{{% 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).
|
||||
{{% /note %}}
|
||||
|
||||
## Upgrade Hugo
|
||||
|
||||
Upgrading Hugo is as easy as downloading and replacing the executable you’ve placed in your `PATH`.
|
||||
|
||||
## 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
|
||||
[govendor]: https://github.com/kardianos/govendor
|
||||
[highlight shortcode]: /content-management/shortcodes/#highlight
|
||||
[installgit]: http://git-scm.com/
|
||||
[installgo]: https://golang.org/dl/
|
||||
[Path Editor]: https://patheditor2.codeplex.com/
|
||||
[pygments]: https://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
|
||||
[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/
|
||||
574
docs/content/getting-started/quick-start.md
Normal file
574
docs/content/getting-started/quick-start.md
Normal file
@@ -0,0 +1,574 @@
|
||||
---
|
||||
title: Quick Start
|
||||
linktitle: Quick Start
|
||||
description: Build an online bookshelf that taps into Hugo's CLI, directory structure, configuration, and theming.
|
||||
date: 2013-07-01
|
||||
publishdate: 2013-07-01
|
||||
lastmod: 2017-06-22
|
||||
categories: [getting started]
|
||||
#tags: [quick start,usage]
|
||||
authors: [Shekhar Gulati, Ryan Watters]
|
||||
menu:
|
||||
docs:
|
||||
parent: "getting-started"
|
||||
weight: 10
|
||||
weight: 10
|
||||
sections_weight: 10
|
||||
draft: false
|
||||
aliases: [/overview/quickstart/]
|
||||
toc: true
|
||||
wip: true
|
||||
---
|
||||
|
||||
{{% note %}}
|
||||
This Quick Start was originally written by [Shekhar Gulati](https://twitter.com/shekhargulati) in his [52 Technologies in 2016](https://github.com/shekhargulati/52-technologies-in-2016) blog series but has been heavily modified to represent additional features and other changes to Hugo.
|
||||
{{% /note %}}
|
||||
|
||||
In this Quick Start, we will build an online bookshelf that lists books and their reviews.
|
||||
|
||||
## Step 1. Install Hugo
|
||||
|
||||
[Install Hugo][install]. If installing from [Hugo releases][releases], you'll need to save the main executable as `hugo` (or `hugo.exe` on Windows) somewhere in your `PATH`. You will need the `hugo` command in the following steps.
|
||||
|
||||
{{% note "Windows Users and Git Bash" %}}
|
||||
If you're on Windows, this Quick Start will assume you're using [Git Bash](https://git-for-windows.github.io/) (aka Git for Windows).
|
||||
{{% /note %}}
|
||||
|
||||
Once `hugo` is installed, make sure to run the `help` command to verify `hugo` installation. The following is an abridged version of what will write to the console when entering the command:
|
||||
|
||||
```bash
|
||||
hugo help
|
||||
|
||||
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 http://gohugo.io/.
|
||||
```
|
||||
|
||||
You can check the version of Hugo you're currently using with the `hugo version` command:
|
||||
|
||||
```bash
|
||||
hugo version
|
||||
```
|
||||
|
||||
```bash
|
||||
Hugo Static Site Generator v0.18.1 BuildDate: 2016-12-30T05:02:43-05:00
|
||||
```
|
||||
|
||||
## Step 2. Scaffold Your Hugo Bookshelf Website
|
||||
|
||||
Hugo's CLI has commands that allow you to quickly scaffold a new website. Navigate to your preferred location on your file system and create a new Hugo site `bookshelf` by executing the `hugo new` command:
|
||||
|
||||
```bash
|
||||
hugo new site bookshelf
|
||||
```
|
||||
|
||||
Change into the newly created `bookshelf` directory. Listing the new directory's content will show the following:
|
||||
|
||||
```bash
|
||||
.
|
||||
├── archetypes
|
||||
├── config.toml
|
||||
├── content
|
||||
├── data
|
||||
├── layouts
|
||||
├── static
|
||||
└── themes
|
||||
|
||||
6 directories, 1 file
|
||||
```
|
||||
|
||||
You'll see the `bookshelf` directory has 6 subdirectories and 1 file. Let's look at each of them quickly. (See [Directory Structure][hugodirectories].)
|
||||
|
||||
* `archetypes`: [Archetypes][archetypes] allow you to preconfigure [front matter][fm] for content files for easier scaffolding of content from the command line using `hugo new`.
|
||||
* `config.toml`: Hugo uses `.toml` as its default configuration format but also accepts `.yml` and `.json`. The configuration settings mentioned in the `config.toml` are applied to the full website an include important global variables such as the `baseURL` and `title` of your website. (See [Configuration][configuration].)
|
||||
* `content`: This single directory houses all of the content for your website. Each subdirectory in content is considered a [section][]. If your website has sections for posts, events, and tutorials, you would create `content/posts`, `content/events`, and `content/tutorials`.
|
||||
* `data`: This directory is used to store files of serialized data (YAML, TOML, or JSON) that can be used in [data templates][datatemplates] and your [website's menu][sitemenu].
|
||||
* `layouts`: This is the hub for all your [templating][templating], including [list and section templates](/templates/lists/) and [shortcodes](/templates/shortcode-templates/).
|
||||
* `static`: This houses all your static content; i.e., images, JavaScript, and CSS. Everything in `/static` is copied over *as is* to your finished website.
|
||||
* `themes`: This is where you will download themes for Hugo. You can see a showcase of all themes at <http://themes.gohugo.io>.
|
||||
|
||||
## Step 3. Add Content
|
||||
|
||||
Let's now add a post to our "bookshelf." We will use the `hugo new` command to add a post. This first post will be on the book [*Good To Great*][bookurl]. Make sure you are inside the `bookshelf` directory.
|
||||
|
||||
{{% code file="create-new-book-review-post.sh" %}}
|
||||
```bash
|
||||
hugo new post/good-to-great.md
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
You should then see the following output:
|
||||
|
||||
```bash
|
||||
/Users/yourusername/bookshelf/content/post/good-to-great.md created
|
||||
```
|
||||
|
||||
The above command will create a new directory `post` inside the `content` directory and create `content/post/good-to-great.md`. The directory for your Hugo project will now look like the following:
|
||||
|
||||
```bash
|
||||
.
|
||||
├── archetypes
|
||||
├── config.toml
|
||||
├── content
|
||||
│ └── post
|
||||
│ └── good-to-great.md
|
||||
├── data
|
||||
├── layouts
|
||||
├── static
|
||||
└── themes
|
||||
```
|
||||
|
||||
Open `good-to-great.md` in your preferred text editor:
|
||||
|
||||
```toml
|
||||
+++
|
||||
date = "2017-02-19T21:09:05-06:00"
|
||||
title = "good to great"
|
||||
draft = true
|
||||
|
||||
+++
|
||||
```
|
||||
|
||||
The text bracketed by `+++` is the TOML [front matter][fm] for the content. Front matter enables you to define embedded metadata that travels with the content file. Since we have not configured any [archetypes][archetypes] for our project, Hugo has used its built-in base archetype, which includes the following three values in the front matter:
|
||||
|
||||
* `date` specifies the date and time at which post was created from the command line
|
||||
* `title` specifies the title for the post, which Hugo will infer from the file name
|
||||
* `draft`, when set to `true`, tells Hugo the content is not yet ready to be published
|
||||
|
||||
Let's update `good-to-great.md` with a short review of *Good to Great*:
|
||||
|
||||
{{% code file="good-to-great-start.md" %}}
|
||||
```markdown
|
||||
+++
|
||||
date = "2016-02-14T16:11:58+05:30"
|
||||
draft = true
|
||||
title = "Good to Great Book Review"
|
||||
+++
|
||||
|
||||
I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great. Although this book is about how companies became great but we could apply a lot of the learnings on ourselves. Concepts like level 5 leader, hedgehog concept, the stockdale paradox are equally applicable to individuals.
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
## Step 4. Serve Content
|
||||
|
||||
Hugo has a built-in server that can serve your website locally for easy previewing and development. To serve content, execute the following command inside the `bookshelf` directory:
|
||||
|
||||
```bash
|
||||
hugo server
|
||||
```
|
||||
|
||||
You should see something similar to the following output:
|
||||
|
||||
```bash
|
||||
Built site for language en:
|
||||
0 of 1 draft rendered
|
||||
0 future content
|
||||
0 expired content
|
||||
0 regular pages created
|
||||
1 other pages created
|
||||
0 non-page files copied
|
||||
0 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
total in 1 ms
|
||||
Watching for changes in /Users/yourusername/bookshelf/{data,content,layouts,static}
|
||||
Serving pages from memory
|
||||
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
This will start the server on port `1313`. You can view your blog at <http://localhost:1313/>. However, when you go to the link, you will see nothing. This is for a couple reasons:
|
||||
|
||||
1. As you can see in the `hugo server` command output, Hugo did *not* render the draft. Hugo will only render drafts if you pass the `buildDrafts` flag to the `hugo server` command.
|
||||
2. We have not specified how Markdown content should be rendered. We need to create our own layouts via templates or specify a theme, the latter of which we will do in the next step.
|
||||
|
||||
Kill the server using <kbd>Ctrl</kbd> + <kbd>C</kbd> and then rerun the server with the `--buildDrafts` flag appended to the command:
|
||||
|
||||
```bash
|
||||
hugo server --buildDrafts
|
||||
```
|
||||
|
||||
You should now see something similar to the following:
|
||||
|
||||
```bash
|
||||
Built site for language en:
|
||||
1 of 1 draft rendered
|
||||
0 future content
|
||||
0 expired content
|
||||
1 regular pages created
|
||||
2 other pages created
|
||||
0 non-page files copied
|
||||
0 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
total in 2 ms
|
||||
Watching for changes in /Users/yourusername/bookshelf/{data,content,layouts,static}
|
||||
Serving pages from memory
|
||||
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
Okay, so we now have our single page "built," but we're not seeing anything in the browser at <http://localhost:1313>. This was only to demonstrate the utility of the `--buildDrafts` flag.
|
||||
|
||||
While we are getting closer, we still need to specific a theme for Hugo to use when building our site.
|
||||
|
||||
## Step 5. Add A Theme
|
||||
|
||||
[Themes][themessection] provide Hugo with layout and templates to render your website. You can see the full selection of open-source themes at <http://themes.gohugo.io>.
|
||||
|
||||
{{% note "No Default Hugo Theme" %}}
|
||||
Hugo currently doesn’t ship with a default theme, thus allowing end users to pick whichever theme best suits their projects.
|
||||
{{% /note %}}
|
||||
|
||||
Themes should be added in the `themes` directory, one of the directories scaffolded with the `hugo new site` command we used to start our Hugo project. To install our themes, first change into the `themes` directory:
|
||||
|
||||
```bash
|
||||
cd themes
|
||||
```
|
||||
|
||||
You can clone one or more themes from within the `themes` directory. We will use the [Robust theme][robusttheme] but at the most recent commit as of this Quick Start's last update.
|
||||
|
||||
Once inside the `themes` directory, you can use the following one-liner to clone Robust, check out the specific commit, and then return to your project's root directory:
|
||||
|
||||
{{% code file="clone-robust-theme" %}}
|
||||
```bash
|
||||
git clone https://github.com/dim0627/hugo_theme_robust.git && cd hugo_theme_robust && git checkout 3baae29 && cd ../..
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Now let's start Hugo's server again but with the addition of the `-theme` flag for Robust:
|
||||
|
||||
{{% code file="hugo-server-with-theme.sh" %}}
|
||||
```bash
|
||||
hugo server --theme=hugo_theme_robust --buildDrafts
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
You should see an output to the console similar to the following:
|
||||
|
||||
```bash
|
||||
Built site for language en:
|
||||
1 of 1 draft rendered
|
||||
0 future content
|
||||
0 expired content
|
||||
1 regular pages created
|
||||
2 other pages created
|
||||
0 non-page files copied
|
||||
2 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
total in 8 ms
|
||||
Watching for changes in /Users/yourusername/bookshelf/{data,content,layouts,static,themes}
|
||||
Serving pages from memory
|
||||
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
If Hugo doesn't find the specified theme in the `themes` directory,
|
||||
it will throw an exception:
|
||||
|
||||
```bash
|
||||
FATAL: 2016/02/14 Unable to find theme Directory: /Users/yourusername/bookshelf/themes/robust
|
||||
```
|
||||
|
||||
To view your website, you can go to <http://localhost:1313/>. You should see something similar to the following image:
|
||||
|
||||
|
||||
|
||||
Similar to the way we looked at the scaffolding for our new Hugo website, let's take a look at what comprises a typical Hugo theme. The following is only a selection of what you would see if you were to list out the contents of the Robust theme directory. These are also some of the default files created by Hugo as of v0.23. (See [Creating a Theme][createtheme])
|
||||
|
||||
```bash
|
||||
.
|
||||
├── LICENSE.md
|
||||
├── archetypes
|
||||
│ └── default.md
|
||||
├── layouts
|
||||
│ ├── 404.html
|
||||
│ ├── _default
|
||||
│ │ ├── list.html
|
||||
│ │ └── single.html
|
||||
│ ├── index.html
|
||||
│ └── partials
|
||||
│ ├── footer.html
|
||||
│ └── header.html
|
||||
├── static
|
||||
│ ├── css
|
||||
│ └── js
|
||||
└── theme.toml
|
||||
```
|
||||
|
||||
* `theme.toml` is the theme configuration file that provides information about the theme; e.g., theme name, theme description, theme author, theme license, and minimum Hugo version, which will default to your locally installed version of Hugo.
|
||||
* `layouts` contains different views (i.e., [templates][templating]) for different content types. In this quick start, we see that each content type has a `single.html` and `list.html`. `single.html` is used for rendering a single piece of content. `list.html` is used to view a list of content items. For example, you will use `list.html` to view `*.md` in the posts [section][listsectiontemplates]. Think of `list.html` as `example.com/posts` and `single.html` as `example.com/posts/my-single-post/`.
|
||||
* `static` has the same purpose as that of the `static` in our original scaffolding. This directory stores all the static assets used by the theme and is copied over *as is* at build time.
|
||||
|
||||
## Step 6. Use Multiple Themes
|
||||
|
||||
You can very easily switch between different themes in Hugo. Let's suppose we want to try out the [`bleak` theme][bleaktheme]. Kill the Hugo server if you are still running it from the command line.
|
||||
|
||||
From your project root, you can use this one-liner to change into `themes`, clone Bleak, and go back to your project's root directory:
|
||||
|
||||
{{% code file="clone-bleak-theme.sh" %}}
|
||||
```bash
|
||||
cd themes && git clone https://github.com/Zenithar/hugo-theme-bleak.git && cd ..
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Now restart the server with our new theme flag:
|
||||
|
||||
{{% code file="run-server-with-bleak.sh" %}}
|
||||
```bash
|
||||
hugo server --theme=hugo-theme-bleak --buildDrafts
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Our website is now using the `bleak` theme at <http://localhost:1313>, which should look similar to the following screenshot:
|
||||
|
||||
|
||||
|
||||
## Step 7. Update Your Configuration
|
||||
|
||||
Kill the Hugo server if you are still running it with the Bleak theme, and then restart the server with the `robust` theme. We will use Robust for the duration of this Quick Start:
|
||||
|
||||
{{% code file="restart-with-robust-sh" %}}
|
||||
```bash
|
||||
hugo server --theme=hugo_theme_robust --buildDrafts
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
### Update Our `config.toml`
|
||||
|
||||
Our website is currently using the dummy values specified in `bookshelf/config.toml`, which were auto-generated with `hugo new site bookshelf`. Let's update the configuration:
|
||||
|
||||
{{% code file="updated-config.toml" %}}
|
||||
```toml
|
||||
baseURL = "http://example.org/"
|
||||
languageCode = "en-us"
|
||||
title = "Shekhar Gulati Book Reviews"
|
||||
|
||||
[Params]
|
||||
Author = "Shekhar Gulati"
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
### Watch Your Site Reload Instantly
|
||||
|
||||
Hugo has built-in support for LiveReload. This means that Hugo will rebuild and reload your site every time you save a change to content, templates, static assets, and even your configuration. You should see something similar to the following screenshot at <http://localhost:1313> once you save the above changes to your `config.toml`:
|
||||
|
||||
|
||||
|
||||
The change is also reflected in the console. As soon as you changed the configuration file, Hugo applied those changes to the affected pages and rebuilt the site:
|
||||
|
||||
```
|
||||
Config file changed: /Users/yourusername/bookshelf/config.toml
|
||||
Started building sites ...
|
||||
Built site for language en:
|
||||
1 of 1 draft rendered
|
||||
0 future content
|
||||
0 expired content
|
||||
1 regular pages created
|
||||
2 other pages created
|
||||
0 non-page files copied
|
||||
2 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
total in 20 ms
|
||||
```
|
||||
|
||||
## Step 8. Customize the Robust Theme
|
||||
|
||||
The `robust` theme is a good start towards our online bookshelf, but we want to customize it a bit to meet our desired look and feel. Hugo makes it very easy to [customize existing themes or create your own][themes] themes as well. For the purpose of the Quick Start, we will focus on customization.
|
||||
|
||||
The first change that we have to make is to use a different default image instead of the one used in the theme. The theme's default image used in both the `list.html` and `single.html` views resides inside `themes/hugo_theme_robust/static/images/default.jpg`. We can easily override it by creating a simple directory structure inside our repository's `static` directory.
|
||||
|
||||
Create an images directory inside of `bookshelf/static` and copy an image with name `default.jpg` inside of it. We will use the default image shown below.
|
||||
|
||||
|
||||
|
||||
Hugo will sync the changes and reload the website to use the new image:
|
||||
|
||||
|
||||
|
||||
Now we need to change the layout of the index page so that only images are shown instead of the text. The file at `themes/hugo_theme_robust/layouts/index.html` refers to a partial `li.html` template that renders the following list view:
|
||||
|
||||
```html
|
||||
<article class="li">
|
||||
<a href="{{ .Permalink }}" class="clearfix">
|
||||
<div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
|
||||
<div class="detail">
|
||||
<time>{{ with .Site.Params.DateForm }}{{ $.Date.Format . }}{{ else }}{{ $.Date.Format "Mon, Jan 2, 2006" }}{{ end }}</time>
|
||||
<h2 class="title">{{ .Title }}</h2>
|
||||
<div class="summary">{{ .Summary }}</div>
|
||||
</div>
|
||||
</a>
|
||||
</article>
|
||||
```
|
||||
|
||||
Create a new file for `li.html` inside the `bookshelf/layouts/_default` directory. If you are in your project root, you can use the following one-liner to both create the file and return to the project root:
|
||||
|
||||
{{% code file="create-new-li-html.sh" %}}
|
||||
```bash
|
||||
cd layouts && mkdir _default && cd _default && touch li.html && cd ../..
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Copy the content shown below into the new `li.html`. When contrasting this with the `li.html` that ships with the Robust theme, you'll notice we have removed details of the book so that only the image is shown:
|
||||
|
||||
{{% code file="layouts/_default/li.html" %}}
|
||||
```html
|
||||
<article class="li">
|
||||
<a href="{{ .Permalink }}" class="clearfix">
|
||||
<div class="image" style="background-image: url({{ $.Site.BaseURL }}images/{{ with .Params.image }}{{ . }}{{ else }}default.jpg{{ end }});"></div>
|
||||
</a>
|
||||
</article>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Now, the website should render similar to the following screenshot:
|
||||
|
||||
|
||||
|
||||
Next, we want to remove information related to the theme from the footer. Let's create a new directory at `bookshelf/layouts/partials`. This will hold our new file called `default_foot.html`.
|
||||
|
||||
This is a new [partial template][partials]. If you are still in the project's root directory, you can use the following one-liner to create the partial before returning to the project root:
|
||||
|
||||
{{% code file="create-new-default-foot.sh" %}}
|
||||
```bash
|
||||
cd layouts && mkdir partials && cd partials && touch default_foot.html && cd ../..
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Now add the following to our new `default_foot.html` partial template:
|
||||
|
||||
{{% code file="layouts/partials/default_foot.html" %}}
|
||||
```html
|
||||
<footer class="site">
|
||||
<p>{{ with .Site.Copyright | safeHTML }}{{ . }}{{ else }}© {{ $.Site.LastChange.Year }} {{ if isset $.Site.Params "Author" }}{{ $.Site.Params.Author }}{{ else }}{{ .Site.Title }}{{ end }}{{ end }}</p>
|
||||
<p>Powered by <a href="http://gohugo.io" target="_blank">Hugo</a>,</p>
|
||||
</footer>
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
So far we are using the default image, but we would like to use the book image so that we can relate to the book. Every book review will define a configuration setting in its front matter. Update the content and front matter of `good-to-great.md` as shown below.
|
||||
|
||||
{{% code file="content/post/good-to-great.md" %}}
|
||||
```markdown
|
||||
+++
|
||||
date = "2017-02-19T21:09:05-06:00"
|
||||
draft = true
|
||||
title = "Good to Great Book Review"
|
||||
image = "good-to-great.jpg"
|
||||
+++
|
||||
|
||||
I read **Good to Great in January 2016**. An awesome read sharing detailed analysis on how good companies became great. Although this book is about how companies became great but we could apply a lot of the learnings on ourselves. Concepts like level 5 leader, hedgehog concept, the stockdale paradox are equally applicable to individuals.
|
||||
```
|
||||
{{% /code %}}
|
||||
|
||||
Grab a (legal) image from somewhere, name it `good-to-great.jpg`, and place it in the `bookshelf/static/images` directory.
|
||||
|
||||
After adding a few more books to our shelf, the shelf appears as shown below.
|
||||
|
||||
|
||||
|
||||
|
||||
## Step 9. Make Your Posts Public
|
||||
|
||||
So far, all the posts that we have written are in draft status (i.e., `draft = true`). To make a draft public, you can run a Hugo CLI command or manually change the draft status in the post's front matter to `false`. Hugo provides a handy command line argument called `undraft` to do this for us:
|
||||
|
||||
```bash
|
||||
hugo undraft content/post/good-to-great.md
|
||||
```
|
||||
|
||||
If we check the front matter of `good-to-great.md` after running this command, we'll notice that Hugo has written the change of draft status to the file:
|
||||
|
||||
```toml
|
||||
+++
|
||||
date = "2017-02-19T22:42:53-06:00"
|
||||
draft = false
|
||||
title = "Good to Great Book Review"
|
||||
image = "good-to-great.jpg"
|
||||
+++
|
||||
```
|
||||
|
||||
Now, we can start the server *without* the `buildDrafts` option.
|
||||
|
||||
```bash
|
||||
hugo server --theme=hugo_theme_robust
|
||||
```
|
||||
|
||||
<!-- ## Step 10. Integrate Disqus Comments
|
||||
|
||||
{{% note "Adding Disqus to Your Website" %}}
|
||||
To implement Disqus comments as part of the Quick Start, you'll need to set up a Disqus account. Follow the [Disqus documentation for adding their service to websites](https://help.disqus.com/customer/portal/articles/1257441-adding-disqus-to-your-site).
|
||||
{{% /note %}}
|
||||
|
||||
To enable Disqus on our new site, we only need to update the `disqusShortname` in the config.toml as shown below.
|
||||
|
||||
```toml
|
||||
[Params]
|
||||
Author = "Shekhar Gulati"
|
||||
disqusShortname = <your disqus shortname>
|
||||
```
|
||||
|
||||
Now, commenting will be enabled in your blog.
|
||||
|
||||
|
||||
-->
|
||||
## Step 10. Build Your Website
|
||||
|
||||
To generate a website that can be deployed to GitHub pages, we first need to change the `baseURL` in our configuration as follows:
|
||||
|
||||
```toml
|
||||
baseURL = "https://<yourgithubusername>.github.io/bookshelf/"
|
||||
```
|
||||
|
||||
Then type the following command while in the root directory of your Hugo project:
|
||||
|
||||
```bash
|
||||
hugo --theme=hugo_theme_robust
|
||||
0 draft content
|
||||
0 future content
|
||||
5 pages created
|
||||
2 paginator pages created
|
||||
0 tags created
|
||||
0 categories created
|
||||
in 17 ms
|
||||
```
|
||||
|
||||
After you run the `hugo` command, a `bookshelf/public` directory will be created containing the generated website source.
|
||||
|
||||
## Step 11. What Next?
|
||||
|
||||
**Congratulations!** Your new `bookshelf`/public directory is a fully generated, deployable Hugo website. Since all your files are *static*, you have innumerable options for hosting, and your new directory structure and simple content format are going to make scaling your website a breeze.
|
||||
|
||||
Here's what you should look into next:
|
||||
|
||||
1. [See hosting and deployment options][hostinganddeploy] for sharing your newly created Hugo website with the world.
|
||||
2. [Learn more about Hugo's powerful templating][templating] to tailor your new Hugo website to your specific needs and keep it scaling accordingly.
|
||||
3. [Visit the Hugo Discussion Forum][forum] to ask questions, answer questions, and become an active member of the Hugo community.
|
||||
|
||||
[archetypes]: /content-management/archetypes/
|
||||
[bookurl]: https://www.amazon.com/Good-Great-Some-Companies-Others/dp/0066620996/
|
||||
[bleaktheme]: http://themes.gohugo.io/bleak/
|
||||
[configuration]: /getting-started/configuration/
|
||||
[createtheme]: /themes/creating/
|
||||
[datatemplates]: /templates/data-templates/
|
||||
[forum]: https://discourse.gohugo.io
|
||||
[fm]: /content-management/front-matter/
|
||||
[hostinganddeploy]: /hosting-and-deployment/
|
||||
[hugodirectories]: /getting-started/directory-structure/
|
||||
[install]: /getting-started/installing/
|
||||
[lists]: /templating/lists/
|
||||
[partials]: /templates/partials/
|
||||
[quickinstall]: /getting-started/installing/#quick-install
|
||||
[releases]: https://github.com/gohugoio/hugo/releases
|
||||
[robusttheme]: https://github.com/dim0627/hugo_theme_robust
|
||||
[section]: /content-management/sections/
|
||||
[sectiontemplates]: /templates/section-templates/
|
||||
[shortcodetemplates]: /templates/shortcode-templates/
|
||||
[sitemenu]: /content-management/menus/
|
||||
[templating]: /templates/introduction/
|
||||
[themessection]: /themes/
|
||||
[themes]: /themes/
|
||||
228
docs/content/getting-started/usage.md
Normal file
228
docs/content/getting-started/usage.md
Normal file
@@ -0,0 +1,228 @@
|
||||
---
|
||||
title: Basic Usage
|
||||
linktitle: Basic Usage
|
||||
description: Hugo's CLI is fully featured but simple to use, even for those who have very limited experience working from the command line.
|
||||
date: 2017-02-01
|
||||
publishdate: 2017-02-01
|
||||
lastmod: 2017-02-01
|
||||
categories: [getting started]
|
||||
#tags: [usage,livereload,command line,flags]
|
||||
menu:
|
||||
docs:
|
||||
parent: "getting-started"
|
||||
weight: 40
|
||||
weight: 40
|
||||
sections_weight: 40
|
||||
draft: false
|
||||
aliases: [/overview/usage/,/extras/livereload/,/doc/usage/,/usage/]
|
||||
toc: true
|
||||
---
|
||||
|
||||
The following is a description of the most command commands you will use while developing your Hugo project. See the [Command Line Reference][commands] for a comprehensive view of Hugo's CLI.
|
||||
|
||||
## Test Installation
|
||||
|
||||
Once you have [installed Hugo][install], make sure it is in your `PATH`. You can test that Hugo has been installed correctly via the `help` command:
|
||||
|
||||
```bash
|
||||
hugo help
|
||||
```
|
||||
|
||||
The output you see in your console should be similar to the following:
|
||||
|
||||
```bash
|
||||
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 http://gohugo.io/.
|
||||
|
||||
Usage:
|
||||
hugo [flags]
|
||||
hugo [command]
|
||||
|
||||
Available Commands:
|
||||
benchmark Benchmark Hugo by building a site a number of times.
|
||||
check Contains some verification checks
|
||||
config Print the site configuration
|
||||
convert Convert your content to different formats
|
||||
env Print Hugo version and environment info
|
||||
gen A collection of several useful generators.
|
||||
help Help about any command
|
||||
import Import your site from others.
|
||||
list Listing out various types of content
|
||||
new Create new content for your site
|
||||
server A high performance webserver
|
||||
undraft Undraft changes the content's draft status from 'True' to 'False'
|
||||
version Print the version number of Hugo
|
||||
|
||||
Flags:
|
||||
-b, --baseURL string hostname (and path) to the root, e.g. http://spf13.com/
|
||||
-D, --buildDrafts include content marked as draft
|
||||
-E, --buildExpired include expired content
|
||||
-F, --buildFuture include content with publishdate in the future
|
||||
--cacheDir string filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
|
||||
--canonifyURLs if true, all relative URLs will be canonicalized using baseURL
|
||||
--cleanDestinationDir remove files from destination not found in static directories
|
||||
--config string config file (default is path/config.yaml|json|toml)
|
||||
-c, --contentDir string filesystem path to content directory
|
||||
-d, --destination string filesystem path to write files to
|
||||
--disable404 do not render 404 page
|
||||
--disableKinds stringSlice disable different kind of pages (home, RSS etc.)
|
||||
--disableRSS do not build RSS files
|
||||
--disableSitemap do not build Sitemap file
|
||||
--enableGitInfo add Git revision, date and author info to the pages
|
||||
--forceSyncStatic copy all files when static is changed.
|
||||
-h, --help help for hugo
|
||||
--i18n-warnings print missing translations
|
||||
--ignoreCache ignores the cache directory
|
||||
-l, --layoutDir string filesystem path to layout directory
|
||||
--log enable Logging
|
||||
--logFile string log File path (if set, logging enabled automatically)
|
||||
--noChmod don't sync permission mode of files
|
||||
--noTimes don't sync modification time of files
|
||||
--pluralizeListTitles pluralize titles in lists using inflect (default true)
|
||||
--preserveTaxonomyNames preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
|
||||
--quiet build in quiet mode
|
||||
--renderToMemory render to memory (only useful for benchmark testing)
|
||||
-s, --source string filesystem path to read files relative from
|
||||
--stepAnalysis display memory and timing of different steps of the program
|
||||
-t, --theme string theme to use (located in /themes/THEMENAME/)
|
||||
--themesDir string filesystem path to themes directory
|
||||
--uglyURLs if true, use /filename.html instead of /filename/
|
||||
-v, --verbose verbose output
|
||||
--verboseLog verbose logging
|
||||
-w, --watch watch filesystem for changes and recreate as needed
|
||||
```
|
||||
|
||||
## The `hugo` Command
|
||||
|
||||
The most common usage is probably to run `hugo` with your current directory being the input directory.
|
||||
|
||||
This generates your website to the `public/` directory by default, although you can customize the output directory in your [site configuration][config] by changing the `publishDir` field.
|
||||
|
||||
The site Hugo renders into `public/` is ready to be deployed to your web server:
|
||||
|
||||
```bash
|
||||
hugo
|
||||
0 draft content
|
||||
0 future content
|
||||
99 pages created
|
||||
0 paginator pages created
|
||||
16 tags created
|
||||
0 groups created
|
||||
in 90 ms
|
||||
```
|
||||
|
||||
## Draft, Future, and Expired Content
|
||||
|
||||
Hugo allows you to set `draft`, `publishdate`, and even `expirydate` in your content's [front matter][]. By default, Hugo will not publish:
|
||||
|
||||
1. Content with a future `publishdate` value
|
||||
2. Content with `draft: true` status
|
||||
3. Content with a past `expirydate` value
|
||||
|
||||
All three of these can be overridden during both local development *and* deployment by adding the following flags to `hugo` and `hugo server`, respectively, or by changing the boolean values assigned to the fields of the same name (without `--`) in your [configuration][config]:
|
||||
|
||||
1. `--buildFuture`
|
||||
2. `--buildDrafts`
|
||||
3. `--buildExpired`
|
||||
|
||||
## LiveReload
|
||||
|
||||
Hugo comes with [LiveReload](https://github.com/livereload/livereload-js) built in. There are no additional packages to install. A common way to use Hugo while developing a site is to have Hugo run a server with the `hugo server` command and watch for changes:
|
||||
|
||||
```bash
|
||||
hugo server
|
||||
0 draft content
|
||||
0 future content
|
||||
99 pages created
|
||||
0 paginator pages created
|
||||
16 tags created
|
||||
0 groups created
|
||||
in 120 ms
|
||||
Watching for changes in /Users/yourname/sites/yourhugosite/{data,content,layouts,static}
|
||||
Serving pages from /Users/yourname/sites/yourhugosite/public
|
||||
Web Server is available at http://localhost:1313/
|
||||
Press Ctrl+C to stop
|
||||
```
|
||||
|
||||
This will run a fully functioning web server while simultaneously watching your file system for additions, deletions, or changes within the following areas of your [project organization][dirs]:
|
||||
|
||||
* `/static/*`
|
||||
* `/content/*`
|
||||
* `/data/*`
|
||||
* `/i18n/*`
|
||||
* `/layouts/*`
|
||||
* `/themes/<CURRENT-THEME>/*`
|
||||
* `config`
|
||||
|
||||
Whenever you make changes, Hugo will simultaneously rebuild the site and continue to serve content. As soon as the build is finished, LiveReload tells the browser to silently reload the page.
|
||||
|
||||
Most Hugo builds are so fast that you may not notice the change unless looking directly at the site in your browser. This means that keeping the site open on a second monitor (or another half of your current monitor) allows you to see the most up-to-date version of your website without the need to leave your text editor.
|
||||
|
||||
{{% note "Closing `</body>` Tag"%}}
|
||||
Hugo injects the LiveReload `<script>` before the closing `</body>` in your templates and will therefore not work if this tag is not present..
|
||||
{{% /note %}}
|
||||
|
||||
### Disable LiveReload
|
||||
|
||||
LiveReload works by injecting JavaScript into the pages Hugo generates. The script creates a connection from the browser's web socket client to the Hugo web socket server.
|
||||
|
||||
LiveReload is awesome for development. However, some Hugo users may use `hugo server` in production to instantly display updated content. The following methods make it easy to disable LiveReload:
|
||||
|
||||
```bash
|
||||
hugo server --watch=false
|
||||
```
|
||||
|
||||
Or...
|
||||
|
||||
```bash
|
||||
hugo server --disableLiveReload
|
||||
```
|
||||
|
||||
The latter flag can be omitted by adding the following key-value to your `config.toml` or `config.yml` file, respectively:
|
||||
|
||||
```toml
|
||||
disableLiveReload = true
|
||||
```
|
||||
|
||||
```yaml
|
||||
disableLiveReload: true
|
||||
```
|
||||
|
||||
## Deploy Your Website
|
||||
|
||||
After running `hugo server` for local web development, you need to do a final `hugo` run *without the `server` part of the command* to rebuild your site. You may then deploy your site by copying the `public/` directory to your production web server.
|
||||
|
||||
Since Hugo generates a static website, your site can be hosted *anywhere* using any web server. See [Hosting and Deployment][hosting] for methods for hosting and automating deployments contributed by the Hugo community.
|
||||
|
||||
{{% warning "Generated Files are **NOT** Removed on Site Build" %}}
|
||||
Running `hugo` *does not* remove generated files before building. This means that you should delete your `public/` directory (or the publish directory you specified via flag or configuration file) before running the `hugo` command. If you do not remove these files, you run the risk of the wrong files (e.g., drafts or future posts) being left in the generated site.
|
||||
{{% /warning %}}
|
||||
|
||||
### Dev vs Deploy Destinations
|
||||
|
||||
Hugo does not remove generated files before building. An easy workaround is to use different directories for development and production.
|
||||
|
||||
To start a server that builds draft content (helpful for editing), you can specify a different destination; e.g., a `dev/` directory:
|
||||
|
||||
```bash
|
||||
hugo server -wDs ~/Code/hugo/docs -d dev
|
||||
```
|
||||
|
||||
When the content is ready for publishing, use the default `public/` dir:
|
||||
|
||||
```bash
|
||||
hugo -s ~/Code/hugo/docs
|
||||
```
|
||||
|
||||
This prevents draft content from accidentally becoming available.
|
||||
|
||||
[commands]: /commands/
|
||||
[config]: /getting-started/configuration/
|
||||
[dirs]: /getting-started/directory-structure/
|
||||
[front matter]: /content-management/front-matter/
|
||||
[hosting]: /hosting-and-deployment/
|
||||
[install]: /getting-started/installing/
|
||||
Reference in New Issue
Block a user