loading...

Create a static site with Python, MkDocs, and S3

yloganathan profile image Yuva Updated on ・2 min read

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.

Posted on by:

yloganathan profile

Yuva

@yloganathan

Eternally optimistic learner with some serious FOMO in life

Discussion

markdown guide