Generating the Theme

You can make a theme by creating a new directory in the themes folder of your site, but Hugo has a built-in theme generator that creates everything you need for your theme. Execute this command from the root of your Hugo site to generate a new theme named basic:

​ ​$ ​​hugo​​ ​​new​​ ​​theme​​ ​​basic​
​ Creating theme at ...portfolio/themes/basic

This command creates the themes/basic directory and several subdirectories and files:

​ themes/basic/
​ ├── LICENSE
​ ├── archetypes
​ │   └── default.md
​ ├── layouts
​ │   ├── 404.html
​ │   ├── _default
​ │   │   ├── baseof.html
​ │   │   ├── list.html
​ │   │   └── single.html
​ │   ├── index.html
​ │   └── partials
​ │   ├── footer.html
​ │   ├── head.html
​ │   └── header.html
​ ├── static
​ │   ├── css
​ │   └── js
​ └── theme.toml

The theme has a place for its own archetypes, as well as directories to store the layout files and static assets like stylesheets, scripts, and images. Each theme has a license file so you can open source your theme if you choose, as well as a configuration file where you can store theme-specific configuration values.

Notice that there’s already a layouts/_default directory with files for single page layouts and list page layouts. There’s also a layouts/index.html file that serves as the home page layout. Those files don’t have any content in them, though.

Move your existing layout files into this new theme. Move the layouts/index.html file to themes/basic/layouts/index.html, and then move layouts/_default/single.html to themes/basic/layouts/_default/single.html. You can do this quickly with these commands:

​ ​$ ​​mv​​ ​​layouts/index.html​​ ​​themes/basic/layouts/index.html​
​ ​$ ​​mv​​ ​​layouts/_default/single.html​​ ​​themes/basic/layouts/_default/single.html​

Before you can use the theme, you have to tell Hugo about it by adding a line to your site’s configuration. Open config.toml and add the following line to the end:

basic_theme/portfolio/config.toml
​ baseURL = ​"http://example.org/"​
​ languageCode = ​"en-us"​
​ title = ​"Brian's Portfolio"​
»theme = ​"basic"​

Save the file and run the server again:

​ hugo server

Visit http://localhost:1313 in your browser. Your home page still displays, which means your theme works. Once you know it works, stop the development server with Ctrl-c.

Now, let’s break the theme up and reduce some duplication by taking advantage of Hugo’s layout framework.