Asset Loading Issue in Azure Static Web Apps with MkDocs-Material Sites in Subdirectories

[pushbroomsweep]

I'm hosting a static site on Azure Static Web Apps, built using MkDocs-Material. The site contains a main landing page and multiple sub-sites (each built individually using mkdocs) located in subdirectories (e.g., /sub-site1/, /sub-site2/). Each sub-site has its own index.html, assets (CSS, JS, images), and content pages.

Here's the structure of the deployed site:

public/
  index.html          # Landing page
  assets/
  stylesheets/
    main.css
  sub-site1/          # Sub-site 1
    index.html
    assets/
    stylesheets/
        main.css
  sub-site2/          # Sub-site 2
    index.html
    assets/
      stylesheets/
        main.css

Problem

While the main landing page loads correctly, sub-site pages fail to load their CSS and JavaScript and the navigation doesn't work properly in the sub-sites either. The browser tries to load the assets from the subdirectory of the current page (e.g., /sub-site1/page1/assets/stylesheets/main.css) instead of the correct directory root for the sub-site (e.g., /sub-site1/assets/stylesheets/main.css).

Debugging Insights

1. Configuration:
   • site_url in mkdocs.yml is set to the correct sub-site URL (e.g., https://example.com/sub-site1/) and for the landing page, it is set to https://example.com/.
   • use_directory_urls: true is used in all builds (I have tried setting this to false as well).
   • My staticwebapp.config.json looks like:

     {
          "trailingSlash": "always",
          "navigationFallback": {
              "rewrite": "/index.html",
              "exclude": [
                  "/sub-site1/*",
                  "/sub-site2/*",
              ]
          },
          "routes": [
              {
                  "route": "/",
                  "methods": ["GET"],
                  "rewrite": "index.html"
              },
              {
                  "route": "/sub-site1/*",
                  "methods": ["GET"],
                  "rewrite": "/sub-site1/"
              },
              {
                  "route": "/sub-site2/*",
                  "methods": ["GET"],
                  "rewrite": "/sub-site2/"
              },
          ],
          "mimeTypes": {
              ".html": "text/html",
              ".css": "text/css",
              ".js": "application/javascript",
              ".json": "application/json",
              ".woff": "font/woff",
              ".woff2": "font/woff2",
              ".ttf": "font/ttf",
              ".svg": "image/svg+xml",
              ".png": "image/png",
              ".jpg": "image/jpeg",
              ".jpeg": "image/jpeg",
              ".gif": "image/gif"
          },
          "responseOverrides": {
              "404": {
                  "rewrite": "/404.html"
              }
          }
      }
     

2. Behavior Observed:
   • The browser throws errors like NS_ERROR_CORRUPTED_CONTENT or 404s for asset files.
   • The asset paths in the generated HTML are relative to the current page's directory rather than the sub-site root.
   • If I try and look at the link to a page in a sub-site, say https://example.com/sub-site1/page1 by clicking on a link in the sub-site home page (which loads without any styles or scripts), it shows as https://example.com/page1.

Question

How can I configure MkDocs and Azure Static Web Apps so that sub-site pages correctly load their assets (CSS, JS) without attempting to fetch them relative to the current page? Is there a specific MkDocs or Azure Static Web Apps configuration I might be missing? Any insights or similar experiences would be greatly appreciated! Or if it is even possible to host a structure like this (where we have a top level site as well as sub-sites built separately as sub-folders which will be linked as paths to the domain) as a static web app?

[squidfunk]

Exact duplicate of Azure/static-web-apps#1603. This is, in fact, a double post, which violates our contributing guidelines:

Opening multiple channels to ask the same question or report the same issue across different forums hinders our ability to manage and address community concerns effectively. This approach is vital for efficient time management, as duplicated questions can consume the time of multiple team members simultaneously. Ensuring that each issue or discussion is unique and progresses with new information helps us to maintain focus and support our community.

You're making more work for everyone. Please don't do that.

[pushbroomsweep]

Thank you for taking the time to review my question. I understand and respect the importance of efficient community management. However, I believe my cross-posting in this case serves a valid purpose that may not have been immediately apparent.

My question sits at the intersection of MkDocs Material and Azure Static Web Apps, requiring expertise in both areas. By posting in both communities, I'm trying to reach two distinct groups of developers who might have encountered similar challenges in their respective domains. A developer experienced with Azure hosting may not follow MkDocs discussions, and vice versa.

The goal wasn't to consume additional resources, but rather to bridge these two technical communities and potentially help future users who might face similar integration challenges. Would it be possible to reconsider keeping this discussion open, perhaps with cross-references to the related thread to maintain transparency?

I appreciate your consideration and remain committed to being a constructive member of both communities.

[kamilkrzyskow]

The goal wasn't to consume additional resources, but rather to bridge these two technical communities and potentially help future users who might face similar integration challenges. Would it be possible to reconsider keeping this discussion open, perhaps with cross-references to the related thread to maintain transparency?

You have published the same post on different forums without informing the relevant parties about it, so there was no bridging. While I admit that your post looks well researched etc., instead of taking up space on both forums at the same time you should wait for instructions from one party before going to the next. Even now, someone on their discussion board might be taking the time to read and investigate your query. Not informing about cross-posts looks like you want to have it fixed ASAP and want as many helping hands as possible.

Also this is mostly an MkDocs / Azure problem, not a Material for MkDocs problem, so this is also not the forum for this question, but I admit the border line is blurry.

As for the question, this is similar to this:

• 404 rendering fails #7595

The go to answer is what you've investigated, if you have different domains / subdirectories, you should always changes the site_url to match the proper base URL. Or use a hook to modify the url filter function to resolve assets with absolute paths to their location, as currently they rely on relative paths on each page.

mkdocs-material/src/templates/base.html

Line 102 in 0602997

<link rel="stylesheet" href="{{ 'assets/stylesheets/main.css' | url }}" />

https://github.com/mkdocs/mkdocs/blob/7e4892ab2dd4a52efd95a9de407eee63310e0780/mkdocs/utils/templates.py#L38

Now would be a good time to ask the question upstream given your new information, but you already did. This might also be an XYProblem, as I don't see the purpose of the sub-site pages. If they are different repositories projects then there is the projects plugin. To keep the same level of relative paths Azure might offer deploying to different subdomains instead of different sub-directories.

[pushbroomsweep]

Thank you, really appreciate the response. Going forward, I'll make sure to include cross-reference links and be upfront about parallel discussions.