Using Jekyll for Open Source Project Documentation

Jekyll powers documentation for thousands of open source projects — Bootstrap, Jekyll itself, GitHub’s own docs, and hundreds of others. It is the natural choice for projects already hosted on GitHub, and the most supported static site generator on GitHub Pages.

Here is how to set up professional documentation for your open source project.

Why Jekyll for open source docs

GitHub Pages native support — push to a docs/ folder or gh-pages branch and your docs are live instantly
Markdown-first — contributors already write Markdown for README files; docs are the same workflow
No build step required — GitHub Pages builds Jekyll automatically on every push
Versioned with your code — docs live in the same repository as code, so pull requests can include both code and doc changes
Free — no hosting cost for open source projects

Two approaches: docs in the repo vs separate docs site

Option A: docs/ folder in your main repository

Jekyll can build from a docs/ folder in your repository. This keeps docs alongside code — ideal for small to medium projects.

In your GitHub repository settings → Pages → Build and deployment, set the source to “Deploy from a branch” and the folder to /docs.

Option B: Separate gh-pages branch

Larger projects often use a dedicated gh-pages branch for documentation. This keeps the main branch clean and allows the docs to have their own git history.

Setting up the docs folder

docs/
├── _config.yml
├── _layouts/
│   ├── default.html
│   └── page.html
├── _includes/
│   ├── nav.html
│   └── sidebar.html
├── assets/
│   ├── css/
│   └── js/
├── index.md          # Landing page / introduction
├── getting-started.md
├── installation.md
├── configuration.md
├── api/
│   ├── overview.md
│   └── reference.md
└── guides/
    ├── quickstart.md
    └── advanced.md

_config.yml for project docs

title: "YourProject Documentation"
description: "The official documentation for YourProject — a [brief description]."
url: "https://yourorg.github.io"
baseurl: "/your-project"

# Theme — just-the-docs is the most popular Jekyll docs theme
remote_theme: just-the-docs/just-the-docs

# Navigation order
nav_order: true

# Search
search_enabled: true

# Footer links
footer_content: "Copyright &copy; 2026 YourProject Contributors."

# GitHub link
gh_edit_link: true
gh_edit_link_text: "Edit this page on GitHub"
gh_edit_repository: "https://github.com/yourorg/your-project"
gh_edit_branch: "main"
gh_edit_source: docs

The Just the Docs theme

Just the Docs is the most popular Jekyll theme for open source documentation. It provides:

Responsive sidebar navigation with automatic TOC
Full-text client-side search
Collapsible navigation sections
Breadcrumbs
Dark mode
Code block copy buttons
Custom callout blocks

To use it with GitHub Pages, add to _config.yml:

remote_theme: just-the-docs/just-the-docs

No Gemfile changes needed for GitHub Pages.

Structuring documentation with front matter

Just the Docs uses front matter to control the navigation:

---
layout: default
title: "Getting Started"
nav_order: 2
description: "How to install and set up YourProject in under 5 minutes."
permalink: /getting-started/
---

Parent-child navigation for nested sections:

# Parent page
---
title: "API Reference"
nav_order: 4
has_children: true
---

# Child page
---
title: "Authentication"
parent: "API Reference"
nav_order: 1
---

Writing great documentation

Every docs site needs these pages:

Introduction — What is the project? Who is it for? What problem does it solve?
Installation — The first thing every new user reads. Be thorough.
Quickstart — Get from zero to working example in 5 minutes or less
Configuration reference — Every configuration option documented, with type, default, and example
API reference (for libraries) — Every public method, parameter, and return value
Changelog — What changed in each version

Documentation writing principles:

Write for a reader who has never seen your project. Avoid assuming knowledge. Every code example should be copy-paste runnable. Include expected output.

Use callout boxes for warnings, tips, and important notes:

{: .warning }
This configuration option was deprecated in v2.0. Use `new_option` instead.

{: .note }
This feature requires YourProject v1.5 or higher.

Version-specific documentation

For projects with multiple active versions, use Jekyll collections:

# _config.yml
collections:
  v2:
    output: true
    permalink: /v2/:path/
  v3:
    output: true
    permalink: /v3/:path/

Or use a branch per version and configure separate GitHub Pages deployments.

Automating docs with GitHub Actions

Auto-build and deploy on every push to main:

# .github/workflows/docs.yml
name: Deploy Docs

on:
  push:
    branches: [main]
    paths: ["docs/**"]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          bundler-cache: true
          working-directory: docs
      - run: bundle exec jekyll build
        working-directory: docs
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: $
          publish_dir: docs/_site

Alternatives to consider

Jekyll is excellent for documentation but not the only option. Compare before committing:

Tool	Best for
Jekyll + Just the Docs	GitHub-hosted projects, Markdown-native teams
Docusaurus	React-based projects, versioned docs, MDX
MkDocs	Python projects, simple setup
GitBook	Teams wanting a hosted, no-build solution
ReadTheDocs	Python/Sphinx projects, automatic versioning

For projects already on GitHub with a Markdown-writing team, Jekyll on GitHub Pages is the fastest path from code to professional documentation — often taking less than an hour to set up.