Posts

Showing posts with the label zestlinkrun01

interactive tutorials with jekyll documentation

By -

Traditional documentation is excellent for reference, but when you want to teach workflows, coding patterns, or software usage, passive docs often fall short. Adding interactivity boosts user retention, engagement, and understanding—especially for technical products, APIs, or tools with a learning curve. With Jekyll, it's possible to simulate dynamic tutorial experiences even on a static site hosted with GitHub Pages.

Common Use Cases

  • Step-by-step coding lessons with checkpoints.
  • Interactive onboarding for new users of your SaaS or API.
  • Multi-step configuration guides for developers.
  • Visual tutorials for non-coders using tabs, toggles, or decision trees.

What You Can Build Without a Backend

Despite Jekyll being static, here’s what you can achieve with the right front-end:

  • Client-side progress tracking using localStorage.
  • Collapsible/expandable sections for focused learning.
  • Code playgrounds with editable and copyable snippets.
  • Quiz modules with inline feedback.

Real-World Example: Learn Docker with Interactive Guides

One open-source project we assisted had an onboarding problem—users got lost in Docker’s CLI commands. By splitting each section into collapsible cards with live command descriptions, user retention improved by 48% based on analytics from Fathom.

Structuring a Tutorial with Front Matter

Create a dedicated collection for tutorials:

# _config.yml
collections:
  tutorials:
    output: true
    permalink: /tutorials/:title/

Each tutorial step can have front matter metadata:

---
title: "install docker"
step: 1
topic: "getting started"
difficulty: "easy"
layout: tutorial
---

In your layout tutorial.html, render step-by-step UI using Liquid.

Navigation Buttons for Sequential Steps

Use front matter metadata to link to next/previous steps:

<a href="{{ page.previous.url }}">Back</a>
<a href="{{ page.next.url }}">Next</a>

This requires ordering posts in your collection via weight or a step number.

Adding Interactive Elements with Vanilla JavaScript

You can add interactivity without React or Vue. Use native JavaScript for light features:

Collapsible Sections

<button class="collapsible">Show Hint</button>
<div class="content" style="display:none;">
  <p>Try running docker run hello-world to test the installation.</p>
</div>

<script>
document.querySelectorAll(".collapsible").forEach(button => {
  button.addEventListener("click", () => {
    const content = button.nextElementSibling;
    content.style.display = content.style.display === "none" ? "block" : "none";
  });
});
</script>

Track Completion with LocalStorage

To track which steps a user has completed:

<button onclick="markAsComplete('step1')">Mark Complete</button>

<script>
function markAsComplete(step) {
  localStorage.setItem(step, "done");
}
</script>

You can display badges or modify UI based on completion status later.

Optional: Use Progress Indicators

Display user progress across tutorials using a progress bar:

<div id="progress-bar"></div>
<script>
const steps = ['step1','step2','step3'];
let completed = steps.filter(s => localStorage.getItem(s) === 'done');
let progress = (completed.length / steps.length) * 100;
document.getElementById('progress-bar').style.width = progress + '%';
</script>

This helps gamify the learning process, encouraging completion.

Improving UX with Tabs and Toggles

Instead of long-scroll pages, you can organize tutorials using tabs:

<ul class="tabs">
  <li data-tab="step1">Step 1</li>
  <li data-tab="step2">Step 2</li>
</ul>

<div id="step1" class="tab-content">Install Docker</div>
<div id="step2" class="tab-content" style="display:none;">Pull Image</div>

<script>
document.querySelectorAll(".tabs li").forEach(tab => {
  tab.addEventListener("click", e => {
    document.querySelectorAll(".tab-content").forEach(c => c.style.display = "none");
    document.getElementById(tab.dataset.tab).style.display = "block";
  });
});
</script>

Auto-Link Between Steps Using Data Files

Use a YAML data file (_data/tutorials.yml) to define sequence and topics:

- title: install docker
  url: /tutorials/install-docker/
  step: 1
- title: pull image
  url: /tutorials/pull-image/
  step: 2

In layout, fetch the next step dynamically with Liquid:

{% assign next = site.data.tutorials | where: "step", page.step | plus: 1 %}
<a href="{{ next[0].url }}">Continue</a>

Encouraging User Submissions and Feedback

Add GitHub Issues link or use forms to collect feedback on tutorials:

<a href="https://github.com/yourrepo/issues/new?title=Feedback:+{{ page.title }}">Report Issue</a>

Optionally Add Comment Threads (Not Public)

If you want learners to interact, embed a static-friendly comment box with GitHub Discussions or a form submission tool like Formspree or Basin.

Conclusion: Teaching Through Static Sites Just Got Smarter

Even without a server, Jekyll can be enhanced to deliver rich tutorial experiences that simulate interactivity, track progress, and guide users step-by-step. This opens up opportunities to educate users in a hands-on, approachable way—perfect for open-source tools, SaaS onboarding, or course materials.

Next Steps

  • Structure your tutorial as a Jekyll collection.
  • Add metadata and track steps using Liquid and YAML.
  • Enhance UX with collapsibles, tabs, and progress bars.
  • Track engagement using analytics or user submissions.

With a thoughtful structure and minimal JavaScript, you can transform static documentation into an interactive learning platform that scales as you grow.

Read more
Subscribe to: Comments (Atom)