Home › Blog › How to Build a Documentation Site with Jekyll
Tutorial

How to Build a Documentation Site with Jekyll

Set up a professional documentation site with Jekyll — using Just the Docs or similar themes, with search, navigation, versioning, and GitHub Pages hosting.

Updated 6 min read
How to Build a Documentation Site with Jekyll

Jekyll is one of the best tools for documentation sites. The result is fast, searchable, version-controllable, and free to host. This guide walks through building a professional documentation site from scratch.

Why Jekyll for Documentation?

Documentation sites have specific requirements that Jekyll handles exceptionally well:

  • Version control — docs live in the same repository as your code
  • Plain text — Markdown files that any developer can edit in a PR
  • Free hosting — GitHub Pages deployment is built-in and free
  • Search — Static search with Lunr.js works without a backend
  • Navigation — Sidebar navigation with nested sections

The Best Jekyll Documentation Themes

Just the Docs

Just the Docs is the most popular Jekyll documentation theme with 8,000+ stars. It includes:

  • Full-text search (Lunr.js)
  • Nested navigation sidebar
  • Responsive design
  • Dark/light mode
  • Code syntax highlighting
  • Callout blocks (note, warning, tip)
  • Table of contents generation

Minimal Mistakes

Minimal Mistakes is more flexible and works for both blogs and documentation. Good if you need a mix of docs and blog posts.

Docsy (Jekyll port)

A port of Google’s Docsy theme, suited for large documentation projects with versioning needs.

Setting Up Just the Docs

Installation

# Gemfile
gem "just-the-docs"

# _config.yml
theme: just-the-docs

Or use it as a remote theme (works with GitHub Pages):

# Gemfile
gem "github-pages"

# _config.yml
remote_theme: just-the-docs/just-the-docs

Basic Configuration

# _config.yml
title: My Project Docs
description: Documentation for My Project
baseurl: ""
url: "https://yourdomain.com"

# Just the Docs settings
search_enabled: true
search:
  heading_level: 2
  previews: 3

# Auxiliary links in top navigation
aux_links:
  "GitHub":
    - "https://github.com/username/repo"

# Footer content
footer_content: "Copyright © 2026 Your Company"

# Colour scheme
color_scheme: light

Structuring Your Documentation

File Organisation

my-docs/
├── _config.yml
├── index.md               # Homepage
├── docs/
│   ├── getting-started/
│   │   ├── index.md       # Section landing page
│   │   ├── installation.md
│   │   └── quickstart.md
│   ├── guides/
│   │   ├── index.md
│   │   └── advanced.md
│   └── api/
│       ├── index.md
│       └── reference.md
└── assets/
    └── images/

Front Matter for Navigation

Just the Docs uses front matter to build the sidebar:

---
layout: default
title: Installation
parent: Getting Started
nav_order: 1
---
  • title — appears in the sidebar
  • parent — nests this page under another
  • nav_order — controls ordering within a section
  • has_children: true — marks a page as a section parent

Section Landing Pages

---
layout: default
title: Getting Started
nav_order: 2
has_children: true
---

# Getting Started

A brief introduction to this section.

Just the Docs includes Lunr.js search out of the box. No configuration needed.

For large documentation sites (hundreds of pages), Lunr can become slow. Consider Algolia DocSearch — it’s free for open-source documentation:

# _config.yml
search_provider: algolia
algolia:
  application_id: YOUR_APP_ID
  index_name: YOUR_INDEX_NAME
  search_only_api_key: YOUR_SEARCH_KEY

Callout Blocks

Just the Docs provides callout blocks for important information:

{: .note }
> This is a note.

{: .warning }
> This will break things if you do it wrong.

{: .tip }
> This will save you time.

Code Blocks with Syntax Highlighting

Jekyll uses Rouge for syntax highlighting:

```ruby
def hello
  puts "Hello, world!"
end
```

Specify the language for correct highlighting.

Just the Docs automatically adds anchor links to headings. Users can link to specific sections with URLs like /docs/installation/#step-2.

Setting Up Multiple Versions

For projects with multiple supported versions, create a version switcher using Jekyll collections.

Create version-specific collections:

# _config.yml
collections:
  v1:
    output: true
    permalink: /v1/:name/
  v2:
    output: true
    permalink: /v2/:name/

Add a version selector to your layout:

<select onchange="window.location.href=this.value">
  <option value="/v2/">v2 (latest)</option>
  <option value="/v1/">v1</option>
</select>

Deploying to GitHub Pages

Documentation sites are perfect for GitHub Pages — they can live in the same repo as the code they document.

Option A: Docs in the same repo

Keep docs in a /docs folder in your code repo:

# GitHub Actions workflow
- name: Build docs
  run: bundle exec jekyll build --source docs --destination _site

Option B: Separate docs repo

Create a username/project-docs repo and deploy from there. Cleaner separation, easier to manage permissions.

Option C: GitHub Pages from /docs folder

In repository Settings → Pages, set source to Deploy from branch → /docs folder. Jekyll builds automatically.

Making Documentation Searchable by Google

  1. Add jekyll-sitemap to generate sitemap.xml
  2. Submit to Google Search Console
  3. Use descriptive titles with relevant keywords in front matter
  4. Use proper heading hierarchy (one H1 per page, logical H2/H3 structure)
  5. Add meta descriptions to important pages
Component Tool
Theme Just the Docs
Search Lunr.js (built-in) or Algolia
Hosting GitHub Pages
Build GitHub Actions
Comments Giscus (for community feedback)
Analytics Plausible or Google Analytics

Browse documentation themes on JekyllHub — filter by the Documentation category to see themes designed specifically for docs sites.

References

jekyll documentation jekyll docs site just the docs static documentation
Share LinkedIn