redhataccess / ascii_binder

AsciiBinder is an AsciiDoc-based system for authoring and publishing closely related documentation sets from a single source.
https://asciibinder.net
MIT License
76 stars 39 forks source link

Broken breadcrumb in OpenShift docs #169

Open gabriel-rh opened 2 years ago

gabriel-rh commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 1 year ago

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'
...