Get started with MkDocs and Markdown

The static site generator (SSG) I'm using is MkDocs. I'll be using the command line to install MkDocs, create a MkDocs project, and preview the documentation.

Install dependencies & create a new project

In order to install MkDocs, you may need to install python and pip. You can follow MkDocs' installation instructions.

If you aren't confident in the command line, I've also recorded a short video in which I walk through some the installation.

Add content

When you create a new project, MkDocs generates a folder and some files.

lavadocs
│  
└───mkdocs.yml
│  
└───docs
    │   index.md

The .yml file allows you to configure your site, e.g. set the theme, define the navigation, activate extensions.

You'll store your site content in the "docs" folder. By default, index.md will be your homepage.

Let's say you want three more pages: About, Resume, and Contact. You would put three additional markdown pages in your "docs" folder.

lavadocs
│  
└───mkdocs.yml
│  
└───docs
    │   index.md
    │   about.md
    │   resume.md
    │   contact.md

Some themes allow multiple levels or navigation, and each theme comes with CSS that determines how the various markdown elements look and behave.

Configure your navigation

Most themes will automatically incorporate your markdown pages into the resulting site, but you can also control the navigation by modifying mkdocs.yml. In the example below, I've created four nav items: Home, About, Resume, and Contact.

site_name: My Docs

nav:
  - Home: index.md
  - About: about.md
  - Resume: resume.md
  - Contact: contact.md

theme: readthedocs

Mkdocs comes with two themes. Above you see I've opted for the Read the Docs theme.

Explore!

Preview, build, and theme your site with help from MkDocs' Getting Started documentation.

---

Last update: 2020-11-16