Posts

Showing posts with the label boostloopcraft01

Reusable Documentation Template with Jekyll

By -

Most documentation sites share a similar structure: homepage, category filters, search, navigation, and content pages. Rather than rebuilding this from scratch for every new product or internal tool, you can create a reusable Jekyll template that you only need to configure — not re-code.

This approach allows you to:

  • Standardize UX across projects
  • Reduce maintenance effort
  • Enable non-devs to deploy new documentation by editing YAML

Core Architecture of a Reusable Jekyll Template

The modular documentation system will be composed of:

  • Collections for structured content (e.g. guides, FAQs, changelogs)
  • Data files for UI strings, categories, access levels
  • Layouts for each content type
  • Includes for reusable interface blocks
  • Configurable filters (category, type, tags)
  • Multilingual support via folder structure and data binding

Step 1: Create Modular Collections

In _config.yml, define your base structure:

collections:
  guides:
    output: true
    permalink: /:collection/:name/
  faqs:
    output: true
    permalink: /:collection/:name/
  changelogs:
    output: true
    permalink: /:collection/:name/

Then, store your content in:

_guides/
_faqs/
_changelogs/

Each item can use shared front matter:

---
title: "How to install"
lang: en
type: guide
tags: [setup, install]
categories: [getting-started]
visibility: public
---

Step 2: Modular Layouts with Includes

Break your layout into includes that can be reused:

_includes/
├── header.html
├── footer.html
├── filter-controls.html
├── content-grid.html
├── lang-switch.html

Your default layout file might look like this:

{% raw %}
<!DOCTYPE html>
<html lang="{{ page.lang | default: site.default_lang }}">
  <head>...</head>
  <body>
    {% include header.html %}
    {% include filter-controls.html %}
    {% include content-grid.html %}
    {% include footer.html %}
  </body>
</html>
{% endraw %}

Step 3: Use Data to Configure UI and Metadata

Allow each site to define its own branding, structure, and labels with YAML files:

_data/
├── site.yml
├── ui.yml
├── categories.yml

site.yml can define branding and routes:

title: "Docs Hub"
logo: "/assets/logo.svg"
collections:
  - guides
  - faqs
  - changelogs

ui.yml will hold text labels and multilingual content:

en:
  search_placeholder: "Search articles..."
  filter_label: "Filter by"
id:
  search_placeholder: "Cari artikel..."
  filter_label: "Saring berdasarkan"

Step 4: Build Content Grid with Filters

The dynamic content grid pulls items from all collections:

{% raw %}
{% assign lang = page.lang | default: site.default_lang %}
{% assign ui = site.data.ui[lang] %}
<h2>{{ ui.filter_label }}</h2>

<ul class="content-grid">
  {% for collection in site.collections %}
    {% assign items = site[collection.label] | where: "lang", lang %}
    {% for item in items %}
      <li class="doc-card" data-type="{{ item.type }}">
        <a href="{{ item.url }}">{{ item.title }}</a>
      </li>
    {% endfor %}
  {% endfor %}
</ul>
{% endraw %}

Step 5: Parameterize the Build

Let every new documentation project define its own data in a project folder or branch. For example:

projects/
├── my-saas-tool/
│   ├── _data/
│   ├── _guides/
│   ├── _faqs/
│   └── index.md
├── internal-wiki/
│   ├── _data/
│   ├── _guides/
│   └── index.md

Use a GitHub Actions matrix or manual branch switch to deploy each subfolder as a separate GitHub Pages site.

Step 6: Custom Themes via Config

Allow theming per project with variables in _data/site.yml:

theme:
  primary_color: "#2233aa"
  font: "Inter"
  button_radius: "12px"

Then use it in your CSS or SCSS:

:root {
  --primary: {{ site.data.site.theme.primary_color }};
  --font: {{ site.data.site.theme.font }};
  --radius: {{ site.data.site.theme.button_radius }};
}

Step 7: Easy Deploy via GitHub Pages

Each documentation instance can be published as:

  • org.github.io/my-saas-docs/
  • org.github.io/tools-wiki/

GitHub Actions can build each variation and push it to its own branch or repo. Every user now has access to a plug-and-play documentation system.

Use Case: Documentation Factory for a SaaS Studio

A SaaS company managing multiple products set up a "documentation factory" using this method. By cloning the base template, they spun up 8 documentation portals — all with consistent UI, language switching, custom branding, and search — simply by editing YAML.

Conclusion

Jekyll isn't just for static blogs. With collections, data files, and modular Liquid templates, it becomes a powerful tool for managing scalable, multilingual, and user-friendly documentation systems — all without any backend or JS frameworks.

This article concludes our deep-dive series on building knowledge base systems with Jekyll and GitHub Pages. You now have a complete, reusable system — searchable, multilingual, access-controlled, and modular — ready for production.

Read more
Subscribe to: Comments (Atom)