hugo documentation by ======= ============= http://github.com/spf13/ table of contents hugo documentation table of contents chapter 1 -- What is Hugo? chapter 2 -- Hugo Quickstart Guide chapter 3 -- Installing Hugo chapter 4 -- Using Hugo chapter 5 -- Configuring Hugo chapter 6 -- Source Organization chapter 7 -- Content Organization chapter 8 -- Front Matter chapter 9 -- Sections chapter 10 -- Content Types chapter 11 -- Archetypes chapter 12 -- Ordering Content chapter 13 -- Example Content File chapter 14 -- Themes Overview chapter 15 -- Installing Themes chapter 16 -- Using a Theme chapter 17 -- Customizing a Theme chapter 18 -- Creating a Theme chapter 19 -- Hugo Templates chapter 20 -- Go Template Primer chapter 21 -- Hugo Template Functions chapter 22 -- Template Variables chapter 23 -- Single Content Template chapter 24 -- Content List Template chapter 25 -- Homepage chapter 26 -- Taxonomy Terms Template chapter 27 -- Content Views chapter 28 -- Partial Templates chapter 29 -- RSS (feed) Templates chapter 30 -- Sitemap Template chapter 31 -- 404.html Templates chapter 32 -- Taxonomy Overview chapter 33 -- Using Taxonomies chapter 34 -- Displaying Taxonomies chapter 35 -- Taxonomy Templates chapter 36 -- Ordering Taxonomies chapter 37 -- Aliases chapter 38 -- Hugo Builders chapter 39 -- Comments in Hugo chapter 40 -- Live Reload chapter 41 -- Menus chapter 42 -- Permalinks chapter 43 -- Shortcodes chapter 44 -- Syntax Highlighting chapter 45 -- Table of Contents chapter 46 -- URLs chapter 47 -- Mailing List chapter 48 -- Press, Blogs and Media Coverage chapter 49 -- Contributing to Hugo chapter 50 -- Hosting on GitHub Pages chapter 51 -- MathJax Support chapter 52 -- Migrate to Hugo from Jekyll chapter 53 -- License chapter 54 -- Hugo Roadmap chapter 55 -- Introduction to Hugo chapter 1 What is Hugo? Hugo is a general purpose website framework. Technically speaking, Hugo is a static site generator. This means that unlike systems like Wordpress, Ghost & Drupal which run on your web server expensively building a page every time a visitor requests one, Hugo does the building when you create your content. Since websites are viewed far more often then they are edited, Hugo is optimized for website viewing while providing a great writing experience. Sites built with hugo are extremely fast and very secure. Hugo sites can be hosted anywhere including Heroku, GoDaddy, GitHub pages, S3 & Cloudfront and work well with CDNs. Hugo sites run without dependencies on expensive run times like Ruby, Python or PHP and without dependencies on any databases. We think of Hugo as the ideal website creation tool. With nearly instant built times and the ability to rebuild whenever a change is made Hugo provides a very fast feedback loop. This is essential when you are designing websites, but also very useful when creating content. What does Hugo do? In technical terms Hugo takes a source directory of markdown files and templates and uses these as input to create a complete website. Hugo boasts the following features: General Extremely fast built times (~1ms per page) Completely cross platform: Runs on Mac OSX, Linux and Windows Easy installation Render changes on the fly with live reload as you develop Complete theme support Host your site anywhere Organization Straightforward organization Support for website sections Completely customizable urls Support for categories and tags Support for configurable taxonomies to create your own organization Ability to sort content as you desire Automatic table of contents generation Dynamic menu creation pretty urls support permalink pattern support Aliases (redirects) Content Content written in Markdown Support for TOML, YAML and JSON metadata in frontmatter Completely customizable homepage Support for multiple content types Automatic and user defined summaries shortcodes to enable rich content inside of markdown "Minutes to Read" functionality "Wordcount" functionality Additional Features Integrated Disqus comment support Automatic RSS creation Support for go and amber templates Syntax highlighting powered by pygments See what's coming next in the roadmap 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, company site, portfolio, tumblog, documentation, single page site or a site with thousands of pages. Why did you write Hugo? I wrote Hugo ultimately for a few reasons. First I was disappointed with wordpress, my then website solution. It rendered slowly. I couldn't create content as efficiently as I wanted to and needed to be online to write posts. The constant security updates and the horror stories of people's hacked blogs. I hated how content was written in HTML instead of the much simpler markdown. Overall I felt like it got in my way more than it helped my from writing great content. I looked at existing static site generators like Jekyll, Middle and Nanoc. All had complicated dependencies to install and took far longer to render my blog with hundreds of posts than I felt was acceptable. I wanted a framework to be able to get rapid feedback while making changes to the templates and the 5+ minute render times was just too slow. In general they were also very blog minded and didn't have the ability to have different content types and flexible urls. I wanted to develop a fast and full featured website framework without dependencies. The Go language seemed to have all of the features I needed in a language. I began developing Hugo in Go and fell in love with the language. I hope you will enjoy using (and contributing to) Hugo as much as I have writing it. Next Steps Install Hugo Quick start Join the Mailing List Star us on Github chapter 2 Hugo Quickstart Guide This quickstart depends on features introduced in hugo v0.11. If you have an earlier version of hugo you will need to upgrade before proceeding. Step 1. Install Hugo Goto hugo releases and download the appropriate version for your os and architecture. Save it somewhere specific as we will be using it in the next step. More complete instructions are available at installing hugo Step 2. Have Hugo Create a site for you Hugo has the ability to create a skeleton site. hugo new site /path/to/site For the rest of the operations we will be executing all commands from within the site directory cd /path/to/site The new site will have the following structure ▸ archetypes/ ▸ content/ ▸ layouts/ ▸ static/ config.toml Currently the site doesn't have any content, nor is it configured. Step 3. Create Some Content Hugo also has the ability to create content for you. hugo new about.md A new file is now created in content/ with the following contents +++ draft = true title = "about" date = 2014-05-20T10:04:31Z +++ Notice the date is automatically set to the moment you created the content. Place some content in this file below the +++ in the markdown format. For example you could put this ## A headline Some Content For fun, let's create another piece of content and place some markdown in it as well. hugo new post/first.md The new file is located at content/post/first.md We still lack any templates to tell us how to display the content. Step 4. Install some themes Hugo has rich theme support and a growing set of themes to choose from. git clone --recursive https://github.com/spf13/hugoThemes themes Step 5. Run Hugo Hugo contains it's own high performance web server. Simply run hugo server and Hugo will find an available port and run a server with your content hugo server --theme=hyde --buildDrafts 2 pages created 0 tags created 0 categories created in 5 ms Serving pages from exampleHugoSite/public Web Server is available at http://localhost:1313 Press ctrl+c to stop We specified two options here. -theme to pick which theme. -buildDrafts because we want to display our content, both set to draft status To learn about what other options hugo has run hugo help To learn about the server options hugo help server Step 6. Edit Content Not only can Hugo run a server, but it can also watch your files for changes and automatically rebuild your site. Hugo will then communicate with your browser and automatically reload any open page. This even works in mobile browsers. Stop the Hugo process by hitting ctrl+c. Then run the following: hugo server --theme=hyde --buildDrafts --watch 2 pages created 0 tags created 0 categories created in 5 ms Watching for changes in exampleHugoSite/content Serving pages from exampleHugoSite/public Web Server is available at http://localhost:1313 Press ctrl+c to stop Open your favorite editor, edit and save your content and watch as Hugo rebuilds and reloads automatically. It's especially productive to leave a browser open on a second monitor and just glance at it whenever you save. You don't even need to tab to your browser. Hugo is so fast, that the new site will be there before you can look at the browser in most cases. Change and save this file.. Notice what happened in your terminal. Change detected, rebuilding site 2 pages created 0 tags created 0 categories created in 5 ms Step 7. Have fun The best way to learn something is to play with it. Things to try: Add a new content file Create a new section Modify a template Create content with toml front matter Define your own field in front matter Display that field in the template Create a new content type chapter 3 Installing Hugo Hugo is written in Go with support for Windows, Linux, FreeBSD and OSX. The latest release can be found at hugo releases. We currently build for Windows, Linux, FreeBSD and OS X for x64 and 386 architectures. Installing Hugo (binary) Installation is very easy. Simply download the appropriate version for your platform from hugo releases. Once downloaded it 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. Installing pygments (optional) The Hugo executable has one optional external dependency for source code highlighting (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 home page. Upgrading Hugo Upgrading hugo is as easy as downloading and replacing the executable you've placed in your path. Installing from source Dependencies Git Go 1.1+ Mercurial Bazaar Get directly from Github: go get github.com/spf13/hugo Building Hugo cd /path/to/hugo go build -o hugo main.go mv hugo /usr/local/bin/ Contributing Please see the contributing guide chapter 4 Using Hugo Make sure either hugo is in your path or provide a path to it. $ hugo help A Fast and Flexible Static Site Generator built with love by spf13 and friends in Go. Complete documentation is available at http://hugo.spf13.com Usage: hugo [flags] hugo [command] Available Commands: server :: Hugo runs it's own a webserver to render the files version :: Print the version number of Hugo check :: Check content in the source directory benchmark :: Benchmark hugo by building a site a number of times new [path] :: Create new content for your site help [command] :: Help about any command Available Flags: -b, --baseUrl="": hostname (and path) to the root eg. http://spf13.com/ -D, --buildDrafts=false: build content marked as draft -F, --buildFuture=false: build content with PublishDate in the future --config="": config file (default is path/config.yaml|json|toml) -d, --destination="": filesystem path to write files to --disableRSS=false: Do not build RSS files --disableSitemap=false: Do not build Sitemap file --log=false: Enable Logging --logFile="": Log File path (if set, logging enabled automatically) -s, --source="": filesystem path to read files relative from --stepAnalysis=false: display memory and timing of different steps of the program -t, --theme="": theme to use (located in /themes/THEMENAME/) --uglyUrls=false: if true, use /filename.html instead of /filename/ -v, --verbose=false: verbose output --verboseLog=false: verbose logging -w, --watch=false: watch filesystem for changes and recreate as needed Use "hugo help [command]" for more information about that command. Common Usage Example: The most common use is probably to run hugo with your current directory being the input directory. $ hugo > X pages created in 8 ms If you are working on things and want to see the changes immediately, tell Hugo to watch for changes. Hugo will watch the filesystem for changes, rebuild your site as soon as a file is saved. $ hugo -s ~/mysite --watch 28 pages created in 18 ms Watching for changes in /Users/spf13/Code/hugo/docs/content Press ctrl+c to stop Hugo can even run a server and create your site at the same time! Hugo implements live reload technology to automatically reload any open pages in all browsers (including mobile). $ hugo server -ws ~/mysite Watching for changes in /Users/spf13/Code/hugo/docs/content Web Server is available at http://localhost:1313 Press ctrl+c to stop 28 pages created 0 tags created in 18 ms chapter 5 Configuring Hugo The directory structure and templates provide the majority of the configuration for a site. In fact a config file isn't even needed for many websites since the defaults follow commonly used patterns. Hugo expects to find the config file in the root of the source directory and will look there first for a config.toml file. If none is present it will then look for a config.yaml file, followed by a config.json file. The config file is a site-wide config. The config file provides directions to hugo on how to build the site as well as site-wide parameters and menus. Examples The following is an example of a typical yaml config file: --- baseurl: "http://yoursite.example.com/" ... The following is an example of a toml config file with some of the default values: contentdir = "content" layoutdir = "layouts" publishdir = "public" builddrafts = false baseurl = "http://yoursite.example.com/" canonifyurls = true [indexes] category = "categories" tag = "tags" Here is a yaml configuration file which sets a few more options --- baseurl: "http://yoursite.example.com/" title: "Yoyodyne Widget Blogging" permalinks: post: /:year/:month/:title/ params: Subtitle: "Spinning the cogs in the widgets" AuthorName: "John Doe" GitHubUser: "spf13" ListOfFoo: - "foo1" - "foo2" SidebarRecentLimit: 5 ... chapter 6 Source Organization Hugo takes a single directory and uses it as the input for creating a complete website. The top level of a source directory will typically have the following elements: ▸ archetypes/ ▸ content/ ▸ layouts/ ▸ static/ ▸ themes/ config.toml Learn more about the different directories and what their purpose is config archetypes content layouts [static]() themes Example An example directory may look like: . ├── config.toml ├── archetypes | └── default.md ├── content | ├── post | | ├── firstpost.md | | └── secondpost.md | └── quote | | ├── first.md | | └── second.md ├── layouts | ├── _default | | ├── single.html | | └── list.html | ├── partials | | ├── header.html | | └── footer.html | ├── taxonomies | | ├── category.html | | ├── post.html | | ├── quote.html | | └── tag.html | ├── post | | ├── li.html | | ├── single.html | | └── summary.html | ├── quote | | ├── li.html | | ├── single.html | | └── summary.html | ├── shortcodes | | ├── img.html | | ├── vimeo.html | | └── youtube.html | ├── index.html | └── sitemap.xml ├── themes | ├── hyde | └── doc └── static ├── css └── js This directory structure tells us a lot about this site: the website intends to have two different types of content, posts and quotes. It will also apply two different indexes to that content, categories and tags. It will be displaying content in 3 different views, a list, a summary and a full page view. chapter 7 Content Organization Hugo uses markdown files with headers commonly called the front matter. Hugo respects the organization that you provide for your content to minimize any extra configuration, though this can be overridden by additional configuration in the front matter. Organization In Hugo the content should be arranged in the same way they are intended for the rendered website. Without any additional configuration the following will just work. Hugo supports content nested at any level. The top level is special in Hugo and is used as the section. . └── content ├── post | ├── firstpost.md // <- http://1.com/post/firstpost/ | ├── happy | | └── ness.md // <- http://1.com/post/happy/ness/ | └── secondpost.md // <- http://1.com/post/secondpost/ └── quote ├── first.md // <- http://1.com/quote/first/ └── second.md // <- http://1.com/quote/second/ Here's the same organization run with hugo --uglyurls . └── content ├── post | ├── firstpost.md // <- http://1.com/post/firstpost.html | ├── happy | | └── ness.md // <- http://1.com/post/happy/ness.html | └── secondpost.md // <- http://1.com/post/secondpost.html └── quote ├── first.md // <- http://1.com/quote/first.html └── second.md // <- http://1.com/quote/second.html Destinations Hugo thinks that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site. As displayed above, the organization of the source content will be mirrored in the destination. There are times when one would need more control over their content. In these cases there are a variety of things that can be specified in the front matter to determine the destination of a specific piece of content. The following items are defined in order, latter items in the list will override earlier settings. filename This isn't in the front matter, but is the actual name of the file minus the extension. This will be the name of the file in the destination. slug Defined in the front matter, the slug can take the place of the filename for the destination. filepath The actual path to the file on disk. Destination will create the destination with the same path. Includes section. section section can be provided in the front matter overriding the section derived from the source content location on disk. See section. path path can be provided in the front matter. This will replace the actual path to the file on disk. Destination will create the destination with the same path. Includes section. url A complete url can be provided. This will override all the above as it pertains to the end destination. This must be the path from the baseurl (starting with a "/"). When a url is provided it will be used exactly. Using url will ignore the --uglyurls setting. Path breakdown in hugo Content . path slug . ⊢-------^----⊣ ⊢------^-------⊣ content/extras/indexes/category-example/index.html . section slug . ⊢--^--⊣ ⊢------^-------⊣ content/extras/indexes/category-example/index.html . section slug . ⊢--^--⊣⊢--^--⊣ content/extras/indexes/index.html Destination permalink ⊢--------------^-------------⊣ http://spf13.com/projects/hugo baseUrl section slug ⊢-----^--------⊣ ⊢--^---⊣ ⊢-^⊣ http://spf13.com/projects/hugo baseUrl section slug ⊢-----^--------⊣ ⊢--^--⊣ ⊢--^--⊣ http://spf13.com/extras/indexes/example baseUrl path slug ⊢-----^--------⊣ ⊢------^-----⊣ ⊢--^--⊣ http://spf13.com/extras/indexes/example baseUrl url ⊢-----^--------⊣ ⊢-----^-----⊣ http://spf13.com/projects/hugo baseUrl url ⊢-----^--------⊣ ⊢--------^-----------⊣ http://spf13.com/extras/indexes/example section = which type the content is by default based on content location front matter overrides slug = name.ext or name/ based on content-name.md front matter overrides path = section + path to file exluding slug based on path to content location url = relative url defined in front matter overrides all the above chapter 8 Front Matter The front matter is one of the features that gives Hugo its strength. It enables you to include the meta data of the content right with it. Hugo supports a few different formats each with their own identifying tokens. Supported formats: YAML, identified by '---'. TOML, indentified with '+++'. JSON, a single JSON object which is surrounded by '{' and '}' each on their own line. YAML Example --- title: "spf13-vim 3.0 release and new website" description: "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." tags: [ ".vimrc", "plugins", "spf13-vim", "vim" ] date: "2012-04-06" categories: - "Development" - "VIM" slug: "spf13-vim-3-0-release-and-new-website" --- Content of the file goes Here TOML Example +++ title = "spf13-vim 3.0 release and new website" description = "spf13-vim is a cross platform distribution of vim plugins and resources for Vim." tags = [ ".vimrc", "plugins", "spf13-vim", "vim" ] date = "2012-04-06" categories = [ "Development", "VIM" ] slug = "spf13-vim-3-0-release-and-new-website" +++ Content of the file goes Here JSON Example { "title": "spf13-vim 3.0 release and new website", "description": "spf13-vim is a cross platform distribution of vim plugins and resources for Vim.", "tags": [ ".vimrc", "plugins", "spf13-vim", "vim" ], "date": "2012-04-06", "categories": [ "Development", "VIM" ], "slug": "spf13-vim-3-0-release-and-new-website", } Content of the file goes Here Variables There are a few predefined variables that Hugo is aware of and utilizes. The user can also create any variable they want to. These will be placed into the .Params variable available to the templates. Field names are case insensitive. Required title The title for the content description The description for the content date The date the content will be sorted by taxonomies These will use the field name of the plural form of the index (see tags and categories above) Optional redirect Mark the post as a redirect post draft If true the content will not be rendered unless hugo is called with -buildDrafts publishdate If in the future, content will not be rendered unless hugo is called with -buildFuture type The type of the content (will be derived from the directory automatically if unset) weight Used for sorting markup (Experimental) Specify "rst" for reStructuredText (requires rst2html,) or "md" (default) for the Markdown slug The token to appear in the tail of the url or url The full path to the content from the web root. If neither slug or url is present the filename will be used. chapter 9 Sections Hugo thinks that you organize your content with a purpose. The same structure that works to organize your source content is used to organize the rendered site ( see organization ). Following this pattern Hugo uses the top level of your content organization as the Section. The following example site uses two sections, "post" and "quote". . └── content ├── post | ├── firstpost.md // <- http://1.com/post/firstpost/ | ├── happy | | └── ness.md // <- http://1.com/post/happy/ness/ | └── secondpost.md // <- http://1.com/post/secondpost/ └── quote ├── first.md // <- http://1.com/quote/first/ └── second.md // <- http://1.com/quote/second/ Section Lists Hugo will automatically create pages for each section root that list all of the content in that section. See List Templates for details on customizing the way they appear. Sections and Types By default everything created within a section will use the content type that matches the section name. Section defined in the front matter have the same impact. To change the type of a given piece of content simply define the type in the front matter. If a layout for a given type hasn't been provided a default type template will be used instead provided is exists. chapter 10 Content Types Hugo has full support for different types of content. A content type can have a unique set of meta data, template and can be automatically created by the new command through using content archetypes. A good example of when multiple types are needed is to look at Tumblr. A piece of content could be a photo, quote or post, each with different meta data and rendered differently. Assigning a content type Hugo assumes that your site will be organized into sections and each section will use the corresponding type. If you are taking advantage of this then each new piece of content you place into a section will automatically inherit the type. Alternatively you can set the type in the meta data under the key "type". Creating new content of a specific type Hugo has the ability to create a new content file and populate the front matter with the data set corresponding to that type. Hugo does this by utilizing archetypes. To create a new piece of content use: hugo new relative/path/to/content.md For example if I wanted to create a new post inside the post section I would type: hugo new post/my-newest-post.md Defining a content type Creating a new content type is easy in Hugo. You simply provide the templates and archetype that the new type will use. You only need to define the templates, archetypes and/or views unique to that content type. Hugo will fall back to using the general templates and default archetype whenever a specific file is not present. Remember, all of the following are optional: Create Type Directory Create a directory with the name of the type in layouts.Type is always singular. Eg /layouts/post. Create single template Create a file called single.html inside your directory. Eg /layouts/post/single.html. Create list template Create a file called list.html inside your directory Eg /layouts/post/list.html. Create views Many sites support rendering content in a few different ways, for instance a single page view and a summary view to be used when displaying a list of contents on a single page. Hugo makes no assumptions here about how you want to display your content, and will support as many different views of a content type as your site requires. All that is required for these additional views is that a template exists in each layout/type directory with the same name. Create a corresponding archetype Create a file called type.md in the /archetypes directory Eg /archetypes/post.md. More details about archetypes can be found at the archetypes docs chapter 11 Archetypes Hugo v0.11 introduced the concept of a content builder. Using the command: hugo new [relative new content path] you can start a content file with the date and title automatically set. This is a welcome feature, but active writers need more. Hugo presents the concept of archetypes which are archetypal content files. Example archetype In this example scenario I have a blog with a single content type (blog post). I use ‘tags' and ‘categories' for my taxonomies. archetypes/default.md +++ tags = ["x", "y"] categories = ["x", "y"] +++ using archetypes If I wanted to create a new post in the posts section I would run the following command... hugo new posts/my-new-post.md Hugo would create the file with the following contents: contents/posts/my-new-post.md +++ title = "my new post" date = 2014-05-14T02:13:50Z tags = ["x", "y"] categories = ["x", "y"] +++ Using a different front matter format By default the front matter will be created in the TOML format regardless of what format the archetype is using. You can specify a different default format in your config file using the MetaDataFormat directive. Possible values are toml, yaml and json. Which archtype is being used The following rules apply: If an archetype with a filename that matches the content type being created it will be used. If no match is found archetypes/default.md will be used. If neither are present and a theme is in use then within the theme... If an archetype with a filename that matches the content type being created it will be used. If no match is found archetypes/default.md will be used. If no archetype files are present then the one that ships with hugo will be used. Hugo provides a simple archetype which sets the title (based on the file name) and the date based on now(). Content type is automatically detected based on the path. You are welcome to declare which type to create using the --kind flag during creation. chapter 12 Ordering Content Hugo provides you with all the flexibility you need to organize how your content is ordered. By default, content is ordered by weight, then by date with the most recent date first, but alternative sorting (by title and linktitle) is also available. The order the content will appear will be specified in the list template. Both the date and weight fields are optional. Unweighted pages appear at the end of the list. If no weights are provided (or if weights are the same) date will be used to sort. If neither are provided content will be ordered based on how it's read off the disk and no order is guaranteed. Assigning Weight to content +++ weight = "4" title = "Three" date = "2012-04-06" +++ Front Matter with Ordered Pages 3 Ordering Content Within Taxonomies Please see the Taxonomy Ordering Documentation chapter 13 Example Content File Somethings are better shown than explained. The following is a very basic example of a content file: mysite/project/nitro.md <- http://mysite.com/project/nitro.html --- Title: "Nitro : A quick and simple profiler for Go" Description: "Nitro is a simple profiler for you go lang applications" Tags: [ "Development", "Go", "profiling" ] date: "2013-06-19" Topics: [ "Development", "Go" ] Slug: "nitro" project_url: "http://github.com/spf13/nitro" --- # Nitro Quick and easy performance analyzer library for Go. ## Overview Nitro is a quick and easy performance analyzer library for Go. It is useful for comparing A/B against different drafts of functions or different functions. ## Implementing Nitro Using Nitro is simple. First use go get to install the latest version of the library. $ go get github.com/spf13/nitro Next include nitro in your application. chapter 14 Themes Overview Hugo provides a robust theming system which is simple, yet capable of producing even the most complicated websites. The Hugo community has created a set of themes ready for using in your own site. Hugo themes have been designed to be the perfect balance between simplicity and functionality. Hugo themes are powered by the excellent go template library. If you are new to go templates, see our primer on go templates. Hugo themes support all modern features you come to expect. They are structured in such a way to eliminate code duplication. Themes are also designed to be very easy to customize while retaining the ability to maintain upgradeability as the upstream theme changes. Hugo currently doesn't ship with a “default” theme, allowing the user to pick whichever theme best suits their project. We hope you will find Hugo themes perfect for your site. chapter 15 Installing Themes Hugo themes are located in a centralized github repository. Hugo Themes Repo itself is really a meta repository which contains pointers to set of contributed themes. Installing all themes If you would like to install all of the available hugo themes, simply clone the entire repository from within your working directory. git clone --recursive https://github.com/spf13/hugoThemes.git themes Installing a specific theme mkdir themes cd themes git clone URL_TO_THEME chapter 16 Using a Theme Please make certain you have installed the themes you want to use in the /themes directory. To use a theme for a site: hugo -t ThemeName The ThemeName must match the name of the directory inside /themes Hugo will then apply the theme first, then apply anything that is in the local directory. To learn more, goto customizing themes chapter 17 Customizing a Theme Hugo themes permit you to supplement or override any template or file from within your working directory. Replacing Static files If you would like to include a different file than the theme ships with.. For example you would like to use a more recent version of jquery then the theme happens to include simply place an identically name file in the same relative location but in your working directory. For example if the theme has jquery 1.6 in /themes/themename/static/js/jQuery.min.js, simply place your file in the same relative path /static/js/jQuery.min.js. Replace a single template file Anytime Hugo looks for a matching template it will first check the working directory before looking in the theme directory. If you would like to modify a template simply create that template in your local layouts directory. In the template documentation each different template type explains the rules it uses to determine which template to use. warning.. This only works for templates that Hugo knows about. If the theme creates partial template files in a creatively named directory Hugo won't know to look for the local /layouts first Replace an archetype If the archetype that ships with the theme for a given content type (or all content types) doesn't fit with how you are using the theme, feel free to copy it to your /archetypes directory and make modifications as you see fit. Beware of the default Default is a very powerful force in Hugo... Especially as it pertains to overwriting theme files. If a default is located in the local archetype directory or /layouts/_default/ directory it will be used instead of any of the similar files in the theme. It is usually better to override specific files rather than using the default in your working directory. chapter 18 Creating a Theme Hugo has the ability to create a new theme in your themes directory for you using the hugo new command. hugo new theme [name] This command will initialize all of the files and directories a basic theme would need. Hugo themes are written in the go template language. If you are new to Go, the go template primer will help you get started. Theme Components A theme consists of templates and static assets such as javascript and css files. Themes can also optionally provide archetypes which are archetypal content types used by the hugo new command. Layouts Hugo is built around the concept that things should be as simple as possible. Fundamentally website content is displayed in two different ways, a single piece of content and a list of content items. With Hugo a theme layout starts with the defaults. As additional layouts are defined they are used for the content type or section they apply to. This keeps layouts simple, but permits a large amount of flexibility. Single Content The default single file layout is located at layouts/_default/single.html. List of Contents The default list file layout is located at layouts/_default/list.html Static Everything in the static directory will be copied directly into the final site when rendered. No structure is provided here to enable complete freedom. It is common to organize the static content into /css /js /img The actual structure is entirely up to you, the theme creator, on how you would like to organize your files. Archetypes If your theme makes use of specific keys in the front matter it is a good idea to provide an archetype for each content type you have. Archetypes follow the guidelines provided. chapter 19 Hugo Templates Hugo uses the excellent go html/template library for its template engine. It is an extremely lightweight engine that provides a very small amount of logic. In our experience that it is just the right amount of logic to be able to create a good static website. While Hugo has a number of different template roles, most complete websites can be built using just a small number of template files. Please don't be afraid of the variety of different template roles. They are enable Hugo to build very complicated sites. Most sites will only need to create a /layouts/_default/single.html & /layouts/_default/list.html If you are new to go's templates the go template primer is a great place to start. If you are familiar with go's templates, Hugo provides some additional template functions and variables you will want to be familiar with. Primary Template roles There are 3 primary kinds of templates that Hugo works with. Single Render a single piece of content List Page that list multiple pieces of content Homepage The homepage of your site Supporting Template Roles (optional) Hugo also has additional kinds of templates all of which are optional Partial Templates Common page parts to be included in the above mentioned templates Content Views Different ways of rendering a (single) content type Taxonomy Terms A list of the terms used for a specific taxonomy eg. a Tag cloud Other Templates (generally unncessary) RSS Used to render all rss documents Sitemap Used to render the XML sitemap 404 This template will create a 404.html page used when hosting on github pages chapter 20 Go Template Primer Hugo uses the excellent go html/template library for its template engine. It is an extremely lightweight engine that provides a very small amount of logic. In our experience that it is just the right amount of logic to be able to create a good static website. If you have used other template systems from different languages or frameworks you will find a lot of similarities in go templates. This document is a brief primer on using go templates. The go docs provide more details. Introduction to Go Templates Go templates provide an extremely simple template language. It adheres to the belief that only the most basic of logic belongs in the template or view layer. One consequence of this simplicity is that go templates parse very quickly. A unique characteristic of go templates is they are content aware. Variables and content will be sanitized depending on the context of where they are used. More details can be found in the go docs. Basic Syntax Go lang templates are html files with the addition of variables and functions. Go variables and functions are accessible within {{ }} Accessing a predefined variable "foo": {{ foo }} Parameters are separated using spaces Calling the add function with input of 1, 2: {{ add 1 2 }} Methods and fields are accessed via dot notation Accessing the Page Parameter "bar" {{ .Params.bar }} Parentheses can be used to group items together {{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }} Variables Each go template has a struct (object) made available to it. In hugo each template is passed either a page or a node struct depending on which type of page you are rendering. More details are available on the variables page. A variable is accessed by referencing the variable name. {{ .Title }} Variables can also be defined and referenced. {{ $address := "123 Main St."}} {{ $address }} Functions Go template ship with a few functions which provide basic functionality. The go template system also provides a mechanism for applications to extend the available functions with their own. Hugo template functions provide some additional functionality we believe are useful for building websites. Functions are called by using their name followed by the required parameters separated by spaces. Template functions cannot be added without recompiling hugo. Example: {{ add 1 2 }} Includes When including another template you will pass to it the data it will be able to access. To pass along the current context please remember to include a trailing dot. The templates location will always be starting at the /layout/ directory within Hugo. Example: {{ template "chrome/header.html" . }} Logic Go templates provide the most basic iteration and conditional logic. Iteration Just like in go, the go templates make heavy use of range to iterate over a map, array or slice. The following are different examples of how to use range. Example 1: Using Context {{ range array }} {{ . }} {{ end }} Example 2: Declaring value variable name {{range $element := array}} {{ $element }} {{ end }} Example 2: Declaring key and value variable name {{range $index, $element := array}} {{ $index }} {{ $element }} {{ end }} Conditionals If, else, with, or, & and provide the framework for handling conditional logic in Go Templates. Like range, each statement is closed with end. Go Templates treat the following values as false: false 0 any array, slice, map, or string of length zero Example 1: If {{ if isset .Params "title" }}

