build an automated documentation dashboard in Jekyll

Once your Jekyll site grows to dozens or hundreds of content files—especially if multiple contributors are involved—it becomes hard to track what’s in draft, what’s outdated, what’s missing metadata, or who authored what.

Why build a documentation dashboard in Jekyll?

An internal dashboard lets content leads or editors monitor the state of your docs in real time. Since Jekyll is static, the dashboard must be auto-generated during build—no JavaScript dashboard or backend needed.

What should a Jekyll documentation dashboard show?

• List of all documents grouped by collection
• Status of each doc: draft, review, published
• Missing or incomplete front matter
• Last modified date or last commit
• Author and assigned reviewer
• Recent additions or updates

Step 1: Standardize front matter fields

To generate a clean dashboard, each file should have consistent metadata:

---
title: "Getting Started"
author: "ari"
status: "draft"
last_updated: 2025-07-26
audience: "developer"
collection: "guides"
---

Without these fields, the dashboard will produce gaps or fail to filter correctly.

Step 2: Use Liquid filters to group and report

On your dashboard page (e.g., _pages/dashboard.html), use Liquid to iterate through collections and generate sections.

---
layout: default
title: "Documentation Dashboard"
permalink: /dashboard/
---

{% raw %}
<h2>Drafts in Progress</h2>
<ul>
{% for doc in site.guides %}
  {% if doc.status == "draft" %}
    <li>{{ doc.title }} by {{ doc.author }} ({{ doc.last_updated }})</li>
  {% endif %}
{% endfor %}
</ul>
{% endraw %}

You can repeat this logic for other collections or statuses like review or published.

Step 3: Highlight files missing metadata

You can check for missing front matter values using simple conditionals:

{% raw %}
<h2>Files Missing Metadata</h2>
<ul>
{% for post in site.guides %}
  {% if post.author == nil or post.status == nil %}
    <li>{{ post.path }} (Missing: 
      {% if post.author == nil %}author{% endif %}
      {% if post.status == nil %}, status{% endif %}
    )</li>
  {% endif %}
{% endfor %}
</ul>
{% endraw %}

Step 4: Add recent updates overview

To track recent contributions, sort docs by date:

{% raw %}
<h2>Recently Updated</h2>
<ul>
{% assign sorted = site.guides | sort: "last_updated" | reverse %}
{% for doc in sorted limit:10 %}
  <li>{{ doc.title }} – {{ doc.last_updated }} by {{ doc.author }}</li>
{% endfor %}
</ul>
{% endraw %}

You can apply this logic across any collection: FAQs, changelogs, tutorials, etc.

Step 5: Track per-author contributions

Want to see who's contributing the most content? Group by author:

{% raw %}
<h2>Contributions by Author</h2>
{% assign authors = site.guides | map: "author" | uniq %}
<ul>
{% for person in authors %}
  <li>{{ person }} – 
    {{ site.guides | where: "author", person | size }} documents
  </li>
{% endfor %}
</ul>
{% endraw %}

Optional: Use _data/ files for extended metadata

For deeper insights (e.g., reviewer assignments, deadlines, checklists), pair your content with external YAML data:

_data/docs-tracking.yml

- slug: getting-started
  reviewer: nita
  checklist:
    - ✅ title
    - ✅ author
    - ⛔️ last_updated

Then link this data to content by matching on slug or title.

How to style the dashboard?

Use colored badges to show statuses, missing fields, or deadlines:

{% raw %}
{% if doc.status == "draft" %}
  <span class="badge badge-warning">Draft</span>
{% elsif doc.status == "review" %}
  <span class="badge badge-info">In Review</span>
{% else %}
  <span class="badge badge-success">Published</span>
{% endif %}
{% endraw %}

You can extend this with collapsible sections, tables, or links to pull requests.

Bonus: Use GitHub metadata via API or Actions

For more accuracy, use GitHub Actions to insert:

• last_modified_at (based on Git commit)
• PR link for each new doc
• Issue reference from which content originated

These fields can be written back to the front matter or a _data/log.yml file during CI.

Conclusion: Why every serious Jekyll repo needs a dashboard

Static sites like Jekyll aren't just for publishing—they’re also collaboration platforms. With a structured dashboard, you gain visibility into the entire documentation lifecycle, even without a backend system.

It’s one of the most effective ways to keep your content organized, catch issues early, and scale your editorial workflow with clarity and control.