Skip to content

Release a static site with 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.

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:

  5. Set up the favicon.

  6. Provide an additional stylesheet that has some minor overrides.
  7. Serve site locally to test using mkdocs serve

Deploy MkDocs site to S3

Setup S3

I recommend using cloud formation 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.

Deploy Site to S3 using GitHub action

Create mkdocs2S3.yml To use this action within your own repository, place the following example in your .github/workflows directory. 

name: DeployToS3

on:
  push:
    branches:
    - master

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - uses: thomasattree/mkdocs2S3@master
      with:
        args: --acl public-read --follow-symlinks --delete
      env:
        AWS_S3_BUCKET: ${{ secrets.AWS_S3_BUCKET }}
        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        AWS_REGION: 'eu-west-1'   # optional: defaults to us-east-1
        SOURCE_DIR: 'site'      # optional: defaults to entire repository
The s3 command uses the raw AWS CLI so any args supported within the CLI can be passed through in the with statement above. If you are going to use the above example verbatim, be warned --delete permanently deletes files in the S3 bucket that are not present in the latest version of your build. The above example will build and deploy your site on any push to master. This means your public site in S3 should always be up to date with your Github repository mkdocs docs directory.

Environment variables

The action requires at least AWS_S3_BUCKET, AWS_ACCESS_KEY_ID & AWS_SECRET_ACCESS_KEY. Store these as Github secrets and not statically typed in your configuration.

Key
 Value Required Default
AWS_S3_BUCKET Name of your S3 bucket eg.my-bucket Yes N/A
AWS_ACCESS_KEY_ID Your AWS IAM access key. Store this as a Github secret Yes N/A
AWS_SECRET_ACCESS_KEY Your AWS IAM secret key. Store this as a Github secret Yes N/A
AWS_REGION The region of your S3 bucket eg. us-west-2 No eu-west-1
SOURCE_DIR The name of the directory you want to sync with S3. Mkdocs by default builds site files in a directory named site No .

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

Comments