{{ index .Params "title" }}

{{ end }} Example 2: If -> Else {{ if isset .Params "alt" }} {{ index .Params "alt" }} {{else}} {{ index .Params "caption" }} {{ end }} Example 3: And & Or {{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} Example 4: With An alternative way of writing "if" and then referencing the same value is to use "with" instead. With rebinds the context . within its scope, and skips the block if the variable is absent. The first example above could be simplified as: {{ with .Params.title }}

{{ . }}

{{ end }} Example 5: If -> Else If {{ if isset .Params "alt" }} {{ index .Params "alt" }} {{ else if isset .Params "caption" }} {{ index .Params "caption" }} {{ end }} Pipes One of the most powerful components of go templates is the ability to stack actions one after another. This is done by using pipes. Borrowed from unix pipes, the concept is simple, each pipeline's output becomes the input of the following pipe. Because of the very simple syntax of go templates, the pipe is essential to being able to chain together function calls. One limitation of the pipes is that they only can work with a single value and that value becomes the last parameter of the next pipeline. A few simple examples should help convey how to use the pipe. Example 1 : {{ if eq 1 1 }} Same {{ end }} is the same as {{ eq 1 1 | if }} Same {{ end }} It does look odd to place the if at the end, but it does provide a good illustration of how to use the pipes. Example 2 : {{ index .Params "disqus_url" | html }} Access the page parameter called "disqus_url" and escape the HTML. Example 3 : {{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}} Stuff Here {{ end }} Could be rewritten as {{ isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" | if }} Stuff Here {{ end }} Context (aka. the dot) The most easily overlooked concept to understand about go templates is that {{ . }} always refers to the current context. In the top level of your template this will be the data set made available to it. Inside of a iteration it will have the value of the current item. When inside of a loop the context has changed. . will no longer refer to the data available to the entire page. If you need to access this from within the loop you will likely want to set it to a variable instead of depending on the context. Example: {{ $title := .Site.Title }} {{ range .Params.tags }}
  • {{ . }} - {{ $title }}
    • {{ end }} Notice how once we have entered the loop the value of {{ . }} has changed. We have defined a variable outside of the loop so we have access to it from within the loop. Hugo Parameters Hugo provides the option of passing values to the template language through the site configuration (for sitewide values), or through the meta data of each specific piece of content. You can define any values of any type (supported by your front matter/config format) and use them however you want to inside of your templates. Using Content (page) Parameters In each piece of content you can provide variables to be used by the templates. This happens in the front matter. An example of this is used in this documentation site. Most of the pages benefit from having the table of contents provided. Sometimes the TOC just doesn't make a lot of sense. We've defined a variable in our front matter of some pages to turn off the TOC from being displayed. Here is the example front matter: --- title: "Permalinks" date: "2013-11-18" aliases: - "/doc/permalinks/" groups: ["extras"] groups_weight: 30 notoc: true --- Here is the corresponding code inside of the template: {{ if not .Params.notoc }}
    {{ .TableOfContents }}
    {{ end }} Using Site (config) Parameters In your top-level configuration file (eg, config.yaml) you can define site parameters, which are values which will be available to you in chrome. For instance, you might declare: params: CopyrightHTML: "Copyright 2013 John Doe. All Rights Reserved." TwitterUser: "spf13" SidebarRecentLimit: 5 Within a footer layout, you might then declare a