modular content blocks in jekyll documentation

Why Modular Content Matters in Documentation

In a growing documentation project, duplication becomes a serious maintenance burden. Repeating the same installation instructions, warnings, or version notes across multiple pages can lead to inconsistencies. Any small update needs to be replicated everywhere manually.

Jekyll supports a modular approach through includes, allowing you to build content blocks that can be reused across many pages and sections with optional parameters to make them flexible. This brings enormous value when your documentation supports multiple languages, versions, or product variants.

Using the Include Tag in Jekyll

Jekyll provides the {% raw %}{% include %}{% endraw %} tag to insert the contents of another file into the current page. It’s commonly used for navigation bars or layout components, but it works just as well for small content fragments.

Basic Include Example

{% raw %}
{% include install-note.html %}
{% endraw %}

This will inject the contents of _includes/install-note.html into your page.

Creating Parameterized Includes

To make your includes more powerful, pass parameters and use them within the include file:

Example: Reusable Alert Block

File: _includes/alert.html

{% raw %}

  {{ include.title }}
  
{{ include.message }}

{% endraw %}

Usage:

{% raw %}
{% include alert.html
  type="warning"
  title="Deprecated"
  message="This feature is no longer supported in version 2.0." %}
{% endraw %}

This avoids repeating the same markup multiple times and allows for consistent styling across your site.

Using Includes with Data Files

Combining includes with YAML data files enables powerful, dynamic documentation blocks. For example, you can define shared steps or content variants in _data/ and loop over them using includes.

Step-by-Step Installation Blocks

File: _data/install_steps.yml

- step: Download the CLI tool
  command: curl -O https://example.com/cli
- step: Make it executable
  command: chmod +x cli
- step: Run the installer
  command: ./cli install

Include: _includes/steps.html

{% raw %}

  {% for item in include.steps %}
    

      
{{ item.step }}
      
{{ item.command }}
    
  {% endfor %}

{% endraw %}

Usage in a Page:

{% raw %}
{% assign steps = site.data.install_steps %}
{% include steps.html steps=steps %}
{% endraw %}

Modular Navigation Blocks

In multilingual or multi-version documentation, your navigation can be included and customized using variables. For example:

File: _includes/sidebar.html

{% raw %}

  {% for section in include.sections %}
    
{{ section.label }}
  {% endfor %}

{% endraw %}

Page Usage:

{% raw %}
{% assign nav = site.data.navigation.en.v2 %}
{% include sidebar.html sections=nav %}
{% endraw %}

This helps you support multiple language/versions with clean layout separation.

Creating Code Snippet Includes

If your documentation has repeated code blocks (like installing via pip or npm), create a small include for each and standardize the presentation.

Example: pip-install.html

{% raw %}
pip install {{ include.package }}
{% endraw %}

Usage:

{% raw %}
{% include pip-install.html package="jekyll-multilang-docs" %}
{% endraw %}

Case Study: Scaling Tutorials for Multiple SDKs

A SaaS company maintained three SDKs: Python, JavaScript, and Go. The onboarding process was almost identical but with slight syntax changes. Previously, all three guides were maintained separately.

Problem

• Triple the maintenance for every change
• Copy-paste errors in tutorials
• Inconsistent terminology

Solution

• Moved steps to data files like _data/python_steps.yml
• Created one parameterized include to render all steps
• Used language toggles to render the correct steps

Now, adding a new step only required editing the YAML file. The include handled the rest. Maintenance dropped by over 60%.

Best Practices for Include Usage

• Name your includes clearly (e.g., alert.html, install-guide.html)
• Keep include files small and focused on a single purpose
• Validate parameters before using (use {% raw %}{% if include.param %}{% endif %}{% endraw %})
• Document what each include does and what parameters it expects

Debugging Includes

If an include fails, Jekyll will silently skip rendering. Always test locally with:

bundle exec jekyll serve

Check that:

• File exists in _includes/
• Parameters are passed correctly
• No syntax errors inside the include

Conclusion

Using includes and parameters in Jekyll is one of the best strategies to keep your documentation clean, scalable, and maintainable. It saves time, reduces duplication, and ensures a consistent experience across multiple pages, languages, and product variants. For large-scale documentation efforts, modularity is not just a preference—it’s a necessity.

In the next article, we’ll dive into how to create interactive tabbed content (for example, language or platform selectors) using a mix of includes and simple JavaScript to further improve usability and clarity in your docs.