Netlify supports two methods to configure redirects — a _redirects file and redirects tables in the netlify.toml. For context, these are two examples of how to redirect page-one to page-two using both methods.

/page-one /page-two

[[redirects]]
  from = "/page-one"
  to = "/page-two"

I use the Hugo framework that outputs HTML files into the public directory, so I configured it as a publish directory in netlify.toml. Since the configuration file was already there, I smashed some new redirects in there. I faced some issues with this setup, so I published this quick post to save you from the unpleasant surprise of broken redirects.

Netlify reads redirects from the base/publish directory#

As long as your website is hosted from the top-level directory of your repo, Netlify will respect redirects configured there. This behaviour changes when you use a framework that pre-builds files to a publish directory. The same applies when the base directory is anything else than the root, typical for monorepos.

In the pre-processing stage, Netlify reads the configuration from the root. Post-processing configuration, like redirects and rewrites, is read from the base/publish directory. In my case, adding a _redirects file to the public directory and removing redirects tables from the top-level netlify.toml solved the problem.

Unfortunately, this part of the official documentation could be better. I understood this only because of one comment by Luke Lawson on the Netlify Support Forum. I will contact the Netlify team and do my best to contribute and improve this part of the documentation.

I still love you Netlify 🫶

Leave a comment#