Create a static site with Python, MkDocs, and S3

We needed a lightweight solution to provide our beta customers with documentation, upcoming features, and FAQs. We wanted to use markdown for developer happiness and wanted something simple and easy to use. We settled on using Python MkDocs to generate a static site that would be hosted in AWS S3.

We decided to add customer documentation as part of the same git repo as the code and started looking for solutions to create a static site from markdown. I picked MkDocs since it was very light weight and easy to get started on.

Building a static site from markdowns

1. Install MkDocs. pip install mkdocs

2. Create the folder structure needed by MkDocs. Below is our sample site:
   

    documents
        -- mkdocs.yml
        -- docs
          -- index.md
          -- faq.md
          -- images/
          -- stylesheets/
   

3. Install material theme for mkdocs pip install mkdocs-material

4. Setup mkdocs by updating mkdocs.yml
   

   site_name: TrainingPeaks Beta
   site_description: How to documents for Beta users.
   theme:
       name: 'material'
       favicon: 'images/favicon.ico'
       extra_css:
          - 'stylesheets/extra.css'
   

   We added a few minor modifications to the material theme:

   • Set up the favicon.
   • Provide an additional stylesheet that has some minor overrides.

5. Serve site locally mkdocs serve

Deploy MkDocs site to S3

Setup S3

I recommend using cloudformation template to create a public bucket to host the documents. AWS documentation on S3 site templates.

1. Create a yaml file
   

   AWSTemplateFormatVersion: 2010-09-09
   Description: Resources to host documentation.
   
   Parameters:
   SiteName:
       Description: Site name
       Type: String
       Default: tp-beta-learning
   
   Resources:
   S3Bucket:
       Type: AWS::S3::Bucket
       Properties:
           BucketName: !Ref SiteName
           AccessControl: PublicRead
           WebsiteConfiguration:
               IndexDocument: index.html
               ErrorDocument: error.html
   
   BucketPolicy:
       Type: AWS::S3::BucketPolicy
       Properties:
       PolicyDocument:
           Id: MyPolicy
           Version: 2012-10-17
           Statement:
             - Sid: PublicReadForGetBucketObjects
               Effect: Allow
               Principal: '*'
               Action: 's3:GetObject'
               Resource: !Join
               - ''
               - - 'arn:aws:s3:::'
                   - !Ref S3Bucket
                   - /*
       Bucket: !Ref S3Bucket
   
   Outputs:
   WebsiteURL:
       Value: !GetAtt
           - S3Bucket
           - WebsiteURL
       Description: URL for website hosted on S3
   
   

2. Deploy the cloud formation using aws cli.

   aws cloudformation create-stack --template-body file://help-site.yaml --stack-name Help-Site

3. Verify that the stack creation is successful. We only need to do this step once.

Deploy Site to S3

1. In the local directory, run mkdocs build. This command will create a site folder with html files.
2. Deploy site to s3 aws s3 sync ./site s3://tp-beta-learning --recursive

The site is up and running in the url http://<bucket-name>.s3-website-<region>.amazonaws.com.

Next step is to use a custom domain for the site.