How can I create a redirect for a non-content file?

I am transferring my WordPress site to Hugo; as such, I need to set up a bunch of redirects so that people don’t end up with dead links.

The posts are easy; I can add aliases to the front matter. But I also have static files (PDFs) whose URLs have changed. As far as I can tell, Hugo has no native support for aliasing non-content files:

Nevertheless, I need to set up redirects. I could just put them in static/.htaccess but then I have no way of testing them, since hugo server does not respect .htaccess. Creating 20 copies of an HTML redirect page and putting them at the old URLs is beyond silly.

What is the proper way to make redirects?

I would use a .htaccess file.

If files retain their names one line should handle all files that need to be redirected.

Thank you for the suggestion. Is there any way to test these redirects locally? As I said, it does not seem like hugo server respects .htaccess.

(Files do not retain their names or paths, as a side note, but I am fine with specifying each redirect by hand.)

If you have a local or staging server with apache you could test it there.

Otherwise, I would suggest installing a different vhost in production to test it.

Very true. hugo server is a golang server and not Apache, although the directory structure makes it really easy to add your .htaccess to static/.htaccess so that it’s there at deployment (as you already mentioned :smile:).

If you want to test locally, the only way I can think of would be to build the site (running hugo), change directories into the built site (public/) and then run an Apache server from there? This is all spitballing: if you’re on a mac.

Question: Were all the PDFs in the same directory, btw? If so, maybe just create the same URL structure within static and drop the PDFs into the corresponding folder.


If I am using .htaccess, I think you are right that running a local non-hugo server is the most appropriate course of action. I’ll look into that.

The PDFs (and, in general, other types of files) were originally all in /files. Now they have been moved to the root directory of the published site, and some of them have been renamed. I’m not sure I understand what you are suggesting—I need the old URL redirected to the new location, not a second copy of my files at the old location.

But perhaps the most elegant solution would just be to add another step to my build process that manually generates 301 redirect pages in the right places, if Hugo can’t do it for me. I was just surprised that this was not supported, since I figured it would be a common task. Am I misunderstanding the intended purpose of the alias feature?


Yeah, I should have expanded a bit on that thought. Basically, I was going to suggested that if the anchors to the docs within your pages, and your baseURL were staying the same, why not just do the simplest thing and drag and drop all of your PDFs to static/files/ and call it a day. That said…

  1. If you have renamed PDFs, you’re going to have to do something server-sideish anyways
  2. If you have changed your baseURL, that’s another matter

Sorry I can’t be of more help, but I will say that to date I haven’t found a static site generator with any kind of document management functionality (for obvious reasons). Please let me know if you figure out a good solution, since I currently use Hugo for an internal-only company website, and my company can be a bit PDF-crazy (much to my chagrin :wink:). Cheers.

Thanks. I figure that I must be misunderstanding something fundamental here, since I can’t see how it wouldn’t be trivial for Hugo to support this. Here is what I am thinking.

In the config.toml, you can set simple path redirects:

  old = "/files/MyOldPath.pdf"
  new = "/MyNewPath.pdf"

  old = "/cgi-bin/assets/img0013.png"
  new = "/images/version-control-with-git.png"

Then, at each of the old paths, a simple HTML page with an http-equiv redirect is generated in public, which will point to the corresponding new path.

Is the problem that it’s impossible to serve that HTML template to the browser when the requested URL ends in .pdf, without server-side configuration? Otherwise I can’t see what would be wrong with this.

That’s a very good question that I would have to punt to the maintainers and collaborators of Hugo. That said, you could try using an alias, but I think that’s kind of missing the point, since (I’m assuming) you’re not using the Hugo server in production…and it’s really only for HTML pages…and what it actually renders is explained in detail in the Hugo docs.

This is really the tough question, since the only answer is “301s”, which is a server-related endeavor, right? At least w/r/t SEO

Hugo is only responsible for generating content files (namely, HTML, but also other content-ish files…images are another story).

To make it easier, why don’t you tell me following in an example and I can tell you if my brain droppings are even worth explaining:

  1. The full URL of a PDF on your Wordpress site
  2. The full URL you want for the PDF on your new website

Exactly! Aliases work great for HTML pages in content (you just specify the aliases in the front matter), but they aren’t currently supported for other types of pages. My idea would be to just put the front-matter alias declarations in config.toml, because you can’t put them in a PDF file.

To reiterate, the alias system is exactly what I wanted originally, except that it’s not supported for all filetypes. That, to me, is an surprising inconsistency regardless of whether or not aliases are the right approach for my problem (which I am beginning to suspect they are not—doing 301 redirects is obviously server-side, and you have a valid point that I should probably be doing my redirects on the server side).

As a concrete example, I used to have a file at

which now lives at

and I need to set up a redirect.

Okay, so, if you have all your PDFs in a single directory, why not just put all the PDFs in static/files in your Hugo directory structure? Then any references to these PDFs will not break. Does that make sense?

Everything in static is moved over as is…

Example with

I have a pdf at static/files/CalculusIntuitiveExplanations.pdf.

When I build my site with Hugo, that pdf can be accessed at…

Then the links in your WP site pages, assuming they’re all from the root (I have no idea how you built that site or how you’re transferring it over), would just work.

But if you changed the file names of the PDFs, that’s different. OR if the PDFs are living in more than one directory, that’s also a different story…

I see the confusion. Sorry I wasn’t clear earlier. The reason I need to set up redirects is because I want to change the URL structure. On my Wordpress site it was /files/IntuitiveExplanations.pdf. Now that I am transferring my website to Hugo, I decided to take advantage of the opportunity to reconsider my URL structure; and purely for reasons of vanity I decided that I liked the URL /CalculusIntuitiveExplanations.pdf better. If I just wanted to recreate the old URL structure, it would be trivial, as you said, to just put the old files in static under the old names and paths.

Gotcha. Then yes, as @magikstm mentioned, that’s a one-liner in .htaccess…or just let go of the vanity and keep files in all your links to the PDFs…:wink: Cheers.