Jekyll & Static Generators
Static site generators transform markdown and templates into fast, secure websites. Learn to use Jekyll (built into GitHub Pages) and other generators like MkDocs with GitHub Actions to create documentation sites, blogs, and professional web projects.
Static site generators (SSGs) are tools that take content files—usually written in Markdown—and templates, then generate complete HTML websites. Instead of building a site with dynamic server-side code, you write content in simple formats, and the generator produces static files ready to be served. This approach offers significant advantages: sites are incredibly fast (no database queries), extremely secure (no server-side vulnerabilities), and easy to version control since everything is text files.
There are dozens of static site generators available, each with different strengths. Jekyll is the most popular for GitHub Pages because it's built-in—you push markdown files, and GitHub automatically builds and deploys your site. Hugo is known for being extremely fast, great for blogs and portfolios. MkDocs is designed specifically for documentation sites. Next.js and Gatsby are React-based generators for more complex applications. All of them can work with GitHub Pages when combined with GitHub Actions.
Jekyll is the static site generator that GitHub Pages uses natively. When you push files to your repository, GitHub automatically runs Jekyll if it detects a _config.yml file. You don't need to set up anything—Jekyll is already installed on GitHub's servers. This makes it the simplest way to create a blog or documentation site.
Jekyll uses a folder structure that's easy to understand. Markdown files in the root become pages. The _posts folder holds blog posts with dates in their filenames. The _layouts folder contains HTML templates. Front matter at the top of each file defines metadata like title, layout, and permalink. Jekyll also supports plugins, though GitHub Pages restricts which plugins can run for security reasons.
# _config.yml - Minimal Jekyll configuration
title: My Awesome Blog
description: Writing about tech and life
theme: minima
# _posts/2024-03-15-first-post.md
---
title: My First Post
date: 2024-03-15
categories: [blog]
---
This is my first blog post written in Markdown.
# To build locally (requires Ruby):
# bundle install
# bundle exec jekyll serve
One of Jekyll's strengths is its rich theme ecosystem. GitHub Pages supports several official themes that you can enable with a single line in your config file. Themes like "Minima", "Cayman", "Leap Day", "Hacker", and "Time Machine" provide professional designs without any CSS work.
You can also use remote themes—themes hosted on GitHub that you reference by repository name. This keeps your repository clean while still using a sophisticated design. Many popular open source projects use this approach for their documentation sites.
# Using an official GitHub Pages theme
# _config.yml
theme: minima
# Using a remote theme from GitHub
# _config.yml
remote_theme: pages-themes/cayman
plugins:
- jekyll-remote-theme
# For custom styling, create assets/css/style.scss
---
---
@import "minima";
/* Custom CSS below */
body { background: #f0f0f0; }
MkDocs is a static site generator designed specifically for project documentation. It's written in Python and uses Markdown for content. MkDocs produces clean, searchable documentation sites with a simple navigation structure—perfect for API docs, user guides, or internal project documentation.
Unlike Jekyll, MkDocs is not built into GitHub Pages, but you can use GitHub Actions to build and deploy MkDocs sites. This gives you full control over the build process while still using GitHub Pages for hosting. MkDocs includes a built-in development server for local preview, and the Material for MkDocs theme is one of the most popular documentation themes available.
# mkdocs.yml - Configuration file
site_name: My Project Documentation
theme: material
nav:
- Home: index.md
- Getting Started: getting-started.md
- API Reference: api.md
# GitHub Actions workflow to build and deploy
name: Deploy MkDocs
on:
push:
branches: [ main ]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.x'
- run: pip install mkdocs mkdocs-material
- run: mkdocs build
- uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./site
For static site generators that aren't Jekyll, you need to build the site before publishing. GitHub Actions provides the perfect solution. You can set up a workflow that runs on every push, builds your site using your preferred generator, and deploys the output to GitHub Pages.
This approach works with any static site generator: Hugo, Gatsby, Next.js, VuePress, Docusaurus, or custom scripts. You keep your source code in the main branch, and the built site goes to the gh-pages branch. GitHub Pages serves the gh-pages branch, so your live site updates automatically after each successful build.
# Universal workflow for any static site generator
name: Build and Deploy
on:
push:
branches: [ main ]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install dependencies
run: |
# For Hugo
curl -L -o hugo.tar.gz https://github.com/gohugoio/hugo/releases/download/v0.120.0/hugo_extended_0.120.0_Linux-64bit.tar.gz
tar -xzf hugo.tar.gz hugo
chmod +x hugo
sudo mv hugo /usr/local/bin/
- name: Build
run: hugo --minify
- name: Deploy
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./public
Jekyll (Ruby) is the default for GitHub Pages. Best for blogs, personal sites, and simple documentation. Built-in support means no build step required.
Hugo (Go) is the fastest SSG, capable of building thousands of pages in milliseconds. Great for blogs, portfolios, and sites with many pages. Uses Go templates and Markdown.
Next.js (React) is a full-featured React framework that can export static sites. Perfect for complex applications with interactive components, while still getting static site benefits.
VuePress (Vue) is designed for documentation sites with Vue components. Popular for technical documentation and API reference sites.
Docusaurus (React) is Facebook's documentation-focused SSG. Features versioning, search, and excellent Markdown support. Used by React, Jest, and many open source projects.
Eleventy (JavaScript) is a simpler JavaScript-based SSG that works with many templating languages. Great for developers who want flexibility without React complexity.
All static site generators use Markdown as their primary content format. Markdown is a lightweight markup language that's easy to read and write. You can create headings, lists, links, images, code blocks, and more with simple syntax. This makes content creation accessible to writers and developers alike.
Markdown files typically have front matter at the top—metadata in YAML format between triple-dashed lines. Front matter can include title, date, layout, tags, and custom variables that your templates can use. Most generators also support Markdown extensions like footnotes, definition lists, and tables.
---
title: My Page Title
description: A short description for SEO
date: 2024-03-15
author: Jane Doe
tags: [tutorial, markdown]
---
# Heading 1
## Heading 2
This is a paragraph with **bold** and *italic* text.
- List item one
- List item two
1. Numbered list
2. Another item
[Link text](https://example.com)
```javascript
function hello() {
console.log("Hello, world!");
}
```
Before pushing changes to GitHub, you'll want to preview your site locally. Most static site generators include a development server that automatically rebuilds and refreshes when you save files. This gives you instant feedback and lets you iterate quickly.
For Jekyll, you need Ruby installed. Run bundle install to install dependencies, then bundle exec jekyll serve. Your site will be available at http://localhost:4000. For MkDocs, use mkdocs serve. For Hugo, use hugo server. Each generator has its own command, but they all provide live reloading.
# Jekyll
gem install bundler
bundle install
bundle exec jekyll serve --livereload
# MkDocs
pip install mkdocs
mkdocs serve
# Hugo
hugo server -D
# Next.js (with static export)
npm run build
npm run serve # serves the out/ directory
assets/images/. Reference them with relative paths. Jekyll's jekyll-assets plugin can optimize images. For other generators, you can use separate tools to optimize assets before building.Static site generators transform how you build websites. Write in Markdown, get a fast, secure site, and deploy with confidence using GitHub Pages and Actions.