DOC-581 | Fix Markdown rendering in combination with render hooks (#245)

* Use .Page.RenderString in tip admonition shortcode

Hugo has a known issue with the markdownify filter in combination with render hooks (here the one for links), not forwarding the page context correctly

* Use .Page.RenderString also for tab content so that relative doc links work

* Render example description frontmatter as it may contain Markdown

The markdownify filter would be sufficient as we won't be putting relative links in the descriptions but RenderString allows us to preserve the wrapping <p> tag if it's only a single paragraph.

Correctly forward context to partials to access .Page

* Use .Page.RenderString for expand shortcodes too

Don't markdownify example outputs but do so for expand titles. Make expand label non-selectable.

* TO BE REVERTED: Test content

* Revert "TO BE REVERTED: Test content"

This reverts commit 5a0aa9e.

Author: Simran-B

site/themes/arangodb-docs-theme/layouts/partials/shortcodes/examples/example.html

@@ -29,7 +29,7 @@
             {{ if $context.Page.Store.Get $name }}
                 {{ $response := .response | base64Decode | transform.Unmarshal }}
                 {{- partial "shortcodes/examples/render.html" (dict
-                "context" .
+                "context" $context
                 "content" $response
                 "options" $options
                 "language" $language
@@ -73,7 +73,7 @@
     {{ with $cacheFound }}
         {{ $response := .response | base64Decode | transform.Unmarshal }}
         {{- partial "shortcodes/examples/render.html" (dict
-        "context" .
+        "context" $context
         "content" $response
         "options" $options
         "language" $language

site/themes/arangodb-docs-theme/layouts/partials/shortcodes/examples/generate.html

@@ -21,7 +21,7 @@
 {{ if $remote }}
     {{ $response := unmarshal $remote.Content }}
     {{- partial "shortcodes/examples/render.html" (dict
-    "context" .
+    "context" $context
     "content" $response
     "options" $options
     "language" $language

site/themes/arangodb-docs-theme/layouts/partials/shortcodes/examples/render.html

@@ -1,28 +1,31 @@
-{{ $options := .options }}
-{{ $content := .content }}
-{{ $language := .language }}
+{{- $context := .context }}
+{{- $options := .options }}
+{{- $content := .content }}
+{{- $language := .language }}
 
-{{ if eq .language "curl" }}
-    {{ $language = "bash" }}
-{{ end }}
+{{- if eq .language "curl" }}
+  {{- $language = "bash" }}
+{{- end }}
 
-<p>{{ $options.description }}</p>
+{{- /* Ensure that a single paragraph is also wrapped in <p></p> */}}
+{{- $options.description | $context.Page.RenderString (dict "display" "block") }}
 
-{{ $input := transform.Highlight $content.input $language }}
+{{- $input := transform.Highlight $content.input $language }}
 {{ $input }}
 
-{{ if $options.bindVars }}
-<strong>Bind Parameters</strong><br>
-
-{{ $bindVars := $options.bindVars | jsonify (dict "indent" "  ") }}
+{{- if $options.bindVars }}
+<strong>Bind Parameters</strong>
+<br>
+{{- $bindVars := $options.bindVars | jsonify (dict "indent" "  ") }}
 {{ transform.Highlight $bindVars "json" }}
-{{ end }}
+{{- end }}
 
-{{ $output := transform.Highlight $content.output $language }}
-{{ $block := printf "%s" $output | markdownify}}
-    {{- partial "shortcodes/expand.html" (dict
-    "content" $block
-    "open"    "open"
-    "title"   "Show output"
+{{- $output := transform.Highlight $content.output $language }}
+{{- $block := printf "%s" $output }}
+{{- partial "shortcodes/expand.html" (dict
+  "context" $context
+  "content" $block
+  "open"    "open"
+  "title"   "Show output"
 ) }}
-<br>
+<br>

site/themes/arangodb-docs-theme/layouts/partials/shortcodes/expand.html

@@ -1,16 +1,15 @@
-{{- $content := .content | markdownify }}
+{{- $context := .context }}
+{{- $content := .content | $context.Page.RenderString }}
 {{- $title := .title | default (T "Expand-title") }}
-{{- $description := .description }}
 {{- $expanded := .open | default false }}
 {{- if eq (printf "%T" $expanded) "string" }}
   {{- $expanded = (eq $expanded "true") }}
 {{- end }}
 {{- with $content }}
 <div class="expand{{- if $expanded }} expand-expanded{{ end }}">
 {{/* things are getting complicated when search tries to open the expand box while jquery sets the display CSS on the element */ -}}
-<a class="expand-label" onclick="toggleExpandShortcode(event)">{{ $title }}</a>
+<a class="expand-label" onclick="toggleExpandShortcode(event)">{{ $title | markdownify }}</a>
 <div class="expand-content" style="display: {{ if $expanded }}block{{ else }}none{{ end }};">
-{{ $description | markdownify }}
 {{ $content | safeHTML }}
 </div>
 </div>

site/themes/arangodb-docs-theme/layouts/partials/shortcodes/tabs.html

@@ -13,7 +13,7 @@
     </div>
     {{- range $idx, $tab := $tabs }}
       <div data-tab-item="{{ .name }}" data-tab-group="{{ $groupid }}" class="tab-item {{ cond (eq $idx 0) "selected" ""}}">
-        {{- .content | markdownify -}}
+        {{- .content | $context.Page.RenderString -}}
       </div>
     {{- end }}
   </div>

site/themes/arangodb-docs-theme/layouts/shortcodes/expand.html

@@ -1,7 +1,7 @@
-{{- $_hugo_config := `{ "version": 1 }` }}
+{{- $_hugo_config := `{ "version": 1 }` }}{{/* TODO: What does this do? */}}
 {{- partial "shortcodes/expand.html" (dict
+  "context" .
   "content" .Inner
   "open"    (.Get "open" | default (.Get 1))
   "title"   (.Get "title" | default (.Get 0))
-  "description" (.Get "description" | default (""))
 ) }}

site/themes/arangodb-docs-theme/layouts/shortcodes/program-options.md

@@ -1,3 +1,4 @@
+{{- $context := . }}
 {{- $program := .Get "name" }}
 {{- $pageVersion := .Page.Store.Get "versionShort" }}
 {{- $dataFolderByVersion := index site.Data $pageVersion }}
@@ -26,17 +27,18 @@
 
   {{- $section := index $optionsMap "General" }}
   {{- if gt ($section | len) 0 }}
-    {{- template "render-section" (dict "name" "General" "section" $section) }}
+    {{- template "render-section" (dict "name" "General" "section" $section "context" $context) }}
   {{- end }}
 
   {{- range $name, $section := $optionsMap }}
     {{- if ne $name "General" }}
-      {{- template "render-section" (dict "name" $name "section" $section) }}
+      {{- template "render-section" (dict "name" $name "section" $section "context" $context) }}
     {{- end }}
   {{- end }}
 {{- end }}
 
 {{- define "render-section" }}
+{{- $context := .context }}
 ## {{ .name }}
 
 {{ range $option := .section }}
@@ -96,6 +98,7 @@ Effective on {{ delimit . ", " " and " }} only.
 
 {{ with $option.longDescription }}
   {{- partial "shortcodes/expand.html" (dict
+    "context" $context
     "content" .
     "open"    "open"
     "title"   "Show details"

site/themes/arangodb-docs-theme/layouts/shortcodes/tip.html

@@ -3,7 +3,7 @@
         <div class="box-content">
             <i class="fas fa-check"></i>
             <div class="box-text">
-                {{ .InnerDeindent | markdownify }}
+                {{ .InnerDeindent | .Page.RenderString }}
             </div>
         </div>
     </div>

site/themes/arangodb-docs-theme/static/css/theme.css

@@ -1657,7 +1657,11 @@ blockquote p {
 
 .expand-label {
     font-size: 1.1rem;
-
+    cursor: pointer;
+    -webkit-user-select: none;
+    -moz-user-select: none;
+    -ms-user-select: none;
+    user-select: none;
 }
 
 .expand-label::before {

site/themes/arangodb-docs-theme/static/js/theme.js

@@ -449,14 +449,14 @@ function copyURI(evt) {
 }
 
 function toggleExpandShortcode(event) {
-    var t = $(event.target)
-    if(t.parent('.expand-expanded.expand-marked').length){
-        t.next().css('display','none') 
-    }else if(t.parent('.expand-marked').length){
-        t.next().css('display','block') }
-    else{ 
-        t.next('.expand-content').slideToggle(100); 
-    } 
+    var t = $(event.target.closest("a"));
+    if (t.parent('.expand-expanded.expand-marked').length) {
+        t.next().css('display','none');
+    } else if (t.parent('.expand-marked').length) {
+        t.next().css('display','block')
+    } else {
+        t.next('.expand-content').slideToggle(100);
+    }
     t.parent().toggleClass('expand-expanded');
 }