How do I make the current /docs/prologue/introduction/ page show up at the root?

[mroswell]

I'm excited to discover doks. I have a good feeling about it!

I'd like to pare down my site to just the docs page, and have it appear on the root. Can you describe how to do that?

Likewise, I'd want Home / Docs / Prologue / Introduction breadcrumb to read: Home / Prologue / Introduction

[h-enk]

In .config/default/config.toml, set the docs permalink structure (see also Permalink Configuration Values):

[permalinks]
  blog = "/blog/:title/"
  docs = "/:sections[1:]/:title/"

In the frontmatter of ./content/docs/prologue/introduction.md, add url:

..
menu:
  docs:
    parent: "prologue"
weight: 100
toc: true
url: /
---

I'm not sure though how to update ./layouts/partials/main/breadcrumb.html (copied over from ./node_modules/@hyas/doks/layouts/partials/main/breadcrumb.html):

{{ with .Parent -}}
  {{ partial "main/breadcrumb.html" . -}}
  <li class="breadcrumb-item"><a href="{{ .RelPermalink }}">{{ if .IsHome }}Home{{ else }}{{ .Title }}{{ end }}</a></li>
{{ end -}}

👉 Help appreciated here!

[mroswell]

In config/_default/config.toml, set the docs permalink structure (see also Permalink Configuration Values):

[permalinks]
  blog = "/blog/:title/"
  docs = "/:sections[1:]/:title/"

This seems to be my solution, so far
In config/_default/menus.toml, remove or comment out:

[[main]]
  name = "Docs"
  url = "/"
  weight = 10

In the frontmatter of ./content/docs/prologue/introduction.md, add url:

..
menu:
  docs:
    parent: "prologue"
weight: 100
toc: true
url: "/"

Remove layouts/index.html

[mroswell]

Thank you!

[mroswell]

The original home page still appears on https://www.hugonewbie.com, which is weird, because locally I was successful moving docs to the home page. I had removed /docs from the menu entirely. Would that impact docs = "/:sections[1:]/:title/"

