Hours lost trying to get about.md published

[lewisl]

Is about.md magic? It seems to be.

I have a very elaborate and successful site at a-view.org. I mention this to indicate I have successfully done some elaborate stuff with hugo.

But, simple things seem very trying.

The troubled site is just a launch place to other sites.

All it has is a home page at index.html with some introductory text and a menu to launch other sites. At some point I made add blog entries–not for now.

It has an about page which might also have more content in the future.

I cannot for the life of me get the about page to generate or appear. I think the theme also has some problems as the layouts are inconsistent with the theme’s documentation. I suspect this is rather common.

Here is the directory structure:

lewislevin-com
   archetypes      # untouched 
   content
      posts
         about.md
      index.md
   data               # untouched
   layouts           # have not added any to the theme
      shortcodes
          debug.html       # I put some arbitrary html here that I can display on pages for debugging purposes (Handy!)
   static                # empty
   themes
       flex-master        # very sparse theme
   .gitignore
   config.toml

I can send the entire config.toml in another post (since attachments aren’t supported) Hugo is very sensitive to settings that might appear to be unrelated, but I can’t tell if something else is causing a problem.

It seems that the relevant sections create the top level menu:

[[menu.nav]]
    name = "Winter Cove"
    url = "https://www.wintercove.org/"

[[menu.nav]]
    name = "Travelogues"
    url = "https://a-view.org"

[[menu.nav]]
    name = "Photos"
    url = "https://photos.lewislevin.com"

  [[menu.nav]]
    name = "About"
    url = "/posts/about/"
    weight = "-100"

When I generate the site to a local output directory, I never see a directory for posts and never see the output file for about.html. So, naturally the above menu entry always generates a 404.

I have tried putting about.md in the content directory and the menu link as “/about/”. Every once a while this seems to work, but never consistently. Or it breaks the home age for reasons unknown.

This is why I am asking if somehow there is special case code in Hugo for about.

[pointyfar]

lewislevin-com
   archetypes      # untouched 
   content
      posts
         about.md
      index.md   # <------ this should be _index.md

[lewisl]

That doesn’t get me what I want. I want a landing page with content. I thought _index.md was not rendered and only provided the front matter to Hugo.

I want an opening page with a menu and some static content.

Three menu items point to external websites. (also not working… …you replied and I didn’t understand).

One menu item points to an internal page. With _index.md I get the about page as the landing page because it is the only content.

Hard things are easier in Hugo than easy things.

This is a site with 2 pages, neither of which work.

Maybe it’s a dud theme?

[lewisl]

Now it’s working. First time all day. It works with index.md. And about shows up properly.

I flushed the browser cache and it still works.

But, then I decided to run hugo server again. Now it doesn’t work.

I can either have content on the landing page or I can have about.

But, not both.

The fragility and inconsistency of Hugo is driving me crazy.

Yet, my complex site with page bundles and NO static landing page (home page) is working perfectly. This one is nearly 800Mb and has more than one hundred pages.

I am beyond frustrated.

You can see the rep at GitHub - lewisl/lewislevin-com.

It’s tiny.

[pointyfar]

Like I said, it needs to be named content/_index.md. It will not work reliably otherwise.

_content/_index.md is the content page for your site homepage, eg. example.com/.

@lewisl

With _index.md I get the about page as the landing page because it is the only content.

Not entirely correct.

Your theme uses layouts/_default/home.html to render the homepage.

The code on that layout page takes content pages (which includes posts/about.md and lists them. If you add another page, content/posts/foo.md and add content to it, the homepage will also pick that up and render that on the homepage as well.

You don’t see the contents of content/_index.md because your theme does not render it. You can see this yourself if you add {{ .Content }} in layouts/_default/home.html just before the closing {{ end }} tag.

---

You need to do the following exactly:

1. Rename content/index.md to content/_index.md
2. Restart hugo server

That will get your homepage working. That will also get /posts/about/ working.

[lewisl]

Of course that worked as you knew it would. I forgot about {{ .Content }} because I have not created a complete template myself, though I added this to another one. I didn’t think the layouts were the key.

I started going through this https://pakstech.com/blog/create-hugo-theme/ but hadn’t finished it yet. I will do so.

It’s not so hard but Hugo has a lot of moving parts. If you added a really nice example and annotated it, it would help people see how the parts come together. There is lots of documentation in much detail but doesn’t bring the crucial pieces together.

Thanks for sticking with me.