Docsy theme with latest submodule -- puts right-hand ToC in the wrong location

[mjang-cobalt]

With the latest submodule, the right-hand TOC appears in the wrong place:

With an earlier version of the Docsy submodule, it all "works fine"

The difference:

• Git commit f82dd5ef works
• Git commit 6e6061b does not

The relevant PR is https://github.com/google/docsy/pull/554

Unknown. When I run git submodule update -f --init, it checks a later (but not the latest) commit,

43a70b21d

Workaround

Include a git checkout f82dd5e in the netlify.toml file:

[build]
publish = "public"
command = "cd themes/docsy && git submodule update -f --init && git checkout f82dd5e && cd ../..   && hugo"

[narrenfrei]

Have you tried to update the submodules recursive? git submodule update --init --recursive

[mjang-cobalt]

Have you tried to update the submodules recursive? `git submodule update --init --recursive

That command changes nothing in my (unfortunately private) repo.

I think I also should match the build pattern described in https://www.docsy.dev/docs/deployment/#deployment-with-netlify Otherwise, my local build varies from what I see when building with Netlify.

Odd bit -- when I try the setup with a sample repo (based on justdocs), the pulled commit (4808e0a) is from October 2020.

[mjang-cobalt]

Also... I can replicate the issue locally on the justdocs repo, using the following steps:

1. Open a branch
2. Navigate to themes/docsy
3. Check out a problematic commit (in this case, git checkout 43a70b21d)
4. cd ../..
5. hugo mod clean
6. hugo server -D

And here's the result:

[mjang-cobalt]

I'd share the branch, but it seems I don't have access rights:

ERROR: Permission to LisaFC/justdocs.git denied to mjang-cobalt.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

[LisaFC]

Hmm, the justdocs repo hasn't had its Docsy submodule updated in some time, I'll fix that (it's also probably not the best example for a "just docs" deployment anymore now that we have Hugo improvements as described in: https://www.docsy.dev/docs/adding-content/content/#alternative-site-structure)

The "menu accidentally appearing in the wrong place" version of the theme was from a while back and fixed pretty quickly, IIRC. If you're using the theme itself as a submodule you should be able to pull the latest Docsy theme from the repo in your local copy with git submodule update --remote

[pschrey2]

Could discussion #631 be the root cause?

[mjang-cobalt]

you should be able to pull the latest Docsy theme from the repo in your local copy with git submodule update --remote

Thanks for confirming at least part of this issue. Unfortunately, when I build to the later commit, the problem persists in Netlify.

[LisaFC]

So just to check what's happening when you're updating - the usual flow (if you're using Netlify) should be:

• Do git submodule update --remote in your local copy
• Add/commit the change:

  git add themes/
  git commit -m "Updating theme submodule" 

• push it to your repository (so your repo version is now pointing to the latest version of Docsy)
• Netlify rebuilds and publishes from that version of your repository

Is that what you've been doing?

[LisaFC]

Could discussion #631 be the root cause?

Hmm, I don't think so - the menus in the current Docsy docs work fine and they're coming from the repo head (which has the accidentally downgraded Bootstrap version).

[mjang-cobalt]

Thanks for the followup, @LisaFC . I've included the additional steps that I take, inline.

So just to check what's happening when you're updating - the usual flow (if you're using Netlify) should be:

• Do git submodule update --remote in your local copy

  cd themes/docsy git checkout f82dd5e cd ../.. Update my netlify.toml file to check out the same submodule commit

• Add/commit the change:

 git add themes/
 git commit -m "Updating theme submodule" 

• push it to your repository (so your repo version is now pointing to the latest version of Docsy)
• Netlify rebuilds and publishes from that version of your repository

[LisaFC]

Couple of things (after which I think I might know what's going on)

• Is there a reason why you're trying to update to a specific commit rather than head? (and yes, we do need to start doing version tags)
• Is the submodule in your source repo (the one Netlify knows about) actually pointing to the version you want to use?
• You shouldn't need to update your netlify.toml to checkout the same version of the Docsy theme if the submodule in your source repo is already pointing to the correct commit, it'll just go with whatever's in the source repo - it feels like you're trying to update the submodule twice

[mjang-cobalt]

@LisaFC I'm pointing the submodule to a specific commit, as that's the latest commit that works for my build. I update my netlify.toml file to point to the same commit, otherwise the build I see from Netlify differs from the build on my local system.

it feels like you're trying to update the submodule twice

You're right. For me, it's a workaround until I either:

• Learn more about setting up submodules to find a working docsy theme build
• See a fix to this bug that works for my build

[LisaFC]

So where is the repo that you're pointing Netlify to? What version of Docsy is that pointing to? I don't quite understand how Netlify is giving you different results (ie an outdated/broken theme version) to your local build unless you haven't pushed the theme update to the repo. I just tried updating a test project to a specific commit in Docsy and it worked fine both locally and in Netlify.

The regular workflow is that you update the theme locally (to your preferred commit if you want), you push the update to your repo, and Netlify gets the version to use from that.

[pschrey2]

I had this same issue when updating the Docsy git submodule to the latest version in my project for the swagger UI pages. But I found the reason: the layouts/swagger/baseof.html file got changed between the two Docsy versions.

Because I initially used on local project level a changed version based on the older Docsy version, the TOC got swapped. After bringing the local version in sync with the new baseof.html file, it went fine again. I guess the class change from "td-toc" to "td-sidebar-toc" on line 23 is the root cause.

[mjang-cobalt]

So where is the repo that you're pointing Netlify to

Unfortunately, I can't share that info at this time.

I don't quite understand how Netlify is giving you different results (ie an outdated/broken theme version) to your local build unless you haven't pushed the theme update to the repo.

The theme updates break my build. For consistency, I have to make sure that what I push, and what Netlify does in their CI includes the same git hash for the docsy submodule.

In https://github.com/google/docsy/issues/626#issuecomment-877187958, I described what I did to confirm this bug in the justdocs repo.

[LisaFC]

So where is the repo that you're pointing Netlify to

Unfortunately, I can't share that info at this time.

Oh sorry, I didn't mean I need to see the repo, I was just wondering if in the repo itself (versus your local copy, or what's happening on Netlify) the submodule is pointing to the correct commit.

The theme updates break my build. For consistency, I have to make sure that what I push, and what Netlify does in their CI includes the same git hash for the docsy submodule.

I'm not entirely sure what you mean here - in my GitHub/Netlify workflow, whatever submodule info (ie which commit hash I want to use Docsy at) I use locally and push to my source repo is what Netlify uses, I don't have to specify it again anywhere.

I was trying to find the last time the problem with the right menu happened - it did happen before to a community member in #590 and it wasn't actually an issue with that commit, it was some kind of git submodules mismatch in their local setup. You could have a look through the issue and see what they tried.

As I said above, the current Docsy docs use the theme from head (as they're in the same repo) and the menus in our Netlify build have been fine throughout (including at the "problematic" commit for #590 and when we accidentally downgraded Bootstrap, which is fixed now).

In #626 (comment), I described what I did to confirm this bug in the justdocs repo.

OK, I'll try to reproduce it with justdocs as well.

Just to be super clear about what your issue is before I start trying to reproduce it with another repo:

• You want to upgrade to the most recent version of Docsy, but when you do this your local build has weird menus or
• You want to use a specific commit of Docsy but when you do this your local build has weird menus or
• You want to use one of the above and your Netlify build has weird menus or
• You want to use one of the above but your Netlify or local build is using a different version of Docsy (submodule at wrong commit)

Can I ask what OS you're on and what version of Hugo for your local build? Also can I check if like @pschrey2 above you have any local overrides of any of our theme layouts?

[LisaFC]

Ok, managed to reproduce "menus go weird with latest submodule" with Just Docs (which has not been updated in ages) but not with a more recently updated site.

Let me see what the difference is....

[LisaFC]

Right, so Just Docs is wrong because it has its own override version of baseof.html, like @pschrey2's project upthread, which won't work with the latest theme without some edits - https://github.com/LisaFC/justdocs/blob/master/layouts/_default/baseof.html

Can you check if you have any overridden layout files that need to be updated?

[mjang-cobalt]

Thanks @LisaFC . To answer your 4 option question, my "wants" are:

• You want to upgrade to the most recent version of Docsy, but when you do this your local build has weird menus
• You want to use one of the above but your Netlify or local build is using a different version of Docsy (submodule at wrong commit)

I understand that the solutions for both "wants" may be the same. As for the other data you requested:

• MacOS 11.4 (Big Sur) (though I'd love an argument to use Linux)
• Hugo 0.83.1 (though I've since upgraded to 0.85)
• I've done a lot of copy/paste, as I'm learning Hugo as I go. So maybe I've copied some of the "override version" files.

[LisaFC]

Great, thanks! Can you check if your own project (in the project root, not the "themes" directory) has a "layouts" directory, and is there anything in it?

[mjang-cobalt]

I do have a <project root>/layouts directory, and have started to "build it out" as I want some custom layouts (such as shortcodes and partials).

Next step: check on the impact of a different (latest?) baseof.html.

[mjang-cobalt]

Bummer. I tried with:

• this later docsy commit: 07ac748 (which appears after I run git submodule update --remote
• overrode all my layouts/_default files with the corresponding files in themes/docsy/layouts/_default

No change that I could see (though I didn't test the corresponding Netlify build)

[LisaFC]

Can you try the Netlify build just to check, as that might show if there's some local/OS-specific issue? I haven't been able to reproduce the behaviour with any sites that don't have an overridden baseof somewhere. Also do check if you have any other baseof files overridden eg layouts/docs/baseof.html, layouts/blog/baseof.html.

(you also shouldn't need to override/change your project layouts/_default or other layout files to get the Docsy versions, just delete them and Hugo will pick up the theme version instead)

[mjang-cobalt]

Hi @LisaFC , sorry for the delay. Was on holiday.

You're right -- the key file is baseof.html. I'm still having problems when I use the latest default baseof.html

What's working for me: here's the content of my layouts/_default/baseof.html file:

<!doctype html>
<html lang="{{ .Site.Language.Lang }}" class="no-js">
  <head>
    {{ partial "head.html" . }}
    <title>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }}</title>
  </head>
  <body class="td-{{ .Kind }}">
    <header>
      {{ partial "navbar.html" . }}
    </header>
    <div class="container-fluid td-outer">
      <div class="td-main">
        <div class="row flex-xl-nowrap">
          <div class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
            {{ partial "sidebar.html" . }}
          </div>
          <div class="d-none d-xl-block col-xl-2 td-toc d-print-none">
            {{ partial "toc.html" . }}
          </div>
          <main class="col-12 col-md-9 col-xl-8 pl-md-5" role="main">
            {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }}
            {{ block "main" . }}{{ end }}
          </main>
        </div>
      </div>
      {{ partial "footer.html" . }}
    </div>
    {{ partial "scripts.html" . }}
  </body>
</html>

[mjang-cobalt]

Here's an example of what I see with the default baseof.html:

[narrenfrei]

Without a possibility to have a look into your repository it's really difficult to give you a advise. Maybe you could make a minimal version (only with useless test content) of your website?

[pschrey2]

try this one as your layouts/_default/baseof.html

<!doctype html>
<html lang="{{ .Site.Language.Lang }}" class="no-js">
  <head>
    {{ partial "head.html" . }}
    <title>{{ if .IsHome }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{ . }} | {{ end }}{{ .Site.Title }}{{ end }}</title>
  </head>
  <body class="td-{{ .Kind }}">
    <header>
      {{ partial "navbar.html" . }}
    </header>
    <div class="container-fluid td-outer">
      <div class="td-main">
        <div class="row flex-xl-nowrap">
          <aside class="col-12 col-md-3 col-xl-2 td-sidebar d-print-none">
            {{ partial "sidebar.html" . }}
          </aside>
          <aside class="d-none d-xl-block col-xl-2 td-sidebar-toc d-print-none">
            {{ partial "toc.html" . }}
          </aside>
          <main class="col-12 col-md-9 col-xl-8 pl-md-5" role="main">
            {{ if not .Site.Params.ui.breadcrumb_disable }}{{ partial "breadcrumb.html" . }}{{ end }}
            {{ block "main" . }}{{ end }}
          </main>
        </div>
      </div>
      {{ partial "footer.html" . }}
    </div>
    {{ partial "scripts.html" . }}
  </body>
</html>

• You need to use <aside> tags instead of <div> tags around the partials sidebar.html and toc.html.
• You need the td-sidebar-toc class instead of the td-toc class for partial toc.html.

[LisaFC]

Hrmm, something funny going on here - the _default/baseof file should be just used for things like landing pages , so it isn't used for any of the page types that have sidebar menus (that's docs/baseof and blog/baseof instead)

Can you see what your docs/baseof and/or blog/baseof look like?

[mjang-cobalt]

I just got permission to publicly release the repo that I'm using https://github.com/cobalthq/cobalt-product-public-docs. Now I can ask my questions on a more substantive basis (aka, you can now see the mistakes I've made ;) ).. Thanks for the suggestions that I haven't checked yet, and I'll let you know when I do (though I'm a little busy atm)

[mjang-cobalt]

Possibly related: https://github.com/LisaFC/justdocs/issues/8

[aidan-wood-43]

I managed to fix my issue at LisaFC/justdocs#8 by using the layouts/_default/baseof.html suggested by @pschrey2.

[LisaFC]

Sorry for the late reply, I was on vacation - that's great that I can see the repo, hopefully I can find a fix!

[LisaFC]

Also just FYI re the Just Docs site (which, apologies, I broke to validate this issue), here's what I commented on the other issue:

I am actually considering removing this example site from the Docsy examples page because it's not actually the best way to do a "just docs" site anymore since Hugo made some improvements with cascading front matter.

Here's how you should do it instead: https://www.docsy.dev/docs/adding-content/content/#alternative-site-structure

[mjang-cobalt]

Also just FYI re the Just Docs site (which, apologies, I broke to validate this issue), here's what I commented on the other issue:

I am actually considering removing this example site from the Docsy examples page because it's not actually the best way to do a "just docs" site anymore since Hugo made some improvements with cascading front matter. Here's how you should do it instead: https://www.docsy.dev/docs/adding-content/content/#alternative-site-structure

Thanks for letting me know, @LisaFC . I appreciate the work you've done!

If I'm reading your links correctly, it's probably easiest if I move to https://github.com/gwatts/mostlydocs/.

[LisaFC]

Yes, Gareth's mostlydocs site is a good example of that approach! It's got a lot less heavy customization than the original JustDocs so it means you're less likely to find yourself with project-specific files/features that go out of sync with or are broken by Docsy updates.

[fahaddilib]

Hi, I also have the same issue mentioned here when upgrading. It seems browser dependent for me. I also tried on the docsy example site and get the same result. On Chrome, the TOC is in the wrong place (and the navbar colour is also incorrect)

But, on Safari it renders on the as expected on the right

Applied the fix suggested by @pschrey2, changing the classname from td-sidebar-toc to td-toc. This seemed to fix the problem on Chrome, but then on Safari it is on the left. 😏

Any ideas what the problem could be on Chrome?

[fahaddilib]

When on incognito mode in Chrome it works perfectly! So must be some stale css being cached, and not refreshing correctly. 🤔

---

Solved: By clearing cached files on Chrome More tools >> Clear Browsing Data >> Cached images and files