Publish via FastAPI (relative url causes problems here)

[Lexachoc]

This question relates to the use of FastAPI, but more to the mkdocs material here.

Issue with FastAPI

The issue came to me when I want to serve static files and the build mkdocs pages from a directory using StaticFiles.

For example, my application structure looks like this:

app/
├─ mkdocs/
│  │   ├─ docs/
│  │   │  ├─ index.md
│  │   ├─ site/   # the auto-build folder after using mkdocs build
│  │   │  ├─ ...     
├─ static/
│  ├─ styles.css
├─ templates/
│  ├─ index.html
├─ main.py

my FastAPI main.py:

from fastapi import FastAPI, Request
from fastapi.responses import HTMLResponse
from fastapi.staticfiles import StaticFiles
from fastapi.templating import Jinja2Templates

app = FastAPI()

app.mount("/static", StaticFiles(directory="static"), name="static")
app.mount("/mkdocs/site", StaticFiles(directory="mkdocs/site"), name="mkdocs")

templates = Jinja2Templates(directory="templates")
help_templates = Jinja2Templates(directory="mkdocs/site")


@app.get("/")
async def root(request: Request):
    return templates.TemplateResponse(name="index.html", request=request)


@app.get("/mkdocs", response_class=HTMLResponse)
async def mkdocs(request: Request):
    return help_templates.TemplateResponse(name="index.html", request=request)

1. cd to the app folder where main.py is located, run python -m uvicorn main:app --reload and go to http://localhost:8000/mkdocs
2. I got errors:

INFO:     127.0.0.1:2605 - "GET /mkdocs HTTP/1.1" 200 OK
INFO:     127.0.0.1:2605 - "GET /assets/stylesheets/main.f2e4d321.min.css HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:2610 - "GET /assets/javascripts/bundle.8fd75fb4.min.js HTTP/1.1" 404 Not Found

because the build files are using relative paths for stylesheets or javascripts
I have to manually add a prefix /mkdocs/site/ to all the src locations in the auto-generated html files

INFO:     127.0.0.1:2995 - "GET /mkdocs/site/assets/stylesheets/main.f2e4d321.min.css HTTP/1.1" 200 OK
INFO:     127.0.0.1:2995 - "GET /mkdocs/site/assets/javascripts/bundle.8fd75fb4.min.js HTTP/1.1" 200 OK
INFO:     127.0.0.1:2995 - "GET /mkdocs/site/assets/javascripts/bundle.8fd75fb4.min.js.map HTTP/1.1" 200 OK
INFO:     127.0.0.1:2995 - "GET /search/search_index.json HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:2995 - "GET /assets/javascripts/workers/search.b8dbb3d2.min.js HTTP/1.1" 404 Not Found
INFO:     127.0.0.1:2995 - "GET /mkdocs/site/assets/images/favicon.png HTTP/1.1" 200 OK

So I would like to know if there is a configuration for adding a base_url as a prefix to the locations of these auto-generated files?

I tried to add site_url, but apparently this has nothing to do with the relative locations within the automatically generated HTML files

Issue with Instant loading

The instant loading function does not work when deploying with GitLab. (Since I have problems with FastAPI deployment, I am currently using GitLab CI to deploy the pages)

I use the exact same gitlab-ci.yml task from https://squidfunk.github.io/mkdocs-material/publishing-your-site/#gitlab-pages
and noticed that the instant loading won't work in gitlab pages while it works locally using mkdocs serve

For reproduction:

app.zip

1. unzip and cd to the app folder where main.py is located
2. run python -m uvicorn main:app --reload
3. go to http://localhost:8000/mkdocs

FastAPI version: 0.109.0
mkdocs-material version: 9.5.9

Does anyone know the solution to these problem?

[alexvoss]

So I would like to know if there is a configuration for adding a base_url as a prefix to the locations of these auto-generated files?

I assume you are not controlling the generation of the files? We did have a question about adding a base_url to image paths the other day, which might be helpful: #6615. It seems that the mkdocs-site-urls plugin does the job. I have not tried it myself, so feedback would be very welcome.

Re the Gitlab instant loading issue, can you be a bit more specific and provide information about what is not working and what you have done so far to investigate?

[kamilkrzyskow]

Hello @Lexachoc,
there is no built-in base_url prefix feature that would prevent the relative link generation.
The path to the assets is processed via the url_filter function:

mkdocs-material/src/templates/base.html

Line 102 in b7fc7ba

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

https://github.com/mkdocs/mkdocs/blob/e755aaed7ea47348a60495ab364d5483ab90a4a6/mkdocs/utils/templates.py#L38
So you could use a hook to monkey patch the function to meet your needs, here is an example: url_filter.zip
In the example I add a base_path prefix to paths starting with assets/

The hook file

try:
    from jinja2 import pass_context as contextfilter  # type: ignore
except ImportError:
    from jinja2 import contextfilter  # type: ignore
    
from mkdocs.utils import templates

def on_startup(*_, **__):
    templates.url_filter = url_filter_wrapper(templates.url_filter)
    
def url_filter_wrapper(func):

    base_path = "/mkdocs/site/"
    
    @contextfilter
    def wrapper(context, value):
        if value.strip().startswith("assets/"):
            value = base_path + value.strip()
        return func(context, value)
        
    return wrapper

