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
- Install MkDocs.
pip install mkdocs
-
Create the folder structure needed by MkDocs. Below is our sample site:
documents -- mkdocs.yml -- docs -- index.md -- faq.md -- images/ -- stylesheets/
Install material theme for mkdocs
pip install mkdocs-material
-
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.
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.
-
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
-
Deploy the cloud formation using aws cli.
aws cloudformation create-stack --template-body file://help-site.yaml --stack-name Help-Site
Verify that the stack creation is successful. We only need to do this step once.
Deploy Site to S3
- In the local directory, run
mkdocs build
. This command will create asite
folder with html files. - 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.
Top comments (0)