Steps to go from standalone page to bundle page

support
1

All - just wanted to post this to explain what I did to convert a page in content to use the new bundle feature. The site I am working on just has a bunch pages under content:

content/about.md
content/products.md
content/contact.md
etc

I have a page with a figure, so I thought I would use the new bundle feature to display it. When I first converted, I went from:

content/mypage.md

…to:

content/mypage/index.md

But, what happens is, Hugo now assumes “mypage” is a section, and because of that, displays it as a list. To get back to where I was, some changes had to be made.

The frontmatter of the page looks like:

---
date: 2018-01-26T00:00:27+09:00
draft: false
tags: 
  - red
  - blue
title: This is My Page
description: My Page description description description
menu:
  main:
     name: My Page
     url: /mypage/
     weight: 50
---
…

First I renamed the index.md to _index.md. I understand that in a section, just index.md will be ignored.

Then I needed to specify a layout for the page. Before I specify the layout in frontmatter, I need a single and its baseof template, for this page. I copied:

layouts/_default/single-baseof.html
layouts/_default/single.html

…to:

layouts/_default/mylayout1-baseof.html
layouts/_default/mylayout1.html

Then I set the frontmatter to use this new layout.

---
date: 2018-01-26T00:00:27+09:00
draft: false
tags: 
  - red
  - blue
title: This is My Page
description: My Page description description description
layout: mylayout1
menu:
  main:
     name: My Page
     url: /mypage/
     weight: 50
---
…

And now it works exactly the same as before. To get here I really tried various approaches until it “clicked”. I am not sure if this is the way to do this, and I wanted to ask for comments on it.

Also, I have not yet converted the figure to use a bundled image, so, I am not sure if it will work in a shortcode in this _index.md file. One step at a time I guess.

Appreciate any comments if someone else has converted and figured out exactly how it works.

Thanks,
Rick

Hugo Static Site Generator v0.35-DEV-8125B4B0 darwin/amd64 BuildDate: 2018-01-22T21:52:05+0900
GOOS="darwin"
GOARCH="amd64"
GOVERSION="go1.9.2"
1 Like
2

That looks a little too hard … But I guess Hugo assumes that the first level is a section, which is an extremely common pattern (/blog, /posts /pages etc.).

What I would recommend is this:

  • If you don’t need a section, create one anyway to make Hugo happy; pick something general (“pages”?)
  • Put your content pages in that folder; name them index.md, which is what you want, I think
  • Create a permalink config for that section that fits your needs
4 Likes
3

Thanks @bep, that does sound easier. I’ll give that a try. :slight_smile:

Can I ask, will I need the frontmatter layout setting in this case, or, can I remove it and if I do, will they just go back to using single?

4

You can use single, which is the simplest and cleanest.

5

perfect, thanks

6

Ok, thanks to @bep’s advice this is cleaner. Closing the loop, here’s what I did to refactor the standalone pages into a pseudo-section that I called “rootpages” (but it can be called whatever):

  1. move content/whatever.md into content/rootpages/whatever.md, and content/mypage/_index.md to content/rootpages/mypage/index.md removing the leading underbar.
  2. set a rootpages permalink rule in my config.toml, to use slug ( n.b. my titles are in Japanese, so, they don’t convert gracefully to slug, so I used that because I can specify it. )
    • like this: rootpages = "/:slug/"
  3. set slug in each content markdown file (thankfully only a handful).
    • like this: slug: mypage
  4. delete the two layouts that I’d specified, namely mylayout1.html and mylayout1-baseof.html.

Then, git commit/push, restart hugo server, clear caches and, voila, back to where I was visually, but with an easier-to-maintain setup, and, the ability to easily convert more pages into bundles when I need to.

The config.toml permalink section looks like:

...
[permalinks]
  post = "/:year/:month/:day/:slug/"
  rootpages = "/:slug/"
...
2 Likes
7

I suspect you could have skipped this step.

8

When I tried it without setting slug, I got lots of errors

9

OK, then I think you can configure the permalinks to use “:filename”, which for bundles will fetch the folder they live in.

1 Like
10

@bep, thanks, indeed you’re right. Ok, I tried changing the permalink setup to:

 page = "/:filename/"

… and after testing I find it means I can remove slug from all my pages’ frontmatter, including from the bundle index.md I have.

I also noticed that my “rootpage” actually becomes a live URL so, I changed to “page” instead. On the section page it lists as plural “pages” which is aesthetically nicer.

11

Summarizing again for the forum searcher, assuming you:

  • have a bunch of markdown content files in /content/, which are displaying correctly based on your single.html template
  • you are ok storing those files in a section “page(s)” under content
  • want to convert one or all of them to “bundles” to take advantage of the new features

…here’s the steps to convert:

  1. create folder content/page, which Hugo will think of as a section
  2. move content/whatever.md into content/page/whatever.md
  3. if you want to make, say, mypage.md into a bundle, move content/page/mypage.md to content/page/mypage/index.md (notice, no underbar before the index)
  4. set a permalink rule in your config.toml, for your section “page”, so that Hugo will set the URL for these pages to the filename.
    • like this: page = "/:filename/"

Then, git commit/push, restart hugo server, clear caches and, you can now for instance use a shortcode to make use of the new bundle template tricks with your image files stored in content/page/mypage/.

Just do the third step again, to convert another markdown file into a bundle.

The config.toml permalink section looks like:

...
[permalinks]
  post = "/:year/:month/:day/:slug/"
  page = "/:filename/"
...
1 Like
12

@bep Should this qualify as something to be fixed in hugo?

It poses a limitation that “leaf” bundles are not allowed at root level of content/. Should the Section (list layout) detection logic be updated so that folders containing index.md (or any valid MIME extension) are not categorized as Sections?

Should I open an issue for this?

13

Yes…

1 Like
14

Thanks. Just back-referencing:

1 Like
15

Thanks, I hadn’t realized it was a bug. I did notice it was sometimes working, sometimes not, so I thought it was Chrome doing weird things with the caching. Appreciate the help.

16

This issue is now fixed on the latest master branch (Thanks @bep for the quick fix!). Now simply moving content/foo.md to content/foo/index.md will/should work :smile:

1 Like
17

Thanks for the quick characterization and work. :slightly_smiling_face: