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.

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.

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.

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.

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.

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.

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.

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

• Browse all free courses
• Cheat sheets & quizzes
• Coding dictionary