March 22, 2018

Generate "pretty" URLs for DocFX websites with Netlify

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:

ugly url

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:

netlify configuration

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

pretty url

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:

ugly url 2

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

pretty url 2

Just one more reason I like Netlify 😎