How to Publish a Jekyll App to Azure Static Web Apps

Last Updated: March 22, 2024

Introduction –

This is a step-by-step guide on installing, setting up, and deploying Jekyll on Azure Static Web Apps using a Github repository and GitHub actions.

Installing Jekyll dependencies

The Jekyll website recommends using the RubyInstaller + DevKit to install the dependencies required by Jekyll. You can find a full list of the RubyInstaller versions from the following website: https://rubyinstaller.org/downloads

Let’s use PowerShell to download and install the RubyInstaller + DevKit. Open PowerShell as Administrator and run the following commands, replacing the .exe names with the newest versions:

Invoke-WebRequest -Uri https://github.com/oneclick/rubyinstaller2/releases/download/RubyInstaller-3.1.2-1/rubyinstaller-devkit-3.1.2-1-x64.exe -OutFile (New-Item -Path "C:\Temp\rubyinstaller-devkit-3.1.2-1-x64.exe" -Force)

C:\temp\rubyinstaller-devkit-3.1.2-1-x64.exe

This will download the .exe and start the installer.

Note: You can also just go to https://rubyinstaller.org/downloads in your web browswer and manually download the file.

1. Accept the license agreement and click Next.
2. Use the default installation folder, and confirm that Add Ruby executables to your PATH and Associate .rb and .rbw files with this Ruby installation are selected. Click Install.
3. Ensure that the MSYS2 development toolchain component is selected and click Next to begin the installation.
4. Once the installation is compelte, confirm that Run ‘ridk install to set up MSYS2 and development toolchain is selected. This is needed for isntalling gems with native extensions. Click Finish.
5. A new command prompt window will appear. Press Enter to use the default options, which will install both the MSYS2 base installation, as well as the MSYS2 and MINGW development toolchain.

Now that Ruby and the other dependencies are installed, we can install Jeckyl. Open a new PowerShell window and run the following commands to install Jekyll and verify that it has been installed properly:

gem install jekyll bundler
jekyll -v

The Output should look something like this, depending on the version number:

jekyll 4.2.2

Create a Jekyll Website using the Jekyll CLI and Git bash

Create a new Jekyll app and initialize a new Git repository, with the following commands:

jekyll new static-app
cd static-app
git init
git add -A
git commit -m "initial commit"

Create GitHub repository for Jekyll

Go to https://github.com/new and create a new GitHub repo. Don’t create a README. Open PowerShellor Git Bash and run the following commands to add the remote repo path and push your local files to it. Managing your project with git and GitHub can significantly enhance your workflow.

git remote add origin https://github.com/<YOUR_USER_NAME>/<YOUR_STATIC_APP_REPO>
git branch -M main
git push -u origin main

Alt Solution: Create a Repository Based on Chirpy Theme

Instead of manually creating a new Jekyll app, we can use the Chirpy Starter repository to create Jekyll with a custom theme. Head over to https://github.com/cotes2020/jekyll-theme-chirpy and click on Chirpy Starter found in Step 1 in the Quick Start guide.

Give the new repository a name and description and make sure to set the repo to Private.

Click Create repository from template to create the repository.

Now that we have create a new repository, we need to clone it to our local machine. Open PowerShell or Git CLI and navigate to the directory where the repo should be stored.

git clone https://github.com/<YOUR_USER_NAME>/<YOUR_STATIC_APP_REPO>.git

Once the repository has been cloned to the local machine, we need to install dependencies and run a local Jekyll server. Navigate to the repository directory and run the following commands in PowerShell:

bundle
bundle exec jekyll s

Open a web browser and navigate to localhost:4000 to view the Jekyll app.

Tip: Check out the Chirpy wiki for useful documentation: https://github.com/cotes2020/jekyll-theme-chirpy/wiki

Deploy Jekyll App to Azure Static Web Apps (Azure CLI)

Head over to portal.azure.com and open the Azure CLI. Create a new resource group if you don’t already have one.

az group create --name rg-jekyll-static-web-app-dev-001 --location "westus2"

Now we will create a the static web app, and deploy the Jekyll app from the repository that was created earlier. Make sure to replace the -source argument with the URL of your Jekyll repository on GitHub. In this example we will create an Azure Static Web App named app-jekyll-dev-001 in the rg-jekyll-static-web-app-dev-001 Resource Group.

