Generating URLs when blanks or capital letters in path

Hi,
I know that using blanks, capital and small letters or special characters isn’t the best way for file and folder names. (And I wouldn’t do it, if I start a new project.) But I have to continue work on a existing projects with blanks and capital letters in file and folder names.

I recognized that Hugo urlize nicely the URL to the page, but not to additional files surrounding a page!

For reproduction I’ve followed the quick start instruction Quick Start | Hugo and made a complete new hugo site. You can find the generated public files here: hugo-quickstart/public/posts at main · raum51/hugo-quickstart · GitHub and compare it with the structure of the content files here: hugo-quickstart/content/posts at main · raum51/hugo-quickstart · GitHub

Is there any given rule for file and folder naming in Hugo?
Is this - I would say bug - already known?

slug and url frontmatter will help you create spaceless links to your content.

I know that I could modify the URL by slug and url.

The URL of the content page is already “cleaned” from blanks and capital letters out of the Hugo box. But the URL of additional content (which are not included as page ressources Page Resources | Hugo) doesn’t get cleaned.

I would not.

TLDR

  1. Use lowercase letters and underscores for file and directory names
  2. Use page bundles to logically connect resources to content

Leaf Bundle

If your content structure is like this:

content
└── posts/
    └── My Directory/
        ├── image.jpg
        └── index.md   <-- indicates that the directory is a page (leaf) bundle

… Hugo knows that the image is a page resource, and the structure of the public directory will look like this:

public/
├── posts/
│   ├── my-directory/
│   │   ├── image.jpg
│   │   └── index.html
│   └── index.html
└── index.html

Branch Bundle

If your content structure is like this:

content/
└── posts/
    └── My Directory/
        ├── a.md
        ├── b.md
        ├── image.jpg
        └── _index.md  <-- indicates that the directory is a page (branch) bundle

… Hugo knows that the image is a page resource, and the structure of the public directory will look like this:

public/
├── posts/
│   ├── my-directory/
│   │   ├── a/
│   │   │   └── index.html
│   │   ├── b/
│   │   │   └── index.html
│   │   ├── image.jpg
│   │   └── index.html
│   └── index.html
└── index.html

Your Structure

But with this content structure:

content/
└── posts/
    └── My Directory/
        ├── a.md
        └── image.jpg  <-- this file is a logical orphan

… the image is a logical orphan; it is not related to the content file in any way. When you build the site, the orphan (and its container) are copied as is:

public/
├── posts/
│   ├── my-directory/
│   │   └── a/
│   │       └── index.html
│   ├── My Directory/
│   │   └── image.jpg
│   └── index.html
└── index.html

You would have the same outcome if your static directory looked like this:

static
└── posts/
    └── My Directory/
        └── image.jpg

Static content is copied as is.

1 Like

I use always only lowercase letter and underscores (or hyphen) for file and directory names for my own projects. But in this case I have to contribute to an already existing project. I tried to find an info in the Hugo docs but couldn’t found such an info. So I asked in my first post:

If such a rule is already documented in the Hugo docs (and I hadn’t found it), OK, then it’s my fault and everybody (also my other project partners) should follow this rules.

Now to your 2nd point

Always when I thought, I have fully understood Hugos concept of Page/Leave/Branch-Bundles I learn something knew or recognize more consequential effects of this concepts.

@jmooring You are completely right. I had a wrong folder structure, because I hadn’t fully understood the difference (and use cases) of leave and branch bundles. Thank you very much!

Franz

For the most part, Hugo doesn’t care if you use capital letters or spaces in your file and directory names, but there are at least a couple of known issues:

Use lowercase-no-spaces is not a rule, but instead guidance based on too many years of tracking down stupid (non Hugo) problems that were easily avoided.

Some operating systems are case sensitive, some are not. Some web servers are case sensitive, some are not. Your mixed case structure and code might work fine on one, but not on another.

1 Like

This topic was automatically closed 2 days after the last reply. New replies are no longer allowed.