Automatic Multi-Format Config Tabs Documentation

[james-d-elliott]

So I've kind of got an idea which is partially working. It needs some refining however. Basically I'd like to write a configuration example once and show it in multiple formats.

For example say you primarily support YAML but also want to show JSON since JSON should also functionally work with a YAML parser, or you want to also show TOML because you support that format as well.

So I had the idea to use the tabs example to create a separate but functionally equivalent shortcode which automatically converts to your chosen formats.

I've included where I'm at currently. But it has these issues for the time being:

1. Most of the standard highlight options are unavailable, probably easily fixed.
2. Some weird spacing at the top and bottom, possibly easily fixed.
3. No copy button.

See the below example shortcode and javascript (note that uses a separate localStorage name and data values):

<!--
  Based on: https://github.com/alex-shpak/hugo-book/blob/master/layouts/shortcodes/tabs.html
-->

{{ if .Inner }}{{ end }}
{{ $id := .Get 0 }}
{{ $group := printf "configs-%s" $id }}
{{ $formats := (strings.Split "yaml,toml,json" ",") }}
{{ $input := "yaml" }}

<nav>
  <div class="nav nav-tabs" id="nav-tab" role="tablist">
  {{ range $index, $lang := $formats -}}
    <button data-toggle-tab-configs="{{ $lang | lower }}" class="nav-link{{ if not $index }} active{{ end }}" id="{{ printf "%s-%d" $group $index }}-tab" data-bs-toggle="tab" data-bs-target="#{{ printf "%s-%d" $group $index }}" type="button" role="tab" aria-controls="{{ printf "%s-%d" $group $index }}" aria-selected="true">
      {{ $lang | upper -}}
    </button>
  {{ end -}}
  </div>
</nav>

<div class="tab-content" id="nav-tabContent">
  {{ range $index, $lang := $formats -}}
    <div data-pane-configs="{{ $lang | lower }}" class="tab-pane fade{{ if not $index }} show active{{ end }}" id="{{ printf "%s-%d" $group $index }}" role="tabpanel" aria-labelledby="{{ printf "%s-%d" $group $index }}-tab" tabindex="0">
{{- if (eq $lang $input) }}
{{- transform.Highlight $.Inner $lang -}}
{{- else }}
{{ transform.Highlight (transform.Remarshal $lang ($.Inner | transform.Unmarshal)) $lang -}}
{{- end }}
    </div>
  {{ end -}}
</div>

// Based on: https://github.com/gohugoio/hugoDocs/blob/master/_vendor/github.com/gohugoio/gohugoioTheme/assets/js/tabs.js

/**
 * Scripts which manages Code Toggle tabs.
 */
var i;
// store tabs variable
var allTabs = document.querySelectorAll('[data-toggle-tab-configs]');
var allPanes = document.querySelectorAll('[data-pane-configs]');

function toggleConfigsTabs(event) {

  if(event.target){
    event.preventDefault();
    var clickedTab = event.currentTarget;
    var targetKey = clickedTab.getAttribute('data-toggle-tab-configs')
  }else {
    var targetKey = event
  }
  // We store the config language selected in users' localStorage
  if(window.localStorage){
    window.localStorage.setItem('configsLangPref', targetKey)
  }
  var selectedTabs = document.querySelectorAll('[data-toggle-tab-configs=' + targetKey + ']');
  var selectedPanes = document.querySelectorAll('[data-pane-configs=' + targetKey + ']');

  for (var i = 0; i < allTabs.length; i++) {
    allTabs[i].classList.remove('active');
    allPanes[i].classList.remove('active');
  }

  for (var i = 0; i < selectedTabs.length; i++) {
    selectedTabs[i].classList.add('active');
    selectedPanes[i].classList.add('show', 'active');
  }

}

for (i = 0; i < allTabs.length; i++) {
  allTabs[i].addEventListener('click', toggleConfigsTabs)
}
// Upon page load, if user has a preferred language in its localStorage, tabs are set to it.
if(window.localStorage.getItem('configsLangPref')) {
  toggleConfigsTabs(window.localStorage.getItem('configsLangPref'))
}

[h-enk]

Interesting idea indeed!

With this code (I created a tabs-2.html):

<!--
  Based on: https://github.com/alex-shpak/hugo-book/blob/master/layouts/shortcodes/tabs.html
-->

{{ if .Inner }}{{ end }}
{{ $id := .Get 0 }}
{{ $group := printf "tabs-%s" $id }}

{{ $formats := (strings.Split "yaml,toml,json" ",") }}
{{ $input := "yaml" }}

<nav>
  <div class="nav nav-tabs" id="nav-tab" role="tablist">
  {{ range $index, $lang := $formats -}}
    <button data-toggle-tab="{{ $lang | lower }}" class="nav-link{{ if not $index }} active{{ end }}" id="{{ printf "%s-%d" $group $index }}-tab" data-bs-toggle="tab" data-bs-target="#{{ printf "%s-%d" $group $index }}" type="button" role="tab" aria-controls="{{ printf "%s-%d" $group $index }}" aria-selected="true">
      {{ $lang | upper -}}
    </button>
  {{ end -}}
  </div>
</nav>

<div class="tab-content" id="nav-tabContent">
  {{ range $index, $lang := $formats -}}
    <div data-pane="{{ $lang | lower }}" class="tab-pane fade{{ if not $index }} show active{{ end }}" id="{{ printf "%s-%d" $group $index }}" role="tabpanel" aria-labelledby="{{ printf "%s-%d" $group $index }}-tab" tabindex="0">

      <div class="expressive-code">
        <figure class="frame not-content">
        <figcaption class="header">
          <span class="title"></span>
        </figcaption>
          {{ transform.Highlight (transform.Remarshal $lang ($.Inner | transform.Unmarshal)) $lang -}}
        </figure>      
      </div>

    </div>
  {{ end -}}
