Publishing with MkDocs, Hugo and Jekyll

By the end of this lesson you'll understand how a folder of Markdown files becomes a real website — how static site generators convert .md to HTML, how front matter and templates fit together, and where to host the result for free.

Learn Publishing with MkDocs, Hugo and Jekyll in our free Markdown course — an interactive lesson with worked examples, a practice exercise and a quick…

Part of the free Markdown course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

What You'll Learn

💡 Real-World Analogy

A static site generator is like a print shop for a book . You hand over loose manuscript pages (your Markdown files) and a style guide (the template and config). The shop typesets every page into the same branded layout, adds a table of contents (the navigation), and returns a finished, bound book (a folder of HTML) ready to put on the shelf (your host). You write the words; the generator handles the consistent presentation.

1. What a Static Site Generator Does

A static site generator takes source files — usually Markdown — and builds a complete set of HTML pages ahead of time. There's no database and no server-side code at request time; the output is just files. That makes the site fast, secure, and cheap to host. Each .md file typically becomes one .html page, wrapped in a shared template.

2. The Big Generators

A few generators dominate. MkDocs is a Python tool focused on documentation, and its Material theme is enormously popular. Hugo is written in Go and is prized for building large sites very fast. Jekyll is a Ruby tool and the engine behind GitHub Pages. Docusaurus is built on React and aimed at project docs.

Generator

Built with

Known for

MkDocs

Python

Docs, Material theme

Hugo

Go

Speed, large sites

Jekyll

Ruby

GitHub Pages default

Docusaurus

React

Project documentation

3. Pages, Front Matter, and Templates

Each page is a Markdown file. Its front matter (the --- block) supplies metadata like the title and which layout to use; the body below it is the content. At build time the generator converts that body to HTML and slots it into a template — the shared HTML that provides the header, navigation, and footer. So every page ends up looking consistent without you repeating the layout.

Write your page in Markdown . The generator converts this file to HTML and drops it inside the site's template.

🎯 Your Turn #1: a navigation list

Fill in the blanks so the program prints a MkDocs nav: block mapping two menu titles to two Markdown files, then run it.

4. Config and Navigation Files

Site-wide settings live in a config file . MkDocs uses mkdocs.yml , where you set the site name, theme, and a nav list that defines the menu. Hugo uses hugo.toml (or config.toml /YAML), and Jekyll uses _config.yml . The config is where you choose a theme and wire up navigation, so it controls how the whole site is assembled.

Here's a worked example that prints a page plus config source . Run it, read each printed line, then place the page in a docs/ folder and the config at the project root and run the generator to build the site.

🎯 Your Turn #2: a docs page

Fill in the blanks so the program prints a documentation page with front matter (a title), an H1 heading, and a sentence of body content.

5. Hosting the Result

Because the output is plain files, hosting is easy. GitHub Pages serves a static site straight from a repository and natively supports Jekyll. Read the Docs automatically builds and hosts documentation, commonly from MkDocs or Sphinx. Many teams also deploy the built folder to a CDN host. In every case you push your Markdown, a build runs, and the HTML goes live.

Common Errors (and the fix)

• My page isn't in the menu. It's missing from the nav list (MkDocs). Add a Title: file.md entry to the config.
• Build fails on the config. A YAML indentation slip in mkdocs.yml or _config.yml breaks the parse. Use spaces, not tabs, and keep levels aligned.
• The whole page is one big code block. A stray indent or unclosed fence in the Markdown confused the converter. Check your fenced code blocks open and close.
• I edited the output and it reverted. You changed site/ or public/ , which the build overwrites. Edit the source Markdown instead.
• Pages Pages shows a 404. The site is being served from the wrong branch or folder. Point GitHub Pages at the branch and path that hold the built (or source) site.

📋 Quick Reference — Publishing

Item

Detail

MkDocs config

mkdocs.yml (Python, Material theme)

Hugo config

hugo.toml / config (Go)

Jekyll config

_config.yml (Ruby)

React-based docs generator

Page metadata

front matter (--- block)

Output folder

site/ (MkDocs), public/ (Hugo)

Hosting

GitHub Pages, Read the Docs

Mini-Challenge: A Tiny Docs Site

No blanks this time — just a brief and an outline. Use console.log to print the source for a config block (site name + a 3-page nav) and one page (front matter + H1 + a line). Run it, then imagine a generator building it into HTML.

Pro Tips

• 💡 Pick by ecosystem. Python team? MkDocs feels natural. Go or speed-focused? Hugo. Already on GitHub Pages? Jekyll is the path of least resistance.
• 💡 Preview locally. Most generators have a serve command that rebuilds as you edit, so you see changes instantly.
• 💡 Let front matter drive titles. Set the title once in front matter; the template uses it for the page heading and the menu.
• 💡 Automate the deploy. A CI action can build and publish to GitHub Pages on every push, so the live site always matches your Markdown.

Frequently Asked Questions

Q: Do I need to know the generator's programming language?

Not for basic use. You write Markdown and a config file; the language matters mainly when you customise themes or install the tool.

Q: Which generator is best for a documentation site?

MkDocs with the Material theme and Docusaurus are both excellent for docs. Hugo and Jekyll work too; the right choice depends on your stack and theme preference.

Usually a content folder like docs/ (MkDocs) or content/ (Hugo), with the config file at the project root. The generator scans that folder.

Often yes. GitHub Pages and Read the Docs host public static sites at no cost, which is why static generators are so popular for open-source docs.

Lesson Complete! 🎉

• ✅ A static site generator turns Markdown into prebuilt HTML files
• ✅ MkDocs (Python/Material), Hugo (Go), Jekyll (Ruby), and Docusaurus (React) lead the field
• ✅ Each page's front matter and a shared template combine into a consistent page
• ✅ Config files like mkdocs.yml set the theme and navigation
• ✅ GitHub Pages and Read the Docs host the built site, often for free

Where to go next: a published site reaches a wide audience, so make sure everyone can use it. Continue to Writing Accessible Markdown to keep your docs usable by all readers.

Practice quiz

Continue this course

• Previous: Markdown Flavors: GFM vs CommonMark
• Next: Writing Accessible Markdown

Related lessons

• YAML Front Matter