Enhancement/deploy to s3 - Add deployment to S3

* Create deployment stack file for cloudformation

* Add deployment script

* Add custom 404 page

* Install couscous manually in deploy workflow

* Add missing sudo statement to chmod command

* Add project board workflow (#649)

* Add i18n Support (#650)

* Add i18n support

* Update requirements.txt to include i18n package

* Update Readme to include explanation for contributing

* Update styling and include mistakes section

* Apply suggestions from code review

* Update per PR changes

Co-authored-by: Tim Condon <0xTim@users.noreply.github.com>

* Remove plugin for now

* Reenable plugin

* Plugin broke search

* Update mkdocs material requirement to be version 7.1 or higher

* remove google analytics. Use highlight for code blocks. Include search in plugins

* Add css file for code block customisation possiblities

Co-authored-by: Tim Condon <0xTim@users.noreply.github.com>

.github/workflows/deploy.yml

@@ -1,17 +1,62 @@
-name: deploy
+name: Build and deploy the Vapor documentation
 on:
   push:
     branches:
       - main
 jobs:
- deploy:
+  deploy:
-   name: docs.vapor.codes
+    name: Build and deploy
-   runs-on: ubuntu-latest
+    runs-on: ubuntu-latest
-   steps:
+    steps:
-     - name: Deploy docs
+    - name: Checkout repository 
-       uses: appleboy/ssh-action@master
+      uses: actions/checkout@v3
-       with:
+    - name: Install dependencies
-         host: vapor.codes
+      run: |
-         username: vapor
+        composer global require couscous/couscous
-         key: ${{ secrets.VAPOR_CODES_SSH_KEY }}
+        pip install -r requirements.txt
-         script: ./github-actions/deploy-docs.sh
+
+        curl -OSL https://couscous.io/couscous.phar
+        sudo chmod +x couscous.phar 
+        sudo mv couscous.phar /usr/local/bin/couscous
+    - name: Build the website
+      run: |
+        bash ./build.sh
+    - name: Configure AWS credentials
+      id: cred
+      uses: aws-actions/configure-aws-credentials@v1
+      with:
+        aws-access-key-id: ${{ secrets.DOCS_DEPLOYER_AWS_ACCESS_KEY_ID }}
+        aws-secret-access-key: ${{ secrets.DOCS_DEPLOYER_AWS_SECRET_ACCESS_KEY }}
+        aws-region: 'eu-west-2'
+    - name: Deploy to AWS Cloudformation
+      id: clouddeploy
+      if: steps.cred.outcome == 'success'
+      uses: aws-actions/aws-cloudformation-github-deploy@v1.0.3
+      with:
+        name: vapor-docs-stack
+        template: stack.yml
+        no-fail-on-empty-changeset: "1"
+        parameter-overrides: >-
+          DomainName=docs.vapor.codes,
+          S3BucketName=vapor-docs-site,
+          AcmCertificateArn=${{ secrets.CERTIFICATE_ARN }}
+    - name: Deploy to S3 
+      id: s3deploy
+      if: steps.clouddeploy.outcome == 'success'
+      uses: jakejarvis/s3-sync-action@master
+      with:
+        args: --acl public-read --follow-symlinks --delete
+      env:
+        AWS_S3_BUCKET: 'vapor-docs-site'
+        AWS_ACCESS_KEY_ID: ${{ secrets.DOCS_DEPLOYER_AWS_ACCESS_KEY_ID }}
+        AWS_SECRET_ACCESS_KEY: ${{ secrets.DOCS_DEPLOYER_AWS_SECRET_ACCESS_KEY }}
+        AWS_REGION: 'eu-west-2'
+        SOURCE_DIR: 'site'
+    - name: Invalidate CloudFront 
+      uses: awact/cloudfront-action@master 
+      env:
+        SOURCE_PATH: '/*'
+        AWS_REGION: 'eu-west-2'
+        AWS_ACCESS_KEY_ID: ${{ secrets.DOCS_DEPLOYER_AWS_ACCESS_KEY_ID }}
+        AWS_SECRET_ACCESS_KEY: ${{ secrets.DOCS_DEPLOYER_AWS_SECRET_ACCESS_KEY }}
+        DISTRIBUTION_ID: ${{ secrets.DOCS_DISTRIBUTION_ID }}

4.0/docs/stylesheets/extra.css

@@ -0,0 +1,20 @@
+/*
+:root > * {
+    --md-code-hl-number-color: #FF0000;
+    --md-code-hl-special-color: #FF0000;
+    --md-code-hl-function-color: #FF0000;
+    --md-code-hl-constant-color: #FF0000;
+    --md-code-hl-keyword-color: #FF0000;
+    --md-code-hl-string-color: #FF0000;
+    --md-code-hl-name-color: #FF0000;
+    --md-code-hl-operator-color: #FF0000;
+    --md-code-hl-punctuation-color: #FF0000;
+    --md-code-hl-comment-color: #FF0000;
+    --md-code-hl-generic-color: #FF0000;
+    --md-code-hl-variable-color: #FF0000;
+
+    --md-code-fg-color: #FF0000;
+    --md-code-bg-color: #FF0000;
+    --md-code-hl-color: #FF0000;
+}
+*/

4.0/mkdocs.yml

@@ -43,46 +43,49 @@ extra:
     - icon: fontawesome/brands/github
       link: https://github.com/vapor
 
-# Google Analytics
+# Custom code highlighting syntax (uncomment if you want to use this. css is in `docs/stylesheets/extra.css`)
-google_analytics:
+# extra_css:
-  - UA-76177358-4
+#   - stylesheets/extra.css
-  - auto
 
 # Extensions
 markdown_extensions:
   - admonition
-  - codehilite:
+  - pymdownx.highlight:
-      guess_lang: false
+      use_pygments: false
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences
   - footnotes
   - meta
   - toc:
       permalink: true
 
-# # Plugins
+# Plugins
-# plugins:
+plugins:
-#   # i18n plugin documentation
+  - search
-#   # https://github.com/ultrabug/mkdocs-static-i18n
+  # i18n plugin documentation
-#   - i18n:
+  # https://github.com/ultrabug/mkdocs-static-i18n
-#       default_language: 'en'
+  - i18n:
-#       # Add the new languages here. DON'T CHANGE THE DEFAULT LANGUAGE
+      default_language: 'en'
-#       languages:
+      # Add the new languages here. DON'T CHANGE THE DEFAULT LANGUAGE
-#         en: 
+      languages:
-#           name: English
+        en: 
-#           build: true
+          name: English
-#         nl: 
+          build: true
-#           name: Nederlands
+        nl: 
-#           site_name: Vapor Documentatie
+          name: Nederlands
-#           build: true
+          site_name: Vapor Documentatie
-#         fr:
+          build: true
-#           name: Français
+        fr:
-#           site_name: Documentation Vapor
+          name: Français
-#           build: true
+          site_name: Documentation Vapor
-#       # Add navigation translations here
+          build: true
-#       nav_translations:
+      # Add navigation translations here
-#         nl:
+      nav_translations:
-#           Welcome: Welkom
+        nl:
-#         fr: 
+          Welcome: Welkom
-#           Welcome: Bienvenue
+        fr: 
+          Welcome: Bienvenue
 
 
 nav:

requirements.txt

@@ -20,7 +20,7 @@
 
 # Direct dependencies
 mkdocs>=1
-mkdocs-material>=3
+mkdocs-material>=7.1.0
 Pygments>=2.2
 pymdown-extensions>=4.11
 mkdocs-static-i18n>=0.45

stack.yml

@@ -0,0 +1,72 @@
+AWSTemplateFormatVersion: '2010-09-09'
+Description: 'The documentation for Vapor'
+Parameters:
+  DomainName:
+    Type: String 
+    Description: The domain name for the site 
+    AllowedPattern: (?!-)[a-zA-Z0-9-.]{1,63}(?<!-)
+    ConstraintDescription: Must be a valid DNS zone name.
+  AcmCertificateArn:
+    Type: String
+    Description: the Amazon Resource Name (ARN) of an AWS Certificate Manager (ACM) certificate.
+    AllowedPattern: "arn:aws:acm:.*"
+  S3BucketName:
+    Type: String
+    Description: Name for the bucket 
+Resources:
+  S3BucketForWebsiteContent:
+    Type: AWS::S3::Bucket
+    Properties:
+      BucketName: !Ref 'S3BucketName'
+      WebsiteConfiguration:
+        IndexDocument: index.html
+        # Redirect
+        ErrorDocument: /4.0/404.html
+        RoutingRules:
+          - RoutingRuleCondition:
+              HttpErrorCodeReturnedEquals: '404'
+              KeyPrefixEquals: /
+            RedirectRule:
+              HostName: !Ref 'DomainName'
+              ReplaceKeyPrefixWith: 4.0/
+  WebsiteCloudfront:
+    Type: AWS::CloudFront::Distribution
+    Properties: 
+      DistributionConfig:
+        Comment: Cloudfront Distribution pointing to S3 bucket
+        Origins:
+        - DomainName: !Join [ '', !Split [ 'http://', !GetAtt 'S3BucketForWebsiteContent.WebsiteURL' ] ]
+          Id: S3Origin
+          CustomOriginConfig:
+            OriginProtocolPolicy: 'http-only'
+        Enabled: true 
+        HttpVersion: 'http2'
+        Aliases:
+        - !Ref 'DomainName'
+        CustomErrorResponses:
+          - ErrorCode: 403
+            ResponseCode: 404
+            ResponsePagePath: /4.0/404.html
+        DefaultCacheBehavior:
+          AllowedMethods:
+          - GET 
+          - HEAD 
+          - OPTIONS
+          Compress: true 
+          TargetOriginId: S3Origin
+          ForwardedValues:
+            QueryString: false 
+            Cookies:
+              Forward: none
+          ViewerProtocolPolicy: redirect-to-https
+        PriceClass: PriceClass_All
+        ViewerCertificate:
+          AcmCertificateArn: !Ref 'AcmCertificateArn'
+          SslSupportMethod: sni-only
+Outputs:
+  CloudfrontURL:
+    Description: 'Cloudfront URL'
+    Value: !GetAtt WebsiteCloudfront.DomainName
+  BucketName:
+    Description: 'Name of S3 bucket to hold website content'
+    Value: !Ref 'S3BucketForWebsiteContent'