az staticwebapp create \
--name app-jekyll-dev-001 \
--resource-group rg-jekyll-static-web-app-dev-001 \
--source https://github.com/<YOUR_USER_NAME>/<YOUR_STATIC_APP_REPO> \
--location "westus2" --branch main --app-location "./" \
--output-location "_site" \
--login-with-github

The Azure CLI will prompt you to enter a code to activate your GitHub user account.

Please navigate to https://github.com/login/device and enter the user code ####-#### to activate and retrieve your github personal access token
Waiting up to '14' minutes for activation

Follow the URL and enter the code provided, then click Authorize AzureAppServiceCLI.

Close the GitHub activation window in your browser, and return to the azure portal.

CI/CD workflow using GitHub Actions

By specifying the GitHub remote repository during the creation of the Azure Static Web App, Azure will automatically create an Azure Static Web Apps CI/CD (Continous Integration / Continuous Development) workflow in GitHub.

Navigate to your Jekyll reposiroty in GitHub, and select Actions on the repository menu.

Here you can view the results of the workflow / GitHub Action that was automatically created with the Azure Static Web App.

Whenever you push changes from your local repository to the remote repository, the GitHub Actions workflow will automatically integrate and publish any changes to the live Azure Static App.

View the live Jekyll Static Web App

Open the Azure portal and locate the newly created Static Web App from the Resource Group that is was placed in.

To view the live Jekyll app online, click on the link in the URL entry in the Static Web App Overview.

Creating a new post in Jekyll

Open your the local Jekyll repository directory in VSCode and create a new post under the _posts directory. Jekyll requires that the file name of each post is prefixed in the following date format:

YEAR-MONTH-DAT-title.md

Example:
2022-01-09-my-new-post.md

Make sure that the new post uses the .md (markdown) file extension.

Each Jekyll post needs to start with a header section to populate metadata for the post. After creating the new post, make sure to add the headerto the top of the markdown file.

---
layout: post
title: My First Post
date: 2022-10-02 11:05:00
categories: [azure]
tags: [azure,static-web-app,jekyll]     # TAG names should always be lower case, and comma-separated values.
---

Enter some content in the new post using Markdown.

Finally, add and commit the changes using git, and push them to the remote repository. The GitHub Actions workflow will automatically integrate and publish to Azure.

Note: You may need to fetch and merge changes from the remote repository before you can use git push.

git fetch origin main
git merge origin main
git add *
git status
git commit -m "initial commit from jekyll".
git push

Map a custom domain to an Azure Static Web App

Open the Jekyll app in the Azure portal, and click on Custom domains on the left-hand menu. Click + Add and select the custom domain type. Select Custom domain on Azure DNS if you are using Azure CDN, or Custom domain on other DNS if you are using an external DNS provider like Namecheap.

Select the second option, since we are using an external CDN (Cloudflare) for this tutorial.

Microsoft recommends creating the domain name with the www subdomain first, then adding the apex domain later.

Enter your domain name with the www prefix in the Domain name field, then click Next. Keep the default settings (CNAME) in the Validate + add tab then copy and paste the CNAME value provided into a new CNAME record on your external CDN site.

CNAME www <YOUR_UNIQUE_URL>.azurestaticapps.net

Note: It can take up to 48 hours for DNS changes to take effect.

Once the domain name has been validated, we can set up the apex domain, so that end-users can go directly to the app in a web browser, without needing to type www. before the domain name.

To add an Apex domain, click on the + Add button, and again select Custom domain on other DNS. Enter the root domain name (without www.) and click Next.

Click Generate code and wait for Azure to generate a custom TXT record value. You may need to refresh the page after a few minutes, but eventually you will be notified to enter a CNAME record with your DNS provider like Namecheap.

CNAME <your-root-domain> <YOUR_UNIQUE_URL>.azurestaticapps.net

Featured Tweet

Learn how to setup a CI/CD Jekyll static website on Azure Static Web Apps (free hosting) with GitHub actions. https://t.co/JKyuffja8X#sysadmin #homelab #azure #staticwebapp #staticwebsite #jekyll #git #GitHub

— rcdevops (@rcdevops) March 22, 2024