generate a contributor page automatically in Jekyll

By -

Why build a contributor page in documentation sites?

Open collaboration thrives on visibility and recognition. Listing contributors not only builds trust and transparency with readers, but also encourages ongoing participation by showing appreciation for contributors' work.

In a Jekyll-based documentation repo, we can automatically create a contributor page by reusing existing metadata—without external databases or plugins.

Step 1: Standardize the author field in front matter

Make sure each post, page, or guide contains a clear author or authors field: 


---
title: "API Authentication"
author: "devina"
contributors: ["nita", "aldo"]
---

Use a consistent naming convention, preferably matching GitHub usernames, to allow potential link generation later.

Step 2: Create a data file to enrich author metadata

Define author bios, links, and profile pictures in _data/contributors.yml: 


devina:
  name: "Devina Rahma"
  github: "devina-r"
  avatar: "https://avatars.githubusercontent.com/devina-r"
  role: "Lead Technical Writer"

nita:
  name: "Nita Suryani"
  github: "nitas"
  avatar: "https://avatars.githubusercontent.com/nitas"
  role: "Documentation Contributor"

Step 3: Extract all unique contributors

On your contributors.md page, iterate over site content to build a dynamic list: 


---
layout: default
title: "Documentation Contributors"
permalink: /contributors/
---


{% raw %}
{% assign authors = "" | split: "" %}
{% for page in site.pages %}
  {% if page.author %}
    {% assign authors = authors | push: page.author %}
  {% endif %}
  {% if page.contributors %}
    {% assign authors = authors | concat: page.contributors %}
  {% endif %}
{% endfor %}

{% assign unique_authors = authors | uniq | sort %}

<div class="contributors-grid">
  {% for username in unique_authors %}
    {% assign profile = site.data.contributors[username] %}
    <div class="contributor-card">
      <img src="{{ profile.avatar }}" alt="{{ profile.name }}" />
      <h3>{{ profile.name }}</h3>
      <p>{{ profile.role }}</p>
      <a href="https://github.com/{{ profile.github }}" target="_blank">@{{ profile.github }}</a>
    </div>
  {% endfor %}
</div>
{% endraw %}

This layout generates a full contributor grid, automatically updated as more files are added.

Step 4: List all documents each person contributed to


{% raw %}
{% assign target = "nita" %}
<h2>Contributions by {{ site.data.contributors[target].name }}</h2>
<ul>
{% for doc in site.pages %}
  {% if doc.author == target or doc.contributors contains target %}
    <li><a href="{{ doc.url }}">{{ doc.title }}</a></li>
  {% endif %}
{% endfor %}
</ul>
{% endraw %}

You can use this block on contributor profile subpages, or even filter via URL params using JavaScript if needed.

Step 5: Show contributor info on each page

At the bottom of each article layout, add:


{% raw %}
{% assign creator = site.data.contributors[page.author] %}
<div class="author-block">
  <img src="{{ creator.avatar }}" alt="{{ creator.name }}" />
  <p>Written by {{ creator.name }} – {{ creator.role }}</p>
  <a href="https://github.com/{{ creator.github }}">GitHub Profile</a>
</div>
{% endraw %}

This adds personal context, authority, and transparency to every article.

Optional: Include commit-based authorship using GitHub Actions

If you want to include people who touched the file even if they didn’t write the original content:

  1. Create a script or GitHub Action that parses git log --format='%an' per file
  2. Generate a JSON/YAML file with contributor mapping
  3. Use that data in addition to front matter for full accuracy

Best practices for contributor credit systems

  • Keep _data/contributors.yml updated in PRs
  • Use GitHub usernames as keys for cross-referencing
  • Avoid hardcoding names in layouts—use data lookup instead
  • Add a CONTRIBUTING.md guide to explain how to get credited

Conclusion: Documentation is a community effort—show it

By automating a contributor page in Jekyll, you honor the time and expertise of your team while encouraging new voices to join. You also create a more human-centered documentation experience where readers know exactly who’s behind the work—and who to thank (or ping).

And the best part: once set up, the contributor system runs itself, updating with every pull request and every new guide added to your repo.