Skip to content

Instantly share code, notes, and snippets.

@simonw

simonw/basic-hugo.md Secret

Created October 23, 2024 02:03
Show Gist options
  • Save simonw/6f7b6a40713b36749da845065985bb28 to your computer and use it in GitHub Desktop.
Save simonw/6f7b6a40713b36749da845065985bb28 to your computer and use it in GitHub Desktop.
Download ZIP
Raw
basic-hugo.md

Setting Up a Hugo Site with a Base Template

human (Oct 22, 2024, 05:10 PM)

I want to use Hugo to manage a site where I have a bunch of pages, each of which has just the title and the content in - then when Hugo runs it wraps each one in my common base template with navigation and footer etc

assistant (Oct 22, 2024, 05:10 PM)

I'll help you set up a Hugo site with a common base template that wraps your content pages. Let me create a basic structure for you.

Hugo Site Structure with Base Template

layouts/_default/baseof.html
<title>{{ if .Title }}{{ .Title }} - {{ end }}{{ .Site.Title }}</title> {{ $style := resources.Get "css/main.css" | minify }} 
<main>
    {{ block "main" . }}{{ end }}
</main>

<footer>
    <p>&copy; {{ now.Format "2006" }} {{ .Site.Title }}</p>
</footer>

layouts/_default/single.html

{{ define "main" }}
<article>
    <h1>{{ .Title }}</h1>
    {{ .Content }}
</article>
{{ end }}

config.toml

baseURL = 'http://example.org/' languageCode = 'en-us' title = 'My Website'

[menu] [[menu.main]] name = 'Home' url = '/' weight = 1 [[menu.main]] name = 'About' url = '/about/' weight = 2

content/about.md

---
title: "About"
menu: main
---
This is the about page content.

content/_index.md

title: "Welcome"

This is the home page content.

assets/css/main.css

body {
    max-width: 800px;
    margin: 0 auto;
    padding: 1rem;
    font-family: sans-serif;
}

nav ul {
    list-style: none;
    padding: 0;
    display: flex;
    gap: 1rem;
}

footer {
    margin-top: 2rem;
    border-top: 1px solid #ddd;
    padding-top: 1rem;
}

Here's how to use this structure:

  1. Create new content pages in the content directory with just title and content:
---
title: "My Page Title"
---
Your content goes here...

  1. The base template (baseof.html) provides:

    • Common HTML structure
    • Navigation menu
    • Footer
    • CSS linking
    • Title handling

  2. The single template (single.html) is minimal and just defines how to render your content within the base template.

To run the site:

  1. Install Hugo
  2. Create these files in your project directory
  3. Run hugo server for development
  4. Visit http://localhost:1313

Each new page you create will automatically:

  • Use the base template
  • Show up in the navigation (if you add menu: main to its front matter)
  • Have consistent styling

Would you like me to explain any part of this in more detail or add any specific features to the templates?

human (Oct 22, 2024, 05:32 PM)

Make that even simpler - can I get away with just a single layout file and a single _index.md file and a single about.html file to demonstrate what HTML as opposed to Markdown would look like? No CSS either

assistant (Oct 22, 2024, 05:32 PM)

Minimal Hugo Site Structure

layouts/_default/baseof.html
<title>{{ .Title }}</title> Home About 
{{ .Content }}

<footer>
    <p>My Site Footer</p>
</footer>

content/_index.md

---
title: Welcome
---
# Welcome to my site

This is my homepage content in Markdown.

content/about.html

title: About

About Us

This is the about page, written directly in HTML.


That's all you need! This gives you:

1. A single template that wraps everything (`baseof.html`)
2. A Markdown homepage (`_index.md`)
3. An HTML about page (`about.html`)

To use it:
1. Create these three files in their respective directories
2. Run `hugo server`
3. Visit `http://localhost:1313`

Want to add a new page? Just drop a `.md` or `.html` file in the `content` directory. The template will automatically wrap it.

**human** (Oct 22, 2024, 05:34 PM)

Error: command error: Unable to locate config file or config directory. Perhaps you need to create a new site.
Run `hugo help new` for details.

**assistant** (Oct 22, 2024, 05:34 PM)

 Ah yes, you need to initialize a Hugo site first! Here's the complete step-by-step:

