Custom 404 error page, Publii and Azure Static Web Apps

404 error pages are important to a website in providing a page to visitors when something has gone wrong such as mistyped links or changes to a URL.   As of July 2017, Publii generates a file called 404.html and is supported by all their themes and can be added to any custom themes. 

Microsoft allows the configuration of Azure Static Web Apps by configuring a file called staticwebapp.config.json and among the settings that this controls is called HTTP response overrides.  This file location needs to be in the folder set as the app_location in the GitHub workflow file, but this is most commonly just the root of your website.

Assuming you have not used this file to configure anything before, open your site in Publii, click on the Tools option on the left and select File Manager. Make sure the root directory is selected and click on the Add new file button. You will be prompted to enter a filename which you should enter staticwebapp.config.json. Publii will create the file but it will have no content. Click on the file in Publii and it will open in a text editor. Add the following HTTP response override configuration and save your file.

{
  "responseOverrides": {
    "404": {
      "rewrite": "/404.html"
    }
  }
}

The file is saved into a folder within your source "input" website files and will be synced with GitHub / Azure Static Web Apps the next time you Sync your Website. Give it a few minutes for your GitHub Actions to run and when visitors visit a webpage that does not exist, they should be presented with the custom themed 404 error page.

Some Microsoft documentation will mention configuring Azure Static Web Apps with a routes.json file, but this has been depreciated. Old documentation can be found at https://github.com/Azure/static-web-apps/wiki/routes.json-reference-(deprecated)

References

Publii Docs - https://getpublii.com/docs/404-error-page-configuration.html

Microsoft Azure Static Web Apps Application Configuration - https://docs.microsoft.com/en-us/azure/static-web-apps/configuration#response-overrides

Publii Feature release blog post from 17th July 2017 - https://getpublii.com/blog/publii-tools-section-plus-404-error-pages.html