Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/hamoid/long-hugo-doc

The documentation of the Hugo static site generator in one long page. LOOKING FOR MAINTAINER. Look at forks for improvements.
https://github.com/hamoid/long-hugo-doc

Last synced: about 11 hours ago
JSON representation

The documentation of the Hugo static site generator in one long page. LOOKING FOR MAINTAINER. Look at forks for improvements.

Host: GitHub
URL: https://github.com/hamoid/long-hugo-doc
Owner: hamoid
Created: 2014-10-22T11:27:00.000Z (about 10 years ago)
Default Branch: master
Last Pushed: 2017-07-31T16:04:43.000Z (over 7 years ago)
Last Synced: 2024-04-15T14:14:58.186Z (7 months ago)
Language: Python
Homepage:
Size: 264 KB
Stars: 54
Watchers: 5
Forks: 8
Open Issues: 0
Metadata Files:
- Readme: README.md

Awesome Lists containing this project

README

This is the documentation of [Hugo](http://gohugo.io/) condensed into one long page. I did this to make the documentation easier to search and navigate. This page was automatically generated using a Python script using the documentation available at Hugo's GitHub repository.
# Index

## about

* Overview
* What is Hugo
* Hugo Features
* The Benefits of Static
* Roadmap
* License

## getting-started

* Get Started Overview
* Quick Start
* Install Hugo
* Basic Usage
* Directory Structure
* Configuration

## themes

* Themes Overview
* Install and Use Themes
* Customize a Theme
* Create a Theme

## content-management

* Content Management Overview
* Organization
* Supported Content Formats
* Front Matter
* Shortcodes
* Sections
* Authors
* Types
* Archetypes
* Taxonomies
* Summaries
* Cross References
* URL Management
* Menus
* Table of Contents
* Comments
* Multilingual and i18n

## templates

* Templates Overview
* Introduction
* Template Lookup Order
* Custom Output Formats
* Base Templates and Blocks
* List Page Templates
* List Ordering and Grouping
* Homepage Template
* Section Templates
* Taxonomy Templates
* Single Page Templates
* Content View Templates
* Data Templates
* Partial Templates
* Shortcode Templates
* Local File Templates
* 404 Page
* Menu Templates
* Pagination
* RSS Templates
* Sitemap Template
* Robots.txt
* Internal Templates
* Alternative Templating
* Template Debugging

## functions

* Functions Quick Reference
* with
* where
* urlize
* upper
* .Unix
* uniq
* union
* truncate
* trim
* title
* time
* substr
* string
* split
* sort
* slicestr
* slice
* singularize
* shuffle
* sha
* seq
* .Scratch
* safeURL
* safeJS
* safeHTMLAttr
* safeHTML
* safeCSS
* replaceRE
* replace
* render
* relURL
* relref
* relLangURL
* ref
* readFile
* readDir
* range
* querify
* printf
* pluralize
* plainify
* partialCached
* .Param
* now
* ne
* md5
* Math
* markdownify
* lt
* lower
* len
* le
* last
* jsonify
* isset
* .IsMenuCurrent
* intersect
* int
* index
* in
* imageConfig
* i18n
* humanize
* htmlUnescape
* htmlEscape
* highlight
* .HasMenuCurrent
* .HasChildren
* hasPrefix
* gt
* getenv
* .Get
* ge
* .Format
* first
* findRE
* eq
* emojify
* echoParam
* dict
* delimit
* default
* dateFormat
* countwords
* countrunes
* chomp
* base64
* apply
* after
* .AddDate
* absURL
* absLangURL
* lang.NumFmt
* .GetPage

## variables

* Variables Overview
* Site Variables
* Shortcode Variables
* Page Variables
* Taxonomy Variables
* File Variables
* Menu Variables
* Hugo Variables
* Git Variables
* Sitemap Variables

## commands

* CLI Overview
* "hugo version"
* "hugo undraft"
* "hugo server"
* "hugo new theme"
* "hugo new site"
* "hugo new"
* "hugo list future"
* "hugo list expired"
* "hugo list drafts"
* "hugo list"
* "hugo import jekyll"
* "hugo import"
* "hugo gen man"
* "hugo gen doc"
* "hugo gen autocomplete"
* "hugo gen"
* "hugo env"
* "hugo convert toYAML"
* "hugo convert toTOML"
* "hugo convert toJSON"
* "hugo convert"
* "hugo config"
* "hugo check ulimit"
* "hugo check"
* "hugo benchmark"
* "hugo"

## troubleshooting

* Troubleshoot
* EOF Error
* Build Performance
* Accented Characters in URLs

## tools

* Developer Tools Overview
* Migrations
* Syntax Highlighting
* Starter Kits
* Frontends
* Editor Plug-ins
* Search
* Other Projects

## hosting-and-deployment

* Hosting & Deployment Overview
* Host on Netlify
* Host on Firebase
* Host on GitHub
* Host on GitLab
* Host on Bitbucket
* Deployment with Wercker
* Deployment with Rysnc

## contribute

* Contribute to Hugo
* Development
* Documentation
* Themes

# About Hugo

Hugo is not your average static site generator.

# What is Hugo

Hugo is a general-purpose website framework. Technically speaking, Hugo is a [static site generator][]. Unlike systems that dynamically build a page with each visitor request, Hugo builds pages when you create or update your content. Since websites are viewed far more often than they are edited, Hugo is designed to provide an optimal viewing experience for your website's end users and an ideal writing experience for website authors.

Websites built with Hugo are extremely fast and secure. Hugo sites can be hosted anywhere, including [Netlify][], [Heroku][], [GoDaddy][], [DreamHost][], [GitHub Pages][], [Surge][], [Aerobatic][], [Firebase][], [Google Cloud Storage][], [Amazon S3][], [Rackspace][], [Azure][], and [CloudFront][] and work well with CDNs. Hugo sites run without the need for a database or dependencies on expensive runtimes like Ruby, Python, or PHP.

We think of Hugo as the ideal website creation tool with nearly instant build times, able to rebuild whenever a change is made.

## How Fast is Hugo?

## What Does Hugo Do?

In technical terms, Hugo takes a source directory of files and templates and uses these as input to create a complete website.

## Who Should Use Hugo?

Hugo is for people that prefer writing in a text editor over a browser.

Hugo is for people who want to hand code their own website without worrying about setting up complicated runtimes, dependencies and databases.

Hugo is for people building a blog, a company site, a portfolio site, documentation, a single landing page, or a website with thousands of pages.

[@spf13]: https://twitter.com/@spf13
[Aerobatic]: https://www.aerobatic.com/
[Amazon S3]: http://aws.amazon.com/s3/
[Azure]: https://blogs.msdn.microsoft.com/acoat/2016/01/28/publish-a-static-web-site-using-azure-web-apps/
[CloudFront]: http://aws.amazon.com/cloudfront/ "Amazon CloudFront"
[contributing to it]: https://github.com/gohugoio/hugo
[DreamHost]: http://www.dreamhost.com/
[Firebase]: https://firebase.google.com/docs/hosting/ "Firebase static hosting"
[GitHub Pages]: https://pages.github.com/
[GitLab]: https://about.gitlab.com
[Go language]: https://golang.org/
[GoDaddy]: https://www.godaddy.com/ "Godaddy.com Hosting"
[Google Cloud Storage]: http://cloud.google.com/storage/
[Heroku]: https://www.heroku.com/
[Jekyll]: http://jekyllrb.com/
[Jekyll]: https://jekyllrb.com/
[Middleman]: https://middlemanapp.com/
[Middleman]: https://middlemanapp.com/
[Nanoc]: http://nanoc.ws/
[Nanoc]: https://nanoc.ws/
[Netlify]: https://netlify.com
[rackspace]: https://www.rackspace.com/cloud/files
[static site generator]: /about/benefits/
[Rackspace]: https://www.rackspace.com/cloud/files
[static site generator]: /about/benefits/
[Surge]: https://surge.sh

# Hugo Features

## General

* [Extremely fast][] build times (< 1 ms per page)
* Completely cross platform, with [easy installation][install] on macOS, Linux, Windows, and more
* Renders changes on the fly with [LiveReload][] as you develop
* [Powerful theming][]
* [Host your site anywhere][hostanywhere]

## Organization

* Straightforward [organization for your projects][], including website sections
* Customizable [URLs][]
* Support for configurable [taxonomies][], including categories and tags
* [Sort content][] as you desire through powerful template [functions][]
* Automatic [table of contents][] generation
* [Dynamic menu][] creation
* [Pretty URLs][] support
* [Permalink][] pattern support
* Redirects via [aliases][]

## Content

* Native Markdown and Emacs Org-Mode support, as well as other languages via *external helpers* (see [supported formats][])
* TOML, YAML, and JSON metadata support in [front matter][]
* Customizable [homepage][]
* Multiple [content types][]
* Automatic and user defined [content summaries][]
* [Shortcodes][] to enable rich content inside of Markdown
* ["Minutes to Read"][pagevars] functionality
* ["Wordcount"][pagevars] functionality

## Additional Features

* Integrated [Disqus][] comment support
* Integrated [Google Analytics][] support
* Automatic [RSS][] creation
* Support for [Go][], [Amber], and [Ace][] HTML templates
* [Syntax highlighting][] powered by [Pygments][]

See what's coming next in the [Hugo roadmap][].

[Ace]: /templates/alternatives/
[aliases]: /content-management/urls/#aliases
[Amber]: https://github.com/eknkc/amber
[content summaries]: /content-management/summaries/
[content types]: /content-management/types/
[Disqus]: https://disqus.com/
[Dynamic menu]: /templates/menus/
[Extremely fast]: https://github.com/bep/hugo-benchmark
[front matter]: /content-management/front-matter/
[functions]: /functions/
[Go]: http://golang.org/pkg/html/template/
[Google Analytics]: https://google-analytics.com/
[homepage]: /templates/homepage/
[hostanywhere]: /hosting-and-deployment/
[Hugo roadmap]: /about/roadmap
[install]: /getting-started/installing/
[LiveReload]: /getting-started/usage/
[organization for your projects]: /getting-started/directory-structure/
[pagevars]: /variables/page/
[Permalink]: /content-management/urls/#permalinks
[Powerful theming]: /themes/
[Pretty URLs]: /content-management/urls/
[Pygments]: http://pygments.org/
[RSS]: /templates/rss/
[Shortcodes]: /content-management/shortcodes/
[sort content]: /templates/
[supported formats]: /content-management/formats/
[Syntax highlighting]: /tools/syntax-highlighting/
[table of contents]: /content-management/toc/
[taxonomies]: /content-management/taxonomies/
[URLs]: /content-management/urls/

# The Benefits of Static Site Generators

The purpose of website generators is to render content into HTML files. Most are "dynamic site generators." That means the HTTP server---i.e., the program that sends files to the browser to be viewed---runs the generator to create a new HTML file every time an end user requests a page.

Over time, dynamic site generators were programmed to cache their HTML files to prevent unnecessary delays in delivering pages to end users. A cached page is a static version of a web page.

Hugo takes caching a step further and all HTML files are rendered on your computer. You can review the files locally before copying them to the computer hosting the HTTP server. Since the HTML files aren't generated dynamically, we say that Hugo is a *static site generator*.

This has many benefits. The most noticeable is performance. HTTP servers are *very* good at sending files---so good, in fact, that you can effectively serve the same number of pages with a fraction of the memory and CPU needed for a dynamic site.

## More on Static Site Generators

* ["An Introduction to Static Site Generators", David Walsh][]
* ["Hugo vs. Wordpress page load speed comparison: Hugo leaves WordPress in its dust", GettingThingsTech][hugovwordpress]
* ["Static Site Generators", O-Reilly][]
* [StaticGen: Top Open-Source Static Site Generators (GitHub Stars)][]
* ["Top 10 Static Website Generators", Netlify blog][]
* ["The Resurgence of Static", dotCMS][dotcms]

["An Introduction to Static Site Generators", David Walsh]: https://davidwalsh.name/introduction-static-site-generators
["Static Site Generators", O-Reilly]: /documents/oreilly-static-site-generators.pdf
["Top 10 Static Website Generators", Netlify blog]: https://www.netlify.com/blog/2016/05/02/top-ten-static-website-generators/
[hugovwordpress]: https://gettingthingstech.com/hugo-vs.-wordpress-page-load-speed-comparison-hugo-leaves-wordpress-in-its-dust/
[StaticGen: Top Open-Source Static Site Generators (GitHub Stars)]: https://www.staticgen.com/
[dotcms]: https://dotcms.com/blog/post/the-resurgence-of-static

# Roadmap

To track Hugo's progress, see our [GitHub Milestones][milestones].

In no particular order, here are some other features currently being worked on:

* Even easier deployment to S3, SSH, GitHub, rsync. Give the [hosting and deployment][] section a shot.
* Import from other website systems. There are already [existing migration tools][migrate], but they don’t cover all major platforms.
* An interactive web-based editor (See the [related forum thread][])
* Additional [themes][], which are always ongoing and [contributions are welcome][themescontrib]!
* Dynamic image resizing via shortcodes ({{< gh 1014 >}})
* Native support for additional content formats (AsciiDoc {{< gh 1435>}}, reST {{< gh 1436 >}})
* And, last but not least, [***your*** best ideas!][]

## Contributions Welcome

Feel free to [contribute to Hugo's development][devcontribute], [improve Hugo's documentation][doccontribute], or [open a new issue][newissue] if you have an idea for a new feature.

[#98]: https://github.com/gohugoio/hugo/issues/98
[#1014]: https://github.com/gohugoio/hugo/issues/1014
[#1435]: https://github.com/gohugoio/hugo/issues/1435
[#1436]: https://github.com/gohugoio/hugo/issues/1436
[devcontribute]: /contribute/development/
[doccontribute]: /contribute/documentation/
[hosting and deployment]: /hosting-and-deployment/
[migrate]: /tools/migrations/
[milestones]: https://github.com/gohugoio/hugo/milestone/14
[newissue]: https://github.com/gohugoio/hugo/issues/
[related forum thread]: https://discourse.gohugo.io/t/web-based-editor/155
[themes]: /themes/
[themescontrib]: /contribute/themes/
[tutorials]: /tutorials
[***your*** best ideas!]: /contribute/

# Apache License

{{% note %}}
Hugo v0.15 and later are released under the Apache 2.0 license.
Earlier versions of Hugo were released under the [Simple Public License](https://opensource.org/licenses/Simple-2.0).
{{% /note %}}

_Version 2.0, January 2004_

*Terms and Conditions for use, reproduction, and distribution*

## 1. Definitions

“License” shall mean the terms and conditions for use, reproduction, and
distribution as defined by Sections 1 through 9 of this document.

“Licensor” shall mean the copyright owner or entity authorized by the copyright
owner that is granting the License.

“Legal Entity” shall mean the union of the acting entity and all other entities
that control, are controlled by, or are under common control with that entity.
For the purposes of this definition, “control” means **(i)** the power, direct or
indirect, to cause the direction or management of such entity, whether by
contract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the
outstanding shares, or **(iii)** beneficial ownership of such entity.

“You” (or “Your”) shall mean an individual or Legal Entity exercising
permissions granted by this License.

“Source” form shall mean the preferred form for making modifications, including
but not limited to software source code, documentation source, and configuration
files.

“Object” form shall mean any form resulting from mechanical transformation or
translation of a Source form, including but not limited to compiled object code,
generated documentation, and conversions to other media types.

“Work” shall mean the work of authorship, whether in Source or Object form, made
available under the License, as indicated by a copyright notice that is included
in or attached to the work (an example is provided in the Appendix below).

“Derivative Works” shall mean any work, whether in Source or Object form, that
is based on (or derived from) the Work and for which the editorial revisions,
annotations, elaborations, or other modifications represent, as a whole, an
original work of authorship. For the purposes of this License, Derivative Works
shall not include works that remain separable from, or merely link (or bind by
name) to the interfaces of, the Work and Derivative Works thereof.

“Contribution” shall mean any work of authorship, including the original version
of the Work and any modifications or additions to that Work or Derivative Works
thereof, that is intentionally submitted to Licensor for inclusion in the Work
by the copyright owner or by an individual or Legal Entity authorized to submit
on behalf of the copyright owner. For the purposes of this definition,
“submitted” means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems, and
issue tracking systems that are managed by, or on behalf of, the Licensor for
the purpose of discussing and improving the Work, but excluding communication
that is conspicuously marked or otherwise designated in writing by the copyright
owner as “Not a Contribution.”

“Contributor” shall mean Licensor and any individual or Legal Entity on behalf
of whom a Contribution has been received by Licensor and subsequently
incorporated within the Work.

## 2. Grant of Copyright License

Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the Work and such
Derivative Works in Source or Object form.

## 3. Grant of Patent License

Subject to the terms and conditions of this License, each Contributor hereby
grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,
irrevocable (except as stated in this section) patent license to make, have
made, use, offer to sell, sell, import, and otherwise transfer the Work, where
such license applies only to those patent claims licensable by such Contributor
that are necessarily infringed by their Contribution(s) alone or by combination
of their Contribution(s) with the Work to which such Contribution(s) was
submitted. If You institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work or a
Contribution incorporated within the Work constitutes direct or contributory
patent infringement, then any patent licenses granted to You under this License
for that Work shall terminate as of the date such litigation is filed.

## 4. Redistribution

You may reproduce and distribute copies of the Work or Derivative Works thereof
in any medium, with or without modifications, and in Source or Object form,
provided that You meet the following conditions:

* **(a)** You must give any other recipients of the Work or Derivative Works a copy of
this License; and
* **(b)** You must cause any modified files to carry prominent notices stating that You
changed the files; and
* **\(c)** You must retain, in the Source form of any Derivative Works that You distribute,
all copyright, patent, trademark, and attribution notices from the Source form
of the Work, excluding those notices that do not pertain to any part of the
Derivative Works; and
* **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.

You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.

## 5. Submission of Contributions

Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.

## 6. Trademarks

This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.

## 7. Disclaimer of Warranty

Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.

## 8. Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.

## 9. Accepting Warranty or Additional Liability

While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.

_END OF TERMS AND CONDITIONS_

## APPENDIX: How to apply the Apache License to your work

To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets `[]` replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same “printed page” as the copyright notice for easier identification within third-party archives.

{{< code file="apache-notice.txt" download="apache-notice.txt" >}}
Copyright [yyyy] [name of copyright owner]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
{{< /code >}}

# Get Started

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/

# Quick Start

{{% note %}}
This quick start uses `macOS` in the examples. For instructions about how to install Hugo on other operating systems, see [install](#getting-started.installing.md).

You also need [Git installed](https://git-scm.com/downloads) to run this tutorial.
{{% /note %}}

## Step 1: Install Hugo

{{% note %}}
`Homebrew`, a package manager for `macOS`, can be installed from [brew.sh](https://brew.sh/). See [install](#getting-started.installing.md) if you are running Windows etc.
{{% /note %}}

```bash
brew install hugo
```

To verify your new install:

```bash
hugo version
```

## Step 2: Create a New Site

```bash
hugo new site quickstart
```

The above will create a new Hugo site in a folder named `quickstart`.

## Step 3: Add a Theme

See [themes.gohugo.io](https://themes.gohugo.io/) for a list of themes to consider. This quickstart uses the beautiful [Ananke theme](https://themes.gohugo.io/gohugo-theme-ananke/).

```bash
cd quickstart;\
git init;\
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke;\

# Edit your config.toml configuration file
# and add the Ananke theme.
echo 'theme = "ananke"' >> config.toml
```

## Step 4: Add Some Content

```
hugo new posts/my-first-post.md
```

Edit the newly created content file if you want. Now, start the Hugo server with [drafts](#getting-started.usage/#draft-future-and-expired-content.md) enabled:

```
▶ hugo server -D

Started building sites ...
Built site for language en:
1 of 1 draft rendered
0 future content
0 expired content
1 regular pages created
8 other pages created
0 non-page files copied
1 paginator pages created
0 categories created
0 tags created
total in 18 ms
Watching for changes in /Users/bep/sites/quickstart/{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
```

**Navigate to your new site at [http://localhost:1313/](http://localhost:1313/).**

## Step 5: Customize the Theme

Your new site already looks great, but you will want to tweak it a little before you release it to the public.

### Site Configuration

Open up `config.toml` in a text editor:

```
baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "ananke"
```

Replace the `title` above with something more personal. Also, if you already have a domain ready, set the `baseURL`. Note that this value is not needed when running the local development server.

{{% note %}}
**Tip:** Make the changes to the site configuration or any other file in your site while the Hugo server is running, and you will see the changes in the browser right away.
{{% /note %}}

For theme specific configuration options, see the [theme site](https://github.com/budparr/gohugo-theme-ananke).

**For further theme customization, see [Customize a Theme](#themes.customizing.md).**

## Recapitulation

# Install Hugo

{{% note %}}
There is lots of talk about "Hugo being written in Go", but you don't need to install Go to enjoy Hugo. Just grab a precompiled binary!
{{% /note %}}

Hugo is written in [Go](https://golang.org/) with support for multiple platforms. The latest release can be found at [Hugo Releases][releases].

Hugo currently provides pre-built binaries for the following:

* macOS (Darwin) for x64, i386, and ARM architectures
* Windows
* Linux
* 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 for the full set of supported combinations of target operating systems and compilation architectures.

## Quick Install

### Binary (Cross-platform)

Download the appropriate version for your platform from [Hugo Releases][releases]. Once downloaded, the binary can be run from anywhere. You don't need to install it into a global location. This works well for shared hosts and other systems where you don't have a privileged account.

Ideally, you should install it somewhere in your `PATH` for easy use. `/usr/local/bin` is the most probable location.

### Homebrew (macOS)

If you are on macOS and using [Homebrew][brew], you can install Hugo with the following one-liner:

{{< code file="install-with-homebrew.sh" >}}
brew install hugo
{{< /code >}}

For more detailed explanations, read the installation guides that follow for installing on macOS and Windows.

### Chocolatey (Windows)

If you are on a Windows machine and use [Chocolatey][] for package management, you can install Hugo with the following one-liner:

{{< code file="install-with-chocolatey.ps1" >}}
choco install hugo -confirm
{{< /code >}}

### 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" >}}
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 %}}

## 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, , and follow the directions there. The most important step is the installation from the command line:

{{< code file="install-brew.sh" >}}
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
{{< /code >}}

#### Step 2: Run the `brew` Command to Install `hugo`

Installing Hugo using `brew` is as easy as the following:

{{< code file="install-brew.sh" >}}
brew install hugo
{{< /code >}}

If Homebrew is working properly, you should see something similar to the following:

```
==> Downloading https://homebrew.bintray.com/bottles/hugo-0.21.sierra.bottle.tar.gz
######################################################################### 100.0%
==> Pouring hugo-0.21.sierra.bottle.tar.gz
🍺 /usr/local/Cellar/hugo/0.21: 32 files, 17.4MB
```

{{% note "Installing the Latest Hugo with Brew" %}}
Replace `brew install hugo` with `brew install hugo --HEAD` if you want the absolute latest in-development version.
{{% /note %}}

`brew` should have updated your path to include Hugo. You can confirm by opening a new terminal window and running a few commands:

```
$ # show the location of the hugo executable
which hugo
/usr/local/bin/hugo

# show the installed version
ls -l $( which hugo )
lrwxr-xr-x 1 mdhender admin 30 Mar 28 22:19 /usr/local/bin/hugo -> ../Cellar/hugo/0.13_1/bin/hugo

# verify that hugo runs correctly
hugo version
Hugo Static Site Generator v0.13 BuildDate: 2015-03-09T21:34:47-05:00
```

### Install Hugo from Tarball

#### Step 1: Decide on the location

When installing from the tarball, you have to decide if you're going to install the binary in `/usr/local/bin` or in your home directory. There are three camps on this:

1. Install it in `/usr/local/bin` so that all the users on your system have access to it. This is a good idea because it's a fairly standard place for executables. The downside is that you may need elevated privileges to put software into that location. Also, if there are multiple users on your system, they will all run the same version. Sometimes this can be an issue if you want to try out a new release.

2. Install it in `~/bin` so that only you can execute it. This is a good idea because it's easy to do, easy to maintain, and doesn't require elevated privileges. The downside is that only you can run Hugo. If there are other users on your site, they have to maintain their own copies. That can lead to people running different versions. Of course, this does make it easier for you to experiment with different releases.

3. Install it in your `Sites` directory. This is not a bad idea if you have only one site that you're building. It keeps every thing in a single place. If you want to try out new releases, you can make a copy of the entire site and update the Hugo executable.

All three locations will work for you. In the interest of brevity, this guide focuses on option #2.

#### Step 2: Download the Tarball

1. Open in your browser.

2. Find the current release by scrolling down and looking for the green tag that reads "Latest Release."

3. Download the current tarball for the Mac. The name will be something like `hugo_X.Y_osx-64bit.tgz`, where `X.YY` is the release number.

4. By default, the tarball will be saved to your `~/Downloads` directory. If you choose to use a different location, you'll need to change that in the following steps.

#### Step 3: Confirm your download

Verify that the tarball wasn't corrupted during the download:

```
tar tvf ~/Downloads/hugo_X.Y_osx-64bit.tgz
-rwxrwxrwx 0 0 0 0 Feb 22 04:02 hugo_X.Y_osx-64bit/hugo_X.Y_osx-64bit.tgz
-rwxrwxrwx 0 0 0 0 Feb 22 03:24 hugo_X.Y_osx-64bit/README.md
-rwxrwxrwx 0 0 0 0 Jan 30 18:48 hugo_X.Y_osx-64bit/LICENSE.md
```

The `.md` files are documentation for Hugo. The other file is the executable.

#### Step 4: Install Into Your `bin` Directory

```
# create the directory if needed
mkdir -p ~/bin

# make it the working directory
cd ~/bin

# extract the tarball
tar -xvzf ~/Downloads/hugo_X.Y_osx-64bit.tgz
Archive: hugo_X.Y_osx-64bit.tgz
x ./
x ./hugo
x ./LICENSE.md
x ./README.md

# verify that it runs
./hugo version
Hugo Static Site Generator v0.13 BuildDate: 2015-02-22T04:02:30-06:00
```

You may need to add your bin directory to your `PATH` variable. The `which` command will check for us. If it can find `hugo`, it will print the full path to it. Otherwise, it will not print anything.

```
# check if hugo is in the path
which hugo
/Users/USERNAME/bin/hugo
```

If `hugo` is not in your `PATH`, add it by updating your `~/.bash_profile` file. First, start up an editor:

```
nano ~/.bash_profile
```

Add a line to update your `PATH` variable:

```
export PATH=$PATH:$HOME/bin
```

Then save the file by pressing Control-X, then Y to save the file and return to the prompt.

Close the terminal and open a new terminal to pick up the changes to your profile. Verify your success by running the `which hugo` command again.

You've successfully installed Hugo.

### Build from Source on Mac

If you want to compile Hugo yourself, you'll need to install Go (aka Golang). You can [install Go directly from the Go website](https://golang.org/dl/) or via Homebrew using the following command:

```
brew install go
```

#### Step 1: Get the Source

If you want to compile a specific version of Hugo, go to and download the source code for the version of your choice. If you want to compile Hugo with all the latest changes (which might include bugs), clone the Hugo repository:

```
git clone https://github.com/gohugoio/hugo
```

{{% warning "Sometimes \"Latest\" = \"Bugs\""%}}
Cloning the Hugo repository directly means taking the good with the bad. By using the bleeding-edge version of Hugo, you make your development susceptible to the latest features, as well as the latest bugs. Your feedback is appreciated. If you find a bug in the latest release, [please create an issue on GitHub](https://github.com/gohugoio/hugo/issues/new).
{{% /warning %}}

#### Step 2: Compiling

Make the directory containing the source your working directory and then fetch Hugo's dependencies:

```
mkdir -p src/github.com/gohugoio
ln -sf $(pwd) src/github.com/gohugoio/hugo

# set the build path for Go
export GOPATH=$(pwd)

go get
```

This will fetch the absolute latest version of the dependencies. If Hugo fails to build, it may be the result of a dependency's author introducing a breaking change.

Once you have properly configured your directory, you can compile Hugo using the following command:

```
go build -o hugo main.go
```

Then place the `hugo` executable somewhere in your `$PATH`. You're now ready to start using Hugo.

## Windows

The following aims to be a complete guide to installing Hugo on your Windows PC.

### 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 Enter when you're done typing.
* Click OK at every window to exit.

{{% note "Path Editor in Windows 10"%}}
The path editor in Windows 10 was added in the large [November 2015 Update](https://blogs.windows.com/windowsexperience/2015/11/12/first-major-update-for-windows-10-available-today/). You'll need to have that or a later update installed for the above steps to work. You can see what Windows 10 build you have by clicking on the Start button → Settings → System → About. See [here](https://www.howtogeek.com/236195/how-to-find-out-which-build-and-version-of-windows-10-you-have/) for more.)
{{% /note %}}

#### For Windows 7 and 8.x users:

Windows 7 and 8.1 do not include the easy path editor included in Windows 10, so non-technical users on those platforms are advised to install a free third-party path editor like [Windows Environment Variables Editor][Windows Environment Variables Editor] or [Path Editor](https://patheditor2.codeplex.com/).

### Verify the Executable

Run a few commands to verify that the executable is ready to run, and then build a sample site to get started.

#### 1. Open a Command Prompt

At the prompt, type `hugo help` and press the Enter key. You should see output that starts with:

```
hugo is the main command, used to build your Hugo site.

Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.

Complete documentation is available at https://gohugo.io/.
```

If you do, then the installation is complete. If you don't, double-check the path that you placed the `hugo.exe` file in and that you typed that path correctly when you added it to your `PATH` variable. If you're still not getting the output, search the [Hugo discussion forum][forum] to see if others have already figured out our problem. If not, add a note---in the "Support" category---and be sure to include your command and the output.

At the prompt, change your directory to the `Sites` directory.

```
C:\Program Files> cd C:\Hugo\Sites
C:\Hugo\Sites>
```

#### 2. Run the Command

Run the command to generate a new site. I'm using `example.com` as the name of the site.

```
C:\Hugo\Sites> hugo new site example.com
```

You should now have a directory at `C:\Hugo\Sites\example.com`. Change into that directory and list the contents. You should get output similar to the following:

```
C:\Hugo\Sites>cd example.com
C:\Hugo\Sites\example.com>dir
Directory of C:\hugo\sites\example.com

04/13/2015 10:44 PM .
04/13/2015 10:44 PM ..
04/13/2015 10:44 PM archetypes
04/13/2015 10:44 PM 83 config.toml
04/13/2015 10:44 PM content
04/13/2015 10:44 PM data
04/13/2015 10:44 PM layouts
04/13/2015 10:44 PM static
1 File(s) 83 bytes
7 Dir(s) 6,273,331,200 bytes free
```

### Troubleshoot Windows Installation

[@dhersam][] has created a nice video on common issues:

## Linux

### Snap Package

In any of the [Linux distributions that support snaps][snaps]:

```
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 %}}

### Debian and Ubuntu

Debian and Ubuntu provide a `hugo` version via `apt-get`:

```
sudo apt-get 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.

### 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.

```
sudo pacman -S yaourt
yaourt -S hugo
```

### Fedora, CentOS, and Red Hat

* (updated to Hugo v0.16)
* (updated to Hugo v0.22); usually released a few days after the official Hugo release.

See the [related discussion in the Hugo forums][redhatforum].

## 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/

# Basic Usage

The following is a description of the most common 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:

```
hugo help
```

The output you see in your console should be similar to the following:

```
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:

```
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:

```
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//*`
* `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 `