</div>

and this in Markdown:

{{< tabs-2 "add-front-matter" >}}
date: 2024-02-02T04:14:54-08:00
draft: false
params:
  author: John Smith
title: Example
weight: 10
{{< /tabs-2 >}}

I get this (solving your issues):

Next (?)

• Is the Javascript still needed (this way)?

• Add option to render the code as front matter

  

[james-d-elliott]

I have some supporting javascript based on the original js for tabs which assists with easily configuring additional groups without too much boiler plate, the tab groups have individual local storage and selectors. In the example we configure a tab group env which I am using for Bare-Metal / Docker environments which has the initializing code customTabsConfigure('env');, it expects the selector [data-toggle-env-tab] matches the tabs, and [data-env-pane] matches the panes.

Example:

const customTabsToggle = (name, event, allTabs, allPanes) => {
  let targetKey;

  if (event.target) {
    event.preventDefault();
    targetKey = event.currentTarget.getAttribute(`data-toggle-${name}-tab`)
  } else {
    targetKey = event
  }

  if (window.localStorage) {
    window.localStorage.setItem(`${name}TabPref`, targetKey)
  }

  let i;

  for (i = 0; i < allTabs.length; i++) {
    allTabs[i].classList.remove('active');
    allPanes[i].classList.remove('active');
  }

  const selectedTabs = document.querySelectorAll(`[data-toggle-${name}-tab=${targetKey}]`);
  const selectedPanes = document.querySelectorAll(`[data-${name}-pane=${targetKey}]`);

  for (i = 0; i < selectedTabs.length; i++) {
    selectedTabs[i].classList.add('active');
    selectedPanes[i].classList.add('show', 'active');
  }
}

const customTabsToggleListener = (name, allTabs, allPanes) => {
  return (ev) => {
    customTabsToggle(name, ev, allTabs, allPanes);
  }
};

const customTabsStorageListener = (name) => {
  return (ev) => {
    if (ev.key !== `${name}TabPref`) {
      return;
    }

    if (ev.newValue && ev.newValue !== '') {
      customTabsToggle(name, ev.newValue);
    }
  }
};

const customTabsConfigure = (name) => {
  // Find all of the related tabs on the page.
  const allTabs = document.querySelectorAll(`[data-toggle-${name}-tab]`);
  const allPanes = document.querySelectorAll(`[data-${name}-pane]`);

  // If no tabs or panes exist skip everything.
  if (allTabs.length === 0 && allPanes.length === 0) {
    return;
  }

  // If the browser supports localStorage, setup localStorage elements.
  if (window.localStorage) {

    // If the preference value exists, make sure those tabs are selected.
    const value = window.localStorage.getItem(`${name}TabPref`);
    if (value) {
      customTabsToggle(name, value, allTabs, allPanes)
    }

    // Make sure we listen for storage events for changes to the specific storage key.
    window.addEventListener('storage', customTabsStorageListener(name));
  }

  // Create the listener used for click events.
  const clickListener = customTabsToggleListener(name, allTabs, allPanes);

  // Make sure each tab has the click event listener.
  for (let i = 0; i < allTabs.length; i++) {
    allTabs[i].addEventListener('click', clickListener)
  }
};

// Register the 'env' tab group listeners etc. on page load.
customTabsConfigure('env');

Less Optimized

const customTabsToggle = (name, event) => {
  let targetKey;

  if (event.target) {
    event.preventDefault();
    targetKey = event.currentTarget.getAttribute(`data-toggle-${name}-tab`)
  } else {
    targetKey = event
  }

  if (window.localStorage) {
    window.localStorage.setItem(`${name}TabPref`, targetKey)
  }

  const allTabs = document.querySelectorAll(`[data-toggle-${name}-tab]`);
  const allPanes = document.querySelectorAll(`[data-${name}-pane]`);

  let i;

  for (i = 0; i < allTabs.length; i++) {
    allTabs[i].classList.remove('active');
    allPanes[i].classList.remove('active');
  }

  const selectedTabs = document.querySelectorAll(`[data-toggle-${name}-tab=${targetKey}]`);
  const selectedPanes = document.querySelectorAll(`[data-${name}-pane=${targetKey}]`);

  for (i = 0; i < selectedTabs.length; i++) {
    selectedTabs[i].classList.add('active');
    selectedPanes[i].classList.add('show', 'active');
  }
}

const customTabsToggleListener = (name) => {
  return (ev) => {
    customTabsToggle(name, ev);
  }
};

const customTabsStorageListener = (name) => {
  return (ev) => {
    if (ev.key !== `${name}TabPref`) {
      return;
    }

    if (ev.newValue && ev.newValue !== '') {
      customTabsToggle(name, ev.newValue);
    }
  }
};

const customTabsConfigure = (name) => {
  const allTabs = document.querySelectorAll(`[data-toggle-${name}-tab]`);
  const listener = customTabsToggleListener(name);

  for (let i = 0; i < allTabs.length; i++) {
    allTabs[i].addEventListener('click', listener)
  }

  // Upon page load, if user has a preferred language in its localStorage, tabs are set to it.
  const value = window.localStorage.getItem(`${name}TabPref`);
  if (value) {
    customTabsToggle(name, value)
  }

  window.addEventListener('storage', customTabsStorageListener(name));
};

customTabsConfigure('env');