tabbed content for multi platform docs

Organizing Content with Tabs in Documentation

As your documentation grows to support multiple SDKs, platforms, or programming languages, presenting all variants on one page can overwhelm users. Instead, use interactive tabs to show one version at a time, keeping your pages clean while offering full flexibility.

This is especially helpful when showing code examples or installation steps across several environments like Python, Node.js, and Go. Let's explore how to build tabbed content using Jekyll includes, data files, and minimal JavaScript.

Common Use Cases for Tabbed Content

• SDK installation instructions for different platforms
• Authentication examples in multiple languages
• Environment-specific configuration (development, staging, production)
• OS-specific paths and commands (Linux, Windows, macOS)

Basic Structure of a Tab Component

A tabbed content block generally includes three main parts:

1. Tab selector buttons
2. Hidden/showing content blocks
3. JavaScript to toggle visibility

Step 1: Define the Tabbed Include File

Create a file in _includes/tabbed.html with parameters for tab labels and content.

{% raw %}

  

    {% for tab in include.tabs %}
      
    {% endfor %}
  
  

    {% for tab in include.tabs %}
      

        {{ tab.content }}
      
    {% endfor %}
  

{% endraw %}

Step 2: Add JavaScript to Toggle Tabs

Place this script in your layout or page to control tab switching behavior.

<script>
document.addEventListener('DOMContentLoaded', function () {
  document.querySelectorAll('.tab-group').forEach(group => {
    const buttons = group.querySelectorAll('.tab-button');
    const contents = group.querySelectorAll('.tab-content');

    buttons.forEach(button => {
      button.addEventListener('click', () => {
        const target = button.getAttribute('data-tab');

        buttons.forEach(b => b.classList.remove('active'));
        button.classList.add('active');

        contents.forEach(content => {
          content.classList.remove('active');
          if (content.getAttribute('data-tab') === target) {
            content.classList.add('active');
          }
        });
      });
    });
  });
});
</script>

Include basic CSS to control visibility and styling.

Step 3: Prepare Your Tab Content

You can define tab blocks directly in your page or dynamically via includes.

Example: Installation for Three Languages

{% raw %}
{% assign sdk_tabs = "" | split: "" %}
{% assign sdk_tabs = sdk_tabs | push: { "name": "python", "label": "Python", "content": "<pre><code>pip install example-sdk</code></pre>" } %}
{% assign sdk_tabs = sdk_tabs | push: { "name": "node", "label": "Node.js", "content": "<pre><code>npm install example-sdk</code></pre>" } %}
{% assign sdk_tabs = sdk_tabs | push: { "name": "go", "label": "Go", "content": "<pre><code>go get example.com/sdk</code></pre>" } %}
{% include tabbed.html id="sdk-install" tabs=sdk_tabs %}
{% endraw %}

Step 4: Support Tabs via Data Files

For maintainability, define tab content in YAML files and loop through them.

File: _data/sdk_install.yml

- name: python
  label: Python
  content: "<pre><code>pip install mypackage</code></pre>"
- name: node
  label: Node.js
  content: "<pre><code>npm install mypackage</code></pre>"
- name: ruby
  label: Ruby
  content: "<pre><code>gem install mypackage</code></pre>"

Page Usage:

{% raw %}
{% assign sdk_tabs = site.data.sdk_install %}
{% include tabbed.html id="language-tabs" tabs=sdk_tabs %}
{% endraw %}

Case Study: DevOps Docs with OS Tabs

A DevOps team built an internal documentation site that had deployment scripts for macOS, Linux, and Windows. Initially, each page had a long scroll with three sets of scripts. Feedback from users was clear: it was hard to follow and cluttered.

Solution

• Switched to tabbed content for OS-specific commands
• Used include to standardize the tab structure
• Stored tab content in YAML for easy updates

Impact

• Pages became 60% shorter and easier to read
• Team updates only one place per OS script
• New hires onboarded 2x faster using the new layout

Design Tips for Better Tabs

• Use icons or flags next to tab labels for clarity
• Highlight the default tab with visual emphasis
• Avoid placing large images or full-page tables inside tabs
• Ensure accessibility (keyboard navigation, screen readers)

Conclusion

Tabbed content helps transform long and repetitive documentation into clean, focused sections. With Jekyll’s flexible templating and data structure, you can implement tabs that are dynamic, reusable, and easy to maintain. Whether you're managing multi-language SDKs or cross-platform instructions, interactive tabs improve clarity without sacrificing depth.

Next in the series, we’ll explore how to integrate client-side search across your documentation sections using Lunr.js, including dynamic indexing from Jekyll’s content and data.