Create a static site with Python, MkDocs, and S3
Tags: aws, mkdocs, tutorial, showdev
Published: 2019-05-12 18:32:03

---
title: Create a static site with Python, MkDocs, and S3
published: true
description: Create a static site with MkDocs and S3
tags: aws, mkdocs, tutorial, showdev
---

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](https://www.mkdocs.org/) 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](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/quickref-s3.html) 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.