(I don't yet understand this syntax.... A lot of learning curve.)

Maybe netlify has a different priority hierarchy, and chooses layouts/index.com over the config url settings?

In any case, implementing the solution above worked locally, but not on the live site. Sigh. suggestions welcome.

Maybe I should try deleting that index page....

[mroswell]

very strange, sometimes the old home page appears locally, despite clearing the cache. despite moving the file, despite implementing the above.

BTW, I'm wondering if on netlify I'm supposed to ask it to run npm start instead of the Build command I had inherited: hugo --gc --minify -b $URL

I want to love hugo, but this is so difficult to figure out.

[mroswell]

Maybe the fact that it is still loading the home page has something to do with module.mounts. Very mysterious.

[mroswell]

I tried installing the starter theme. I'm having the same thing happen, where the docs will appear on the home page for a few minutes, and then it just defaults back to the original home page after that. Why would that happen? so weird. also, very frustrating. (By the way, I still see mounts on the starter theme. Does that mean that static and assets will still come from the source instead of locally?

I very much want the docs to be the home page. But that home page remains persistent... like a zombie. It seems to be gone, but then it isn't. Can anyone else replicate this?

1. start with new child or starter theme.
2. make the change above.
3. voila, docs on the home page, until a few minutes later it's back to the original home page.

[mroswell]

For a minute I thought putting "/" in quotes was a solution. but several minutes later, it's back to the zombie home page.

I hope someone can replicate this weird experience.

Also, if the home page issue is ever resolved, (replacing home page with docs) I hope to also get guidance on how to edit menus.toml to remove the extraneous /docs in the menu.

[mroswell]

For now all is working. Maybe removing index was the key. There are some slight changes here, from the answer provided above.

In config/_default/config.toml, set the docs permalink structure (see also Permalink Configuration Values):

[permalinks]
  blog = "/blog/:title/"
  docs = "/:sections[1:]/:title/"

This seems to be my solution, so far
In config/_default/menus.toml, remove or comment out:

[[main]]
  name = "Docs"
  url = "/"
  weight = 10

In the frontmatter of ./content/docs/prologue/introduction.md, add url:

..
menu:
  docs:
    parent: "prologue"
weight: 100
toc: true
url: "/"

Remove layouts/index.html

[mroswell]

Nope, the zombie home page is back, locally. (so docs--the sole purpose of the site--are completely gone from the menu...)

[mroswell]

I hope someone else is able to replicate my experience. Seems to take more than 5 minutes of clicking around before the zombie home page returns.

• start with new child or starter theme.
• make the change above.
• voila, docs on the home page, until a few minutes later (sometimes longer) it's back to the original home page.

[h-enk]

See also #187

@epogrebnyak, how did you manage to get this similar setup?

[epogrebnyak]

@mroswell - do you have source of the website somewhere in gith7b or other version control?

[epogrebnyak]

* make the change above.

Need the source you are building from

[mroswell]

https://github.com/mroswell/hugonewbie.com

[epogrebnyak]

We have an "open book" layout here: https://github.com/epogrebnyak/finec-mgimo-v2, you can click on website too. We had to change index.html and not much else, especially if you stay in one-language setup. @necelntano was helping a lot with setup, may be he has some details too сб, 19 июн. 2021 г., 16:59 Henk Verlinde ***@***.***>:

…

See also #187 <#187> @epogrebnyak <https://github.com/epogrebnyak>, how did you manage to get this similar setup? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#343 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACGWBLXGSEGX2VWLH37VIN3TTSPC5ANCNFSM4632HZOQ> .

[mroswell]

https://github.com/mroswell/hugonewbie.com From memory, typed on phone. At family gathering right now. Sometimes it works and then 10 minutes later still the old site. Either a caching issue or a retrieving from the parent theme issue, I guess.

On Sat, Jun 19, 2021 at 10:10 AM Evgeny Pogrebnyak ***@***.***> wrote: @mroswell <https://github.com/mroswell> - do you have source of the website somewhere in filesystem? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#343 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABPAOE6IBYEUM2DRNOTMITTTSQNBANCNFSM4632HZOQ> .

-- -- http://HealthyCampaign.org http://SugarWars.com http://bit.ly/antiviral-nutrition

[mroswell]

It occurs to me that I'm probably working with four different caches:

• The Chrome browser cache (which I was consistently clearing)
• The GitHub cache,
• A Netlify cache (that I haven't yet learned about in any detail...)
• And also an IDE cache.

I discovered an option in WebStorm which is "Invalidate caches."

What was happening was so weird this morning. Sometimes things worked locally but not on the live site. Sometimes visa versa. "Working," meaning the docs appeared on the home page. (I've decided against figuring out breadcrumbs for now, which was in the original question.)

Fingers crossed, I haven't seen the unwanted homepage this evening.

I figured out that this was more likely a caching issue (as opposed to some parent theme override, or somesuch), when I later simply turned off breadcrumbs, and they would appear or not appear, kind of randomly for a while, and then finally no longer appeared.

I'll let you know if I have any more bizarre caching issues. I'm thinking that I can proceed with this project as a happy Doks user! Thanks so much for the support. I'll figure out how to mark an answer... and then maybe make one additional query about the section syntax.

[mroswell]

Oy! This morning the original home page is back on my local dev server! I chose "Invalidate caches" again in WebStorm (with the default middle item selected) and it resolved the issue. But I do want to know: Is the parent theme somehow causing this? (That home page doesn't exist anywhere in my project anymore, file-wise. I deleted it. So that original home page should not appear in the project.) Or is it still some crazy caching issue? I'm exiting my editor, opening it back up again.

I also plan to to learn about .idea files in WebStorm. I wonder if deleting that would help. (I've been using WebStorm for years, it's what I know how to use... so I want to stick with it...)

I truly don't understand how parent/child themes work, which is part of what makes this issue so confusing. (though obviously, having zombie content appear--it's not there, but it's there-- is confusing all on its own.)

[mroswell]

Also back at: https://www.hugonewbie.com/ (at least for me) even though the home page file is not in the directory, and I followed the solution above (plus removing from menu)

Please help me to resolve this.

[mroswell]

I'm going to use the Doks starter theme to see if that resolves the issue. But it may be a few days before I have a chance to complete this.

[mroswell]

I used kaleidoscope (mac directory comparison tool) to try to move everything from the starter theme over to the one that was using the child theme. (I did this because last time I tried to wholesale replace a project, I got caught up in git/github hell.) Of course, I retained the essential change from above. For some reason the zombie page was STILL there on local. I renamed the root _index.md to was_index.md. that seemed to (at least for now) remove the zombie home page.

This has been one of the craziest web development experiences I've ever had. I'm hoping to get the docs format on the home page with no starter page.

(I wouldn't invest this much time in making this work if I didn't have an otherwise REALLY good feeling about this theme and in Hugo in general.)

I just keep suspecting that the mount has something to do with this... but I just don't know.

[mroswell]

I deployed, and once again what appears locally is different than what appears on my local site. https://www.hugonewbie.com/

All the pages implement the theme but the home page.

I don't know what's going on.

[mroswell]

I'd like to find someone who is very skilled in hugo help me out. I'd be happy to pay for time over zoom on Tuesday.

[mroswell]

I'll leave this thread alone until I find help... but just a note that I'm trying so many things, that a given status described above might not be the state of the site when you see it. Definitely hoping to overcome this big bump in the hugo learning curve.

[epogrebnyak]

@necelentano - might be available for hired work. Andrey - can you please have a look?

[mroswell]

Thanks. A note that this issue seems to be resolved. (I still don't entirely understand the mounts, or the section syntax in h-enk's answer, but I'm definitely clearer on template hierarchy... and I think (not sure) that the cause of the zombie page was that it might've been pulling it from node_modules. I'm happy to get past this big bump, and to continue climbing the Hugo learning curve!

[mroswell]

Ahah: the permalinks section code is coming into focus. docs/ is removed from the url by docs = "/:sections[1:]/:title/" because it's taking a slice of the sections. I guess the section by default would be something like docs/prologue, and the :sections[1:] slice removes docs/ (I still need to learn more about the initial colon, and when that is used.)

[mroswell]

I downloaded the starter theme from scratch. did the steps described above in
#343 (comment)
Went on to remove /docs from the menu (since that should've been part of the answer. it shouldn't be in the menu because of it's already the home page, plus it is a 404 at that point.

Same issue: the zombie home page (making docs disappear), even on a project started from scratch, without using Webstorm... just these steps.

Can anyone else replicate and identify a solution?

[h-enk]

Your setup holds a conflict. On the one hand, Hugo tries to set the Introduction page as the homepage (as per setting url = "/" in the frontmatter of the page). On the other hand, Hugo follows the Layout Lookup for Home Page, and tries to list out all pages as the homepage, because ./layouts/_default/list.html is present.

So, try renaming ./layouts/_default/list.html to ./layouts/_default/list.bak.html (probably not needed anyway — in your setup)

[mroswell]

Thank you!

[mroswell]

I'm pretty sure (not confident, because I tried so many things) that the zombie home page issue was related to this module.mounts. I haven't had the issue since I commented it out. (But maybe the above would've taken care of it too, I don't know.)

[[module.mounts]]
source = "node_modules/@hyas/doks/layouts"
target = "layouts"

I feel so lucky to have your support. I wanted to love Hugo (and this theme as well!), and have success with my learning curve. I think I will, now that I can proceed!

[mroswell]

Pulling solutions together in one comment:

1. In config/_default/config.toml, set the docs permalink structure (see also Permalink Configuration Values):

[permalinks]
  blog = "/blog/:title/"
  docs = "/:sections[1:]/:title/"

2. In the frontmatter of ./content/docs/prologue/introduction.md, add url:

..
menu:
  docs:
    parent: "prologue"
weight: 100
toc: true
url: "/"

3. In menus.toml, remove or comment out

[[main]]
  name = "Docs"
  url = "/"
  weight = 10

4. Delete or rename layouts/index.html

5. Delete or rename./layouts/_default/list.html to ./layouts/_default/list.bak.html

6. if this effort causes the "zombie" home page effect, in config.toml, comment out:
   [[module.mounts]]
   source = "node_modules/@hyas/doks/layouts"
   target = "layouts"

7. Be aware of how to clear editor cache, browser cache, netlify cache, and maybe wait long enough for github cache to clear.

8. Still left to resolve: remove "docs/" from permalinks

(Open to feedback if there are still tweaks that can be made to this.)

[epogrebnyak]

@necelentano - can you please review the steps taken at https://github.com/mroswell/hugonewbie.com?

[epogrebnyak]

With starter theme you do not depend on node_modules - so may be easier to manage. пн, 21 июн. 2021 г. в 15:36, Marjorie Roswell ***@***.***>:

…

Thanks. A note that this issue seems to be resolved. (I still don't entirely understand the mounts, or the section syntax in h-enk's answer, but I'm definitely clearer on template hierarchy... and I think (not sure) that the cause of the zombie page was that it might've been pulling it from node_modules. I'm happy to get past this big bump, and to continue climbing the Hugo learning curve! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#343 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACGWBLVUMYJYGGUPDNPLMTLTT4W4FANCNFSM4632HZOQ> .

[james-s-w-clark]

I got this to work a bit differently (at least, it looks like it works so far!).

My files have paths like project\content\en\docs\topic\specific-post\index.md, and links looked like http://localhost:1313/docs/topic/specific-topic/

Two changes seem to get this to work for http://localhost:1313/topic/specific-topic/

First:
project\config\_default\config.toml

[permalinks]
- blog = "/blog/:title/"
- # docs = "/docs/1.0/:sections[1:]/:title/"
+ docs = "/:sections[1:]/:title/"

Second:
in project\config\_default\menus\menus.en.toml
For every [[docs]] entry, do

-	url = "/docs/introduction/"
+	url = "/introduction/"

I will try deploying and see what Netlify thinks of it. I tried instructions above and got a few broken pages.

[smythp]

I just worked through the main steps outlined above, and it does seem to work, in the sense that I have a specific docs page be the main page. However, I get a huge number of warnings, such as:

WARN 2023/07/31 20:08:59 found no layout file for "Sitemap" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2023/07/31 20:08:59 found no layout file for "HTML" for kind "term": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2023/07/31 20:08:59 found no layout file for "HTML" for kind "home": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

I'm not sure how to interpret this, but it suggests the solution outlined here will cause other issues. (It seems others on this thread had problems with broken paths, which is not surprising.) I'm going to try to approach this in another way, but I also wonder if anyone here has developed a more elegant, maintainable, and/or straightforward solution before I spend two days learning everything about Hugo so I can brute force this.

[james-s-w-clark]

@smythp I switched to Docusaurus, but it has its own quirks. I have no more info to help on this route; good luck!

[smythp]

For my own reference, for posterity, and for any internet wanderer that may happen across this thread, here's what I did to resolve the issue in a more straightforward way.

1. In layouts/_default/index.html, remove everything, including the "main" wrapper, and add the below.

{{ range .Site.Pages }}
  {{ if .Params.home }}
    {{.Render}}
  {{ end }}
{{ end }}

This cycles through all the pages on the site (not just the top level, so may not be appropriate for enormous sites). If it finds a page with home: true in the front matter, it renders it on the home page.

2. In the front matter of the page you'd like to make your home page, add:

home: true
images: []
contributors: []

[h-enk]

Thanks for sharing!

Another way to get the desired behavior is to set things up on the hosting side. This is e.g. how I did that recently on Netlify — using netlify.toml:

[[redirects]]
  from = "/"
  to = "/start-here/getting-started/"
  status = 301
  force = true

More background: Redirects and rewrite

[johnnymatthews]

There have been a lot of changes this the solutions were posted in this thread. It seems that none of them work in the latest version of Doks. @h-enk, do you have any pointers as to how folks can disable the homepage and point users straight to the /docs section?

[h-enk]

Thanks for sharing!

Another way to get the desired behavior is to set things up on the hosting side. This is e.g. how I did that recently on Netlify — using netlify.toml:

[[redirects]]
  from = "/"
  to = "/start-here/getting-started/"
  status = 301
  force = true

More background: Redirects and rewrite

The recommended way (still) is to do this server side (there is no proper Hugo way). I will add this to the docs