Broken breadcrumb in OpenShift docs

[gabriel-rh]

Sample content: https://github.com/gabriel-ocp/ocp-breadcrumbs

Sample output: https://gabriel-ocp.github.io/ocp-breadcrumbs/openshift-enterprise/main/level1/level2/level3/level3-intro.html

Note how the level 2 breadcrumb disappears when you navigate to the 3rd level

Name: Level 1
Dir: level1
Distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-online,openshift-dpu
Topics:
- Name: level1 intro
  File: level1-intro.adoc
- Name: level 2
  Dir: level2
  Topics:
  - Name: level2 intro
    File: level2-intro.adoc
  - Name: level 3
    Dir: level3
    Topics:
    - Name: level3 intro
      File: level3-intro.adoc

===================

Originally reported in:

https://issues.redhat.com/browse/OADP-443

From https://docs.openshift.com/container-platform/4.9/backup_and_restore/application_backup_and_restore/installing/installing-oadp-aws.html

You can click on Backup and Restore (see screenshot) and be linked to a broken https://docs.openshift.com/container-platform/4.9/backup_and_restore/application_backup_and_restore/backup_and_restore/index.html

[gabriel-rh]

Changes required on the OpenShift side:

$ git diff _templates/page.html.erb
diff --git a/_templates/page.html.erb b/_templates/page.html.erb
index 7661b0f..651b15d 100644
--- a/_templates/page.html.erb
+++ b/_templates/page.html.erb
@@ -8,7 +8,7 @@
     subgroup_id = topics[0] + "::" + topics[1]
     subsubgroup_id = topics[0] + "::" + topics[1] + "::" + topics[2]
     # TO DO if breadcrumbs become an issue
-    breadcrumb_subsubgroup_block = ""
+    #breadcrumb_subsubgroup_block = ""
     breadcrumb_topic = topic_title
   end
 %>
@@ -23,6 +23,7 @@
            :subgroup_id => subgroup_id,
            :subsubgroup_id => subsubgroup_id,
            :subgroup_title => subgroup_title,
+           :subsubgroup_title => subsubgroup_title,
            :topic_id => topic_id,
            :topic_title => topic_title,
            :article_title => article_title,

$ git diff _templates/_page_openshift.html.erb
diff --git a/_templates/_page_openshift.html.erb b/_templates/_page_openshift.html.erb
index 947ebf6..8c351a0 100644
--- a/_templates/_page_openshift.html.erb
+++ b/_templates/_page_openshift.html.erb
@@ -122,6 +122,7 @@
         <%= breadcrumb_group %>
       </li>
       <%= breadcrumb_subgroup_block %>
+      <%= breadcrumb_subsubgroup_block %>
       <li class="hidden-xs active">
         <%= breadcrumb_topic %>
       </li>

[rohennes]

I have replicated the issue with my local asciibinder build. Using @gabriel-rh 's container image with his updated version of asciibinder, I verified the fixes worked as expected.

[gabriel-rh]

There is a bit of a chicken-and-egg problem releasing this fix. The new asciibinder (1.0.2) will work with the old templates, but the old asciibinder (1.0.1 or 1.0) will fail against the new templates (see error below).

That means that the new asciibinder needs to be released before the template changes are merged (otherwise the build for the templates PR will fail).

But then, after merging the new templates, if writers do not upgrade to the latest version of asciibinder, their local builds will fail.

Building OKD for branch 'OADP-443-broken-breadcrumb'
Error: Could not generate docs:
NameError: undefined local variable or method `subsubgroup_title' for #<AsciiBinder::TemplateRenderer:0x000000000286b6e8>
Did you mean?  subsubgroup_id
               subgroup_title at
    /home/gmcgoldr/github/openshift-docs-latest/_templates/page.html.erb:26:in `__tilt_1920'
...