Having said that, I consider this issue out of scope of the theme, as the server is responsible for serving the files.
It's true that the relative paths in the urls don't resolve to actual files, but that happens, because the server doesn't handle the url paths.
I never used FastAPI, so it's hard for me to tell what is the best course of action here, but the first idea that comes to mind is to setup the mkdocs/ endpoint at the actual file path mkdocs/site/ and then create a redirect from mkdocs/ to mkdocs/site/, or create some other redirect from assets/ to mkdocs/site/assets/.

---

As for the Instant loading not working, the logic is in JavaScript, so check the developer tools in your browser.
Perhaps there is some CORS issue and the fetch isn't resolving, or some other issue with paths again.
But like Alex said, we need more detail about what is not working in thet Instant loading.

[Lexachoc]

@alexvoss Thank you for the plugin suggestion, I also found that post before asking this question but that plugin deals with the paths in the markdown file, while in my case the paths I want to add a base_url are the script and style paths in the index.html.

The monkey patch solution from @kamilkrzyskow solves the problem partially

The search bar will not work due to the error below (in console)

index.ts:113 
        
GET http://127.0.0.1:8000/search/search_index.json 404 (Not Found)

the probelm came from this line in the index.html:

<script id="__config" type="application/json">{"base": ".", "features": [], "search": "/mkdocs/site/assets/javascripts/workers/search.b8dbb3d2.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>

The value of the key base must also be changed, in my case my base_url is /mkdocs/stie, so I change it to "base": "/mkdocs/site/".
After that it works.
the value of base is definded also in the base.html:

mkdocs-material/src/templates/base.html

Line 391 in b7fc7ba

"base": base_url,

However

I noticed that this won't work when having nav (page trees). Thanks for the hint of templates/base.html, so another easier solution maybe to direct modify the base.html jinja blocks relates to the paths. But it turns out that lots of things need to be modified:

1. The base_url
2. All resources inside assets folder in the src/templates/base.html
3. links like href in a tag for navigation

I also found this plugin: https://github.com/ncdc/mkdocs-modify-base-url/tree/main

This gives me some hint that I can add prefix to the base.html, e.g.:

mkdocs-material/src/templates/base.html

Line 435 in b7fc7ba

<script src="{{ 'assets/javascripts/bundle.js' | url }}"></script>

to
<script src="{{ 'mkdocs/site/assets/javascripts/bundle.js' | url }}"></script>

But this won't work with other pages (when using nav), since they use relative paths: e.g.,
<script src="../assets/javascripts/bundle.8fd75fb4.min.js"></script> in my another page.

so...many things also need to be updated here to make everything work

---

Regarding to the Issue with Instant loading:

No CORS errors and I can see that from the "Network" tab of the developer tool in Chrome it works when using mkdocs serve:

But after deploying in GitLab:

You could check the files in here: https://git.uni-jena.de/ce65pen/instant-loading-issue/-/blob/main/mkdocs.yml
and the deployed page in here:
https://instant-loading-issue-ce65pen-60c9fc3c8f88c7fd0de42d98693958913.gitpages.uni-jena.de/

Thank you for the help!

[kamilkrzyskow]

The base_url here:

mkdocs-material/src/templates/base.html

Line 391 in 4fd52fd

"base": base_url,

comes from MkDocs:
https://github.com/mkdocs/mkdocs/blob/e755aaed7ea47348a60495ab364d5483ab90a4a6/mkdocs/commands/build.py#L68-L78
and you can monkey patch it similarly to the url_filter above to modify the output. So that's the >1. The base_url
The hook from before with url_filter is the >2. All resources inside assets folder in the src/templates/base.html
And the last thing >3. links like href in a tag for navigation, would probably be in the RelativePathProcessor:
https://github.com/mkdocs/mkdocs/blob/e755aaed7ea47348a60495ab364d5483ab90a4a6/mkdocs/structure/pages.py#L418
Though the processor likely only works with the Markdown links [name](url) and not HTML <a href=url>name</a>

If so much monkey patching isn't preferred, you could do a hook with the on_post_build/on_post_page event and process the final HTML with regex to detect all anchors and convert relative into absolute paths. However, I don't think that this approach is easier, and will be slower to process.

You have to go through the trial and error process yourself to fine-tune the hook for exceptions or edge-cases etc.
Good luck ✌️

---

Thanks for the example project, I was surprised to see that there are no errors, but since I could run the project I did a file comparison against files generated with mkdocs serve and mkdocs build and it turned out that, mkdocs serve sets thet site_url to https://127.0.0.1/, so the canonical url gets added in base.html:

mkdocs-material/src/templates/base.html

Lines 48 to 51 in 4fd52fd

	<!-- Canonical -->
	{% if page.canonical_url %}
	<link rel="canonical" href="{{ page.canonical_url }}" />
	{% endif %}

Perhaps there is some other difference too, but I did test with a local server and files from mkdocs build and adding the site_url to the mkdocs.yml file did actually help.

So it seems you have to use the site_url, I don't know if it's a bug, as it's not documented.

[Lexachoc]

@kamilkrzyskow thank you so much! I add the site_url and now it works in the GitLab.
I will open an issue for that.

issue open in here: #6792