Use another file instead _index.md as the homepage

support
1

Hi,
I have a problem of content management.
Normally you would use _index.md under content/ as the page content for the homepage, but I wrote that introduction in intro.md, and that cannot change.
I tried to use

<article id=book-content>
	{{- (.Site.GetPage "intro").Content -}}
</article>

in home.html but it says

Error: Error building site: “/home/drm/WEBSITE/content/docs/intro.md:1:1”: “/home/drm/WEBSITE/layouts/home/_markup/render-image.html:39:156”: execute of template failed: template: home/_markup/render-image.html:39:156: executing “home/_markup/render-image.html” at <.RelPermalink>: can’t evaluate field RelPermalink in type interface {}

the frontmatter is:

---
title: Purpose of this website
type: "home"
url: '/'
---

What’s the slickest, hugoest way to tell it to use intro.md (or any named files) instead of _index.md ?
Before I used to include intro.md with a shortcode ({{ with .Get 0 | site.GetPage }}{{ .RawContent | .Page.RenderString }}{{ end }}) but it separates the frontmatter from the actual content and I don’t like it.

2

This might be dependent on the webserver in use. By default they look to each dir for a webpage file named “index”. There are a couple things you can try. First thing I would try is the url string in the frontmatter below:

url: "/index.html"

Keep in mind that no matter how far down the page is nested, the first “/” in the url string of frontmatter is the root of the entire site. For instance, if you are trying to make a main page for a “content” subdirectory, you can try changing the url frontmatter to “/content/” or “/content/index.html”

You might be able to create an “.htaccess” file in the desired dir and add the following to it, which will allow you to specify a different filename to be the index of that dir, through use of the static folder.

DirectoryIndex customfilename.html

Other than that there maybe someone more qualified on here to troubleshoot further. Maybe there is a setting in the site’s config which can specify an index for a specific dir.

3

Not sure how slick it is, but I think the only way is to configure that mapping as a mount:

But note: Once you add 1 content mount, you must also add the content folder as a mount.

2 Likes
4

To put it simply, I don’t understand anything about that message or the site page.
What do I need to write to map /content/docs/intro.md to /content/_index.md ?
I would suppose:

[module]
[[module.mounts]]
source = “content/docs/intro/”
target = “content/”

5

I’ve done it like this:

  • frontmatter of intro.md:
---
title: Purpose of this website
type: "home"
_build:
 render: false
---

No content/_index.md.
In home.html:

<article id=book-content>
	{{with .GetPage "intro.md"}}{{.Content }}{{end}}
</article>

No intro.html produced. Perfect.
The only caveat, rather unimportant, is that I need {{with .File}} in a few places because _index.md really is absent. I would prefer hugo to consider intro.md AS the new content/_index.md
This is pretty annoying, simply surrounding the home template with a {{ with .GetPage "intro.md" }} doesn’t work, nor things like {{ partial "docs/html-head-specific" (.GetPage "intro.md") }} !

6

Whats stopping you from adding the partials you need to home.html?

What you are doing is a valid way to achieve what you want.

Simply edit your index.html template or make a new template and set it in the _index.md front matter with .GetPage and any other partials you need.

7

See

for the docs for the configuration bep showed.

8

Obviously I read what is talked about. But it doesn’t seem make any sense in the context of what I ask, because it’s for mounting one or more directory into a virtual folder. I don’t see that it works for files. At least I can’t make do anything.

9

Ah. Well Hugo’s virtual file system supports mounting files as well as directories. I guess adding and explanation of that would be a good first submission to the hugoDocs repo (hint, hint).

You can mount files into a directory, with same name as the source file:

[[module. Mounts]]
source = "README.md"
target = "content/some-dir/"

would mean Hugo would ‘see’: content/some-dir/README.md

or you can mount the file with a new name, anywhere in the virtual file system.

[[module. Mounts]]
source = "README.md"
target = "content/_index.md"

as bep showed.

In this case Hugo ‘sees’: content/_index.md with the contents of the repo’s README.md.

From what it sounds like you have:

source = "content/intro.md"
target = "content/_index.md"

In which case Hugo would ‘see’ content/_index.md with the contents of content/intro.md.

HTH.

