What layout is used for root-level content pages (content/about.md)?

support
1

Hi folks, I am trying to wrap my head around the best way to set up simple root level pages, e.g. foo.com/about. My understanding is that there are basically two options:

The first and older approach is to treat “about” as a section, so content/about/_index.md. Consistent with the docs, this defaults to using the layouts/_default/list.html template. Which would make intuitive sense for foo.com/posts, but less so for non-list dead-end pages like foo.com/about. I tried unsuccessfully to override this with layout = "single" etc. in front matter.

The second approach (e.g. detailed here) is content/about.md.

Which mostly works for me – the content renders – except I don’t understand how Hugo determines what layout, if any, to use. According to the above link, it should use layouts/_default/single.html, which is what I want, but it only does that if there is front matter in content/about.md. Even empty front matter. No front matter, however, and about.md renders bare, without being wrapped in single.html.

Is this the expected behavior? How come? I see it possibly is based on this thread but I’d love to understand why.

3 Likes
2

Do you mean layout: single, or front matter in general? You should share your site’s project, so we can look at it and assist.

Also, have you tried testing a regular test file with proper front matter in it, to see if it renders? Like, the following at content/test.md:

+++
categories = ["test"]
date = "2017-01-02T20:45:04-08:00"
tags = ["another test"]
title = "Test Page"
+++

Some content here.

That should create a page at /test/, using the lookup order for single pages.

3

I mean that “+++[return]+++” with no actual key/value pairs is sufficient to make content/about.md render using single.html, and removing those two lines is sufficient to make it render without it. Aka “+++[return]+++” appears to be mandatory boilerplate.

I’m in the middle of a commit but I’ll post it soon if it’s still helpful.

Re: your second question, yes, a file like content/test.md with actual front matter renders using single.html.

4

Repo: https://github.com/zda/og

5

Yep, that appears correct.

I am little confused about your questions. The thread title is about which layout is called, and that is in the lookup order docs. And to render the pages, it needs the front matter blocks. Is there anything else we missed?

…

I was poking around, wondering if you just have a preference to not use front matter, when I looked at your raw about.md file. I think I know what is happening here!

The default behavior of Hugo is to render Markdown files using Go templates, in the theme and in the layouts directory. Your pages are marked up as HTML, with inline divs and all that. Most Markdown parsers handle that, but it isn’t what Hugo is made for. At that point, you are doing all the work of the templates in each piece of content, whereas Hugo assists in writing Markdown and creating the HTML when the site builds.

Anyhow, I suggest you move the layout HTML into the templates, and rewrite the content pages as Markdown, with front matter. For instance, you can use title in the front matter to pass the title of the page in the template, rather than hard-coding an h1 in each piece of content.

It may seem like a lot of work for a small site with four pages, but one of the features of Hugo is that it can scale for very large sites, and if you are going to hand code each page, you may be better off not using a site generator.

Also, most themes presume front matter, such as how Minimo chooses to show the title. With empty front matter, Hugo isn’t doing you any favors.

Good luck with that, that website seems like a valuable effort. :slight_smile:

6

I just hit this, too, and have spent a few hours trying to figure out what was wrong before I found this post.

While I can’t answer for zda, my use-case is that I’m migrating a preexisting static website to Hugo by importing raw HTML files. My next step will be to convert the posts to Markdown/Ace/whatnot and templatize things. I think this is a sane migration strategy for a preexisting static site.

Cheers,
Jens

7

That would be my next step, as well. Obviously for some sites that is going to be a massive undertaking. In the past I’ve handled such projects with everything from Mechanical Turk to summer work for high school kids.

But to do all the fun stuff with Hugo, you kinda need the content to live apart from the style and layouts. That is why we like it so much, ne? :slight_smile:

8

I think this answers my question so feel free to mark this resolved. TL;DR always add front-matter to content/.md files, even if it’s just +++\n+++.

As for HTML vs. Markdown, I am well aware that the intent behind Hugo/et al. is for content to be written as Markdown. Thing is, that is more work if you are migrating an existing site/content that wasn’t written in Markdown to begin with.

Moreover, I don’t think it’s relevant to talk about how “Most Markdown parsers handle (HTML).” The relevant question is whether the specific Markdown processor Hugo specifically uses supports embedded HTML. If Hugo’s MD library doesn’t support HTML, or if that functionality were removed, IMHO that would be a major regression in the usefulness of Hugo.

I’m pretty sure it does actually support HTML currently, since I’m using it that way successfully; I’m just saying I hope HTML in Markdown is not seen as an accidental or unsupported feature.

Thanks for the help!