Hosting Jekyll website on Azure Static WebApps

May 25, 2020 | Utkarsh Shigihalli Utkarsh Shigihalli | 3 min read

Jekyll Azure Azure Static WebApps


Now that Azure now has a free service for hosting static web apps via Azure Static Web Apps, I decided to write a quick post on how to host Jekyll website on Azure Static WebApps. To my surprise it turned out to be quite simple and easy to host.

Jekyll - static site generator

Jekyll is a simple, static site generator.

Installation

Jekyll website has a good post on installation already based on your operating system. You can use WSL (Windows Subsystem for Linux) and it works just fine. If you specifically like to have Windows installation guide, David Burela has posted a neat trick to install it in 3 easy steps here using Chocolatey.

Creating a simple blog

Once you have Jekyll working, you can create a simple blog post by running the following command

jekyll new .

This will create a basic a blog structure which will look like below.

Jekyll folder structure

The _posts folder will contain all your blog posts and each post is a markdown file. Each markdown contains a front matter which allows you to add the meta data for the post.

Now to run your website locally run jekyll serve and you will see the blog up and running in local machine under port 4000 at http://localhost:4000.

Jekyll will build your site using jekyll build and store the generated static content in _site folder. Your site will be served from this _site folder.

Home Page

Source control your website using GitHub

  1. Initialise the repo

    1
    
     git init
    
  2. Commit the changes

    1
    2
    
     git add -A
     git commit -m "initial commit"
    

    I committed mine here. Finally push the changes to the repo.

  3. Next, create a repo on GitHub (if you have not done already) and add the remote to that GitHub repo.

    1
    
     git remote add origin https://github.com/<YOUR_USER_NAME>/jekyll-azure-static
    
  4. Finally, push the repo

    1
    
     git push --set-upstream origin master
    

Deploying the to Azure Static Web App

Create the application

  1. Navigate to the Azure portal
  2. Click Create a Resource
  3. Search for Static Web Apps
  4. Click Static Web Apps (Preview)
  5. Click Create
  6. Fill the details and click Sign in with GitHub button
Create the Static WebApp resource

You will be prompted to authorise the Azure Static WebApp to GitHub. Make sure you Grant access to organisation that has the repo.

Complete the steps in the popup and you will see the below screen where you will select the repository and organisation. My values look as below.

⚠️ If for any reason, you missed granting access to the right organisation, you have to Revoke that Authorisation from GitHub by going to Applications section in the Settings and Revoking for Azure Static Web Apps as shown below

Setting up Build

  1. Next click Next: Build > button to edit the build configuration.
  2. Set the App location to _site since, that is the default folder where Jekyll puts the generated files.
  3. No need to fill the App artifact location and also API location as this is not an API.
Build configuration

Review and create

  1. Click the Review + Create button to verify the details are all correct.

  2. Click Create to start the creation of the Azure Static Web Apps and provision a GitHub Action for deployment.

  1. Once you see the notification that resource deployment is successful, the Azure Static Web App would have created a workflow for GitHub Action on the repository.

  2. Navigate to your terminal and pull the commit with the GitHub Action to your machine.

    1
    
     git pull
    
  3. In the workflow at .github\workflows\<workflow-file-name>.yml, replace the line - uses: actions/[email protected] with the following, to build the Jekyll application.

In the below steps, I am setting up Ruby (needed for installing Jekyll and dependencies), then installing the dependencies (using bundle install) and finally calling jekyll build to generate the static site.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
    - uses: actions/[email protected]
      with:
      submodules: true
        
    - name: Set up Ruby
      # To automatically get bug fixes and new Ruby versions for ruby/setup-ruby,
      # change this to (see https://github.com/ruby/setup-ruby#versioning):
      # uses: ruby/[email protected]
      uses: ruby/[email protected]
      with:
      ruby-version: 2.6

    - name: Install dependencies
      run: bundle install

    - name: Jekyll build
      run: jekyll build

    - name: Build And Deploy
      id: builddeploy
      uses: Azure/[email protected]
      with:
      azure_static_web_apps_api_token: $
      repo_token: $ 
      action: 'upload'
      app_location: '/_site' # App source code path
      api_location: '' # Api source code path - optional
      app_artifact_location: '' # Built app content directory - optional

I had a struggle with this to be honest. Eventually I had to change the app_location path to generated /_site instead of setting it as just _site (see line # 27)

Refer to the complete workflow file in the GitHub User repository

  1. Commit the updated workflow and push to GitHub.

    1
    2
    3
    
     git add -A
     git commit -m "Updating GitHub Actions workflow"
     git push
    
  2. Wait for the GitHub Action to complete.

  3. In the Azure portal’s Overview window of newly created Azure Static Web Apps resource, click the URL link to open your deployed application. You can check the the demo site here

Isn’t it cool! Go check it out.


About author
Utkarsh Shigihalli
Utkarsh Shigihalli
Utkarsh is passionate about software development and has experience in the areas of Azure, Azure DevOps, C# and TypeScript. Over the years he has worked as an architect, independent consultant and manager in many countries including India, United States, Netherlands and United Kingdom. He is a Microsoft MVP and has developed numerous extensions for Visual Studio and Azure DevOps.
Comments