From 571b921cd512f1b365bcefed904811a384f6100f Mon Sep 17 00:00:00 2001 From: barcar Date: Sun, 29 Mar 2026 11:32:43 +0100 Subject: [PATCH 1/3] Added publishing details for Azure Static Web Apps Added publishing details for Azure Static Web Apps --- docs/publish-your-site.md | 51 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/docs/publish-your-site.md b/docs/publish-your-site.md index 2bba7a8..08033d2 100644 --- a/docs/publish-your-site.md +++ b/docs/publish-your-site.md @@ -109,3 +109,54 @@ Your documentation is now published under `.gitlab.io/`. [site_dir]: setup/basics.md#site_dir [default branch]: https://docs.gitlab.com/ee/user/project/repository/branches/default.html +## Azure Static Web App + +You can deploy your Zensical site to [Azure Static Web Apps (SWA)](https://azure.microsoft.com/products/app-service/static) using GitHub Actions (or other methods). Azure SWA supports advanced features such as custom domains and authentication (including Microsoft Entra ID) which are not covered here. + +These are the steps to create an Azure SWA and configure a GitHub hosted site to automatically build and deploy a basic, public site: + +1. In your site repository, disable the default, automatic GitHub Pages workflow in `.github/workflows/docs.yml` - you can do this by deleting the file or changing the trigger to workflow_despatch. + ```yaml + on: + workflow_dispatch: + ``` +2. In the [Azure Portal](https://portal.azure.com/), create a new **Static Web App** resource: + - **Subscription:** Select your Azure subscription + - **Resource Group:** Create or select an existing group + - **Name:** Choose a unique name for your SWA + - **Hosting Plan:** Free or Standard (free is fine for a basic, public site) + - **Source:** GitHub + - Click **Sign in with GitHub** + - Click **Authorize AzureAppService** + - Authenticate with your GitHub account + - **Organization/Repository/Branch:** Select your organization, repository and branch (e.g. `main`) +3. Click **Review + create** and wait for validation +4. Click **Create** to deploy your application, wait for this to complete +5. Click **Go to resource** to open the application +6. Make a note of the default URL `https://UNIQUE_NAME.azurestaticapps.net` +7. Ignore the initial GitHub Action deployment error which is caused by missing settings in the workflow +8. Open your GitHub repository (remember to pull the changes made by the Azure setup) and find the new Azure workflow YAML in `.github/workflows/` - it will be named something like `azure-static-web-apps-UNIQUE_NAME.yml` +9. You need to update this workflow file in two places to correctly build and deploy your Zensical site. Firstly, find the `actions/checkout` step and paste the following steps between it and the following `Azure/static-web-apps-deploy` step: + + ```yaml + - uses: actions/setup-python@v6 + with: + python-version: 3.x + - run: pip install zensical + - run: zensical build --clean + ``` +10. Secondly, in the `Azure/static-web-apps-deploy` step, look for the `app_location` setting and modify it and the surrounding block to look like this: + + ```yaml + app_location: "site" # App source code path + api_location: "" # Api source code path - optional + skip_app_build: true # not required since zensical is already building the app + skip_api_build: true # not required since there is no API + output_location: "" # Built app content directory - optional + ###### End of Repository/Build Configurations ###### + ``` +11. Commit and push your changes, monitor the GitHub Action to make sure the site deploys successfully + +You can now validate your site has been published at `https://UNIQUE_NAME.azurestaticapps.net`. On each subsequent push to the configured branch, GitHub Actions will rebuild your site and deploy it to Azure SWA. + +For more details, see [Azure Static Web Apps documentation](https://learn.microsoft.com/azure/static-web-apps/overview). \ No newline at end of file From ffb8a4a374b218b6fd8299684c000cf7e60018e9 Mon Sep 17 00:00:00 2001 From: barcar Date: Sun, 29 Mar 2026 15:53:56 +0100 Subject: [PATCH 2/3] docs: link to community Azure SWA guides in publish-your-site Replace the inline Azure Static Web Apps walkthrough with a concise "Other" section pointing to external Zensical guides for GitHub and Azure DevOps deployments. Made-with: Cursor --- docs/publish-your-site.md | 62 ++++++--------------------------------- 1 file changed, 9 insertions(+), 53 deletions(-) diff --git a/docs/publish-your-site.md b/docs/publish-your-site.md index 08033d2..d0f552a 100644 --- a/docs/publish-your-site.md +++ b/docs/publish-your-site.md @@ -104,59 +104,15 @@ the workflow in action. Your documentation is now published under `.gitlab.io/`. +## Other + +We cannot document every hosting provider here. The following community guides +describe how to deploy a Zensical site elsewhere: + +* [Azure Static Web Apps with GitHub](https://zensical-guides.hypercat.net/azure-static-web-app-github/) +* [Azure Static Web Apps with Azure DevOps](https://zensical-guides.hypercat.net/azure-static-web-app-devops/) + [GitLab Pages]: https://gitlab.com/pages [GitLab CI]: https://docs.gitlab.com/ee/ci/ [site_dir]: setup/basics.md#site_dir - [default branch]: https://docs.gitlab.com/ee/user/project/repository/branches/default.html - -## Azure Static Web App - -You can deploy your Zensical site to [Azure Static Web Apps (SWA)](https://azure.microsoft.com/products/app-service/static) using GitHub Actions (or other methods). Azure SWA supports advanced features such as custom domains and authentication (including Microsoft Entra ID) which are not covered here. - -These are the steps to create an Azure SWA and configure a GitHub hosted site to automatically build and deploy a basic, public site: - -1. In your site repository, disable the default, automatic GitHub Pages workflow in `.github/workflows/docs.yml` - you can do this by deleting the file or changing the trigger to workflow_despatch. - ```yaml - on: - workflow_dispatch: - ``` -2. In the [Azure Portal](https://portal.azure.com/), create a new **Static Web App** resource: - - **Subscription:** Select your Azure subscription - - **Resource Group:** Create or select an existing group - - **Name:** Choose a unique name for your SWA - - **Hosting Plan:** Free or Standard (free is fine for a basic, public site) - - **Source:** GitHub - - Click **Sign in with GitHub** - - Click **Authorize AzureAppService** - - Authenticate with your GitHub account - - **Organization/Repository/Branch:** Select your organization, repository and branch (e.g. `main`) -3. Click **Review + create** and wait for validation -4. Click **Create** to deploy your application, wait for this to complete -5. Click **Go to resource** to open the application -6. Make a note of the default URL `https://UNIQUE_NAME.azurestaticapps.net` -7. Ignore the initial GitHub Action deployment error which is caused by missing settings in the workflow -8. Open your GitHub repository (remember to pull the changes made by the Azure setup) and find the new Azure workflow YAML in `.github/workflows/` - it will be named something like `azure-static-web-apps-UNIQUE_NAME.yml` -9. You need to update this workflow file in two places to correctly build and deploy your Zensical site. Firstly, find the `actions/checkout` step and paste the following steps between it and the following `Azure/static-web-apps-deploy` step: - - ```yaml - - uses: actions/setup-python@v6 - with: - python-version: 3.x - - run: pip install zensical - - run: zensical build --clean - ``` -10. Secondly, in the `Azure/static-web-apps-deploy` step, look for the `app_location` setting and modify it and the surrounding block to look like this: - - ```yaml - app_location: "site" # App source code path - api_location: "" # Api source code path - optional - skip_app_build: true # not required since zensical is already building the app - skip_api_build: true # not required since there is no API - output_location: "" # Built app content directory - optional - ###### End of Repository/Build Configurations ###### - ``` -11. Commit and push your changes, monitor the GitHub Action to make sure the site deploys successfully - -You can now validate your site has been published at `https://UNIQUE_NAME.azurestaticapps.net`. On each subsequent push to the configured branch, GitHub Actions will rebuild your site and deploy it to Azure SWA. - -For more details, see [Azure Static Web Apps documentation](https://learn.microsoft.com/azure/static-web-apps/overview). \ No newline at end of file + [default branch]: https://docs.gitlab.com/ee/user/project/repository/branches/default.html \ No newline at end of file From 1dbaf8f9666b72a4c0f32e57d3be333b79022e5b Mon Sep 17 00:00:00 2001 From: barcar Date: Sun, 29 Mar 2026 19:12:52 +0100 Subject: [PATCH 3/3] Fix formatting and remove duplicate links in documentation Signed-off-by: barcar --- docs/publish-your-site.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/publish-your-site.md b/docs/publish-your-site.md index d0f552a..e45b275 100644 --- a/docs/publish-your-site.md +++ b/docs/publish-your-site.md @@ -104,6 +104,11 @@ the workflow in action. Your documentation is now published under `.gitlab.io/`. + [GitLab Pages]: https://gitlab.com/pages + [GitLab CI]: https://docs.gitlab.com/ee/ci/ + [site_dir]: setup/basics.md#site_dir + [default branch]: https://docs.gitlab.com/ee/user/project/repository/branches/default.html + ## Other We cannot document every hosting provider here. The following community guides @@ -111,8 +116,3 @@ describe how to deploy a Zensical site elsewhere: * [Azure Static Web Apps with GitHub](https://zensical-guides.hypercat.net/azure-static-web-app-github/) * [Azure Static Web Apps with Azure DevOps](https://zensical-guides.hypercat.net/azure-static-web-app-devops/) - - [GitLab Pages]: https://gitlab.com/pages - [GitLab CI]: https://docs.gitlab.com/ee/ci/ - [site_dir]: setup/basics.md#site_dir - [default branch]: https://docs.gitlab.com/ee/user/project/repository/branches/default.html \ No newline at end of file