Compiling a portable website

Hi everyone. A hopefully simple question… how do I compile a Hugo website while ensuring that is 100% portable and thus can be emailed as a .zip or put on a OneDrive share, and will operate perfectly if the end user just clicks on the index.html file?

I have tried doing this using a BaseURL = “/”, and have tried all the combinations of true and false for relativeURLs and uglyURLs. I compiled simply using “hugo” on the command line.

This “compile to portable” requirement seems rather trivial, but I cannot for the life of me find an answer online anywhere.



Someone posted in here about portable sites:

1 Like

Rick, thanks for that. Perhaps I have another different problem then… I have read thru the thread you referenced and followed a few links and reached this thread:

Perhaps then my problem is not only relative links. Here is my still-troubling problem…

For the website I am generating, the top menu text for “ABOUT” (as an example) points to the address:


but then I click the link, instead of the browser opening the page, I instead get a file listing:


So is this a Hugo compilation issue that can be changed with a setting, or is this a browser issue? Surely the index.html file should be opening?

Thanks again.


Can’t test but, since your browser isn’t a web server, I think you need “ugly urls” to get the link to go to an HTML file.

1 Like

I think I read somewhere that uglyURLs have been deprecated. But assuming they are still working in 0.51 then they don’t generate the “/index.html” suffix. This is the code snippet generating the menu, so perhaps this code is the issue:

{{ range .Site.Menus.nav }}
        <li class="nav-item">
             <a class="nav-link" href="{{ .URL }}">{{ .Name }}</a>
{{ end }}

Sry not sure. I do remember .URL is being deprecated.

1 Like

I have my complete “Web Server” on a USB stick (USB disks work better).
For Windows systems I use

This is a fast way to spin up a web server.
I sync my hugo source directory to the stick, generating the pages from/to USB is very slow, but it works.

1 Like

Thanks for the reply ju52. My target audience is on Mac and PC so I would need both web servers. I guess I an stating the obvious, but the fact that we need a web server to run a static website just seems wrong and unnecessary and complicated.

1 Like

I made a quick sample project and seem to have this working when browsing the generated site using chrome. A few notes:

I added these to my config.toml:

relativeURLs = true
uglyURLs = true

When referencing any page besides index.html, you may want to use the ref or relref shortcodes. For example, when linking to the About page:

See the [about]({{< relref "/" >}}) page.

Or, just [hardcode](/about.html) it. 

Then anytime you reference the home page, hardcode the link to index.html. For example:

See the [index](/index.html) page.

Hope that helps.

Also, check the URLs in your menu nav. As an example:

  name = "Home"
  url = "index.html"
  weight = 1
  name = "About"
  url = "about.html"
  weight = 2

For what is worth, we have the same problem : we need to generate every night a portable web site created from some CSV files.

This is achieve with those 2 options, and we open the site directly in filesystem without any web server :

relativeURLs = true
uglyURLs = true
1 Like

Thanks everyone for your help. I think the problem is now solved. I will document it a bit below for others, but before that I would make some observations and comments about the portability of Hugo.

It seems from my many DuckDuckGo searches that lots of people want to make 100% portable server-free static websites, but nobody (apart from you guys) have simple and clean solutions for achieving this. This in itself is a problem as it [a] wastes a lot of time, [b] probably turns people off using Hugo, myself included and [c] seems simple to fix in principle at least.

So, those who are capable of coding, could you perhaps look at adding a compile switch, perhaps

hugo --UglyUglyURLs

which forces absolutely every internal URL to point specifically at a specific file. e.g. the HOME url which is often just coded as:


could instead enforce the address as:


The way I have gotten around this in this instance is to modify the partial “header.html” file inside the theme that I downloaded to read:

<a class="navbar-brand" href="index.html">

which is hardly an ideal solution as a theme update will overwrite my changes.

Of course it could be that my issue is actually that the theme is not written correctly? In that case, are there clear examples of HOWTO and HOWNOTTO guidelines for writing link code within themes?

Another example from the theme I used is that the menu:


is coded such that HOME is separated from the rest of the menu items, which are generated by iterating over data in config.toml. To solve this problem, I removed the separate (HOME) code from the theme file, and added the HOME code into config.toml so that home is also generated during the iteration loop along with the rest of the menu items, and thus the very specific URLs (e.g. index.html) are used.

Just override that file in your project then. Hugo gives precedence to same-name same-location files that it finds closer to the root of the project.

1 Like

Could do, but then I would have two copies of the theme file. This could then lead to potential incompatibilities further down the track if I was to download a newer copy of the theme. I think that Ideally the theme files should remain untouched, and all changes should be made in the config file.

Another option is to fork the theme repo.

This way, you keep all your custom changes, then you can pull in theme updates into your fork as you see fit.