If you need to make sure the file doesn’t appear to hugo in both places you can use a cascade in the config.toml (or hugo.toml) that targets only /intro.md and sets it to not be rendered or listed.

See Configure Hugo | Hugo , Front Matter | Hugo and Build Options | Hugo (gohugo.io)

And of course, after posting, I noticed I missed that you already saw some of this.

1 Like
10

And couldn’t make it work… meaning I must have missed something. The devil’s in the details.

11

Heh, you were too fast! I edited the post with the following (which is I think the magic you need):

If you need to make sure the file doesn’t appear to hugo in both places you can use a cascade in the config.toml (or hugo.toml) that targets only /intro.md and sets it to not be rendered or listed.

See Configure Hugo | Hugo

12

Ok… it had to be the right combination of what I put in template, config, directory structure and frontmatters. Trying different things made a bit of a mess, someone had to lay out what it does in simple terms, then I could go back and clean the mess.
Seems like it doesn’t need cascade, there is no /intro/index.html
Thanks ! No more whacky editing templates, that way it’s exactly like it had moved and renamed intro before building.

1 Like
13

Glad I could help.

One thing to keep in mind is that once you have mounts config, there is no automatic config. That means nothing else under content will be visible to Hugo unless you mount your content directory.

E.g.

[[module.mounts]]
source = "content"
target = "content"

At which point the intro.md will be mounted again and you will need the cascade.

Or you could do as bep showed and only mount subdirectories of content.

And thank you for asking questions, even if it sometimes gets frustrating, and being willing to say when you don’t understand. It not only helps us help you, but I hope it can improve the understanding of what non-developers need for documentation.

14

Note that this is covered in the documentation, including an example at the bottom of the page:
https://gohugo.io/hugo-modules/configuration/#module-config-mounts

1 Like
15

Thank for the reminder Joe. I wanted to highlight that in this discussion because it is easy to miss (or not recognize the importance of), IMO.

1 Like
16

I checked and there is no direct example of mounting files, it just says:

One or more glob patterns matching files or directories to include. If excludeFiles is not set, the files matching includeFiles will be the files mounted.

My issue was that I didn’t understand what it meant, what mounting meant. More precisely, when in the whole building chain files/directories were moved around (virtually). I thought it could before everything or after, moving around .html files. I got confused with both redirections and alternative urls.
All those notions share similarities, this is the kind of thing which I think confuses unexperienced laymen.

My mistake is mentioned indeed:

When you add a mount, the default mount for the concerned target root is ignored: be sure to explicitly add it.

Problem is, that sounds like Chinese. What that really means is not obvious, nor what happens when you do forget it.
A short explanation in simple terms, might sound stupid but would help a lot. I know about system files, mounting usb sticks or disks, beside html and css this is about the common denominator to all amateur webdeveloppers. No need to go too basic, but pictures help.

What about the following - feel free to correct the terminology and make it a bit shorter perhaps, although too concise a wording and you loose people. In short, dumb it down in the spirit of the collection “for dummies”, when it makes sense.

Before mounts are considered:

├──􀀂  content 
│  └──􀀂  docs … 
│  	  └──􀇱  intro.md 
├──􀀂  data 
└──􀀂  2data 

[module]
[[module.mounts]]
  source = 'content'
  target = 'content'
[[module.mounts]]
  source = '2data'
  target = 'data'
[[module.mounts]]
  source = 'data'
  target = 'data'
[[module.mounts]]
  source = 'content/docs/intro.md'
  target = 'content/_index.md'

In this example, directory 2data and data are fused as if all their content files were dumped into a third directory named “data”.
Without the third mount mapping “data” to “data”, the original “data” folder is erased instead of fusing with the new one. Mounting files, has the effect of moving them in the project arborescence and if the names of the source and target differ, renaming them too.
These virtual change occur before all building and processing, so what Hugo sees at the start of it is:
After the mounting, before building:

├──􀀂  content 
│  ├──􀀂  docs … 
│  └──􀇱  _index.md \\ file content of intro.md
└──􀀂  data \\ content of data + 2data

NB: When you add a mount, the default mount for the concerned target root is ignored: be sure to explicitly add it. In this case, without the first mapping of content to content, content is not seen at all, as if all content files had been deleted.

1 Like
17

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