Structure Jekyll repos for content-heavy sites and editorial workflows

Jekyll is often seen as a lightweight tool, but it is more than capable of powering large-scale editorial sites—blogs, documentation hubs, news portals, or knowledge bases. The real challenge lies not in Jekyll itself, but in how you structure the repository to handle:

• Hundreds or thousands of posts and pages
• Multiple authors or editors
• Scheduled publishing and archival
• Custom layouts per section
• Tagging, categorization, and internal linking

Why is structure essential in editorial workflows?

A clean structure supports clarity. Without it, writers won’t know where to place drafts, editors can’t manage revisions, and developers may end up hardcoding logic that should be abstracted. Editorial teams need a framework that supports their process without disrupting the build system.

What is a good folder structure for content-heavy Jekyll projects?

A scalable structure separates published content from drafts, groups posts by collection or topic, and supports automation for metadata like authors, dates, and tags.

/
├── _config.yml
├── _data/
│   └── authors.yml
├── _layouts/
├── _includes/
├── _sass/
├── assets/
├── drafts/
│   └── my-unpublished-post.md
├── _posts/
│   └── 2025-07-01-new-feature-release.md
├── _archive/
│   └── 2021/
│       └── 2021-03-15-legacy-post.md
├── _case_studies/
├── _interviews/
├── pages/
│   ├── index.md
│   └── about.md
└── README.md

With this layout:

• _posts/ holds live blog posts.
• drafts/ holds unpublished content (excluded from production builds).
• _archive/ separates historical content from actively updated content.
• Additional collections (_case_studies, _interviews) support modular storytelling and custom display logic.

How do you manage authors and editorial metadata?

Centralize metadata in the _data directory, especially for reusable elements like authors, tags, or partner organizations. For example:

_data/authors.yml

indriani:
  name: "Indriani"
  role: "Editor-in-Chief"
  bio: "Specialist in SEO and technical documentation."
  avatar: "/assets/images/authors/indriani.jpg"

david:
  name: "David Warner"
  role: "Technical Writer"
  bio: "Open-source contributor and frontend advocate."
  avatar: "/assets/images/authors/david.jpg"

Each post then references authors like so:

---
title: "Introducing New AI Features"
author: indriani
date: 2025-07-01
tags: [ai,features]
layout: post
---

How do you handle content stages: draft, review, publish?

For a simple editorial workflow without CMS, you can use:

• drafts/: For content being written (excluded from production builds).
• labels: Use front matter fields like status: draft or status: review.
• branches: Use a dedicated content-drafts branch for peer review or preview deployments.

You can also create preview builds using GitHub Actions or Netlify to show unpublished content before merging.

How do you organize content for navigation and discoverability?

Content-heavy sites need tagging, categorization, and section-based organization. Avoid putting everything in _posts. Instead, split content by purpose:

collections:
  blog:
    output: true
  case_studies:
    output: true
  interviews:
    output: true

Each section gets its own index page, layout, and navigation logic. This makes internal linking and search easier while keeping codebase modular.

How do you prevent performance degradation as the content grows?

Large Jekyll sites with thousands of files can slow down during local builds. To mitigate:

• Use incremental builds: bundle exec jekyll build --incremental
• Use pagination and filters to reduce looping over large data sets
• Split layouts using includes to reduce render cost
• Limit site-wide queries like site.posts—filter by category or collection instead

What’s the role of tagging and taxonomies in large content sites?

Tags and categories help users find related content and support editorial strategy. Store centralized tag descriptions in _data/tags.yml and include tag metadata in post front matter.

tags:
  - ai
  - accessibility

Render dynamic tag index pages by looping through the site’s taxonomy:

{% raw %}
{% for tag in site.tags %}
  <a href="/tag/{{ tag[0] | slugify }}">{{ tag[0] }} ({{ tag[1].size }})</a>
{% endfor %}
{% endraw %}

How do you organize archival content separately?

Older content should be isolated to avoid clutter in main navigation and search. Use a folder like _archive/ and either:

• Exclude it from navigation
• Move it to a dedicated subdomain or section (e.g., /legacy/)

In _config.yml:

defaults:
  - scope:
      path: "_archive"
    values:
      layout: archive
      noindex: true

How can teams contribute without breaking the main site?

Use the GitHub Flow model:

• Authors submit content as pull requests from feature/ or draft/ branches
• Each pull request can be previewed using deploy previews
• Editors comment and request revisions before merge

This approach mirrors a lightweight CMS workflow without compromising the static nature of Jekyll.

Conclusion: What’s the key to scaling content-heavy Jekyll sites?

It all comes down to discipline and modularity. Keep content types separated, authors centralized, navigation predictable, and metadata structured. Use Jekyll collections for sectioning, _data/ for reuse, and folder-based drafts for staging. As your site grows, so will your team—make sure they can find what they need, work without fear, and build confidently on a clean foundation.