1. Create a new directory and initialize a Hugo site:
```bash
mkdir mysite
cd mysite
hugo new site . --force
  1. Then create the minimal files we discussed:

Minimal Hugo Site with Config

hugo.toml

baseURL = 'http://example.org/' languageCode = 'en-us' title = 'My Site'

layouts/_default/baseof.html

<!DOCTYPE html>
<html>
<head>
    <title>{{ .Title }}</title>
</head>
<body>
    <nav>
        <a href="/">Home</a>
        <a href="/about.html">About</a>
    </nav>

    {{ .Content }}

    <footer>
        <p>My Site Footer</p>
    </footer>
</body>
</html>

content/_index.md

title: Welcome

Welcome to my site

This is my homepage content in Markdown.

content/about.html

---
title: About
---
<h1>About Us</h1>
<p>This is the about page, written directly in HTML.</p>

Now you can run:

hugo server

And visit http://localhost:1313 to see your site. The error you got was because Hugo needs at least a config file to run. Let me know if you'd like to add anything to this minimal setup!

human (Oct 22, 2024, 05:34 PM)

what does --force do?

assistant (Oct 22, 2024, 05:34 PM)

The --force flag in hugo new site allows Hugo to create a new site in a directory that's not empty. Without --force, Hugo requires an empty directory and will give you an error if there are any existing files.

In this case, since we're creating the site in the current directory (.), which likely contains the terminal's . and .. directory entries, we need --force to proceed. If we were creating the site in a completely new empty directory, we wouldn't need the --force flag.

You could alternatively do:

mkdir mysite
cd mysite
hugo new site .

or:

hugo new site mysite
cd mysite

Both of these would work without needing --force since they're working with completely empty directories.

human (Oct 22, 2024, 05:35 PM)

what should I put in hugo.toml ?

assistant (Oct 22, 2024, 05:35 PM)

For a minimal site, you only need three basic settings in hugo.toml:

baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My Site'

Here's what each does:

  • baseURL: The root URL where your site will be deployed. For local development, you can leave it as example.org
  • languageCode: Sets the language of your site
  • title: Your site's name, which can be referenced in templates with {{ .Site.Title }}

That's all you need to get started! You can add more settings later as needed, such as:

  • theme if you want to use a theme
  • publishDir to change the output directory from "public"
  • permalinks to customize URL structures
  • params for custom site parameters

But for your minimal site with just a few pages and a base template, these three basic settings are sufficient.

human (Oct 22, 2024, 05:35 PM)

(base) simon@Mac h % hugo build Start building sites … hugo v0.136.4+extended darwin/arm64 BuildDate=2024-10-22T08:35:58Z VendorInfo=brew WARN found no layout file for "html" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination. WARN found no layout file for "html" for kind "page": You should create a template file which matches Hugo Layouts Lookup Rules for this combination. WARN found no layout file for "html" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

assistant (Oct 22, 2024, 05:35 PM)

We need to adjust our template structure slightly. Hugo is looking for specific layout files based on the content type. Let's modify the structure to make it work:

Corrected Hugo Site Structure

layouts/_default/baseof.html
<title>{{ .Title }}</title> Home About 
{{ block "main" . }}{{ end }}

<footer>
    <p>My Site Footer</p>
</footer>

layouts/_default/single.html

{{ define "main" }}
    {{ .Content }}
{{ end }}

layouts/index.html

{{ define "main" }} {{ .Content }} {{ end }}

content/_index.md

---
title: Welcome
---
# Welcome to my site

This is my homepage content in Markdown.

content/about.html

title: About

About Us

This is the about page, written directly in HTML.


The key changes are:
1. Added `{{ block "main" . }}{{ end }}` to `baseof.html` instead of directly including content
2. Added `single.html` for regular pages (like about.html)
3. Added `index.html` for the homepage

Now `hugo build` should work without warnings. The structure follows Hugo's lookup rules:
- `index.html` handles the home page
- `single.html` handles individual pages
- `baseof.html` provides the shared template that both use

Try running `hugo build` again and the warnings should be gone!

**human** (Oct 22, 2024, 05:37 PM)

WARN  found no layout file for "html" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

**assistant** (Oct 22, 2024, 05:37 PM)

 Ah, we need to add a layout for taxonomies (like categories and tags) or disable them. The simplest solution is to disable taxonomies since we're not using them in this minimal site.

Add this to your hugo.toml:

```toml
baseURL = 'http://example.org/'
languageCode = 'en-us'
title = 'My Site'

# Disable taxonomies
disableKinds = ['taxonomy', 'term']

The disableKinds setting tells Hugo not to generate taxonomy pages, which we don't need for a simple site with just content pages. This should eliminate the taxonomy warning.

If you later want to use categories or tags, you can remove this setting and add the appropriate taxonomy templates, but for now this keeps things minimal!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment