After receiving some questions about how this blog was implemented, I created this tutorial on how to create your own blog.
This blog is hosted on Azure Static Web Apps, and it uses the framework Hugo for site generation. I use Visual Studio Code to edit the content and GitHub for source control. For Continuous Integration and Continuous Delivery (CI/CD) the site use GitHub Actions
1. About Azure Static Web Apps
First, what is Azure Static Web Apps?
Let’s ask Microsoft Copilot:
Azure Static Web Apps is a service provided by Microsoft Azure that automates the process of building and deploying full-stack web applications directly from a code repository. It’s designed to streamline a developer’s workflow by automatically building and deploying applications based on code changes. Here are some key features of Azure Static Web Apps:
- Web hosting for static content like HTML, CSS, JavaScript, and images.
- Integrated API support provided by managed Azure Functions, with options to link existing functions or other services.
- First-class GitHub and Azure DevOps integration for continuous integration and deployment (CI/CD) workflows.
- Globally distributed static content, which reduces latency by serving files closer to users.
- Free SSL certificates that are automatically renewed.
- Custom domains, allowing for branded customizations to your app.
- Seamless security model with a reverse-proxy for API calls, eliminating the need for CORS configuration.
- Authentication provider integrations with services like Microsoft Entra ID and GitHub.
- Customizable authorization roles for defining and assigning permissions.
- Back-end routing rules for full control over content and routes.
- Generated staging versions powered by pull requests for previewing site changes before publishing.
- CLI support through the Azure CLI for creating cloud resources and local development.
Azure Static Web Apps supports a variety of web frameworks and libraries such as Angular, React, Svelte, Vue, or Blazor for WebAssembly applications, and it’s particularly well-suited for apps where server-side rendering isn’t required.
Source: Conversation with Copilot, 16. June 2024
2. About Hugo
Hugo is an open source static site generator. It use markdown from content files, runs the markdown through template files, and then generates the HTML files that is used for the blog/website. After the site is deployed to your host, the HTML content is ready for your site visitors when visiting the site. Thereby a static site.
To learn more about Hugo you can read more in the Hugo Documentation
3. How to create a Hugo site on your local machine
For this example I use the Hugo quickstart guide, that you will also find on the Hugo website. I use VS Code as code editor. Along with VS Code you also need Git installed on your machine.
First install Hugo on your machine from this link
In VS Code open a terminal and create a new folder for your site.
Run this command to create a new Hugo site (if Hugo was installed correctly you should get the same output when it competes):
PS C:\src\tutorial> hugo new site quickstart
Congratulations! Your new Hugo site was created in C:\src\tutorial\quickstart.
Change directory:
cd quickstart
Initialize a new Git repository in the quickstart directory:
git init
Add a theme for the Hugo site. This example uses the Ananke theme. You can find several other themes here (and you can also create your own theme). The theme is added as a Git submodule.
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
Open and edit the hugo.toml file. Append this line in the file to configure Ananke as the site theme: theme = “ananke”
baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'
theme = "ananke"
To add the first page to your site - run this command:
hugo new content posts/my-first-post.md
Locate the new file that was added in posts/my-first-post.md to edit it. The content will look like this:
+++
title = 'My First Post'
date = 2024-06-16T07:07:07+01:00
draft = true
+++
Edit the file, add some text and set draft = false.
+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
draft = false
+++
## Introduction
This is **bold** text, and this is *emphasized* text.
Visit the [Hugo](https://gohugo.io) website!
Save the file and start Hugo’s local server by running this command in the terminal:
hugo server
The Hugo development server will start, and the terminal will output the address for your local webserver. Example output:
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
You can now preview your new Hugo site by opening the web server address in your browser.
Publish the site:
Running this command in the terminal will create a new folder named public. The public folder contains the static version of your site with CSS, javascripts and images:
hugo
You will find more information on how to configure the site, how to use markdown, and more, in the Hugo Getting Started documentation
When you are done building the site, create a new GitHub repository and push the Hugo directory to the repo.
The next step will describe how to host your new site with Azure Static Web Apps.
4. How to create a new Azure Static Web App for the Hugo site
This section assumes that you have an active Azure subscription. If you don’t have a subscription, you can create a free Azure account to start building your own projects in the cloud. This includes free Azure Static Web Apps, with 100 GB bandwidth per subscription, 2 custom domains and .5 GB storage per app.
4.1 Create a new Azure Static Web App Resource
Select your subscription, use an existing resource group, or create a new one. Enter a name for the Static Web App. As for the hosting plan, select “Free” for when testing this example. Click Review+Create.
In Deployment details select GitHub as the source. For organization select your GitHub account. Select the repository and branch that you pushed the site into.
In Build Details, select Hugo for Build Presets. You can leave the defaut values in App location, Api location and Outout location.
Click the Preview workflow file to take a look at the GitHub action file that will be generated. The generated file will be uploaded to the Hugo repository. The generated workflow will look like this:
name: Azure Static Web Apps CI/CD
on:
push:
branches:
- master
pull_request:
types: [opened, synchronize, reopened, closed]
branches:
- master
jobs:
build_and_deploy_job:
if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
runs-on: ubuntu-latest
name: Build and Deploy Job
steps:
- uses: actions/checkout@v3
with:
submodules: true
lfs: false
- name: Build And Deploy
id: builddeploy
uses: Azure/static-web-apps-deploy@v1
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_<GENERATED_HOSTNAME> }}
repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for Github integrations (i.e. PR comments)
action: "upload"
###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
# For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
app_location: "/" # App source code path
api_location: "" # Api source code path - optional
output_location: "public" # Built app content directory - optional
###### End of Repository/Build Configurations ######
close_pull_request_job:
if: github.event_name == 'pull_request' && github.event.action == 'closed'
runs-on: ubuntu-latest
name: Close Pull Request Job
steps:
- name: Close Pull Request
id: closepullrequest
uses: Azure/static-web-apps-deploy@v1
with:
azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_<GENERATED_HOSTNAME> }}
action: "close"
Click review and create, and the Create to create the Static Web App. During the deployment a new GitHub action will be added to your repository.
When the deployment is complete go to the new created resource. You will be provided with the an URL for the website. Before opening the website URL, log in to GitHub and open the Actions tab in the repository for your Hugo site.
Under workflows, you should find a commit named ci: add Azure Static Web Apps workflow file.
Click on the workflow to see more details about the job that was run. Status should be Success, and the Build and Deploy job should be green.
You should now be able to open the URL for your Hugo site (found in the details for the Static Web App).
When you push new changes to repository and branch configured for the static web app, the changes will be published to your site.
Congratulations - you have created a new Hugo blog hosted on Azure Static Web Apps!
You can keep using the random hostname that Azure created for you, or you could register a custom domain for your blog/site.
To configure a custom domain - go to the Add a custom domain section in your Static Web App and follow the instructions.
5. Summary
Here’s a summary of the current page created by Microsoft Copilot:
-
Azure Static Web Apps: The blog details how Azure Static Web Apps automate the build and deployment of web applications from a code repository, highlighting features like global distribution, free SSL certificates, and GitHub integration.
-
Hugo Framework: It explains Hugo as an open-source static site generator that uses markdown for content files and templates to generate HTML for websites.
-
Creating a Hugo Site: The post provides a step-by-step guide on setting up a Hugo site locally, including installation, adding a theme, and creating content.
-
Hosting on Azure: Instructions are given on how to host the Hugo site using Azure Static Web Apps, including setting up a new resource, deployment details, and custom domain configuration