Top Navigation Logo - Url Issue - 404 page

[VaclavElias]

Hi,

I've been working on the new version of Stride Docs, leveraging a modern template and the latest version of DocFX. We're deploying it to Azure App Service, using IIS. You can test it here: Test https://stride-docs-test.azurewebsites.net/4.1/en/index.html

The Stride Docs repository (https://github.com/VaclavElias/stride-docs-next) is quite complex due to its support for multiple versions and languages. To manage this complexity, we're using PowerShell for orchestration. This setup might be useful for others who require similar functionality, or perhaps some features could be integrated into DocFX itself to simplify the process.

Issues

Issue 1: 404 Page Post-Processing (Resolved)

We've post-processed (in PowerShell) the 404.html generated from 404.md because this specific page needs absolute paths for assets like CSS and JS. It is because how 404 works on IIS.

Issue 2: Top Navigation Logo

Another issue arises when navigating to a non-existent page, for example https://stride-docs-test.azurewebsites.net/4.1/en/tutoridals/index.html (non existing folder). The top logo doesn't point to the root, which in this case should be https://stride-docs-test.azurewebsites.net/latest/en/ It instead points to index.html. That means, when I click on the logo, I remain where I am on the 404 page.

Note that other links (Manual, Tutorials, Release Notes, API) are working correctly.

Questions

What behavior would you recommend for handling 404 errors? Should DocFX offer an optional parameter to overwrite the Logo URL with an absolute path to improve the user experience on the 404 page?

The examples listed in other discussions are deployed on GitHub Pages, where the 404 pages are not customized and rely on users manually correcting the link. However, if a 404 page resembles another documentation page in our case, users might intuitively click on the logo image.

Example of BenchmarkDotNet Docs deployed on GitHub Pages

https://benchmarkdotnet.org/articles/features/parameterizatiodn.html

Thanks for any input :)

[yufeih]

What behavior would you recommend for handling 404 errors?

One approach is for docfx to expose a metadata that controls whether output URL is relative or absolute. This could be applied individually to a page such as 404 or the whole docset.

Note that other links (Manual, Tutorials, Release Notes, API) are working correctly.

The logo is rendered at build time, while other links are rendered in browser relative to docfx:navrel. It seems the 404 post process turns docfx:navrel into an absolute URL, as a workaround, is it possible to adjust the post process to replace the logo URL with an absolute URL?

related #2865

[VaclavElias]

Thank you @yufeih.

One approach is for docfx to expose a metadata that controls whether output URL is relative or absolute. This could be applied individually to a page such as 404 or the whole docset.

If you can see that others could also benefit from this feature then it can be added to the backlog 🙂.

The logo is rendered at build time, while other links are rendered in browser relative to docfx:navrel. It seems the 404 post process turns docfx:navrel into an absolute URL, as a workaround, is it possible to adjust the post process to replace the logo URL with an absolute URL?

Of course. We are doing post-processing specifically for 404 so we can do this as well, because it applies only to this one page.

Thanks again for your input and your work on docfx!