Skip to content

Host MkDocs Site using NGINX Server

In this tutorial, we will show you how to take site generated using MkDocs, and host it on your AWS EC2 instance using NGINX server.

Pre-requisites

  1. This tutorial assumes that you have already completed previous tutorial that sets up NGINX webserver
  2. You have built static HTML based documentation using MkDocs.

Build the MkDocs Site

Once you have an MkDocs based site that you have previewed and verified using its built-in dev-server, you are ready to deploy the site. Execute following command in the directory that contains mkdocs.yaml: 

$ ls
docs        mkdocs.yml
$ mkdocs build
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: ~/pulleycloud/site
INFO     -  Documentation built in 0.28 seconds

Notice that the build command generates site directory 

$ ls 
docs        mkdocs.yml  site

This site directory contains HTML pages built by MkDocs based on Markdown content. 

$ ls site 
404.html    assets      index.html  search      sitemap.xml sitemap.xml.gz  topic-1     topic-2
$ ls site/topic-1/ site/topic-1/
site/topic-1/:
index.html

site/topic-1/:
index.html

Also notice contents of site/sitemap.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
         <loc>https://www.put-your-domain-here.com/</loc>
         <lastmod>2022-01-01</lastmod>
         <changefreq>daily</changefreq>
    </url>
    <url>
         <loc>https://www.put-your-domain-here.com/topic-1/</loc>
         <lastmod>2022-01-01</lastmod>
         <changefreq>daily</changefreq>
    </url>
    <url>
         <loc>https://www.put-your-domain-here.com/topic-2/</loc>
         <lastmod>2022-01-01</lastmod>
         <changefreq>daily</changefreq>
    </url>
</urlset>%

This file provides information about pages on our site. Search engines like Google read this file to crawl our website more efficiently. Learn more about sitemaps on Google Search Central if you are curious.

Copy Site to the EC2 instance

We need to copy the generated site to EC2 instance so that NGINX can serve it. Copy it to the instance using scp. Sample command:

scp -i <your ec2 instance pem file path> -r site/ ubuntu@<put-your-domain-here>:~/mkdocs_site

ssh to your EC2 instance:

$ ssh -i <your ec2 instance pem file path> ubuntu@<put-your-domain-here>

On your EC2 instance, copy generated site to /usr/local/share/nginx/ directory:

$ sudo mv ~/mkdocs_site /usr/local/share/nginx/

Update NGINX config to serve MkDocs site

If you followed this tutorial where we setup a hello world NGINX web server, it used /etc/nginx/conf.d/hello_web.conf config file that served static page in /usr/local/share/nginx/html directory. We will update the location stanza as follows:

        location / {
                root /usr/local/share/nginx/mkdocs_site;
                index index.html index.htm;
                try_files $uri $uri/ /index.html;
        }

This serves MkDocs HTML site on your domain.

Start/Restart NGINX

To actually make NGINX use the updated config file, we need to start/restart it.

Command to start NGINX: 

$ sudo nginx -t && sudo nginx

If NGINX is already running, use following command to reload new configs: 

sudo nginx -t && sudo nginx -s reload

And that's how easy it is to set-up a website using MkDocs! Notice how sitemap.xml is accessible via www.put-your-domain-here.com/sitemap.xml. Go ahead and Submit your sitemap to Google so that crawler can index them.

Have any feedback?

If you have any feedback regarding this article or need tutorial on any specific topic, please submit this feedback form.