Generate "pretty" URLs for DocFX websites with Netlify

Published: 22 March 2018


Since I am now jobless, one of the many things I am doing to keep busy is to help Kévin Chalet out with the documentation for his OpenIddict project - a free, open-source OpenID Connect server for ASP.NET Core.

We are using DocFX to generate the documentation, but one of the issues with DocFX is that the generated output contains the .html extension in the URL for all pages.

For example:

This does not quite sit right with Kevin (and neither with me), so I looked into it. I am aware that Netlify has a Pretty URLs feature as part of its Asset Optimization feature set.

I looked into this before for the OpenIddict documentation, but at that time I did not get it to work. On that occasion, however, I created the website by copying the DocFX generated files directly from my computer to Netlify.

I looked into it again, but this time around, I configured Netlify to deploy from GitHub and checked the DocFX generated documentation into a GH repo. I then ensured that I configure Netlify to make the URLs pretty:

With everything in place, I triggered a build for the website, and sure enough, Netlify did its thing. No more ugly URLs!

I am not quite sure how this works technically, but I suspect there is some sort of URL rewriting going on. However, it is more than just that. Netlify also fixes all internal links in the website to redirect to the pretty URL.

For example, notice the URL for the link when I hover over the Migration Guide link. Without Netlify, you will notice that the URL for that link contains the .html extension:

Here is the Netlify version. Notice that the URL for the link is the pretty one, without the .html extension:

Just one more reason I like Netlify 😎

PS: I publish a weekly newsletter for ASP.NET Developers called ASP.NET Weekly. If you want to get an email every Friday with all the best ASP.NET related blog posts from the previous week, please sign up!