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.
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 sidebarparent— nests this page under anothernav_order— controls ordering within a sectionhas_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.
Adding Search
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
Navigation Best Practices
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. In your Markdown files, open a fenced code block with three backticks followed by the language name — for example, “ruby”, “yaml”, “bash”, or “javascript”. Rouge detects the language and applies appropriate token colouring. Specifying the language is optional but strongly recommended; without it, Rouge cannot highlight syntax correctly and the code renders as plain monospaced text, which is significantly harder to read.
Anchor Links for Headings
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
- Add
jekyll-sitemapto generatesitemap.xml - Submit to Google Search Console
- Use descriptive titles with relevant keywords in front matter
- Use proper heading hierarchy (one H1 per page, logical H2/H3 structure)
- Add meta descriptions to important pages
Recommended Documentation Site Stack
| 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
Writing documentation that people actually use
A documentation site’s success is measured by how quickly users find answers, not by how comprehensive the content is. Structure and navigation matter as much as the content itself.
Short, scannable pages beat long exhaustive ones. A page covering one concept — installation, configuration, a specific API method — is easier to navigate than a 10,000-word monolith. Users search for what they need and land on the specific page. A long page means more scrolling to find the relevant section.
Use consistent heading hierarchy. Every page should have one # H1 (the page title), logical ## H2 sections, and ### H3 subsections within those. Just the Docs automatically generates a right-side table of contents from H2 and H3 headings — this only works if headings are properly nested.
Provide working code examples. Readers of technical documentation want copy-pasteable code that actually runs. If an example requires prerequisites, list them explicitly. If a code snippet is incomplete (a fragment of a larger file), say so.
Keep the getting-started path short. New users need to reach a working state as quickly as possible. The getting-started section should lead them from zero to “it works” in under five minutes. More detailed configuration comes later.
Advanced Just the Docs features
Callout blocks with content
The built-in callout syntax accepts multi-line content:
{: .tip }
> **Performance tip:** Enable `bundle exec jekyll serve --incremental` during development.
> This skips rebuilding unchanged pages and makes your feedback loop faster.
Callout types: .note, .tip, .warning, .important, .caution.
Tables with formatting
Markdown tables with alignment:
| Setting | Type | Default | Description |
|:--------|:-----|:--------|:------------|
| `search_enabled` | Boolean | `true` | Enable/disable search |
| `search.heading_level` | Integer | `2` | Which heading levels to index |
| `nav_sort` | String | `case_sensitive` | Sort navigation items |
The colons in the header separator row control alignment: :--- is left, :---: is center, ---: is right.
Custom colour schemes
Just the Docs supports custom colour scheme overrides. Create _sass/color_schemes/custom.scss:
$link-color: #7c3aed;
$btn-primary-color: #7c3aed;
$base-button-color: #ede9fe;
$sidebar-color: #f5f3ff;
$table-background-color: #ffffff;
Reference it in _config.yml:
color_scheme: custom
Organising documentation for maintainability
Documentation has a tendency to become outdated faster than it is updated. A few practices that reduce maintenance overhead:
Version your docs with your software. If your project has version 1.x and 2.x, your documentation should too. Use Jekyll collections for each major version, or use branches with separate GitHub Pages deployments.
Add a “last reviewed” date to important pages. Front matter makes this easy:
last_reviewed: 2026-01-15
Add a warning banner to pages that have not been reviewed in over six months:
{% if page.last_reviewed %}
{% assign days_since = 'now' | date: "%s" | minus: page.last_reviewed | date: "%s" | divided_by: 86400 %}
{% if days_since > 180 %}
<div class="stale-warning">
This page was last reviewed {{ days_since }} days ago. Some information may be outdated.
</div>
{% endif %}
{% endif %}
Use {% include %} for repeated content. If the same configuration snippet appears in five documentation pages, extract it to an include. Updates happen in one place.
Encouraging contributions
Documentation that lives in a GitHub repository benefits from community contributions. Make it easy:
Add an “Edit this page on GitHub” link to every documentation page. Just the Docs supports this natively with a configuration key:
# _config.yml
gh_edit_link: true
gh_edit_link_text: "Edit this page on GitHub"
gh_edit_repository: "https://github.com/your-org/your-docs-repo"
gh_edit_branch: "main"
gh_edit_source: docs/
gh_edit_view_mode: "edit"
This adds an edit link at the bottom of every page that opens the file in GitHub’s web editor — lowering the barrier for users to fix typos and add missing information.
Write a CONTRIBUTING.md that explains how to run the documentation site locally, what the PR process looks like, and what makes a good documentation contribution.
Monitoring documentation quality
Once your documentation site is live, track its effectiveness:
Search queries with no results reveal content gaps. If users frequently search for “authentication” and find nothing, add that content.
High bounce rates on specific pages may indicate the page does not answer the question users arrived with. Revise the content or add a “Was this helpful?” widget.
Support tickets that reference documentation show whether docs are solving problems or creating new ones. If users frequently email asking about something the docs cover, the docs are unclear.
Broken link checks should run regularly. Add HTMLProofer to your CI pipeline:
bundle exec htmlproofer ./_site --checks Links --disable-external
External links go stale too — run a weekly check with external link validation enabled.
Documentation is a product, not an afterthought. Investing in structure, discoverability, and maintainability pays off in reduced support burden and happier users. Browse JekyllHub’s documentation themes to find a well-designed starting point.
Choosing between Just the Docs and building custom
Just the Docs is the right choice for the vast majority of documentation sites. It handles navigation, search, syntax highlighting, and responsive design out of the box. The main reasons to build custom instead are: extremely specific design requirements that conflict with the theme, a need for complex versioning systems, or integration with external tooling that the theme does not support.
Before deciding, spend an hour with Just the Docs’ starter template. The configuration options cover more use cases than the documentation suggests — colour schemes, layout variants, nav configuration, callout styles, and search tuning are all available without touching the theme’s source code.
Documentation site SEO
Documentation sites have different SEO needs than blogs. Users search for specific procedures (“how to configure X”) rather than topics (“best practices for Y”). A few adjustments help documentation rank for procedural queries:
Title tags — use descriptive, specific titles rather than just the topic name. “Installing Jekyll on macOS” ranks better than “Installation” for relevant searches.
Meta descriptions — add a description: field to every page’s front matter summarising what the page covers and what problem it solves.
Internal linking — documentation pages should link to related topics. Just the Docs’ “parent/child” navigation creates implicit links, but explicit “see also” sections in the content add more link equity.
Code snippet structured data — if your documentation includes a large number of how-to procedures, adding HowTo schema markup to those pages makes them eligible for rich results in Google Search.
Canonical URLs — if your documentation exists in multiple places (GitHub README and a dedicated docs site), set canonical tags to the authoritative version.
Deploying documentation alongside code
For open-source projects, documentation that deploys from the same repository as the code is easiest to maintain. Changes to code and docs are in the same commit, and contributors who fix a bug can update the docs in the same PR.
Two common setups:
Docs in /docs folder, deployed to GitHub Pages. Configure GitHub Pages in repository settings to deploy from the /docs folder on the main branch. Jekyll processes the docs automatically. The downside: GitHub Pages only supports whitelisted plugins. If you need jekyll-archives or other non-whitelisted plugins, use GitHub Actions instead.
Docs in /docs folder, built with GitHub Actions. A workflow in .github/workflows/docs.yml builds the docs site and deploys to GitHub Pages or an external host. This unlocks all plugins but adds a small amount of workflow maintenance.
Separate docs repository. Create your-org/your-project-docs on GitHub. More organisational overhead, but cleaner separation of concerns — especially useful when the documentation team and the engineering team are different groups of people.
For private repositories or internal tools, Netlify and Cloudflare Pages both support private deployments with authentication, making them good choices for internal documentation that should not be publicly accessible.
Documentation analytics and user research
Knowing how users interact with your documentation reveals what is working and what is not.
Page views by topic — which documentation pages get the most traffic? These are your most important pages and should receive the most maintenance attention. A page that nobody reads does not need to be perfect.
Search queries — what do users search for on your documentation site? Queries that return no results are unmet needs. Queries that return results but users leave without clicking are navigation failures — the results did not match what users expected.
Time on page — very short time on page for complex documentation suggests users are not finding what they need. Very long time on page for simple documentation suggests the content is unclear.
Exit pages — where do users leave the documentation? If users consistently exit at the “Configuration” page, that page may be confusing or leading them to give up.
Plausible Analytics (privacy-focused, GDPR-friendly) or Google Analytics work well for this. Plausible’s “entry pages” and “exit pages” reports are particularly useful for documentation sites.
Jekyll documentation sites combine the simplicity of plain Markdown files with professional presentation, fast load times, and free hosting on GitHub Pages. The result is a documentation site that developers can actually maintain — no CMS to manage, no database to back up, just Markdown files in Git. Browse documentation-focused Jekyll themes on JekyllHub to find the right starting point.
Structuring documentation for discoverability
Great documentation is not just accurate — it is findable. Readers arrive with a specific question and need to get to the answer in as few clicks as possible. Structuring your documentation for discoverability means building three navigation layers: top-level section navigation, page-level headings, and within-page search.
Top-level navigation should be flat and logical — five to seven sections maximum in the primary nav. Group by user task rather than by product structure. “Getting started,” “Configuration,” “Recipes,” and “API reference” are task-oriented sections that match what users search for. “Product overview,” “Advanced topics,” and “Miscellaneous” are internal organisational categories that reflect how the documentation was written, not how readers use it.
Page-level headings should use descriptive text that answers the question a reader would type into a search engine. “Installing on Windows” ranks better and is more useful than “Windows installation” — the verb-first phrasing matches search intent more closely. Every H2 heading in your documentation should be answerable as a complete question: “How do I install on Windows?” finds a page titled “Installing on Windows” faster than it finds “Windows Installation Guide.”
Within-page search via Pagefind handles long pages with many sections. Enable deep-linking by ensuring every heading has a stable anchor ID — Jekyll generates these automatically from the heading text, but be aware that changing heading text changes the anchor, breaking inbound links. Use {#custom-anchor} syntax (supported with the jekyll-anchor-headings plugin or Kramdown) to assign stable IDs to important headings.
Managing documentation versions
Long-lived open source projects face the challenge of maintaining documentation for multiple product versions simultaneously. Users of version 2.x need the 2.x docs; users of the current version need the current docs; and both sets of docs need to be discoverable without creating confusion.
Jekyll handles this with directory-based version separation. Store each version’s documentation in a subdirectory (/docs/v2/, /docs/v3/) or as a collection with a version prefix. A version switcher in the navigation — a dropdown showing available versions — lets readers move between them. The canonical URL for each version should point to the current version’s equivalent page, preventing older version pages from competing with current ones in search.
A simpler approach for most projects: maintain one set of “current” documentation and keep an archived copy of each major version in a _archive/v2/ directory with noindex in the page front matter. This keeps the main documentation site clean and search-optimised while preserving older versions for users who need them.
Writing documentation that stays accurate
Technical documentation ages faster than any other form of writing. An API changes, a configuration option is renamed, a default value shifts — and suddenly a tutorial that was correct last month leads users into a dead end. Building accuracy maintenance into your documentation workflow prevents this accumulation of outdated content.
The most effective pattern is to link documentation to release notes. Every pull request that changes user-facing behaviour should include a required documentation update — enforced by a PR template checklist. Many open source projects implement this with a bot that labels PRs as “needs docs” when certain files change. The discipline of treating documentation as part of the feature, not an afterthought, keeps doc quality high even as the project evolves quickly.
Run automated link checking on your documentation site with every build. Tools like html-proofer (a Jekyll-compatible Ruby gem) check every internal and external link in your built HTML and report broken ones before deployment. A broken link in documentation — whether to an API endpoint that was renamed or an external reference that moved — destroys reader trust quickly. Automated checking catches these regressions at the PR stage, before they reach your users.
For documentation that includes code samples, test the code samples. Copy them verbatim, run them against the current version of your product, and verify the output matches what the documentation claims. Untested code samples are documentation debt — they work when written and fail silently thereafter. Even running samples in a CI environment once per week catches regressions before readers report them.